Ciclo de vida da operação
Uma operação de crédito passa por etapas bem definidas, da apuração de margem ao desembolso. Entender essa sequência é o que evita deixar entidades em estado inconsistente.
Visão geral do fluxo
Estados do empréstimo
Depois de emitido, o empréstimo caminha por uma máquina de estados. O campo
status informa onde ele está, e o hint proxima_acao (no GET /v1/emprestimos/{id}) sugere o que fazer em seguida.
| Status | Significado | Próxima ação típica |
|---|---|---|
em_assinatura | CCB emitida, aguardando assinatura | enviar_assinatura |
validar_assinatura | Assinatura recebida (fluxo externo) | iniciar_averbacao |
averbada | Margem reservada no consignante | desembolsar |
desembolso_agendado | PIX agendado no BaaS | aguardar liquidação |
desembolsada | Crédito liberado | — |
em_atraso | Parcelas em atraso | — |
cancelada | Operação cancelada / excluída | — |
Use o proxima_acao como bússola. Em vez de codificar a máquina de estados
no seu lado, consulte o empréstimo e siga o hint que a API devolve.
Por que a ordem importa
- A simulação e a emissão do empréstimo dependem de uma consulta de margem válida
(
consulta_margem_id). Sem ela, a API respondeCONSULTA_MARGEM_NAO_ENCONTRADA(422). - O desembolso só é permitido com o empréstimo
averbada— tentar antes resulta em conflito. - A averbação é disparada automaticamente quando a assinatura é via
Socinal (D4Sign), mas é explícita (
POST .../averbacao) no fluxo de assinatura externa.
Síncrono vs. assíncrono
Algumas etapas concluem na hora; outras rodam em segundo plano e respondem
202 Accepted:
- Assíncronas: envio para assinatura, averbação, desembolso. O resultado chega por webhook (recomendado) ou por consulta ao recurso.
- Síncronas: consulta de margem, simulação e emissão do empréstimo retornam o resultado imediatamente.
Veja Webhooks para reagir aos eventos assíncronos sem ficar consultando em loop.