Documentação da API

A API REST do ConsultaScore (versão v1) expõe autenticação, consultas de crédito (Serasa), recursos de IA opcionais, pagamentos via Asaas 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. Exemplo de health check: GET BASE_URL/health retorna {"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).

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: {"email":"usuario@empresa.com","password":"sua_senha"}
• Resposta inclui access_token (string) e objeto user (id, email, empresa_id, admin, etc.).

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 com {"email":"..."} — fluxo genérico que envia e-mail se o usuário existir.
• POST BASE_URL/api/v1/auth/confirm-reset-password com {"token":"...","new_password":"..."} para definir nova senha.

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

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 {"nome":"Integração ERP"}; requer Bearer JWT de usuário admin. Resposta inclui id, nome e key (texto claro só nesta resposta).
• 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.

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.

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.

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.

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).

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.

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.

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.

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.

Integração com Asaas para faturas e pedidos. Requer variáveis de ambiente no servidor (tokens Asaas, URL de callback público HTTPS).

Fatura (mensalidade / cobrança gerada no sistema)

• POST BASE_URL/api/v1/pay/checkout — Bearer JWT. PIX: {"fatura_id","method":"pix"}. Cartão: inclua credit_card (holder_name, number, expiry_month, expiry_year, ccv) e card_holder (name, email, cpf_cnpj, postal_code, address_number, phone; opcionais address_complement, mobile_phone).
• PIX: resposta inclui pix.encodedImage, pix.payload, pix.expirationDate para exibir QR Code.
• Cartão: captura na API Asaas; resposta inclui payment_id e status (sem checkout_url). Customer Asaas (empresa ou ASAAS_DEFAULT_CUSTOMER_ID) obrigatório.
• 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).

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 (ASAAS_CALLBACK_BASE_URL) não pode ser localhost em produção — use domínio público ou túnel HTTPS cadastrado no Asaas.

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.

O ConsultaScore recebe notificações do Asaas para atualizar status de pagamento (eventos como PAYMENT_RECEIVED, PAYMENT_CONFIRMED). Isso não é um webhook que sua empresa configura para receber dados do ConsultaScore — é a URL que você cadastra no painel do Asaas apontando para esta API.

URLs aceitas (equivalentes)

• POST BASE_URL/asaas/webhook
• POST BASE_URL/api/v1/webhooks/asaas

Segurança opcional

• Se a variável ASAAS_WEBHOOK_TOKEN estiver definida no servidor, cada requisição deve incluir o cabeçalho asaas-access-token com exatamente o mesmo valor.
• Se o token estiver errado ou ausente quando exigido, a API responde 401 Invalid webhook token.
• Corpo: JSON do evento Asaas (payment, checkoutSession, etc.).

No painel Asaas, configure a URL pública HTTPS e o mesmo segredo no cabeçalho, alinhado ao ASAAS_WEBHOOK_TOKEN. Eventos são processados para marcar faturas/pedidos pagos e fluxos associados (ex.: NFS-e automática conforme regras do servidor).

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.

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.

• 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.