Creación de Folio - Integración de Firma

Este endpoint permite crear un folio de firma electrónica y enviar uno o varios documentos a las personas que deben firmarlos.

En palabras simples:

• Tú envías documentos
• Indicas quiénes deben firmar
• Firmaris se encarga del proceso de firma electrónica

---

Endpoint

POST https://www.sandboxadmin.firmaris.co/api/integrations/sign

---

Headers obligatorios

x-api-key: Bearer {TOKEN_EMPRESA}
Content-Type: multipart/form-data

Importante:

• El token identifica a tu empresa
• Sin token → la API no funciona
• Debe enviarse exactamente como se muestra

---

Parámetros (form-data)

Estos datos se envían como form-data, no como JSON puro.

Parámetro	Tipo	Requerido	Qué es	Reglas
signers	JSON string	Sí	Personas que deben firmar	JSON válido, máx. 10 firmantes
folioName	string	Sí	Nombre del folio	Máx. 100 caracteres
folioMessage	string	Sí	Mensaje para los firmantes	Máx. 500 caracteres
signatureType	integer	Sí	Tipo de firma	1 o 2
urlReturn	string	Sí	URL de retorno	URL válida
fileType	string	Sí	Tipo de envío de documentos	file o base64
sendEmail	string	Sí	Enviar correo a firmantes	true o false
documents[]	file	Condicional	Archivos PDF	Solo si fileType=file
documentsBase64	JSON string	Condicional	Documentos en base64	Solo si fileType=base64

---

Estructura del objeto signers

Este parámetro siempre es un JSON convertido a string.

[
  {
    "name": "Nombre Completo",
    "email": "correo@ejemplo.com",
    "documentType": "CC",
    "documentNumber": "123456789",
    "cellPhoneNumber": "3001234567"
  }
]

Tipos de documento permitidos

• CC → Cédula de ciudadanía
• CE → Cédula de extranjería
• NIT → Número de identificación tributaria
• TI → Tarjeta de identidad

---

Ejemplo 1: Envío con archivo PDF

{
  "signers": "[{...}]",
  "folioName": "Contrato de Servicios",
  "folioMessage": "Por favor firme el contrato",
  "signatureType": "1",
  "urlReturn": "https://miempresa.com/callback",
  "fileType": "file",
  "sendEmail": "true",
  "documents[]": "contrato.pdf"
}

---

Ejemplo 2: Envío con Base64

{
  "signers": "[{...}]",
  "folioName": "Contrato de Trabajo",
  "folioMessage": "Por favor firme el contrato",
  "signatureType": "2",
  "urlReturn": "https://miempresa.com/webhook",
  "fileType": "base64",
  "sendEmail": "true",
  "documentsBase64": "[{ \"name\": \"contrato.pdf\", \"content\": \"JVBERi0x...\" }]"
}

---

Respuesta exitosa (200 OK)

{
  "success": true,
  "status": 200,
  "message": "Folio creado con éxito",
  "data": {
    "folioId": "abc123...",
    "signProcessUrl": "https://www.devapp.firmaris.co/?f=..."
  }
}

---

Errores comunes

Error 400 – Datos inválidos

Sucede cuando falta información o el formato es incorrecto.

Error 403 – Acceso denegado

El token no es válido o no tiene permisos.

Error 409 – Error al guardar documentos

Los archivos no cumplen las reglas.

Error 500 – Error interno

Problema inesperado del sistema.

---

Checklist antes de enviar

• Token válido
• Máx. 10 firmantes
• Emails correctos
• Documentos PDF válidos
• URL de retorno válida
• Base64 correcto (si aplica)

---

Notas importantes

• Este endpoint es Sandbox
• Usa Sandbox antes de producción
• Nunca expongas el token
• Usa variables de entorno