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 4 arquivos obrigatórios — ccb_assinada (PDF, ≤10MB), selfie, doc_frente, doc_verso (JPEG/PNG, ≤5MB) — e o campo metadados (JSON) com as evidências da assinatura. Arquiva o pacote, registra a auditoria e transiciona o empréstimo para validar_assinatura. 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.

selfiestring<binary>obrigatório

Selfie do signatário — JPEG/PNG, ≤5MB.

doc_frentestring<binary>obrigatório

Documento de identidade (frente) — JPEG/PNG, ≤5MB.

doc_versostring<binary>obrigatório

Documento de identidade (verso) — JPEG/PNG, ≤5MB.

metadadosstringobrigatório

String JSON com as evidências da assinatura coletada no seu ambiente (uma evidência por empréstimo). Campos obrigatórios: 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

201Pacote registrado; empréstimo em `validar_assinatura`.

400Header `Idempotency-Key` ausente (`IDEMPOTENCY_KEY_OBRIGATORIA`). Dados inválidos (`ERRO_VALIDACAO`).

401Token ausente ou inválido (`CREDENCIAL_INVALIDA`).

404Empréstimo inexistente (`EMPRESTIMO_NAO_ENCONTRADO`).

Request

curl -X POST 'http://localhost:3101/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": "validar_assinatura",
  "proxima_acao": "averbar"
}