> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.credicarro.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrar um financiamento

> Todas as chamadas de um financiamento, do token à proposta finalizada, com exemplos prontos

Este guia leva uma proposta de **financiamento** do começo ao fim no staging. Cada passo traz a requisição e a resposta.

> [!NOTE]
>
> Antes de começar, tenha as credenciais de staging e um `cnpjLoja` vinculado ao seu cadastro. Veja [Ambiente de testes](https://documentacao.credicarro.com.br/pages/development.md). Os valores dos exemplos são ilustrativos.

## Visão geral

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant I as Seu sistema
    participant C as Credicarro
    participant P as Cliente
    I->>C: POST /v1/authentication/accesstoken
    I->>C: POST /v1/webhook (uma vez)
    I->>C: POST /v1/customer/unified
    I->>C: GET /v2/proposal/simulation/range/financing
    I->>C: POST /v2/proposal/simulation/financing
    I->>C: POST /v2/proposal
    C-->>I: Webhook (status e etapas)
    I->>C: POST /v2/proposal/{id}/document
    I->>C: POST /v2/proposal/{id}/vehicle-detail
    P->>C: Biometria pelo link recebido
    C-->>I: Webhook (FINALIZADA)
```

Nos exemplos, `$BASE` é `https://api.staging.credicarro.com.br/integration` e `$TOKEN` é o token de acesso.

***

**1. Gere o token**

```bash theme={null}
curl -X POST $BASE/v1/authentication/accesstoken \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "<client-id>", "clientSecret": "<client-secret>" }'
```

Guarde `token_de_acesso` e reaproveite até perto de `expira_em`. Veja [Autenticação](https://documentacao.credicarro.com.br/pages/authentication.md).

**2. Cadastre o webhook de proposta (uma vez)**

```bash theme={null}
curl -X POST $BASE/v1/webhook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 3,
    "url": "https://parceiro.com.br/webhooks/credicarro",
    "tipo_autenticacao": 3,
    "credencial": "<token-que-seu-endpoint-espera>"
  }'
```

```json Resposta (201) theme={null}
{
  "id_webhook": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "segredo_assinatura": "<segredo-de-assinatura>"
}
```

> [!WARNING]
>
> O `segredo_assinatura` só aparece nesta resposta. Guarde-o para validar as notificações.

**3. Cadastre o cliente com dados completos**

A proposta só é aceita com dados pessoais, endereço, ocupação e renda. O endpoint unificado envia tudo de uma vez. Sem `Idempotency-Key`, chamar de novo com o mesmo CPF atualiza o cadastro.

```bash theme={null}
curl -X POST $BASE/v1/customer/unified \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678909",
    "nome": "Maria",
    "sobrenome": "Souza",
    "email": "maria.souza@exemplo.com.br",
    "celular": "+55 (11) 99876-5432",
    "dataDeNascimento": "1990-05-20T00:00:00-03:00",
    "endereco": {
      "rua": "Av. Paulista",
      "numero": "1578",
      "complemento": "Bloco B, Apto 1203",
      "bairro": "Bela Vista",
      "cidade": "São Paulo",
      "estado": "SP",
      "cep": "01311000"
    },
    "dadosProfissionais": { "tipoOcupacao": 3, "renda": 6500.00 }
  }'
```

```json Resposta (200) theme={null}
{ "id_cliente": "123e4567-e89b-12d3-a456-426614174000" }
```

**4. Consulte a entrada mínima (opcional)**

```bash theme={null}
curl "$BASE/v2/proposal/simulation/range/financing?placa=ABC1D23&cnpjLoja=11222333000181" \
  -H "Authorization: Bearer $TOKEN"
```

```json Resposta (200) theme={null}
{
  "opcoes_por_prazo": [
    { "prazo": 24, "valor_minimo_entrada": 4500.00 },
    { "prazo": 36, "valor_minimo_entrada": 5000.00 },
    { "prazo": 48, "valor_minimo_entrada": 6750.00 }
  ]
}
```

Use a resposta para orientar o valor de entrada antes de simular.

**5. Simule**

```bash theme={null}
curl -X POST $BASE/v2/proposal/simulation/financing \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "cpf": "12345678909",
    "placa": "ABC1D23",
    "valorVeiculo": 45000,
    "valorEntrada": 5000,
    "uf": "SP",
    "isVeiculoZeroKm": false,
    "cnpjLoja": "11.222.333/0001-81"
  }'
```

```json Resposta (201) theme={null}
{
  "simulacoes": [
    {
      "id_simulacao": "123e4567-e89b-12d3-a456-426614174000",
      "valor_solicitado": 40000,
      "prazo": 36,
      "valor_parcela": 2042.42,
      "valor_tac": 1500,
      "valor_boleto": 3.5,
      "valor_seguro": 0,
      "valor_iof": 872,
      "percentual_iof": 1.92,
      "valor_credito_total": 42722,
      "valor_divida_total": 73527.12,
      "percentual_cet_mensal": 3.75,
      "percentual_cet_anual": 55.52,
      "percentual_juros_mensal": 3.29,
      "percentual_juros_anual": 47.47
    }
  ]
}
```

A resposta traz **uma simulação para cada prazo elegível**. Mostre as opções ao cliente e guarde o `id_simulacao` escolhido. Veja [Simulação](https://documentacao.credicarro.com.br/pages/v2/simulation/reference.md).

**6. Crie a proposta**

```bash theme={null}
curl -X POST $BASE/v2/proposal \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "cpf": "12345678909", "simulacaoId": "123e4567-e89b-12d3-a456-426614174000" }'
```

```json Resposta (201) theme={null}
{ "id_proposta": "bea8d060-f93d-48eb-b6c4-45f64483cdd9" }
```

Guarde o `id_proposta`. A partir daqui, a proposta avança pelas etapas.

**7. Acompanhe pelo webhook**

A cada mudança, a Credicarro envia o [webhook de proposta](https://documentacao.credicarro.com.br/pages/v2/webhooks.md) com o retrato da proposta. Para cada participante (`comprador` e `loja`), olhe o `status_ativo`:

| `responsavel_acao` | O que fazer |
| - | - |
| `INTEGRADOR` | Chame o endpoint da `etapa` (tabela abaixo). |
| `CLIENTE` | Oriente o cliente. Na `ANALISE_BIOMETRIA`, o cliente usa o link recebido da Credicarro — ou o `link_biometria` da [consulta da proposta](https://documentacao.credicarro.com.br/pages/v2/proposal/get.md), se a sua integração conduz o contato. |
| `CREDICARRO` | Aguarde. |
| `NENHUM` | A proposta foi encerrada. |

| `etapa` | Endpoint |
| - | - |
| `ENVIO_DOCUMENTOS` / `CORRECAO_DOCUMENTOS` | [`POST /v2/proposal/{id}/document`](https://documentacao.credicarro.com.br/pages/v2/proposal/document) |
| `DADOS_VEICULO` | [`POST /v2/proposal/{id}/vehicle-detail`](https://documentacao.credicarro.com.br/pages/v2/proposal/vehicle-detail) |

**8. Envie os documentos**

Um documento por chamada, em Base64, com `Idempotency-Key` obrigatória.

```bash theme={null}
curl -X POST $BASE/v2/proposal/bea8d060-f93d-48eb-b6c4-45f64483cdd9/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: doc-bea8d060-comprador-cnh-1" \
  -d '{
    "participante": "COMPRADOR",
    "tipoDocumento": 1,
    "nomeArquivo": "cnh-comprador.pdf",
    "conteudoBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoK..."
  }'
```

Veja o [guia de envio de documentos](https://documentacao.credicarro.com.br/pages/guides/document-upload.md) para tipos, limites e correção.

**9. Informe os dados do veículo**

Quando a etapa ativa da **loja** for `DADOS_VEICULO`:

```bash theme={null}
curl -X POST $BASE/v2/proposal/bea8d060-f93d-48eb-b6c4-45f64483cdd9/vehicle-detail \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "renavam": "12345678900",
    "chassi": "9BWZZZ377VT004251",
    "placa": "ABC1D23",
    "cor": "PRATA"
  }'
```

Resposta: `204 No Content`.

**10. Aguarde a biometria e o pagamento**

O cliente faz a biometria pelo link que a Credicarro envia por WhatsApp e e-mail na aprovação (ou pelo `link_biometria`, se a sua integração conduz o contato com o cliente). Depois, a Credicarro conclui o contrato e paga a loja. A proposta chega a `FINALIZADA` e o `responsavel_acao` passa a `NENHUM`.

***

## Erros comuns neste fluxo

| `tipo` | Passo | Como resolver |
| - | - | - |
| `Customer.Account.NotFound` | Simulação | Cadastre o cliente antes de simular. |
| `Store.Integration.NotFound` | Faixa ou simulação | Confira o `cnpjLoja` e o vínculo da loja com o seu cadastro. |
| `Store.Integration.Intermediation` | Faixa ou simulação | Use outra loja ou fale com o time Credicarro. |
| `Customer.Account.Incomplete` | Proposta | Complete endereço, ocupação e renda em `/v1/customer/unified`. |
| `Proposal.DownPaymentInvalid` | Simulação | Nenhum prazo aceita a entrada informada. Consulte a faixa financiável. |
| `Proposal.RequestAmountInvalid` | Simulação | A entrada deixa menos de 10% do valor do veículo para financiar. |
| `Proposal.InvalidStatus` | Dados do veículo | Envie só quando a etapa ativa da loja for `DADOS_VEICULO`. |

> **[Todos os códigos](https://documentacao.credicarro.com.br/pages/errors.md)**
>
> Veja o formato de erro e a lista completa de códigos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.