Documentación de la API

Tabla de contenidos

SDKs Oficiales
Información General
Autenticación
- Cómo obtener un Token de Acceso
- Revocar un Token de Acceso
Templates
- Obtener una lista de todos los templates
- Obtener la información de un template específico
Documentos
Webhook para Procesos de Firma Completados
Comprobar cuántos créditos de documento están disponibles

SDKs Oficiales

eSignBase proporciona SDKs oficiales para varios lenguajes de programación. Estos simplifican la integración con nuestra API REST, manejando la autenticación, la gestión de solicitudes y el tratamiento de errores.

Los SDKs son opcionales – por supuesto, también puede trabajar directamente con la API REST.

Python

Código fuente e incidencias: GitHub - esignbase-python-sdk
Paquete: PyPI - esignbase-sdk

Instalación:

pip install esignbase-sdk

Node.js

Código fuente e incidencias: GitHub - esignbase-node-sdk
Paquete: npm - esignbase-sdk

Instalación:

npm install esignbase-sdk

Nota: El SDK de Node.js requiere Node.js versión 18 o superior.

Información General

Todas las fechas en esta documentación siguen el formato ISO 8601: YYYY-MM-DDTHH:MM:SS+00:00. Por ejemplo: 2025-08-25T13:49:00+00:00.

Los ID, como el ID de documento o ID de plantilla, son actualmente UUIDs. Sin embargo, recomendamos no depender de un formato específico y tratarlos simplemente como cadenas únicas.

Si busca una guía paso a paso, consulte nuestro tutorial: Cómo crear y firmar un documento utilizando la API REST de eSignBase

Autenticación

La API de eSignBase utiliza OAuth2 para la autenticación. Debes incluir el token de acceso de OAuth2 en el encabezado de cada llamada que hagas a nuestra API.

Cómo obtener un Token de Acceso

Primero, obtén tu Client ID y Client Secret en https://app.esignbase.com/oauth2/client creando un Cliente OAuth2.

Luego, codifica en base64 la concatenación del Client ID y Client Secret, separados por dos puntos (:):

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

Con esto, podrás obtener un token de acceso.

Request:

POST: /oauth2/token
headers:
  Authorization Basic <basic_auth_credentials>
  Content-Type: application/x-www-form-urlencoded

POST Body (form encoded):
grant_type=client_credentials&scope=all

scope puede ser:

all
read
create_document
delete
sandbox

El scope sandbox tiene un significado especial. Cuando se incluye:

La sesión se crea en el entorno sandbox.

No se consumirán créditos.

Solo estarán disponibles las plantillas que hayas creado previamente en el entorno sandbox.

Nota: El scope all no incluye el scope sandbox.

Solicitar múltiples scopes

Puedes solicitar varios scopes incluyendo una lista separada por espacios:

POST /oauth2/token
Headers:
  Authorization: Basic <basic_auth_credentials>
  Content-Type: application/x-www-form-urlencoded

Body (form-encoded):
  grant_type=client_credentials&scope=all sandbox

El servidor devolverá un token válido para todos los scopes solicitados que estén permitidos.

Response:

{ "access_token": "<your_access_token>" }

Usas el token de acceso en futuras llamadas a la API. El token de acceso es válido por 5 minutos, después de lo cual se debe obtener uno nuevo.

Revocar un Token de Acceso

Request:

POST: /oauth2/revoke
headers:
Content-Type: application/x-www-form-urlencoded

POST Body (form encoded):
token=<your_access_token>

Templates

Los templates se utilizan para generar documentos que los clientes pueden rellenar y firmar.

Puedes subir archivos PDF para usarlos como templates aquí: https://app.esignbase.com/dashboard

Una vez subidos, deberías ver el template en la tabla de templates del dashboard. El menú de acciones te permite acceder al editor de templates, donde puedes agregar campos de formulario y campos de firma al template.

Obtener una lista de todos los templates:

Request:

GET /api/templates
headers:
Authentication: Bearer <your_access_token>

Response:

[
    {
        "id": "the_template_id",
        "ctime": "2025-08-25T13:49:00+00:00",
        "filename": "my_file.pdf",
        "num_of_pages": 2,
        "page_standard": "a4",
        "form_role_names": ["signee_1"]
    },
    {
        "id": "another_template_id",
        "ctime": "2025-08-25T14:49:00+00:00",
        "filename": "my_other_file.pdf",
        "num_of_pages": 1,
        "page_standard": "letter",
        "form_role_names": ["signee_1", "viewer_1"]
    }
]

Estándares de página admitidos:

page_standard	Descripción
A4	Tamaño de papel estándar utilizado comúnmente a nivel internacional, que mide 210 mm x 297 mm (8,27 pulgadas x 11,69 pulgadas).
letter	Tamaño de papel común utilizado en Estados Unidos y Canadá, que mide 8,5 pulgadas x 11 pulgadas (216 mm x 279 mm).

Obtener la información de un template específico:

Request:

GET /api/template/<template_id>
headers:
Authentication: Bearer <your_access_token>

Response:

    {
        "id": "<template_id>",
        "ctime": "2025-08-25T13:49:00+00:00",
        "filename": "my_file.pdf",
        "num_of_pages": 2,
        "page_standard": "a4",
        "form_role_names": ["signee_1"]
    }

Para cada valor en form_role_names definido en un template, se debe especificar un recipient correspondiente en la solicitud “Create Document” utilizando el campo role_name. Puedes definir el role_name del template en la Web Application utilizando el editor de templates (template editor).

Documentos

Obtener una lista de todos los documentos:

La recuperación de documentos es paginada. Puedes recuperar un máximo de 100 documentos a la vez configurando el parámetro limit. El parámetro offset especifica el punto de inicio para la recuperación.

Request:

GET /api/documents?limit=1&offset=0
headers:
Authentication: Bearer <your_access_token>

Response:

{
    "documents": [
        {
            "id": "the_document_id",
            "template_id": "template_id_this_document_is_based_of",
            "name": "Employee Contract",
            "owner": "name used in mails if send to signees",
            "ctime": "2025-08-25T13:49:00+00:00",
            "mtime": "2025-09-25T13:49:00+00:00",
            "expiration_date": "2025-10-25T13:49:00+00:00",
            "page_standard": "a4",
            "num_of_pages": 2,
            "completed_date": null,
            "status": "SENT",
            "recipients": [
                {
                    "email": "signee@mail.com",
                    "first_name": "John",
                    "last_name": "Doe",
                    "days_before_voided": 5,
                    "form_role": "signee_1",
                    "locale": "en"
                }
            ],
            "user_defined_metadata" {
                "internal_id": "42",
                "internal-name": "contract-developer"
            }
        }
    ],
    "count": 1
}

El campo count en la respuesta te permite saber cuántos documentos están disponibles y, con esto, cuál debería ser el máximo offset durante la paginación.

Estado del Documento

La siguiente tabla describe los posibles status para un documento:

Status	Descripción
`DRAFT`	Documento creado pero aún no enviado a ningún destinatario.
`PARTIALLY_SENT`	Enviado a algunos de los destinatarios pero no a todos.
`SENT`	Enviado a todos los destinatarios.
`PARTIALLY_SIGNED`	Firmado por algunos firmantes pero no por todos.
`WAITING_FOR_PREPARATION`	El documento fue firmado completamente por todas las partes, pero la cola de tareas aún no generó un PDF.
`WAITING_FOR_DIGITAL_SIGNATURE`	Se generó un PDF a partir de los datos del documento y está a la espera de que se le aplique una firma digital.
`DIGITAL_SIGNATURE_CREATED`	El documento fue firmado completamente por todas las partes y se ha generado un PDF con una firma digital.
`COMPLETED`	El procedimiento de firma del documento está completo.
`VOIDED`	El documento ha sido anulado.

user_defined_metadata es un campo opcional representado como un objeto JSON donde cada valor debe ser una cadena de texto. Puede utilizarse para incluir información adicional relevante para el proceso de firma del documento. Un documento puede tener un máximo de 10 campos en un objeto user_defined_metadata. Cada campo puede tener hasta 500 caracteres y las claves pueden tener hasta 25 caracteres.

Obtener información de un documento específico:

Request:

GET /api/document/<document_id>
headers:
Authentication: Bearer <your_access_token>

Response:

{
    "id": "<document_id>",
    "template_id": "template_id_this_document_is_based_of",
    "name": "Employee Contract",
    "owner": "name used in mails if send to signees",
    "ctime": "2025-08-25T13:49:00+00:00",
    "mtime": "2025-09-25T13:49:00+00:00",
    "expiration_date": "2025-10-25T13:49:00+00:00",
    "page_standard": "a4",
    "num_of_pages": 2,
    "completed_date": null,
    "status": "COMPLETED",
    "recipients": [
        {
            "email": "signee@mail.com",
            "first_name": "John",
            "last_name": "Doe",
            "days_before_voided": 5,
            "form_role": "signee_1",
            "locale": "es"
        }
    ],
    "user_defined_metadata" {
        "internal_id": 42,
        "more_info": "some text"
    }
}

Crear un nuevo documento.

Crear un nuevo documento significa que utilizamos una plantilla existente y definimos quiénes serán los destinatarios del documento. Llamar a este endpoint de la API resultará en una nueva solicitud de firma.

Una definición de plantilla tiene el campo form_role_names. Por ejemplo: "form_role_names": ["signee_1"]. Si deseas crear un nuevo documento a partir de esta plantilla, necesitas un destinatario con este role_name. En el caso del ejemplo, esto sería: "role_name": "signee_1".

La creación del documento permite opcionalmente almacenar datos definidos por el usuario en user_defined_metadata. El valor es un objeto JSON donde tanto las claves como los valores son cadenas de texto.

Los destinatarios deben coincidir con los roles de firmante requeridos asignados a la plantilla.

Se puede definir un locale para un destinatario. Este locale se utilizará al enviar correos electrónicos al destinatario. Si no se define ningún locale, se utilizará en como valor predeterminado.

Locales admitidos:

Locale	Idioma
en	Ingles
de	Aleman
es	Español

El campo expiration_date es opcional. Una vez que un documento expira, su estado cambiará a VOIDED. Una vez que un documento ha sido creado, ya no puede ser editado.

Request:

POST /api/document
headers:
Content-Type: application/json
Authentication: Bearer <your_access_token>

Request data:

{
    "name":  "Your Contract",
    "template_id": "id_of_template_used_for_document",
    "recipients": [
        {
            "email": "signee@mail.com",
            "first_name": "John",
            "last_name": "Doe",
            "role_name": "signee_1",
            "locale": "es"
        }
    ],
    "user_defined_metadata": {
        "any_key": "any string value",
    },
    "expiration_date": "2025-09-25T13:49:00+00:00"
}

Response:

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

Descargar un documento completado

Descarga el PDF finalizado y firmado de un documento.

Un documento solo puede descargarse una vez que haya alcanzado uno de los siguientes estados:

DIGITAL_SIGNATURE_CREATED
COMPLETED

Request:

GET /api/document/<document_id>/download
headers:
Authentication: Bearer <your_access_token>

Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="yourfile.pdf"
Content-Length: <file_size_in_bytes>
Last-Modified: Tue, 18 Feb 2026 12:34:56 GMT
Accept-Ranges: bytes

<binary pdf content>

El endpoint admite solicitudes con rangos (Range requests):

Range: bytes=0-1023 Respuesta parcial exitosa:

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/245678

Eliminar un documento existente.

Request:

DELETE /api/document/<document_id>
headers:
Authentication: Bearer <your_access_token>

Si la operación es exitosa, se devolverá un estado HTTP 200 OK.

Webhook para Procesos de Firma Completados

Para recibir una notificación cuando se complete un proceso de firma, activa el “Hook de Documento Completado” en los Ajustes de la API.

Validación de Seguridad: Cada solicitud del webhook incluye un encabezado de firma para su validación. Usa el “Secreto del Hook de Documento Completado” que se muestra para verificar la autenticidad de la solicitud.

Configuración:

Ingresa la URL de callback que debe ser llamada cuando se complete un documento
Las solicitudes se realizan mediante el método POST
Valida cada solicitud usando el encabezado de firma

Solicitud

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Signature-Secret: your_hook_secret_here

{
  "document_id": "<id del documento>",
  "status": "<estado del documento>"
}

Comprobar cuántos créditos de documento están disponibles

Se requiere un crédito para iniciar el proceso de firma de un documento, independientemente del número de firmas o destinatarios involucrados.

Request:

GET /api/credits
headers:
Authentication: Bearer <your_access_token>

Response:

{"credits": 100}