Cómo crear y firmar un documento utilizando la API REST de eSignBase

Cómo crear y firmar un documento utilizando la API REST de eSignBase

En esta guía, explicaremos cómo crear y enviar una solicitud de firma de documentos utilizando la API REST de eSignBase, basándonos en una plantilla de documento existente.

Esta guía se centra en el flujo de trabajo integral:

  1. Preparación de una plantilla de documento
  2. Autenticación con la API REST
  3. Creación de una solicitud de firma a partir de la plantilla

Puede encontrar la referencia completa de la API aquí: https://app.esignbase.com/api_documentation

Créditos de Documentos y Modo Sandbox

La creación de una solicitud de firma de documentos en eSignBase normalmente requiere un crédito de documento. Cada crédito cubre un flujo de trabajo de firma completo, incluyendo el sellado del documento y la generación del rastro de auditoría (audit trail).

Modo Sandbox (Pruebas Gratuitas)

Para el desarrollo y las pruebas de integración, eSignBase ofrece un modo sandbox que no consume créditos. Esto le permite:

  • Probar la API REST completa.
  • Crear y enviar solicitudes de firma.
  • Validar flujos de trabajo de extremo a extremo y depurar integraciones sin impacto en la facturación.

Nota: Los documentos en modo Sandbox no están destinados a un uso legal. No contienen una firma AES y solo se envían a la dirección de correo electrónico de la cuenta de eSignBase.

Requisitos previos: Preparar una plantilla de documento

Antes de poder activar una solicitud de firma a través de la API REST, ya debe existir una plantilla de documento en su cuenta de eSignBase.

Subir un PDF

Abra la aplicación web de eSignBase y suba el archivo PDF que servirá como plantilla para las solicitudes de firma. Consejo de experto: Si planea realizar pruebas en modo Sandbox, asegúrese de activar el interruptor a “Sandbox” antes de subir el archivo.

Captura de pantalla de cómo subir un PDF

Añadir campos de firma

Después de la carga, abra el editor de plantillas y añada al menos un Campo de Firma. Arrastre y suelte el campo desde la paleta de campos de formulario sobre el documento. También puede añadir campos de formulario adicionales (campos de texto, casillas de verificación, fechas, etc.) dependiendo de la información que deba proporcionar el firmante.

Captura de pantalla de arrastrar y soltar campo de firma

El editor de plantillas guarda los cambios automáticamente; la plantilla puede reutilizarse para múltiples solicitudes de firma a través de la API REST.

Autenticación de la API

Para comenzar, necesita un Client ID y un Client Secret de OAuth.

  1. Abra la página de configuración de la API.
  2. Cree un nuevo cliente OAuth.
  3. Guarde el Client ID y el Client Secret generados de forma segura.

Estas credenciales son necesarias para solicitar un token de acceso.

Obtención de un Token de Acceso

Para autenticar las solicitudes de la API, debe obtener un token de acceso OAuth. Los tokens de acceso tienen un tiempo limitado y deben renovarse cuando caducan.

Envíe una solicitud POST a: https://app.esignbase.com/oauth2/token

Encabezados (Headers) requeridos:

Authorization: Basic <basic_auth_credentials>
Content-Type: application/x-www-form-urlencoded

Donde: basic_auth_credentials = base64(client_id + ":" + client_secret)

Grant Types admitidos La API de eSignBase admite los siguientes tipos de concesión (grant types) de OAuth 2.0:

  • client_credentials (recomendado para uso de servidor a servidor)
  • password (credenciales de contraseña del propietario del recurso)

Ejemplo: Password Grant (curl)

El siguiente ejemplo muestra cómo obtener un token de acceso utilizando el tipo password:

curl -X POST 'https://app.esignbase.com/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<SU_CLIENT_ID>' \
  -d 'client_secret=<SU_CLIENT_SECRET>' \
  -d 'grant_type=password' \
  -d 'scope=sandbox all' \
  -d 'username=user@example.com' \
  -d 'password=<SU_CONTRASEÑA>'

Su solicitud de token debe incluir: scope=sandbox all si desea utilizar el modo sandbox; de lo contrario, use scope=all.

Client Credentials Grant (Sin contraseña)

Para la autenticación sin contraseña (recomendado para servicios backend), use: grant_type=client_credentials. En este caso, el encabezado Authorization debe contener las credenciales del cliente codificadas en Base64, y no se requieren credenciales de usuario.

Respuesta del Token

Si la solicitud tiene éxito, la API responde con un JSON que contiene el token de acceso:

{ "access_token": "<su_token_de_acceso>" }

Este access_token debe incluirse como un Bearer token en el encabezado Authorization de todas las solicitudes posteriores a la API.

Creación de una solicitud de firma a partir de una plantilla

Una vez que tenga un token de acceso válido y una plantilla preparada (con al menos un campo de firma), puede crear una nueva solicitud de firma a través de la API REST. Esta operación toma la plantilla existente, asigna destinatarios a los roles definidos en dicha plantilla e inicia el flujo de firma.

Comprensión de la plantilla

Las plantillas en eSignBase pueden incluir uno o más roles de formulario (definidos en la interfaz web). Cada rol (como “signer_1”) debe coincidir con un objeto de destinatario correspondiente en su solicitud.

Puede listar todas las plantillas para encontrar la que desea usar:

GET /api/templates
Authorization: Bearer <su_token_de_acceso>

La respuesta incluye campos como id, filename y form_role_names. Utilizará el id de la plantilla en el siguiente paso.

Realizar la solicitud de creación de documento

Para crear un nuevo documento basado en una plantilla existente e iniciar el proceso de firma, envíe una solicitud POST al endpoint /api/document con el cuerpo JSON adecuado:

POST /api/document
Authorization: Bearer <su_token_de_acceso>
Content-Type: application/json

Ejemplo del cuerpo de la solicitud (Request Body)

A continuación se muestra un ejemplo de carga útil (payload) que:

  • Referencia el ID de la plantilla.
  • Asigna un único destinatario al rol requerido.
  • Incluye opcionalmente metadatos y configuración de vencimiento.
{
  "name": "Contrato de Empleado",
  "template_id": "su_id_de_plantilla_aquí",
  "recipients": [
    {
      "email": "signer@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "role_name": "signer_1",
      "locale": "es"
    }
  ],
  "user_defined_metadata": {
    "internal_id": "42",
    "purpose": "contract-signing-test"
  },
  "expiration_date": "2026-03-15T23:59:00+00:00"
}

Aspectos destacados de los campos:

  • name: una etiqueta para la solicitud de firma. Este nombre también se usará en el correo enviado al firmante.
  • template_id: el UUID de la plantilla que preparó anteriormente.
  • recipients: un array de definiciones de firmantes que coinciden con los form_role_names de la plantilla.
  • user_defined_metadata: (opcional) datos clave/valor para su seguimiento interno.
  • expiration_date: (opcional) cuándo debe expirar la solicitud.

Ejemplo con curl

Aquí hay un ejemplo completo usando curl:

curl -X POST "https://app.esignbase.com/api/document" \
  -H "Authorization: Bearer <SU_TOKEN_DE_ACCESO>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato de Empleado",
    "template_id": "<SU_ID_DE_PLANTILLA>",
    "recipients": [
      {
        "email": "signer@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "role_name": "signer_1",
        "locale": "es"
      }
    ],
    "user_defined_metadata": {
      "internal_id": "42",
      "purpose": "contract-signing-test"
    },
    "expiration_date": "2026-03-15T23:59:00+00:00"
  }'

Qué sucede después

Una solicitud exitosa devuelve una respuesta JSON con el nuevo document_id y su estado inicial, normalmente “DRAFT”:

{
  "document_id": "nuevo_id_doc",
  "status": "DRAFT"
}

En este punto:

  • El documento existe y está listo.
  • eSignBase enviará correos electrónicos de firma automáticamente a los destinatarios.
  • Puede usar otros endpoints para consultar el estado o descargar el PDF firmado final una vez completado.

Notas y consejos

  • Soporte de idioma (Locale): El locale para cada destinatario determina el idioma utilizado en las notificaciones. Los códigos admitidos incluyen en, de y es.
  • Vencimiento: Los documentos con una expiration_date que pase antes de la finalización pasarán automáticamente a estado VOIDED (Anulado).
  • Metadatos: Use user_defined_metadata para adjuntar identificadores de negocio internos o valores de seguimiento.

Sus próximos pasos suelen incluir:

  • Comprobar el estado del documento (usando GET /api/document/<id>).
  • Gestionar webhooks para notificaciones de finalización.
  • Descargar el PDF firmado una vez que esté disponible.