Documentación de la API

SDKs Oficiales

eSignBase proporciona un cliente oficial de Python que envuelve la API REST y simplifica la autenticación, el manejo de solicitudes y el procesamiento de errores.

El SDK es opcional — toda la funcionalidad está disponible a través de la API REST — pero puede reducir significativamente el esfuerzo de integración para sistemas basados en Python.

- SDK de Python (GitHub): https://github.com/matt-the-midnight-hacker/esignbase-python-sdk
- SDK de Python (PyPI): https://pypi.org/project/esignbase-sdk/

Instalar mediante: pip install esignbase-sdk

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.

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_standardDescripción
A4Tamañ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).
letterTamañ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).

Documents

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 estados (status) para un documento.

StatusDescripción
DRAFTDocumento creado pero aún no enviado a ningún firmante.
PARTIALLY_SENTEnviado a algunos de los destinatarios pero no a todos.
SENTEnviado a todos los destinatarios.
PARTIALLY_SIGNEDFirmado por algunos firmantes pero no por todos.
WAITING_FOR_ESIGNATUREFirmado completamente por todas las partes, y la generación de un PDF con firma electrónica está en proceso.
ESIGNATURE_CREATEDFirmado completamente por todas las partes y se ha generado un PDF con firma electrónica.
COMPLETEDProcedimiento de firma del documento completado.
VOIDEDDocumento 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:

LocaleIdioma
enIngles
deAleman
esEspañ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"}

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:

  1. Ingresa la URL de callback que debe ser llamada cuando se complete un documento
  2. Las solicitudes se realizan mediante el método POST
  3. 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}