Desembolso (PIX)

Libera o valor da CCB para o trabalhador via PIX.

Endpoint

POST /v1/emprestimos/{id}/desembolso — escopo desembolso:write, com Idempotency-Key obrigatória. O corpo é vazio ({}): a conta de destino e a conta de liquidação vêm do cadastro, não da requisição.


curl -X POST https://econsignado-api.socinal.com.br/v1/emprestimos/emp_77aa.../desembolso \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Idempotency-Key: 1f0c...-desemb-1' \
  -H 'Content-Type: application/json' \
  -d '{}'


{ "enfileirado": true }

Responde 202 — a liquidação é assíncrona. Confirme pelo webhook desembolso.liquidado (ou desembolso.falhou).

Pré-requisitos

Do seu lado (parceiro)

O que	Como garantir
Empréstimo em `averbada`	Aguarde o webhook `averbacao.concluida`. Chamar antes disso dá `409`
Escopo `desembolso:write` na credencial	Peça à Socinal ao criar/ajustar a credencial
Header `Idempotency-Key`	Uma chave por tentativa de desembolso — repetir a mesma chave não duplica o PIX

Do lado da Socinal (provisionamento)

O desembolso é executado no sistema de liquidação da Socinal, e ele exige dois cadastros que não são feitos pela API pública e não dependem de nada que você envie:

O que	Quem provisiona	Quando é feito
Conta corrente da linha de crédito do parceiro cadastrada no sistema de liquidação	Socinal (operações/financeiro)	No onboarding do parceiro, uma vez por linha de crédito
CCB registrada como proposta no sistema de liquidação	Socinal (automático na emissão da CCB)	Em `POST /v1/emprestimos`; pode faltar se a emissão foi concluída em um ambiente reconfigurado depois

Se algum desses cadastros estiver faltando, a resposta é 503 OPERACAO_NAO_PROVISIONADA — e não um erro de negócio. Isso significa que a sua requisição está correta: não altere o payload nem a Idempotency-Key. Acione o suporte com o número do empréstimo e, depois da confirmação, repita a chamada com a mesma Idempotency-Key.

Erros possíveis

HTTP	`code`	Significado	O que fazer
400	`IDEMPOTENCY_KEY_OBRIGATORIA`	Faltou o header	Envie a `Idempotency-Key`
403	`ESCOPO_INSUFICIENTE`	Credencial sem `desembolso:write`	Solicite o escopo
404	`EMPRESTIMO_NAO_ENCONTRADO`	Id inexistente ou de outro parceiro	Confira o `id`
409	—	Empréstimo não está em `averbada`	Aguarde `averbacao.concluida`
422	`ERRO_NEGOCIO`	Regra do sistema de liquidação recusou este pedido (ex.: o estado da proposta não permite aprovações)	Leia a `message`; normalmente o empréstimo já foi desembolsado ou cancelado
503	`OPERACAO_NAO_PROVISIONADA`	Falta cadastro do lado da Socinal (conta corrente da linha de crédito ou proposta da CCB)	Não é erro seu: acione o suporte e repita depois com a mesma `Idempotency-Key`
502 / 503	`DATAPREV_INDISPONIVEL`	Indisponibilidade momentânea	Retry com backoff e a mesma `Idempotency-Key`

O details.upstream do envelope de erro traz o status e o corpo devolvidos pelo sistema de liquidação (com segredos redigidos) — inclua esse trecho ao abrir um chamado.

Caminho de suporte

Para 503 OPERACAO_NAO_PROVISIONADA, abra um chamado no canal de suporte da Socinal informando:

numero_emprestimo (formato Axxxxxx-xxx) e o id do empréstimo;
data/hora da tentativa (com fuso) e a Idempotency-Key usada;
o error.code, a error.message e o details.upstream da resposta.

O provisionamento é resolvido pela Socinal; a operação não precisa ser reemitida.