Plataforma DANAsign – Guía de uso de la API REST para firma de documentos

DANAsign es una plataforma de firma digital de documentos desarrollada por DANAconnect, que permite crear plantillas de firma electrónica o digital y realizar envíos masivos o de persona a persona.

Incluye endpoints REST para integraciones seguras y automatizadas, orientadas a flujos de documentos, gestión de contactos y procesos de firma.

Esta guía documenta los principales endpoints REST, junto con ejemplos de uso, encabezados, cuerpos de solicitud y posibles respuestas.

1. Generar el API Token desde la interfaz de la plataforma DANAsign

Antes de realizar peticiones a la API, debe generarse un API Token en la interfaz administrativa de DANAsign. Este token se empleará para autenticar todas las solicitudes provenientes de integraciones externas.

Pasos para generar un token en la plataforma DANAsign

1. Inicie sesión en DANAsign utilizando un usuario con rol Administrador.
2. En el menú lateral, seleccione Configuración > API Tokens.
3. Haga clic en Crear nuevo token.
4. Asigne un nombre descriptivo, por ejemplo: Integración CRM.
5. Seleccione los permisos o scopes requeridos:

• contacts:write — creación y actualización de contactos.
• documents:write — creación de documentos.
• documents:read — lectura y consulta de documentos.

6. Guarde el token y copie el valor generado.
7. Incluya el token en los encabezados de las peticiones API.

2. Autenticación

La autenticación puede realizarse directamente mediante el token de API, sin necesidad de credenciales de usuario, o bien creando sesiones temporales desde dicho token.

2.1 Crear sesión desde un API Token

Crea una sesión de usuario utilizando un token de API válido.

Endpoint

POST {CLIENT_SERVER_URL}/api/tokens/session
Header: x-danassign-api-key: <API_TOKEN>

Respuesta exitosa

{
  "sessionToken": "r:...",
  "userId": "...",
  "scopes": ["contacts:write", ...],
  "token": { ... }
}

2.2 Consultar el token actual

Permite verificar la validez y permisos asociados al token activo.

Endpoint

GET {CLIENT_SERVER_URL}/api/tokens/whoami
Header: x-danassign-api-key: <API_TOKEN>

Respuesta

Devuelve información del usuario autenticado y los permisos asociados a su token.

3. Gestión de Contactos

Los endpoints de contactos permiten registrar y mantener información de los firmantes.

Se requiere el permiso contacts:write en el API Token o un X-Parse-Session-Token válido.

3.1 Crear un contacto individual

Crea un nuevo contacto dentro de la base de datos de DANAsign.

Endpoint

POST {CLIENT_SERVER_URL}/api/1.0/contacts

Encabezados

Content-Type: application/json
x-api-token: <API_TOKEN>

Cuerpo de la solicitud

{
  "name": "Laura Test",
  "email": "laura@example.com",
  "phone": "555-1234"
}

Campos requeridos

Respuesta (201 Created)

{
  "data": {
    "objectId": "...",
    "Name": "Laura Test",
    "Email": "laura@example.com"
  }
}

3.2 Carga masiva de contactos

Permite registrar múltiples contactos en una única petición.

Endpoint

POST {CLIENT_SERVER_URL}/api/1.0/contacts/batch

Encabezados

Content-Type: application/json
x-api-token: <API_TOKEN>

Cuerpo de la solicitud

{
  "contacts": [
    { "Name": "Ana Lote",  "Email": "ana.lote@example.com" },
    { "Name": "Luis Lote", "Email": "luis.lote@example.com", "Phone": "555-0002" }
  ]
}

Campos requeridos dentro de “contacts”

Respuesta

{ "data": { "success": 2, "failed": 0 } }

3.3 Listar contactos

Permite recuperar los contactos creados por el usuario autenticado. Este endpoint admite paginación y búsqueda parcial por nombre o correo electrónico.

Endpoint

GET {CLIENT_SERVER_URL}/api/1.0/contacts?limit=20&skip=0&search=ana

Encabezados

x-api-token: <API_TOKEN>

Parámetros de consulta

Ejemplo de solicitud

curl "http://{CLIENT_SERVER_URL}/api/1.0/contacts?limit=20&skip=0&search=ana" \
  -H "x-api-token: TU_TOKEN"

Respuesta exitosa

{
  "data": [
    {
      "objectId": "mKJ82GH1",
      "Name": "Ana López",
      "Email": "ana.lopez@example.com",
      "Phone": "555-1234",
      "createdAt": "2025-03-10T12:34:56.789Z",
      "updatedAt": "2025-03-11T09:15:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "skip": 0,
    "total": 1,
    "hasMore": false
  }
}

Códigos de respuesta

4. Gestión de Documentos (/api/1.0)

Los endpoints de documentos permiten crear, listar y consultar documentos de firma.

Se requiere un token con permisos documents:read y/o documents:write.

4.1 Listar documentos por estado

Obtiene una lista de documentos filtrados por su estado actual.

Endpoint

GET {CLIENT_SERVER_URL}/api/1.0/documentlist/{status}?limit=20&skip=0
Header: x-api-token: <API_TOKEN>

Parámetros disponibles

Respuesta

[
  {
    "documentId": "...",
    "title": "Contrato X",
    "status": "completed",
    "createdAt": "2025-03-10T12:34:56.789Z",
    "updatedAt": "2025-03-12T08:15:00.000Z"
  }
]

4.2 Crear un documento desde un archivo PDF

Crea un documento para firma a partir de un archivo PDF codificado en Base64.

Endpoint

POST {CLIENT_SERVER_URL}/api/1.0/createdocument

Encabezados

Content-Type: application/json
x-api-token: <API_TOKEN>

Requisitos

• Permiso documents:write en el token.
• Archivo PDF codificado en Base64.
• Al menos un firmante con su rol y posición definidos.

Cuerpo de ejemplo

{
  "file": "…base64…",
  "filename": "contrato-api.pdf",
  "title": "Contrato servicio API",
  "signers": [
    {
      "role": "Firmante 1",
      "name": "María Gómez",
      "email": "mgomez@example.com",
      "identityVerification": {
        "enabled": true,
        "requireDocument": true,
        "threshold": 85,
        "notes": "Validación previa a la firma"
      }
    },
    {
      "role": "Firmante 2",
      "name": "Pedro Pérez",
      "email": "peperez@example.com"
    }
  ],
  "placeholders": [
    { "role": "Firmante 1", "widgets": [ { "type": "signature", "page": 1, "x": 120, "y": 520, "w": 220, "h": 60 } ] },
    { "role": "Firmante 2",  "widgets": [ { "type": "signature", "page": 1, "x": 120, "y": 640, "w": 220, "h": 60 } ] }
  ],
  "prefill": [
    { "type": "textbox", "page": 1, "x": 100, "y": 713, "w": 260, "h": 28,
      "options": { "name": "cliente_nombre", "response": "Cliente ACME S.A.", "fontSize": 10, "fontColor": "#1F2937" } }
  ],
  "settings": { "sendInOrder": true, "allowModifications": false, "automaticReminders": true, "timeToCompleteDays": 12, "redirectUrl": "https://www.example.com/" },
  "metadata": { "externalId": "DOC-MOCK-001" }
}

Campos requeridos

Respuesta exitosa

{
  "documentId": "lHqHh3zQ9X",
  "status": "sent",
  "sentAt": "2025-03-18T08:25:33.123Z",
  "expiresAt": "2025-03-28T08:25:33.123Z"
}

Códigos de error

4.3 Crear un documento desde una plantilla existente

Permite generar un documento a partir de una plantilla configurada previamente en la plataforma.

Endpoint

POST {CLIENT_SERVER_URL}/api/1.0/createdocument/<TEMPLATE_ID>

Encabezados

Content-Type: application/json
x-api-token: <API_TOKEN>

Ejemplo de cuerpo

{
  "signers": [
    { "role": "Cliente", "name": "Ana Pérez", "email": "ana@example.com" },
    { "role": "Vendedor", "name": "Ventas", "email": "ventas@example.com" }
  ],
  "defaults": [
    { "name": "email", "default": "ana@example.com" },
    { "name": "date",  "default": "2025-12-31" }
  ],
  "metadata": {
    "externalId": "TPL-2025-002",
    "tags": ["contratos"]
  }
}

Respuesta

{
  "documentId": "...",
  "templateId": "<TEMPLATE_ID>",
  "title": "Contrato Plantilla",
  "status": "draft",
  "createdAt": "...",
  "updatedAt": "..."
}

5. Recuperar plantillas disponibles

Endpoint

GET {CLIENT_SERVER_URL}/api/1.0/templates
Header: x-api-token: <API_TOKEN>

Parámetros de consulta

Ejemplo (cURL)

curl "http://{CLIENT_SERVER_URL}/api/1.0/templates?limit=20&skip=0&search=contrato" \
  -H "x-api-token: TU_TOKEN"

Respuesta

{
  "data": [
    {
      "objectId": "K8uV4NgY1z",
      "Name": "Contrato estándar",
      "Description": "Plantilla base para clientes nuevos",
      "SignatureType": ["draw"],
      "SendinOrder": true,
      "AutomaticReminders": false,
      "TimeToCompleteDays": 15,
      "RemindOnceInEvery": 5,
      "updatedAt": "2025-03-10T12:34:56.789Z",
      "createdAt": "2025-01-05T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "skip": 0,
    "total": 1,
    "hasMore": false
  }
}

5.1 Obtener detalles de una plantilla

Recupera la información completa de una plantilla específica, incluyendo firmantes, placeholders y configuraciones de envío.

Endpoint

GET {CLIENT_SERVER_URL}/api/1.0/template/<TEMPLATE_ID>

Encabezados

x-api-token: <API_TOKEN>

Parámetros de ruta

Ejemplo de solicitud

curl "http://{CLIENT_SERVER_URL}/api/1.0/template/K8uV4NgY1z" \
  -H "x-api-token: TU_TOKEN"

Respuesta exitosa

{
  "data": {
    "objectId": "K8uV4NgY1z",
    "Name": "Contrato estándar",
    "Description": "Plantilla base para clientes nuevos",
    "SignatureType": ["draw"],
    "SendinOrder": true,
    "AutomaticReminders": false,
    "TimeToCompleteDays": 15,
    "RemindOnceInEvery": 5,
    "IsEnableOTP": false,
    "AllowModifications": false,
    "NotifyOnSignatures": false,
    "RedirectUrl": null,
    "Placeholders": [...],
    "Signers": [...],
    "Bcc": [...],
    "ExtUserPtr": { ... },
    "updatedAt": "2025-03-10T12:34:56.789Z",
    "createdAt": "2025-01-05T10:00:00.000Z"
  }
}

Códigos de respuesta

6. Errores comunes

7. Coordenadas de Widgets en DANAsign

A continuación se describen los parámetros y cálculos necesarios para colocar widgets (como firmas o campos) en un documento PDF mediante la API de DANAsign.

Parámetros comunes de los widgets

• type: Indica el tipo de widget.
• page: Número de página donde se colocará el widget.
• x, y: Coordenadas del punto inicial (arriba–izquierda) del widget.
• • El valor x aumenta hacia la derecha.
  • El valor y aumenta hacia abajo.
• w, h: Ancho y alto del widget.

.

Cómo calcular las coordenadas X y Y

Las coordenadas definen la posición del widget dentro del PDF.

La API de DANAsign utiliza DPI = 72 puntos por pulgada.

Fórmulas de conversión

Si tienes distancias en pulgadas:

xPosition (points) = 72 * DistanceX_in_inches
yPosition (points) = 72 * DistanceY_in_inches

Si tienes distancias en milímetros:

xPosition (points) = DistanceX_mm / 3.527
yPosition (points) = DistanceY_mm / 3.527

Las posiciones deben redondearse al entero más cercano.

Ejemplo de formatos de página

Ejemplo de uso: CreateDocument API con coordenadas

{
  "file": "{{PdfBase64}}",
  "filename": "contrato.pdf",
  "title": "Contrato API",
  "signers": [
    { "role": "Role 1", "name": "María Gómez", "email": "mgomez@example.com" },
    { "role": "Role 2", "name": "Pedro Pérez", "email": "pperez@example.com" },
    { "role": "Role 3", "name": "Luis González", "email": "lgonzalez@example.com" }
  ],
  "placeholders": [
    {
      "role": "Role 1",
      "widgets": [
        { "type": "signature", "page": 1, "x": 0, "y": 0, "w": 140, "h": 35 }
      ]
    },
    {
      "role": "Role 2",
      "widgets": [
        { "type": "signature", "page": 1, "x": 298, "y": 421, "w": 140, "h": 35 }
      ]
    },
    {
      "role": "Role 3",
      "widgets": [
        { "type": "signature", "page": 1, "x": 149, "y": 631, "w": 140, "h": 35 }
      ]
    }
  ],
  "settings": {
    "sendInOrder": true,
    "timeToCompleteDays": 5,
    "bcc": [
      { "email": "legal@example.com", "name": "Equipo Legal" }
    ]
  }
}

Consideraciones finales

• Los encabezados válidos son x-api-token o x-danassign-api-key, según el endpoint.
• Las sesiones Parse usan X-Parse-Session-Token.
• La versión actual de las rutas REST es 1.0.
• Los sessionToken no expiran automáticamente; se invalidan al revocar el token o cerrar sesión.

Actualizado el: 24/11/2025