Firma de documentos

Descripción del producto #

Permite firmar documentos digitalmente con OTP para verificación, generando hashes encriptados para integridad y no repudio. Incluye inicio de flujo (envío OTP) y validación para firmar.

Requisitos de autenticación #

• Método: HTTP Basic (concatenar client_id:client_secret, codificar en Base64).
• Header: Authorization: Basic <base64_string>.
• Nota: Las credenciales (client_id y client_secret) deben solicitarse al equipo de S.O.F.I.A. para pruebas en el entorno de sandbox. Estas serán proporcionadas una vez que el cliente esté inscrito.

Endpoints #

• Solicitud de firma: POST https://sandbox-sofiapp.bio.credit/create_signature (Sandbox).
• Firmar documento: POST https://sandbox-sofiapp.bio.credit/sign_document (Sandbox).

Headers #

Key	Value	Description
Accept	application/json	Formato de respuesta esperado.
Content-Type	application/json	Formato del body.
Authorization	Basic [Base64]	Credenciales de autenticación.

Parámetros de entrada (body) #

Para solicitud de firma: #

Key	Type	Required	Description
tenant_id	string	Sí	Identificador de la empresa.
transaction_id	string	Sí	ID único de transacción.
user_selfie	file	Sí	Selfie del usuario.
image_front	file	Sí	Frontal de ID.
image_back	file	No	Reverso de ID.
phone	string	Sí	Teléfono para OTP.
email	string	Sí	Email para OTP.
document_sign	file	Sí	Documento a firmar (e.g., PDF).

Ejemplo JSON Request (simulado):

{
  "tenant_id": "empresa-123",
  "transaction_id": "txn-987654",
  "user_selfie": "selfie.jpg",
  "image_front": "id_front.jpg",
  "image_back": "id_back.jpg",
  "phone": "+573001234567",
  "email": "user@example.com",
  "document_sign": "contract.pdf"
}
        

Para firmar documento: #

Key	Type	Required	Description
transaction_id	string	Sí	ID de transacción.
otp_code	string	Sí	Código OTP.

Ejemplo JSON Request (simulado):

{
  "transaction_id": "txn-987654",
  "otp_code": "123456"
}
        

Parámetros de salida (respuesta) #

Para solicitud de firma: #

Key	Type	Description
transaction_id	string	ID de transacción.
status	string	Estado (e.g., “PENDING_OTP”).
timestamp	string	Fecha de la transacción.
storage_paths	object	URLs de archivos almacenados.

Ejemplo JSON Response:

{
  "transaction_id": "txn-987654",
  "status": "PENDING_OTP",
  "timestamp": "2025-09-05T21:12:00Z",
  "storage_paths": {
    "user_selfie": "http://storage.example.com/selfie.jpg",
    "image_front": "http://storage.example.com/id_front.jpg",
    "image_back": "http://storage.example.com/id_back.jpg",
    "document_sign": "http://storage.example.com/contract.pdf"
  }
}
        

Para firmar documento: #

Key	Type	Description
transaction_id	string	ID de transacción.
status	string	Estado (e.g., “SIGNED”).
signed_document_url	string	URL del documento firmado.
signature_hash	string	Hash de la firma.
timestamp	string	Fecha de la transacción.
trace_log_id	string	ID de log de trazabilidad.

Ejemplo JSON Response:

{
  "transaction_id": "txn-987654",
  "status": "SIGNED",
  "signed_document_url": "http://storage.example.com/signed_contract.pdf",
  "signature_hash": "x9y8z7w6v5u4t3s2",
  "timestamp": "2025-09-05T21:14:00Z",
  "trace_log_id": "654321"
}
        

Manejo de errores #

HTTP Code	Error Code	Description
400	WHK001	OTP inválido o campos faltantes.
401	WHK002	Autenticación fallida.
404	WHK004	Transacción no encontrada.

Notas adicionales #

• Almacena archivos en bucket (nube) y logs en transaction_log (service_type: ‘signature_create’ o ‘signature_sign’).
• Cumple con trazabilidad legal; hash incrustado en PDF como metadato.