Enviar Documentos

Utilize este endpoint para anexar os documentos comprobatórios necessários para a formalização da proposta de crédito.

⚠️

Envio individual por requisição

A API processa apenas um arquivo por requisição. Para enviar múltiplos documentos, realize uma chamada separada para cada arquivo.

Esta etapa é assíncrona: o endpoint recebe o arquivo, mas a validação do conteúdo (análise do documento) ocorre posteriormente pelo time interno da Creditas.

Pré-requisitos

Antes de iniciar o upload, certifique-se de que:

• A proposta possui um proposalId válido. Consulte a página Criar Proposta para detalhes sobre como criar uma proposta e obter o proposalId.
• O step atual da proposta é DOCUMENTS. Você pode verificar isso através do endpoint GET /proposals/{proposalId}/status.

Como identificar o step DOCUMENTS

O endpoint de status retorna a lista de steps percorridos pela proposta. A proposta está pronta para receber documentos quando o step DOCUMENTS estiver presente e ainda não possuir o campo finishedAt — ou seja, está iniciado mas não finalizado:

{
    "steps": [
        {
            "startedAt": "2026-04-14T21:20:20.989504",
            "finishedAt": "2026-04-14T21:20:23.512201",
            "name": "PROPOSAL_CREATED"
        },
        {
            "startedAt": "2026-04-14T21:20:23.553983",
            "finishedAt": "2026-04-14T21:20:25.471039",
            "name": "PRE_QUALIFICATION"
        },
        {
            "startedAt": "2026-04-14T21:20:25.499506",
            "finishedAt": "2026-04-14T21:20:35.771152",
            "name": "PROCESSING"
        },
        {
            "startedAt": "2026-04-14T21:20:35.798774",
            "finishedAt": "2026-04-14T21:20:58.309348",
            "name": "LOAN_PROPOSAL_ANALYSIS"
        },
        {
            "startedAt": "2026-04-14T21:20:58.292334",
            "name": "DOCUMENTS"
        }
    ]
}

✅

No exemplo acima, o step DOCUMENTS está em andamento (possui startedAt mas não finishedAt), indicando que a proposta está pronta para o envio de documentos.

O não cumprimento destas regras resultará em erro 400 Bad Request ou 409 Conflict.

Regras de envio

Tipos de documento (group)

Utilize os valores da coluna Enum no parâmetro group da sua requisição.

📘

Nota de UX: Instrua seu usuário final a tirar fotos em locais iluminados, sem flash e garantindo que todas as bordas do documento estejam visíveis. Isso reduz a taxa de rejeição do documento enviado.

Titularidade do documento (subject)

O parâmetro subject é opcional e indica a qual titular da proposta o documento pertence. Quando não informado, o valor padrão é BORROWER.

Endpoint

Exemplo de URL (staging):

https://stg-api.creditas.io/b2b/proposals/{proposalId}/documents

Exemplo de URL (production):

https://api.creditas.io/b2b/proposals/{proposalId}/documents

Headers

🔑

Para detalhes sobre como obter o token JWT, consulte a página Autenticação e Ambientes.

Parâmetros da requisição

Exemplo de requisição

curl --location --request POST '{{url_base}}/proposals/B2B-68A9769C-1DFB-47B5-BBC2-A25DB0C2D0D0/documents' \
  --header 'Authorization: Bearer {{your_access_token}}' \
  --form 'file=@"/caminho/para/seu_arquivo.pdf"' \
  --form 'group="PROOF_RESIDENCE"' \
  --form 'subject="BORROWER"'

Resposta de sucesso — 201 Created

{
  "id": "B2B-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

ℹ️

O campo id retornado identifica o documento registrado na proposta. Guarde esse valor caso necessite referenciar o documento futuramente.

Envio de múltiplos documentos

Como a API registra um documento por vez, para enviar todos os documentos necessários repita a chamada individualmente para cada arquivo:

# 1. Comprovante de renda
curl --request POST '{{url_base}}/proposals/{proposalId}/documents' \
  --header 'Authorization: Bearer {{your_access_token}}' \
  --form 'file=@"/documentos/comprovante_renda.pdf"' \
  --form 'group="INCOME_STATEMENT"'

# 2. Comprovante de residência
curl --request POST '{{url_base}}/proposals/{proposalId}/documents' \
  --header 'Authorization: Bearer {{your_access_token}}' \
  --form 'file=@"/documentos/comprovante_residencia.pdf"' \
  --form 'group="PROOF_RESIDENCE"'

# 3. Documento de identidade
curl --request POST '{{url_base}}/proposals/{proposalId}/documents' \
  --header 'Authorization: Bearer {{your_access_token}}' \
  --form 'file=@"/documentos/rg_frente.jpg"' \
  --form 'group="PROOF_IDENTITY"'

Respostas de erro