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 (ou refaça a simulação direto)
`13`	Aguardando motor de crédito	Aguarde o resultado. Não envie a proposta
`26`	Aprovado pelo motor	Pode enviar. Refazer a simulação aqui descarta a análise
`27`	Aprovado com alteração pelo motor	Pode enviar: o motor mudou valor ou prazo, mas autorizou. Refazer a simulação aqui descarta a análise
`28`	Reprovado pelo motor	O envio responde `409`. Se a esteira oferecer a nova análise, submeta de novo com os dados complementares; senão, crie uma nova proposta. Refazer a simulação mantém a recusa
`14`	Enviando proposta	Em registro na bancarizadora
`9`	Falha na inclusão da proposta	Corrija e chame a reabertura (ou refaça a simulação, ou reenvie direto)
`5`	Aguardando assinaturas	Formalização em curso, conduzida pela bancarizadora
`6`	Finalizado	Contrato ativo. A CCB fica disponível
`30`	Falha no pagamento	A CCB está assinada e liberada, mas a instituição financeira não conseguiu pagar o desembolso. O tratamento é operacional; a proposta volta a `6` quando a conta é corrigida
`7`	Cancelado	Estado terminal

Enquanto o motor não decide (resultado pendente ou mesa de crédito), a proposta continua em 13. O antigo 16 (Retorno do motor recebido) não é mais gravado: as propostas que estavam nele passaram para 26, 27 ou 28, conforme o resultado.

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

O que cada estado aceita¶

Cada ação só é aceita em alguns estados; nos demais a API responde 409. A tabela mostra só o portão de status: as demais condições de cada ação (análise aprovada no envio, ficha completa, documentos...) continuam valendo.

Status	Simular	Submeter à análise	Enviar	Reabrir	Cancelar
`1` Em digitação	✅	✅	✅	❌	✅
`10` Falha na simulação	✅	❌	❌	✅	❌
`9` Falha na inclusão da proposta	✅	❌	✅	✅	❌
`13` Aguardando motor de crédito	❌	✅ (repetir o pedido não reenvia)	✅ *	❌	❌
`26`, `27` e `28` Retorno do motor	✅	✅	✅	❌	❌
`14` Enviando proposta, `5` Aguardando assinaturas, `6` Finalizado, `30` Falha no pagamento, `7` Cancelado	❌	❌	❌	❌	❌

* Em esteira que exige análise de crédito, o envio com a proposta ainda aguardando o motor responde 409 pela barreira da análise — ver 6.8. Envio da Proposta.

Com a CCB emitida (numeroCcb preenchido), nenhuma dessas ações é aceita, qualquer que seja o status: simular, submeter à análise, enviar, reabrir e cancelar respondem 409, e o tratamento passa a ser operacional. Ver 6.10. Consultar, Listar e Pendências.

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 avança: a submissão à análise de crédito responde 409 e a consulta da proposta aponta a reabertura como próxima etapa. A nova simulação é aceita direto nos dois estados, e o novo envio na falha de inclusão. Para devolver a proposta à digitação:

POST /credito/propostas/{idProposta}/reabertura

A reabertura é permitida enquanto não houver CCB gerada. Depois disso — com o numeroCcb preenchido —, a reabertura, a nova simulação, o novo envio, a submissão à análise e o cancelamento respondem 409, e 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.

Como ler a resposta da repetição:

O resultado da primeira execução, com o header Idempotent-Replay: true: a operação já tinha sido executada. Use o resultado.
409 com campo igual a Idempotency-Key: a primeira chamada com esta chave ainda está em processamento. Nada foi duplicado: aguarde e repita com a mesma chave.
422 com campo igual a Idempotency-Key: a chave já foi usada nesta rota com um corpo diferente. Não repita: gere uma chave nova para a operação nova.
500 informando que a operação não foi executada: repita com a mesma chave.

Todos os desfechos, inclusive o 400 da chave com mais de 200 caracteres, estão em 1.1.7 Idempotência.