Primeiros passos

Guia de integração para parceiros: autenticação, headers, contratos de request e response, catálogo completo de erros mapeados e webhooks.

Contrato: v1 (application/vnd.creditas.v1+json) · atualizado em 28 set 2026

1. Ambientes

2. Autenticação

Todas as rotas de negócio exigem um caller autenticado. A API é stateless: não há sessão,
não há cookie, e o token deve ser enviado em toda requisição.

Authorization: Bearer <access_token>

As credenciais (usuário/senha de serviço) são emitidas pela Creditas para cada parceiro no
onboarding. O token é obtido no serviço de autenticação da Creditas e tem validade curta —
faça cache do token e renove antes do vencimento, não solicite um token novo por requisição.

Rotas públicas (não exigem token): /health, /metrics.

Escopo por parceiro. O parceiro é identificado a partir do próprio token. Nenhum endpoint
recebe partnerId no path, query ou body — os recursos retornados/afetados são sempre
restritos ao parceiro autenticado. Tentar acessar um recurso de outro parceiro resulta em
404 Not Found, não 403.

3. Headers obrigatórios

Atenção ao Accept. O versionamento da API é feito exclusivamente pelo header Accept.
Um Accept ausente, */* ou application/json é rejeitado com 406 Not Acceptable antes
mesmo de chegar ao endpoint. Não existe versionamento por path (/v1/...).

Exemplo mínimo de chamada:

curl -X POST "https://stg-api.creditas.io/rentals-partner-api/pre-profile-analysis" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.creditas.v1+json" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

4. Convenções gerais

• JSON em camelCase em requests e responses.
• Datas em ISO 8601: YYYY-MM-DD para datas, YYYY-MM-DDTHH:mm:ssZ (UTC) para timestamps.
• Documentos (CPF/CNPJ) e telefones sempre somente dígitos, sem pontuação ou máscara.
• Campos aditivos: novos campos podem ser adicionados às responses sem mudança de versão.
  O cliente não deve falhar ao receber um campo desconhecido.
• Enums: valores são um conjunto fechado e documentado. Um valor não reconhecido deve ser
  tratado defensivamente (log + fallback), nunca causar exceção fatal no parceiro.

Formato padrão de erro

Toda resposta de erro mapeada segue a mesma estrutura:

{
  "code": "PLAN_NOT_AVAILABLE",
  "message": "Plan 3f6a1e2b-1234-4d56-8abc-9876543210ff is not available for this lead",
  "details": []
}

5. Visão geral do fluxo

1. POST /pre-profile-analysis                             → preProfileAnalysisId
   GET  /pre-profile-analysis?cpf=|creId=                 → resultado (200) ou processando (202)
2. POST /leads                                            → idApplication + decision
3. GET  /leads/{idApplication}/plans                      → planos disponíveis
   POST /leads/{idApplication}/plans/{planId}/selection
4. POST /leads/{idApplication}/anti-fraud                 → 202 (assíncrono)
   GET  /leads/{idApplication}/anti-fraud/biometry
   GET  /leads/{idApplication}/anti-fraud/court
5a. POST   /contract-responsible                          → cadastra/reaproveita por cnpj (id)
    GET    /contract-responsible?cnpj={cnpj}              → lista os já cadastrados pro cnpj
    DELETE /contract-responsible/{id}                     → inativa (some da lista, opcional)
5b. POST /leads/{idApplication}/contract                   → vincula responsável (id de 5a) + termos
6.  POST /leads/{idApplication}/signature-form             → dispara a assinatura (Make/Clicksign)
    GET  /leads/{idApplication}/signature-form             → status por signatário
7. (acompanhamento também por webhook contract.signature.finished)

Regras de ordem:

• O idApplication retornado no passo 2 é o identificador do lead e é usado em todos os
  endpoints subsequentes.
• O passo 4 (antifraude) exige que um plano já tenha sido selecionado no passo 3.
• O passo 5a não depende de nenhum lead existir. É por CNPJ da imobiliária — pode ser
  chamado antes, durante ou depois de qualquer lead. Faça uma vez por profissional e reuse o
  id retornado em todos os leads dessa imobiliária.
• O passo 5b grava responsável + termos. Ele não dispara a assinatura — isso é o passo 6,
  um endpoint próprio (seção 7). Fechar o contrato e enviar para assinatura são duas chamadas
  distintas, de propósito.
• A inativação em 5a é opcional e fora do fluxo de originação: serve para tirar da lista um
  profissional que não deve mais assinar contratos daquela imobiliária (6.12).