1.3. Operações Assíncronas¶

Especificação — em construção

Os serviços descritos nesta área ainda não estão disponíveis.

Por que parte da API é assíncrona¶

O cálculo da operação, a análise de crédito e o registro da proposta são executados pela bancarizadora. O VeTrust orquestra essas chamadas, persiste o resultado e mantém o estado da proposta.

Isso significa que essas operações não devolvem o resultado na resposta. Elas devolvem 202 Accepted — "recebi e estou processando" — e o resultado aparece depois, de duas formas: você consulta, ou nós avisamos.

Quais operações são assíncronas¶

Operação	Resposta	Como saber o resultado
Simulação avulsa	`200` síncrono	vem no corpo da resposta
Simulação da proposta	`202`	consulta ou webhook
Análise de crédito	`202`	consulta ou webhook
Envio da proposta	`202`	consulta ou webhook
Formalização (assinatura)	—	webhook
Todo o resto (cadastros, consultas, documentos, parcelas)	`200` / `201` síncrono	vem no corpo

A simulação avulsa é síncrona de propósito. É o serviço para negociar com o cliente: você itera valor e prazo em tempo real, sem criar nada e sem esperar. Use-a para cotar, e a simulação da proposta apenas para gravar as condições acordadas.

O padrão: aceite, consulta, webhook¶

1. Aceite¶

{
  "sucesso": true,
  "dados": {
    "status": "processando",
    "consultarEm": "/credito/propostas/1001/simulacao"
  }
}

O campo consultarEm traz o caminho que devolve o estado atual. Use-o em vez de montar a URL no seu código.

2. Consulta¶

A consulta sempre responde 200, inclusive quando a operação falhou. O resultado está no corpo:

{
  "sucesso": true,
  "dados": {
    "status": { "id": 1, "nome": "Em digitação" },
    "temErro": false,
    "erros": null,
    "dadosFinanceiros": { }
  }
}

E em caso de falha:

{
  "sucesso": true,
  "dados": {
    "status": { "id": 10, "nome": "Falha na simulação" },
    "temErro": true,
    "erros": "Prazo informado é inválido para o produto.",
    "dadosFinanceiros": null
  }
}

Não trate temErro: true como erro de HTTP

A consulta responde 200 porque a consulta funcionou. O que falhou foi a operação assíncrona, e isso é dado, não erro de transporte. Se o seu cliente HTTP só olha o status code, ele vai concluir que deu tudo certo. Sempre inspecione temErro e erros.

3. Webhook¶

Assine os eventos e pare de fazer polling. Cada operação assíncrona tem um evento de conclusão e um de falha:

Operação	Evento de sucesso	Evento de falha
Simulação da proposta	`credito.simulacao.concluida`	`credito.simulacao.falhou`
Análise de crédito	`credito.analise.concluida`	— (o resultado recusado vem no mesmo evento)
Envio da proposta	`credito.proposta.registrada`	`credito.proposta.falhou`
Formalização	`credito.contrato.formalizado`	—

Ver 8.1. Visão Geral.

Se você ainda não tem webhook: como fazer polling sem se machucar¶

Aguarde pelo menos 5 segundos antes da primeira consulta. A operação depende de uma chamada externa; consultar imediatamente só gasta a sua cota.
Consulte em intervalos de 10 segundos.
Pare quando o status sair do estado de espera — ou por temErro: true.
Estabeleça um teto (sugerimos 5 minutos). Se estourar, registre e trate como pendência operacional, não como falha do cliente.
Respeite o limite de 100 requisições por minuto. Um laço de polling agressivo sobre muitas propostas consome a cota inteira e passa a receber 429.

Estados da proposta¶

Códigos numéricos correspondentes — os mesmos devolvidos no campo status:

Código	Nome	O que significa para você
`1`	Em digitação	Pode simular, alterar e avançar
`10`	Falha na simulação	Corrija os dados e chame a reabertura
`13`	Aguardando motor de crédito	Aguarde o resultado. Não envie a proposta
`16`	Retorno do motor recebido	Consulte o resultado antes de enviar
`14`	Enviando proposta	Em registro na bancarizadora
`9`	Falha na inclusão da proposta	Corrija e chame a reabertura
`5`	Aguardando assinaturas	Formalização em curso, conduzida pela bancarizadora
`6`	Finalizado	Contrato ativo. A CCB fica disponível
`7`	Cancelado	Estado terminal

A lista completa está em 2.1. Enumerações.

Quando a proposta trava¶

Uma falha de cálculo ou de registro deixa a proposta em Falha na simulação ou Falha na inclusão da proposta. Nesses estados ela não aceita nova simulação — é preciso reabri-la explicitamente:

POST /credito/propostas/{idProposta}/reabertura

A reabertura é permitida enquanto não houver CCB gerada. Depois disso, o tratamento passa a ser operacional, pela plataforma. Ver 6.12. Reabertura.

Idempotência é o que torna o retry seguro¶

Numa jornada assíncrona, timeout de rede é comum: você não sabe se a operação foi aceita ou não. A resposta certa é repetir a chamada com a mesma Idempotency-Key — a plataforma devolve o resultado da primeira execução em vez de criar uma segunda proposta ou uma segunda cobrança.

POST /credito/esteiras/12/propostas
Idempotency-Key: 8f14e45f-ea4f-4e2c-9c3e-9b1a72d0c5f1

Gere a chave antes da primeira tentativa e reutilize-a em todas as repetições daquela mesma operação. Uma chave nova em cada tentativa anula a proteção.