Registrar assinatura externa

POST/v1/emprestimos/{id}/documentos

🔒 Requer Bearer token

Escopo documentos:write. Requer header Idempotency-Key. Disponível apenas para parceiros com assinatura externa habilitada no cadastro (senão 403). multipart/form-data com a CCB assinada + evidências. Na variante **agrupada** (padrão) os 4 arquivos são obrigatórios — ccb_assinada (PDF, ≤10MB), selfie, doc_frente, doc_verso (JPEG/PNG, ≤5MB) — assim como o campo metadados (JSON) com as evidências da assinatura. Na variante **diferida** (entrega_docs_dataprev_diferida=true) este passo é **opcional**: a averbação não exige documento nenhum e o pacote assinado inteiro pode ir direto no passo final (POST /v1/emprestimos/:id/documentos-dataprev). Se quiser adiantar a CCB, envie **só** a ccb_assinada — selfie/frente/verso são ignorados aqui e metadados é **opcional**. Registra a auditoria e transiciona o empréstimo para aguardando_averbacao. Responde **202** — como todo endpoint de envio de documentos, o processamento derivado (arquivamento/encaminhamento e webhook assinatura.concluida) corre em segundo plano. A averbação é disparada separadamente via POST /v1/emprestimos/:id/averbacao.

Parâmetros

idstringpathobrigatório

Corpo da requisição

ccb_assinadastring<binary>obrigatório

CCB assinada — PDF, ≤10MB. Obrigatória nas duas variantes.

selfiestring<binary>opcional

Selfie do signatário — JPEG/PNG, ≤5MB. Obrigatória na variante agrupada; não enviar na diferida.

doc_frentestring<binary>opcional

Documento de identidade (frente) — JPEG/PNG, ≤5MB. Obrigatório na variante agrupada; não enviar na diferida.

doc_versostring<binary>opcional

Documento de identidade (verso) — JPEG/PNG, ≤5MB. Obrigatório na variante agrupada; não enviar na diferida.

metadadosstringopcional

String JSON com as evidências da assinatura coletada no seu ambiente (uma evidência por empréstimo). Obrigatório na variante agrupada; na diferida é opcional — pode ser enviado depois, junto com os documentos, em POST /v1/emprestimos/:id/documentos-dataprev. Campos obrigatórios (quando enviado): signatario — nome completo de quem assinou; tipo_assinatura — "eletronica" (aceite por clique/OTP) ou "digital" (certificado ICP-Brasil); assinatura_ip — endereço IP de onde o signatário assinou (IPv4 ou IPv6); localizacao — objeto { "lat": número, "lng": número } com a geolocalização no momento do aceite; assinado_em — data/hora do aceite em ISO 8601 (ex.: "2026-06-03T00:27:42.573Z"). Campos opcionais: hash_ccb — hash (ex.: SHA-256) do PDF assinado, para conferência de integridade; provedor — nome da plataforma de assinatura usada (ex.: "Clicksign", "DocuSign"). Enviado como texto no campo do multipart — não como objeto. JSON inválido retorna 400.

Respostas

Corpo da resposta 202

emprestimo_idstring<uuid>obrigatório

statusstringobrigatório

emitindoem_assinaturaaguardando_averbacaoaverbadadesembolso_agendadodesembolsadaem_atrasoliquidadacanceladarefinanciada

proxima_acaostringobrigatórionullable

aguardar_emissaoenviar_assinaturaregistrar_assinaturainiciar_averbacaoaguardar_validacaodesembolsaraguardar_desembolso

Request

curl -X POST 'https://econsignado-api.socinal.com.br/v1/emprestimos/:id/documentos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Idempotency-Key: 3f1c8a90-0000-4000-8000-000000000000' \
  -F 'ccb_assinada=@ccb-assinada.pdf' \
  -F 'selfie=@selfie.jpg' \
  -F 'doc_frente=@doc-frente.jpg' \
  -F 'doc_verso=@doc-verso.jpg' \
  -F 'metadados={"signatario":"João da Silva","tipo_assinatura":"eletronica","assinatura_ip":"177.0.0.1","localizacao":{"lat":-23.5505,"lng":-46.6333},"assinado_em":"2026-06-03T00:27:42.573Z","hash_ccb":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","provedor":"Clicksign"};type=application/json'

Response

{
  "emprestimo_id": "8f2a1c4e-1234-5678-9abc-def012345678",
  "status": "aguardando_averbacao",
  "proxima_acao": "iniciar_averbacao"
}