--- title: 1.3. Operações Assíncronas url: https://docs.vehub.com.br/Emiss%C3%A3o%20de%20Ativos/API/Cr%C3%A9dito/1.%20In%C3%ADcio/1.3.%20Opera%C3%A7%C3%B5es%20Ass%C3%ADncronas/ --- # 1.3. Operações Assíncronas !!! warning "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](../5.%20Simulação/5.1.%20Simular.md) | **`200` síncrono** | vem no corpo da resposta | | [Simulação da proposta](../6.%20Proposta/6.2.%20Simulação%20da%20Proposta.md) | `202` | consulta ou webhook | | [Análise de crédito](../6.%20Proposta/6.7.%20Análise%20de%20Crédito.md) | `202` | consulta ou webhook | | [Envio da proposta](../6.%20Proposta/6.8.%20Envio%20da%20Proposta.md) | `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 ```json { "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: ```json { "sucesso": true, "dados": { "status": { "id": 1, "nome": "Em digitação" }, "temErro": false, "erros": null, "dadosFinanceiros": { } } } ``` E em caso de falha: ```json { "sucesso": true, "dados": { "status": { "id": 10, "nome": "Falha na simulação" }, "temErro": true, "erros": "Prazo informado é inválido para o produto.", "dadosFinanceiros": null } } ``` !!! danger "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](../8.%20Notificações%20-%20WebHook/8.1.%20Visão%20Geral.md). --- ## Se você ainda não tem webhook: como fazer *polling* sem se machucar 1. Aguarde **pelo menos 5 segundos** antes da primeira consulta. A operação depende de uma chamada externa; consultar imediatamente só gasta a sua cota. 2. Consulte em intervalos de **10 segundos**. 3. Pare quando o `status` sair do estado de espera — ou por `temErro: true`. 4. Estabeleça um **teto** (sugerimos 5 minutos). Se estourar, registre e trate como pendência operacional, não como falha do cliente. 5. 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 ```mermaid stateDiagram-v2 [*] --> EmDigitacao: criar proposta EmDigitacao --> EmDigitacao: simular EmDigitacao --> FalhaNaSimulacao: erro no cálculo FalhaNaSimulacao --> EmDigitacao: reabertura EmDigitacao --> AguardandoMotorCredito: submeter à análise AguardandoMotorCredito --> RetornoMotorRecebido: resultado da análise RetornoMotorRecebido --> EnviandoProposta: envio (só se aprovada) EmDigitacao --> EnviandoProposta: envio (esteira sem análise) EnviandoProposta --> AguardandoAssinaturas: registrada na bancarizadora EnviandoProposta --> FalhaNaInclusao: erro no registro FalhaNaInclusao --> EmDigitacao: reabertura AguardandoAssinaturas --> Finalizado: formalização concluída AguardandoAssinaturas --> Cancelado: cancelamento EmDigitacao --> Cancelado: cancelar proposta Finalizado --> [*] Cancelado --> [*] ``` 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](../2.%20Enumerações/2.1.%20Enumerações.md). --- ## 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](../6.%20Proposta/6.12.%20Reabertura.md). --- ## 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. ```http 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.