Documentação B2B
  1. Erros de integração

Erros criação da proposta

Abaixo listamos os possíveis erros retornados ao enviar uma proposta de solicitação de empréstimo.

🚧

Recomendação importante

Para que a integração tenha qualidade e seja possível obter resultados positivos com sua operação, é muito importante ter atenção as dicas descritas ao decorrer deste documento.


Confira abaixo os principais códigos de retorno para mapear na integração:

Code statusCodeMessageDescrição
400REQUEST_VALIDATION_ERRORSome fields are invalidIndica que existem erros em um ou mais campos da sua solicitação. Confira o detalhamento dos principais motivos de erros 400


Lead já existente (DUPLICITY)

A criação da proposta não retorna erro de lead duplicado. O lead é validado durante o processamento e, quando já existe um lead ativo para o mesmo cliente, a proposta é recusada com rejectionReason: DUPLICITY no step PROPOSAL_CREATED. Esse motivo aparece na consulta de status da proposta.

Casos em que isso ocorre:

  • Existência de outro lead ativo na esteira (usando o mesmo CPF ou e-mail).
  • Inconsistência de dados cadastrais (e-mail ou CPF) de tentativas anteriores e da atual.

Para minimizar esse caso, verifique a elegibilidade antes de criar a proposta: Auto ou Home.


Principais erros na Criação da Proposta

Ao enviar uma solicitação de empréstimo precisamos que os campos sejam preenchidos corretamente e com valores válidos, caso contrário a solicitação não será concluída com sucesso.

Para garantir que isso não ocorra a dica é garantir que os campos na sua experiência tenham as devidas validações durante o preenchimento do cliente, reduzindo assim um possível erro 400.

Principais erros identificados:

  • Campos sem a devida validação
  • Falta de monitoramento na integração, importante observar os retornos e o detalhe dos erros

Confira alguns exemplos e dicas para garantir a validação de erros 400


Descrição do erroMensagem de erro API / Envio incorretoFormato correto / Como corrigir
  • *Data de aniversário** com formato inválido
  • *must be a valid date, pattern example: yyyy-MM-dd** ⚠️
01-08-89		O campo data deve seguir o formato YYYY-MM-DD
  • *Ano de fabricação** incompatível com o ano do modelo
  • *must be equal or at most 1 year later than modelYear** ⚠️
modelYear:"2010"
manufacturingYear:"2020"

O campo ANO DE FABRICAÇÃO (manufacturingYear) deve ser igual ao ANO MODELO (modelYear) ou, no máximo, 1 ano posterior.

Os campos devem estar de acordo com as informações do veículo

  • *Placa do veículo** com valor inválido
  • *Invalid license plate format** ⚠️
licensePlate: "1234HAJ"

Recomendamos que seja feita uma validação para garantir o correto preenchimento seguindo padrões de placas brasileiras.
Placas antigas (antes de 2019) tinham o formato com 3 letras seguidas por 4 números (ex: XXX9999). Já as placas novas tem o padrão de 4 letras e 3 números.

Exemplo de validação utilizando expressão regular para validar os formatos.

  • *Placa do veículo** com quantidade de caracter inválido ou campo vazio
  • *Invalid license plate format** ⚠️
licensePlate: ""		O campo placa deve conter entre 7 ou 8 dígitos, não deve ser enviado vazio.
  • *Dados de Bacen** faltando no header
  • *Missing headers (X-User-Ip, X-User-Agent, X-Bacen-Authorized-At)** ⚠️
Informações não sendo enviadas no header		As informações de header e temos devem seguir as recomendações de autorização bacen
  • *Dados de Bacen** com formato inválido
  • *Invalid X-Bacen-Authorized-At header, please send date in format (ISO): YYYY-MM-DDTHH:mm:sssZ. Example: 2021-01-22T09:00** ⚠️
Informações enviadas incorretamente, exemplos:
  • Data com formato inválido
  • IP inválido
  • Texto de consentimento com informação correta

Formato correto da data deve ser ISO

2021-01-22T09:00

CEP com formato inválido ou vazio
  • *must be a valid postal code, pattern example: 04571010** ⚠️
postalCode: "5947000"
postalCode: ""		O campo CEP deve conter 8 números.
Nome com valor inválido
  • *must be a valid full name** ⚠️
fullName: "Nome de Teste 32"		O campo nome deve conter apenas letras.
E-mail inválido
  • *Invalid email** ⚠️
email: "email@email"		O campo email deve conter o domínio completo e seu um e-mail válido.
Telefone inválido
  • *must be a valid cellphone, pattern example: 988888888** ⚠️
O campo telefone deve seguir o formato 988888888, contendo 9 dígitos no total
DDD inválido
  • *must be a valid DDD, pattern example: 11** ⚠️
cellphoneCode: "011"
O campo cellphoneCode deve conter apenas 2 dígitos (ex.: 11).
Valor fora das opções aceitas (ex.: estado civil, tipo de imóvel)
  • *must be one of [...]** ⚠️
maritalStatus: "CASADO"
Envie um dos valores listados na própria mensagem de erro e na documentação do campo (ex.: MARRIED).
Proprietários do imóvel com valor inválido (Home)
  • *must be one of [BORROWER, SPOUSE, OTHER]** ⚠️
owners: ["FAMILIA"]
O campo owners deve conter ao menos um item entre BORROWER, SPOUSE e OTHER.
Dados profissionais do cônjuge ausentes quando ele é co-signatário (Home)
  • *must not be null when borrower.spouse.isCosigner is true** ⚠️
spouse.isCosigner: true sem spouse.professionalInfo
Informe os dados profissionais (professionalInfo) do cônjuge quando isCosigner for true.

Temos um processo de monitoramento para garantir a qualidade das integrações e os resultados do negócio e um processo importante dele é o processo de homologação da sua integração. No processo conferimos o formato de envio de cada campo porém, ao subir sua integração para um ambiente de produção, se não garantir as validações na sua experiência do cliente, o volume e tipos diferentes de usuários pode preencher indevidamente os campos e com isso é possível que nosso time técnico identifique erros e seja obrigatória a correção para manter o funcionamento.


👍

Sucesso na integração

Todos os erros mencionados podem ser tratados antecipadamente ao envio, o ponto importante é implementar validação em cada campo, utilizar o recurso de máscara e mensagens de instruções para que dessa forma o cliente possa ter maior assertividade no preenchimento dos campos e com uma conclusão mais positiva.

Updated 5 days ago