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` (agrupada) ou `POST /{id}/documentos-dataprev` (diferida)
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`

Duas variantes de entrega dos documentos

A assinatura externa tem duas variantes, definidas pela Socinal no cadastro do parceiro pela configuração entrega_docs_dataprev_diferida:

Variante	`entrega_docs_dataprev_diferida`	Ordem dos passos	Pacote assinado (CCB + selfie + frente/verso)
Agrupada (padrão)	`false`	devolver o pacote → averbar → desembolsar	vai inteiro em `POST /{id}/documentos`, antes da averbação
Diferida	`true`	averbar → desembolsar → devolver o pacote	entregue no final, em `POST /{id}/documentos-dataprev`

Averbar não exige documento. Na variante diferida você averba logo depois de emitir a CCB, com o empréstimo ainda em em_assinatura — sem enviar arquivo nenhum, nem a CCB assinada. É o que permite averbar em segundos enquanto o seu provedor de KYC/assinatura ainda processa o pacote.

Na variante diferida, a averbação abre uma necessidade de envio de docs Dataprev (docs_dataprev_status=aguardando) com prazo de 5 dias — o envio dos documentos (CCB e demais) é uma obrigação posterior à contratação, não uma condição para averbar. O parceiro entrega o pacote a qualquer momento a partir da averbação (não precisa esperar o desembolso) e a Socinal encaminha tudo ao Dataprev.

Essa pendência é uma dimensão de estado separada do ciclo de vida da CCB: no GET /{id} ela aparece no bloco entrega_docs_dataprev, e é entrega_docs_dataprev.proxima_acao que vale entregar_documentos_dataprev enquanto a necessidade estiver aberta (aguardar_averbacao antes de a averbação concluir). O proxima_acao da raiz continua descrevendo só a CCB — em averbada com documentos pendentes ele segue desembolsar. Ver Ciclo de vida → Duas dimensões de estado.

Passos — variante agrupada (padrão)

Emita o empréstimo

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

Assine a CCB

A CCB assinada enviada no próximo passo pode ser a do próprio parceiro (documento que você emite no seu ambiente) ou o modelo gerado pela Socinal. Usar o nosso modelo é opcional — se quiser, baixe-o (escopo documentos:read):


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

Assine no seu ambiente e colete a 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.

Responde 202 (o processamento derivado corre em segundo plano):


{ "emprestimo_id": "emp_77aa...", "status": "aguardando_averbacao",
  "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 — responde 202 com o empréstimo em desembolso_agendado; a liquidação do PIX é confirmada pelo webhook desembolso.liquidado. A Socinal encaminha os documentos ao Dataprev automaticamente após o desembolso.

Passos — variante diferida

Disponível apenas para parceiros com entrega_docs_dataprev_diferida=true. Nessa variante o passo POST /{id}/documentos é opcional — serve só para quem quiser adiantar a CCB assinada. Nada impede averbar antes dele.

Emita o empréstimo

POST /v1/emprestimos → nasce em_assinatura. Colete a assinatura no seu ambiente em paralelo — a CCB pode ser a do próprio parceiro ou o modelo da Socinal (GET /{id}/ccb, opcional). O passo seguinte não espera por ela.

Inicie a averbação

POST /v1/emprestimos/{id}/averbacao — escopo emprestimos:write, com Idempotency-Key, corpo vazio. Sem documento nenhum: chame com o empréstimo ainda em em_assinatura. A Socinal revalida a margem, averba de forma assíncrona (202) e, ao concluir, abre a necessidade de envio dos documentos (aguardando, prazo de 5 dias) e dispara o webhook docs_dataprev.pendente.


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

Desembolse

Com averbada, chame POST /v1/emprestimos/{id}/desembolso. Diferente da variante agrupada, o encaminhamento ao Dataprev não acontece aqui — ele aguarda a entrega do pacote no próximo passo.

Devolva o pacote assinado

POST /v1/emprestimos/{id}/documentos-dataprev — multipart/form-data, escopo documentos:write, com Idempotency-Key. Envie ccb_assinada (PDF, ≤10MB), selfie, doc_frente e doc_verso (JPEG/PNG, ≤5MB) + o campo metadados com as evidências da assinatura (sem elas o endpoint responde 400). Se você adiantou a CCB em POST /{id}/documentos, ccb_assinada vira opcional aqui (reenviar só substitui). Pode ser chamado a partir da averbação — não exige o desembolso. A Socinal arquiva tudo, marca a necessidade como entregue, encaminha o pacote ao Dataprev de forma assíncrona (202) e dispara docs_dataprev.recebido.


{ "emprestimo_id": "emp_77aa...", "status": "desembolsada",
  "docs_dataprev_status": "entregue" }

Alternativa — envio incremental (um documento por vez). Para reduzir o tráfego por requisição, em vez do envio em lote acima você pode enviar cada arquivo separadamente em POST /v1/emprestimos/{id}/documentos/{tipo} ({tipo} = ccb_assinada, selfie, doc_frente ou doc_verso) — multipart/form-data com o campo único arquivo e Idempotency-Key por envio. Cada envio apenas acumula; quando o pacote fica completo (CCB + as 3 imagens + evidências), o encaminhamento ao Dataprev é disparado automaticamente (efeito_disparado: true) — não há passo de “finalizar”. As evidências (metadados) podem ser anexadas em qualquer um dos envios quando ainda não registradas. Consulte o que falta em GET /v1/emprestimos/{id}/documentos-pendentes:


{ "emprestimo_id": "emp_77aa...", "recebidos": ["ccb_assinada", "selfie"],
  "pendentes": ["doc_frente", "doc_verso"], "metadados_pendente": false }

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

Códigos de sucesso

Todo passo deste fluxo que dispara processamento em segundo plano responde 202 Accepted — o corpo diz o estado no momento da resposta, e o desfecho chega por webhook (ou por GET /v1/emprestimos/{id}):

Passo	Código
`POST /{id}/documentos` (registrar assinatura externa)	`202`
`POST /{id}/documentos-dataprev` (pacote diferido, em lote)	`202`
`POST /{id}/documentos/{tipo}` (envio incremental)	`202`
`POST /{id}/averbacao` e `POST /{id}/averbacao/retry`	`202`
`POST /{id}/desembolso`	`202`

Trate qualquer 2xx como sucesso. Ao integrar, compare o status por faixa (>= 200 && < 300), nunca com um valor exato.

Webhooks

Além de assinatura.concluida, averbacao.concluida/falhou e desembolso.liquidado/falhou, a variante diferida emite:

Evento	Quando
`docs_dataprev.pendente`	necessidade aberta na averbação (payload traz o `prazo`)
`docs_dataprev.recebido`	parceiro entregou o pacote em `POST /{id}/documentos-dataprev`

Na variante diferida, assinatura.concluida só dispara se você usar o passo opcional POST /{id}/documentos. Averbando direto de em_assinatura, o marco equivalente é docs_dataprev.recebido, na devolução do pacote.