Primeiros passos

📘

Contrato v1

application/vnd.creditas.v1+json

📘

Onde está cada coisa

Esta página cobre ambientes, autenticação, headers, convenções e o fluxo geral. O detalhe de cada rota está em outras páginas:

• Request e response de cada rota: Endpoints
• Assinatura do contrato: Assinatura do contrato
• Eventos e callbacks: Webhooks
• Credenciais e geração do token: Autenticação e Ambientes
• Todos os códigos de erro: Catálogo de códigos de erro
• Retry, idempotência e suporte: Boas práticas e suporte

1. Visão geral do fluxo

sequenceDiagram
    participant P as Parceiro
    participant C as API Creditas

    P->>C: POST /pre-profile-analysis
    C-->>P: 200 preProfileAnalysisId
    alt webhook
        C-->>P: evento profile_analysis.finished
    else consulta
        loop até receber 200
            P->>C: GET /pre-profile-analysis?cpf= ou ?creId=
            C-->>P: 202 (processando) ou 200 (resultado)
        end
    end
    P->>C: POST /leads (profileAnalysisId)
    C-->>P: idApplication + decision
    P->>C: GET /leads/{idApplication}/plans
    P->>C: POST .../plans/{planId}/selection
    P->>C: POST .../anti-fraud
    C-->>P: 202 (assíncrono)
    alt webhook
        C-->>P: eventos biometry.finished e court_check.finished
    else consulta
        loop até concluir
            P->>C: GET .../anti-fraud/biometry e .../anti-fraud/court
        end
    end
    P->>C: POST /contract-responsible (uma vez por CNPJ)
    P->>C: POST /leads/{idApplication}/contract
    P->>C: POST .../signature-form
    C-->>P: webhook contract.signature.finished
    opt status por signatário
        P->>C: GET .../signature-form
    end

Acompanhamento: webhook ou consulta

Para receber eventos, registre uma credencial e um webhook. Os eventos disponíveis estão no Catálogo de eventos.

Regras de ordem

idApplication (passo 2)

• Pré-requisito: lead criado.
• Efeito: identifica o lead e é usado em todos os endpoints seguintes.
• Erro comum: guardar só o preProfileAnalysisId e perder o idApplication. Persista os dois.

Antifraude (passo 4)

• Pré-requisito: plano já selecionado no passo 3.
• Efeito: 202 e processamento assíncrono. Acompanhe por biometry e court.
• Erro comum: iniciar sem plano selecionado. Retorna 422 PLAN_NOT_SELECTED.

Responsável (passo 5a)

• Pré-requisito: nenhum lead precisa existir. O cadastro é por CNPJ da imobiliária e pode ser feito antes, durante ou depois de qualquer lead.
• Efeito: faça uma vez por responsável e reuse o id em todos os leads dessa imobiliária.
• A inativação (DELETE, Inativar responsável) é opcional e fora do fluxo de originação. Serve para tirar da lista um responsável que não deve mais assinar contratos daquela imobiliária.

Fechamento do contrato (passo 5b)

• Pré-requisito: lead criado e id do responsável obtido no 5a.
• Efeito: grava responsável e termos. Não dispara a assinatura.
• Fechar o contrato (5b) e enviar para assinatura (6) são duas chamadas distintas, de propósito. Detalhes em Assinatura do contrato.

2. Ambientes

3. Autenticação

Todas as rotas de negócio exigem um parceiro 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 tem validade curta: faça cache e renove antes do vencimento, sem solicitar um token novo por requisição.

Como solicitar credenciais, em quais URLs gerar o access_token e o formato da requisição e da resposta estão em Autenticação e Ambientes.

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

🚧

401 e token expirado

Authorization ausente, malformado ou token expirado retorna 401 com corpo vazio. Gere um novo token (veja Autenticação e Ambientes) e repita a requisição. Veja os demais erros de protocolo no Catálogo de códigos de erro.

📘

Escopo por parceiro

O parceiro é identificado a partir do próprio token. Nenhum endpoint recebe partnerId no path, query ou body: os recursos retornados ou afetados são sempre restritos ao parceiro autenticado. Acessar um recurso de outro parceiro retorna 404 Not Found, não 403.

Recebi 404, mas o recurso existe. O motivo mais provável é usar as credenciais de outro parceiro. Confira o usuário de serviço usado para gerar o token antes de abrir chamado.

4. Headers obrigatórios

🚧

Atenção ao Accept

O versionamento é feito exclusivamente pelo header Accept. Accept ausente, */* ou application/json é rejeitado com 406 Not Acceptable antes de chegar ao endpoint. Não existe versionamento por path (/v1/...). Se sua primeira chamada falhar com 406, comece por aqui.

O Accept usa um media type próprio (vnd.creditas.v1+json) porque ele carrega a versão do contrato. O Content-Type descreve só o formato do body que você envia, por isso é application/json.

Sua primeira chamada

Antes de chamar, gere o access_token conforme Autenticação e Ambientes e exporte em TOKEN. O body abaixo é o do endpoint Iniciar pré-análise de perfil. Os valores são de exemplo. persons é a lista de pretendentes (não pode ser vazia), isLead: true marca o pretendente principal e realEstate identifica a imobiliária por nome e CNPJ. As regras de cada campo estão na página do endpoint.

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 '{
    "persons": [
      {
        "cpf": "52998224725",
        "fullName": "John Doe",
        "phone": "11999999999",
        "email": "[email protected]",
        "monthlyIncome": 5000.0,
        "isLead": true
      }
    ],
    "realEstate": {
      "name": "Real Estate Ltda.",
      "cnpj": "11444777000161"
    }
  }'

const res = await fetch(
  "https://stg-api.creditas.io/rentals-partner-api/pre-profile-analysis",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TOKEN}`,
      Accept: "application/vnd.creditas.v1+json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      persons: [
        {
          cpf: "52998224725",
          fullName: "John Doe",
          phone: "11999999999",
          email: "[email protected]",
          monthlyIncome: 5000.0,
          isLead: true,
        },
      ],
      realEstate: { name: "Real Estate Ltda.", cnpj: "11444777000161" },
    }),
  }
);
console.log(res.status, await res.json());

import os
import requests

res = requests.post(
    "https://stg-api.creditas.io/rentals-partner-api/pre-profile-analysis",
    headers={
        "Authorization": f"Bearer {os.environ['TOKEN']}",
        "Accept": "application/vnd.creditas.v1+json",
        "Content-Type": "application/json",
    },
    json={
        "persons": [
            {
                "cpf": "52998224725",
                "fullName": "John Doe",
                "phone": "11999999999",
                "email": "[email protected]",
                "monthlyIncome": 5000.0,
                "isLead": True,
            }
        ],
        "realEstate": {"name": "Real Estate Ltda.", "cnpj": "11444777000161"},
    },
)
print(res.status_code, res.json())

Resposta de sucesso (200 OK):

{ "preProfileAnalysisId": "rentals_pa_abc123xyz" }

O resultado da pré-análise não é síncrono. Consulte-o em GET /pre-profile-analysis por cpf ou creId (Consultar resultado da pré-análise): 200 traz o resultado e 202 indica que ainda está processando. Se enviar os dois parâmetros, creId tem precedência. Para evitar polling, assine o evento profile_analysis.finished (Webhooks). O preProfileAnalysisId da resposta acima é o profileAnalysisId enviado depois em POST /leads.

5. 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 de negócio mapeada segue a mesma estrutura:

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

Nem todo erro segue esse formato. Os erros de protocolo 401 (corpo vazio), 406 e 415 são devolvidos antes de chegar ao endpoint e não trazem code de negócio. A lista está no Catálogo de códigos de erro.

Glossário

Suporte

Dúvidas, erros inesperados e como abrir chamado: Boas práticas e suporte.