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} e na listagem) sugere o que fazer em seguida.

Emissão em andamento (status: emitindo)

POST /v1/emprestimos responde 201 no caminho normal: a CCB já nasce em_assinatura, com o número definitivo. Esse é o caso da esmagadora maioria das emissões e nada muda para quem já integra.

Quando o sistema de liquidação da Socinal não confirma a proposta dentro da requisição (timeout, indisponibilidade momentânea), a resposta é 202 Accepted:

{
  "emprestimo_id": "6f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b",
  "status": "emitindo",
  "proxima_acao": "aguardar_emissao"
}

O que isso significa, na prática:

• O empréstimo existe e é endereçável por emprestimo_id — não é erro e não há nada a corrigir no seu pedido;
• não reemita. Repetir a chamada com a mesma Idempotency-Key devolve esta mesma resposta (202); uma chave nova arriscaria uma segunda operação para o mesmo trabalhador;
• o desfecho chega por webhook — emprestimo.emitido (a CCB vai para em_assinatura, com o número definitivo) ou emprestimo.emissao_falhou (o empréstimo é cancelado e aí sim você emite de novo, com uma chave nova);
• a qualquer momento, GET /v1/emprestimos/{id} mostra o estado atual. Enquanto durar, status: emitindo e proxima_acao: aguardar_emissao.

Duas dimensões de estado

status e proxima_acao descrevem apenas o ciclo de vida da CCB — da emissão à liquidação. A pendência de entrega de documentos ao Dataprev é uma dimensão independente e vive em um bloco próprio:

{
  "status": "averbada",
  "proxima_acao": "desembolsar",
  "docs_dataprev_status": "aguardando",
  "docs_dataprev_prazo": "2026-06-08T00:31:12.500Z",
  "entrega_docs_dataprev": {
    "status": "aguardando",
    "prazo": "2026-06-08T00:31:12.500Z",
    "proxima_acao": "entregar_documentos_dataprev"
  }
}

Regras do contrato:

• Uma pendência de documentos nunca suprime uma ação pendente da CCB. Em averbada com documentos pendentes, proxima_acao continua desembolsar.
• entrega_docs_dataprev é null quando não existe essa dimensão — ou seja, em tudo que não é assinatura externa com entrega diferida (entrega_docs_dataprev_diferida), e também nela enquanto a averbação ainda não abriu a necessidade. Trate null como “não se aplica”, não como “entregue”.
• docs_dataprev_status e docs_dataprev_prazo continuam na raiz da resposta, com os mesmos valores do bloco, por compatibilidade com integrações existentes.

Matriz completa: status → proxima_acao, por modalidade

Esta é a tabela autoritativa da 1ª dimensão (ciclo de vida da CCB). As três modalidades são configurações do parceiro, não escolhas por requisição: Socinal (D4Sign) (assinatura_socinal=true), externa agrupada (assinatura_socinal=false) e externa diferida (assinatura_socinal=false + entrega_docs_dataprev_diferida=true).

O vocabulário de proxima_acao é fechado — são exatamente estes sete valores (mais null): aguardar_emissao, enviar_assinatura, registrar_assinatura, iniciar_averbacao, aguardar_validacao, desembolsar, aguardar_desembolso. Os aguardar_* significam “nada a fazer do seu lado”; os demais correspondem a uma chamada sua. Se aparecer um valor que você não conhece, trate como “aguardar/consultar” em vez de falhar.

Matriz da 2ª dimensão: entrega_docs_dataprev

Só a modalidade externa diferida tem as duas dimensões ao mesmo tempo — nas outras duas o bloco é sempre null:

aguardar_averbacao no bloco de documentos significa: a necessidade já está aberta, mas a entrega só é aceita depois de a averbação concluir — antes dela o envio responde 409.

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 responde CONSULTA_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. Na variante de entrega diferida desse fluxo, averbar não exige documento algum: pode ser chamada com o empréstimo ainda em em_assinatura, e o pacote assinado é devolvido depois do desembolso.

Síncrono vs. assíncrono

Algumas etapas concluem na hora; outras rodam em segundo plano e respondem 202 Accepted:

• Assíncronas (202): envio para assinatura, os três envios de documentos (POST /{id}/documentos, POST /{id}/documentos-dataprev, POST /{id}/documentos/{tipo}), averbação (e o retry) e desembolso. O resultado chega por webhook (recomendado) ou por consulta ao recurso.
• Síncronas (200/201): consulta de margem, simulação, emissão do empréstimo (201; 202 só quando fica emitindo) e cancelamento da CCB (200, é a resposta do próprio consignante).

Veja Webhooks para reagir aos eventos assíncronos sem ficar consultando em loop.