Documentação da API ConsulteScore

Nas URLs abaixo, use {BASE_URL} como o host da API (ex.: https://api.seudominio.com), sem barra no final.

Introdução

A API REST do ConsultaScore (versão v1) expõe autenticação, consultas de crédito (Serasa), recursos de IA opcionais, pagamentos (checkout e faturas) e cadastro de empresas. Todas as rotas versionadas ficam sob o prefixo /api/v1. Use HTTPS em produção.

Substitua BASE_URL pelo endereço da sua instância. O health check confirma que a API está no ar.

curl -sS -X GET \
  '{BASE_URL}/health'
# Exemplo de resposta: {"status":"ok"}

A própria API FastAPI gera documentação interativa em BASE_URL/docs (Swagger UI) e BASE_URL/redoc — útil para testar rotas com o token já configurado.

Formato e erros

Corpo das requisições: JSON com Content-Type: application/json (salvo onde indicado).
Respostas de erro costumam trazer HTTP 4xx/5xx com campo detail (mensagem) no padrão FastAPI.
401 Unauthorized: token ausente, inválido ou expirado; 403: sem permissão (ex.: não é admin); 400: validação; 502/503: dependência externa indisponível (ex.: Serasa não configurada).

Autenticação com JWT (usuário e senha)

O login devolve um access_token JWT. Envie-o nas rotas protegidas no cabeçalho: Authorization: Bearer <access_token>. O tempo de vida padrão segue ACCESS_TOKEN_EXPIRE_MINUTES no servidor (ex.: 1440 minutos = 24 h).

Login padrão

POST BASE_URL/api/v1/auth/login
Corpo JSON com email e password.
Resposta inclui access_token (string) e objeto user (id, email, empresa_id, admin, etc.).

curl -sS -X POST \
  '{BASE_URL}/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"email":"usuario@empresa.com","password":"sua_senha"}'

Login restrito ao backoffice

POST BASE_URL/api/v1/auth/login-backoffice
Mesmo corpo do login; só funciona se o usuário tiver perfil de backoffice ou admin.
Se não tiver permissão, retorna 403.

Recuperação de senha

POST BASE_URL/api/v1/auth/forgot-password — envia e-mail se o usuário existir.
POST BASE_URL/api/v1/auth/confirm-reset-password — define nova senha com token recebido por e-mail.

curl -sS -X POST \
  '{BASE_URL}/api/v1/auth/forgot-password' \
  -H 'Content-Type: application/json' \
  -d '{"email":"usuario@empresa.com"}'

Usuários sem senha cadastrada recebem 403 no login até usarem o fluxo de recuperação.

Chaves de API (X-API-Key)

Além do JWT, integrações servidor-a-servidor podem usar uma chave de API no cabeçalho X-API-Key. A chave é gerada pelo painel/administrador da empresa e fica vinculada ao empresa_id. Ela é mostrada apenas uma vez na criação — guarde em cofre de segredos.

Gerenciamento (usuário admin da empresa)

POST BASE_URL/api/v1/api-keys — corpo opcional com nome; requer Bearer JWT de usuário admin.
GET BASE_URL/api/v1/api-keys — lista chaves da empresa (sem revelar o segredo completo).
DELETE BASE_URL/api/v1/api-keys/{key_id} — revoga a chave.

curl -sS -X POST \
  '{BASE_URL}/api/v1/api-keys' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Integração ERP"}'

Uso nas rotas

Rotas que aceitam consulta com Bearer OU X-API-Key incluem POST /api/v1/consulta e POST /api/v1/ai/score. Outras rotas (ex.: melhorar texto, usuários) exigem apenas Bearer conforme a implementação atual.

curl -sS -X POST '{BASE_URL}/api/v1/consulta' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <sua_chave>' \
  -d '{"doc":"12345678909","report":"score_pf"}'

Consulta de crédito (Serasa)

POST BASE_URL/api/v1/consulta — executa relatório PF ou PJ via integração Serasa da empresa. Autenticação: Authorization: Bearer <JWT> ou X-API-Key.

curl -sS -X POST '{BASE_URL}/api/v1/consulta' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "doc": "12345678909",
    "report": "nome_do_relatorio",
    "report_options": null,
    "empresa_id": null,
    "force_new": false
  }'

Corpo JSON

doc (obrigatório): CPF com 11 dígitos ou CNPJ com 14 (somente números ou com máscara; o servidor normaliza).
report (obrigatório): nome do relatório Serasa (reportName), conforme contrato/plano — exemplos comuns incluem score_pf / tipos definidos pela Serasa; confira com o seu consultor ou o catálogo contratado.
report_options (opcional): string — repassada como optionalFeatures na API Serasa (formato esperado pelo provedor).
empresa_id (opcional): se omitido, usa o empresa_id do token JWT ou o da chave de API.
force_new (opcional, boolean, padrão false): se true, ignora cache do ConsultaScore e força nova consulta na Serasa.

Resposta (sucesso)

status_code: 200
data: payload JSON retornado pela Serasa.
source: "serasa" (nova consulta) ou "cs" (resposta reutilizada do cache, quando aplicável).
empresa: dados cadastrais usados na operação.
hist_id: identificador do registro no histórico de consultas.

Erros frequentes

503: Serasa não configurada no servidor (SERASA_EXTERNAL_URL) ou mensagem contendo "não configurada".
404: empresa não encontrada.
403: cadastro da empresa inativo.
400: documento inválido, tipo de relatório ausente ou validação de relatório.

IA — análise de score (opcional)

POST BASE_URL/api/v1/ai/score — após obter dados de consulta, pode gerar análise assistida por modelo de linguagem. Aceita o mesmo esquema de autenticação que /consulta (Bearer ou X-API-Key).

curl -sS -X POST '{BASE_URL}/api/v1/ai/score' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentos": ["00000000000"],
    "report": "score_pf",
    "report_options": null,
    "empresa": null,
    "llm_model": null
  }'

Corpo JSON

documentos: lista de strings com CPF/CNPJ (um ou vários).
report / report_options: mesma ideia da consulta (opcionais conforme implementação).
empresa (opcional): empresa_id; se omitido, usa o token.
llm_model (opcional): modelo customizado se suportado pela configuração do servidor.

POST BASE_URL/api/v1/ai/improve-text — recebe {"texto":"..."} e retorna texto melhorado; requer Bearer JWT (usuário logado), não use apenas X-API-Key nesta rota.

curl -sS -X POST '{BASE_URL}/api/v1/ai/improve-text' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"texto":"Texto a refinar."}'

Usuários e perfil

Rotas sob BASE_URL/api/v1/users exigem Bearer JWT. Exemplos: GET /users/me — dados do usuário atual; PATCH /users/me — atualização; rotas administrativas combinam get_current_user com permissão admin.

curl -sS -X GET '{BASE_URL}/api/v1/users/me' \
  -H 'Authorization: Bearer <access_token>'

GET /users — lista usuários da empresa (filtros por atributos conforme query params na implementação); POST /users — cria usuário (admin). Operações por id: PATCH, DELETE, enable/disable, troca de senha, conforme exposto no Swagger em /docs.

Business — empresa, planos e relatórios

Prefixo BASE_URL/api/v1/business. Quase todas as operações exigem JWT; muitas rotas administrativas exigem admin. Um usuário comum só acessa dados da própria empresa (usuario.empresa_id igual ao CNPJ/documento da rota), salvo se for admin.

Exemplos de recursos

GET /business/planos — planos disponíveis.
GET /business/empresas/{doc} — dados da empresa (doc = CNPJ).
POST /business/empresas — cadastro de empresa (formato EmpresaCreate no OpenAPI).
GET /business/empresas/{doc}/plano — plano vigente; PATCH /business/empresas/{doc}/plano-vigente — alterar plano (admin).
GET /business/empresas/{doc}/faturas — faturas da empresa.
GET /business/empresas/{doc}/consultas/historico — histórico de consultas.
Endpoints de relatórios customizados, AI overview, contrato em PDF, etc. — ver lista completa em BASE_URL/docs.

curl -sS -X GET '{BASE_URL}/api/v1/business/planos' \
  -H 'Authorization: Bearer <access_token>'

Pagamentos (faturas e checkout)

Checkout de faturas (mensalidades) e de pedidos por produto, com PIX ou cartão. A confirmação pode ser feita por polling nas rotas de status ou pelos webhooks de pagamento expostos pelo ConsultaScore (veja seção Webhooks). Em produção, use URL pública HTTPS para callbacks configurados no servidor.

Fatura (mensalidade / cobrança gerada no sistema)

POST BASE_URL/api/v1/pay/checkout — Bearer JWT. Método pix ou cartão com credit_card e card_holder conforme OpenAPI.
PIX: resposta inclui pix.encodedImage, pix.payload, pix.expirationDate para exibir QR Code.
Cartão: resposta inclui payment_id e status (sem checkout_url). Cadastro de cliente de cobrança vinculado à empresa é obrigatório quando aplicável.
GET BASE_URL/api/v1/pay/status?fatura_id=... — polling {"paid": true|false} após PIX ou cartão (confirmação também via webhook do ConsultaScore).

curl -sS -X POST '{BASE_URL}/api/v1/pay/checkout' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fatura_id": 123,
    "method": "pix"
  }'

curl -sS -X GET \
  '{BASE_URL}/api/v1/pay/status?fatura_id=123' \
  -H 'Authorization: Bearer <access_token>'

Pedido por produto (ex.: conversa / produto avulso)

POST BASE_URL/api/v1/payments/checkout — PIX: conversation_id, product, method pix. Cartão: os mesmos campos mais credit_card e card_holder (mesmo formato que em /pay/checkout).
Produtos e valores vêm do catálogo no servidor (ex.: product consulta_score); método inválido retorna 400.
GET BASE_URL/api/v1/payments/status?order_id=... — acompanha confirmação do pedido (PIX ou cartão).
A URL de callback da instância não pode ser localhost em produção — use domínio público ou túnel HTTPS conforme a configuração do gateway de pagamento.

curl -sS -X POST '{BASE_URL}/api/v1/payments/checkout' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversation_id": "uuid-da-conversa",
    "product": "consulta_score",
    "method": "pix"
  }'

NFS-e (nota fiscal)

POST BASE_URL/api/v1/pay/faturas/{fatura_id}/emitir-nfse — emissão quando configurado (variáveis NFSE_* no servidor).
Outras rotas administrativas de NFS-e podem constar no Swagger.

Webhooks de pagamento (ConsultaScore)

O ConsultaScore expõe endpoints HTTP que recebem notificações do provedor de pagamento para atualizar status de faturas e pedidos (por exemplo eventos de pagamento confirmado). São URLs da sua instância da API — o que você configura no painel do provedor é o destino dessas chamadas, apontando para o ConsultaScore.

URLs aceitas (equivalentes)

POST BASE_URL/asaas/webhook
POST BASE_URL/api/v1/webhooks/asaas
(Os caminhos refletem compatibilidade com integrações existentes; o processamento é feito pela API ConsultaScore.)

# Exemplo: o provedor de pagamento envia um POST JSON para a sua API ConsultaScore:
curl -sS -X POST '{BASE_URL}/api/v1/webhooks/asaas' \
  -H 'Content-Type: application/json' \
  # Se a instância exigir token, adicione o cabeçalho indicado no Swagger (BASE_URL/docs).
  -d '{"event":"PAYMENT_CONFIRMED","payment":{"id":"..."}}'

Segurança opcional

Se a instância estiver configurada com token de validação de webhook, cada requisição deve incluir o cabeçalho esperado (nome e valor definidos na configuração do servidor — consulte o Swagger em BASE_URL/docs).
Se o token estiver errado ou ausente quando exigido, a API responde 401 Invalid webhook token.
Corpo: JSON do evento enviado pelo provedor (estrutura conforme payload real; campos como payment, checkoutSession, etc.).

No painel do provedor de pagamento, cadastre a URL pública HTTPS da sua instância ConsultaScore e o mesmo segredo no cabeçalho, alinhados à configuração do servidor. Os eventos são processados para marcar faturas/pedidos pagos e fluxos associados (ex.: NFS-e automática conforme regras do servidor).

Contrato público (sem login)

Rotas públicas para o fluxo de contrato de prestação: prefixo BASE_URL/api/v1/public/contrato — incluem GET com token para visualizar, POST para assinar com corpo contendo dados de aceite e assinatura. Detalhes dos campos no schema OpenAPI em /docs.

Jobs internos (não use sem autorização)

POST BASE_URL/api/v1/internal/cron/fechamento-mensal e POST BASE_URL/api/v1/internal/cron/fechamento-meses-retroativos são protegidos pelo cabeçalho HTTP X-Cron-Secret com o mesmo valor configurado em CRON_FECHAMENTO_SECRET no servidor. Sem esse header correto a API retorna 401. Existe também fluxo administrativo via JWT em POST /api/v1/pay/admin/fechamento-mensal (usuário admin). Estes endpoints não são para integração típica de cliente nem devem ser expostos em apps públicos.

curl -sS -X POST '{BASE_URL}/api/v1/internal/cron/fechamento-mensal' \
  -H 'X-Cron-Secret: <valor_secreto>'

CORS, ambiente de testes e boas práticas

O servidor pode listar origens permitidas para chamadas a partir de navegadores; integrações servidor-a-servidor não sofrem CORS.
Nunca envie X-API-Key ou senhas em apps front-end públicos — use backend próprio como proxy.
Trate 401 renovando login ou rotacionando chave revogada.
Use sempre BASE_URL/docs da sua instância para confirmar paths e schemas exatos.

Documentação da API

Assistente da documentação

Introdução

Formato e erros

Autenticação com JWT (usuário e senha)

Login padrão

Login restrito ao backoffice

Recuperação de senha

Chaves de API (X-API-Key)

Gerenciamento (usuário admin da empresa)

Uso nas rotas

Consulta de crédito (Serasa)

Corpo JSON

Resposta (sucesso)

Erros frequentes

IA — análise de score (opcional)

Corpo JSON

Usuários e perfil

Business — empresa, planos e relatórios

Exemplos de recursos

Pagamentos (faturas e checkout)

Fatura (mensalidade / cobrança gerada no sistema)

Pedido por produto (ex.: conversa / produto avulso)

NFS-e (nota fiscal)

Webhooks de pagamento (ConsultaScore)

URLs aceitas (equivalentes)

Segurança opcional

Contrato público (sem login)

Jobs internos (não use sem autorização)

CORS, ambiente de testes e boas práticas