Assinatura externa (gerenciada pelo parceiro)

Por padrão, a Socinal coleta a assinatura via D4Sign. Mas um parceiro habilitado pode assinar a CCB no próprio ambiente e devolver o pacote assinado pela API.

A escolha do fluxo não é por requisição — é uma configuração do parceiro (assinatura_socinal=false), definida pela Socinal no seu cadastro. Sem ela, POST /{id}/documentos retorna 403.

Como difere do fluxo padrão

Aspecto	Socinal (D4Sign)	Externa (parceiro)
Entrada da assinatura	`POST /{id}/assinatura`	`POST /{id}/documentos`
Validação	operador Socinal valida	confiada ao parceiro (auditada)
Disparo da averbação	automático	explícito (`POST /{id}/averbacao`)
Escopos	`emprestimos:write`	`documentos:write` + `emprestimos:write`

Passos

Emita o empréstimo

POST /v1/emprestimos → nasce em_assinatura, sem disparo do D4Sign.

Baixe a CCB


curl https://api.socinal.com.br/v1/emprestimos/emp_77aa.../ccb \
  -H 'Authorization: Bearer SEU_TOKEN' --output ccb.pdf

Escopo documentos:read. Assine no seu ambiente e colete CCB assinada + selfie + documento (frente e verso) + evidências.

Devolva o pacote assinado

POST /v1/emprestimos/{id}/documentos — multipart/form-data, escopo documentos:write, com Idempotency-Key. Inclui os arquivos (ccb_assinada, selfie, doc_frente, doc_verso) e um campo metadados (JSON) com signatario, tipo_assinatura, assinatura_ip, localizacao e assinado_em.


{ "emprestimo_id": "emp_77aa...", "status": "validar_assinatura",
  "proxima_acao": "iniciar_averbacao" }

Dispara o webhook assinatura.concluida. Não entra na fila de validação do operador.

Inicie a averbação

POST /v1/emprestimos/{id}/averbacao — escopo emprestimos:write, com Idempotency-Key. Revalida a margem, cria a averbação e processa de forma assíncrona (202).


{ "averbacao_id": "av_...", "status": "averbacao_iniciada" }

Aguarde e desembolse

Aguarde o webhook averbacao.concluida (ou consulte GET /v1/emprestimos/{id}/averbacao). Com averbada, chame POST /v1/emprestimos/{id}/desembolso.

Se a averbação falhar (averbacao.falhou), use POST /v1/emprestimos/{id}/averbacao/retry para reprocessar.