Integrar um financiamento

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

Antes de começar, tenha as credenciais de staging e um cnpjLoja vinculado ao seu cadastro. Veja Ambiente de testes. Os valores dos exemplos são ilustrativos.

Visão geral

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

Gere o token

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.

Cadastre o webhook de proposta (uma vez)

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>"
  }'

Resposta (201)

{
  "id_webhook": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "segredo_assinatura": "<segredo-de-assinatura>"
}

O segredo_assinatura só aparece nesta resposta. Guarde-o para validar as notificações.

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.

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 }
  }'

Resposta (200)

{ "id_cliente": "123e4567-e89b-12d3-a456-426614174000" }

Consulte a entrada mínima (opcional)

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

Resposta (200)

{
  "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.

Simule

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"
  }'

Resposta (201)

{
  "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.

Crie a proposta

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" }'

Resposta (201)

{ "id_proposta": "bea8d060-f93d-48eb-b6c4-45f64483cdd9" }

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

Acompanhe pelo webhook

A cada mudança, a Credicarro envia o webhook de proposta 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, 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`
`DADOS_VEICULO`	`POST /v2/proposal/{id}/vehicle-detail`

Envie os documentos

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

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 para tipos, limites e correção.

Informe os dados do veículo

Quando a etapa ativa da loja for DADOS_VEICULO:

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.

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

Veja o formato de erro e a lista completa de códigos.

Integração

Guias

Ajuda

Integrar um financiamento

Visão geral

Erros comuns neste fluxo

Todos os códigos

​Visão geral

​Erros comuns neste fluxo

Todos os códigos

Visão geral

Erros comuns neste fluxo