¿Cómo funciona la API de DIGID para creación y envío de documentos a firma?

14 oct 2026

¿Cómo funciona la API de DIGID para creación y envío de documentos a firma?

Cuando una empresa integra la firma electrónica de DIGID en su sistema, el flujo completo — desde que se genera el documento hasta que llega firmado al expediente — ocurre a través de cuatro pasos encadenados: crear el documento, asignar los firmantes, enviar a firma y recibir la confirmación cuando el proceso termina.

Este artículo describe ese flujo con el detalle suficiente para que un equipo de desarrollo pueda entender cómo implementarlo, y para que quien toma la decisión de integrar entienda qué está comprando.

El flujo completo en cuatro pasos

1. Crear el documento

El primer paso es subir el PDF que se va a firmar y registrarlo en DIGID. La solicitud incluye el archivo y los metadatos del documento — nombre, referencia interna si aplica, configuración de la firma.

POST /documents
{
  "name": "Contrato de servicio - Cliente X",
  "file": "<pdf en base64>",
  "reference": "ORD-2024-00123"
}

POST /documents
{
  "name": "Contrato de servicio - Cliente X",
  "file": "<pdf en base64>",
  "reference": "ORD-2024-00123"
}

POST /documents
{
  "name": "Contrato de servicio - Cliente X",
  "file": "<pdf en base64>",
  "reference": "ORD-2024-00123"
}

La respuesta incluye el identificador del documento (document_id) que se usa en los siguientes pasos.

{
  "document_id": "doc_abc123",
  "status": "draft",
  "created_at": "2024-11-15T10:30:00Z"
}

{
  "document_id": "doc_abc123",
  "status": "draft",
  "created_at": "2024-11-15T10:30:00Z"
}

{
  "document_id": "doc_abc123",
  "status": "draft",
  "created_at": "2024-11-15T10:30:00Z"
}

2. Asignar los firmantes

Con el documento creado, el siguiente paso es definir quién va a firmar y en qué orden. Cada firmante se registra con su nombre, correo o número de teléfono para el envío del enlace de firma, y su posición en la secuencia si el documento requiere firmas ordenadas.

POST /documents/doc_abc123/signers
{
  "signers": [
    {
      "name": "Ana García",
      "email": "ana.garcia@empresa.com",
      "order": 1
    },
    {
      "name": "Carlos Méndez",
      "email": "carlos.mendez@empresa.com",
      "order": 2
    }
  ]
}

POST /documents/doc_abc123/signers
{
  "signers": [
    {
      "name": "Ana García",
      "email": "ana.garcia@empresa.com",
      "order": 1
    },
    {
      "name": "Carlos Méndez",
      "email": "carlos.mendez@empresa.com",
      "order": 2
    }
  ]
}

POST /documents/doc_abc123/signers
{
  "signers": [
    {
      "name": "Ana García",
      "email": "ana.garcia@empresa.com",
      "order": 1
    },
    {
      "name": "Carlos Méndez",
      "email": "carlos.mendez@empresa.com",
      "order": 2
    }
  ]
}

Si el documento solo requiere la firma del destinatario — sin firma interna de la empresa — el arreglo incluye únicamente ese firmante.

3. Enviar a firma

Una vez asignados los firmantes, el documento está listo para enviarse. Este paso activa el flujo: DIGID notifica a cada firmante según el orden definido y genera el enlace de firma correspondiente.

POST /documents/doc_abc123/send

POST /documents/doc_abc123/send

POST /documents/doc_abc123/send

La respuesta confirma que el envío fue exitoso y devuelve el estado actualizado del documento.

{
  "document_id": "doc_abc123",
  "status": "pending",
  "signers": [
    {
      "name": "Ana García",
      "status": "notified",
      "sign_url": "https://sign.digid.com.mx/s/xyz789"
    }
  ]
}

{
  "document_id": "doc_abc123",
  "status": "pending",
  "signers": [
    {
      "name": "Ana García",
      "status": "notified",
      "sign_url": "https://sign.digid.com.mx/s/xyz789"
    }
  ]
}

{
  "document_id": "doc_abc123",
  "status": "pending",
  "signers": [
    {
      "name": "Ana García",
      "status": "notified",
      "sign_url": "https://sign.digid.com.mx/s/xyz789"
    }
  ]
}

El sistema de la empresa puede usar el sign_url para mostrar el enlace al firmante directamente en su interfaz, en lugar de depender del correo de notificación.

4. Recibir la confirmación mediante webhook

Cuando cada firmante completa su firma, DIGID envía una notificación al endpoint que la empresa configuró. El payload incluye el estado del documento, los datos del firmante que acaba de firmar y, cuando todos han firmado, la URL para descargar el documento final.

{
  "event": "document.signed",
  "document_id": "doc_abc123",
  "signer": {
    "name": "Ana García",
    "email": "ana.garcia@empresa.com",
    "signed_at": "2024-11-15T11:05:32Z"
  },
  "document_status": "partially_signed"
}

{
  "event": "document.signed",
  "document_id": "doc_abc123",
  "signer": {
    "name": "Ana García",
    "email": "ana.garcia@empresa.com",
    "signed_at": "2024-11-15T11:05:32Z"
  },
  "document_status": "partially_signed"
}

{
  "event": "document.signed",
  "document_id": "doc_abc123",
  "signer": {
    "name": "Ana García",
    "email": "ana.garcia@empresa.com",
    "signed_at": "2024-11-15T11:05:32Z"
  },
  "document_status": "partially_signed"
}

Cuando el último firmante completa el proceso:

{
  "event": "document.completed",
  "document_id": "doc_abc123",
  "document_status": "completed",
  "signed_document_url": "https://api.digid.com.mx/documents/doc_abc123/download",
  "nom151_certificate_url": "https://api.digid.com.mx/documents/doc_abc123/certificate"
}

{
  "event": "document.completed",
  "document_id": "doc_abc123",
  "document_status": "completed",
  "signed_document_url": "https://api.digid.com.mx/documents/doc_abc123/download",
  "nom151_certificate_url": "https://api.digid.com.mx/documents/doc_abc123/certificate"
}

{
  "event": "document.completed",
  "document_id": "doc_abc123",
  "document_status": "completed",
  "signed_document_url": "https://api.digid.com.mx/documents/doc_abc123/download",
  "nom151_certificate_url": "https://api.digid.com.mx/documents/doc_abc123/certificate"
}

El sistema de la empresa descarga el documento firmado y la constancia NOM-151 y los almacena donde corresponda — en su base de datos, en su sistema de gestión documental, vinculados al registro del cliente o del servicio.

Consultar el estado de un documento

En cualquier momento, el sistema puede consultar el estado de un documento activo — quién ha firmado, quién está pendiente, cuándo ocurrió cada firma.

GET /documents/doc_abc123

{
  "document_id": "doc_abc123",
  "name": "Contrato de servicio - Cliente X",
  "status": "partially_signed",
  "signers": [
    {
      "name": "Ana García",
      "status": "signed",
      "signed_at": "2024-11-15T11:05:32Z"
    },
    {
      "name": "Carlos Méndez",
      "status": "pending"
    }
  ]
}

GET /documents/doc_abc123

{
  "document_id": "doc_abc123",
  "name": "Contrato de servicio - Cliente X",
  "status": "partially_signed",
  "signers": [
    {
      "name": "Ana García",
      "status": "signed",
      "signed_at": "2024-11-15T11:05:32Z"
    },
    {
      "name": "Carlos Méndez",
      "status": "pending"
    }
  ]
}

GET /documents/doc_abc123

{
  "document_id": "doc_abc123",
  "name": "Contrato de servicio - Cliente X",
  "status": "partially_signed",
  "signers": [
    {
      "name": "Ana García",
      "status": "signed",
      "signed_at": "2024-11-15T11:05:32Z"
    },
    {
      "name": "Carlos Méndez",
      "status": "pending"
    }
  ]
}

Eso permite que la empresa muestre el estado en tiempo real en su propio sistema, sin que el usuario tenga que salir a consultar otra plataforma.

Autenticación

Todas las llamadas a la API se autentican con un token de acceso que la empresa obtiene al crear su cuenta en DIGID. El token se envía en el header de cada solicitud:

Authorization: Bearer <token>

Authorization: Bearer <token>

Authorization: Bearer <token>

El sandbox usa credenciales separadas de producción, lo que permite probar el flujo completo sin afectar documentos reales.

Qué queda en el expediente

Cada documento completado a través de la API genera automáticamente:

El PDF firmado con las firmas de todas las partes
El audit trail completo con fecha, hora, IP y dispositivo de cada firma
La constancia NOM-151 que acredita la integridad del documento y su fecha exacta

Todo disponible para descarga via API en cualquier momento posterior.

Preguntas frecuentes

¿El PDF puede ser de cualquier tamaño o hay límites? La API acepta PDFs estándar. La documentación técnica especifica los límites de tamaño y el formato aceptado para el archivo.

¿Puedo cancelar un documento después de enviarlo a firma? Sí. La API incluye un endpoint para cancelar documentos que están en estado pendiente, antes de que todos los firmantes hayan completado el proceso.

¿Qué pasa si un firmante no firma en un plazo determinado? La configuración del documento puede incluir una fecha de expiración. Cuando el documento expira sin completarse, DIGID envía un webhook con el evento correspondiente para que el sistema de la empresa tome la acción que corresponda.

¿Se puede reenviar la notificación a un firmante que no recibió el correo? Sí. La API permite reenviar la notificación a un firmante específico sin reiniciar el proceso completo.

¿Los webhooks tienen reintentos si mi endpoint no está disponible? Sí. DIGID reintenta la entrega del webhook si el endpoint no responde o devuelve un error. El artículo dedicado a webhooks entra en detalle sobre la política de reintentos y las mejores prácticas para recibirlos.

Integra el flujo completo de firma en tu sistema

Con la API REST de DIGID puedes automatizar la creación, envío y confirmación de documentos firmados — con sandbox disponible y documentación completa para tu equipo de desarrollo.

Solicita acceso al sandbox y empieza a probar.

¿Cómo pueden las empresas integrar firma electrónica y KYC en sus sistemas mediante API? ›