API REST de e-Signature.eu — firmas electrónicas (SES, AES, QES)

1. Presentación

La API REST de e-Signature.eu permite a su aplicación enviar documentos para firma electrónica (simple SES, avanzada AES o cualificada QES según eIDAS) sin pasar por nuestra web. Usted envía el PDF y los firmantes; nosotros gestionamos la verificación de identidad, la firma y el seguimiento; usted recibe el documento firmado mediante la API o un callback.

Esta documentación describe la API v3. ¿Ya usa la API v2 (https://api.e-signature.eu/v2/signature/)? Consulte el Changelog.

2. Autenticación

Sus credenciales están en Mi cuenta > Firmas API una vez conectado en e-signature.eu:

• User ID: en la URL, como parámetro userid de cada llamada;
• API token: en la cabecera HTTP x-api-key de cada llamada.

curl -X GET "https://api.e-signature.eu/v3/signature/requestBalance?userid=123" \
  -H "x-api-key: YOUR_API_TOKEN"

Mantenga su token en secreto: da acceso completo a su cuenta mediante la API. Las llamadas deben hacerse desde su servidor, nunca desde un navegador o una app móvil.

3. Convenciones

Peticiones y respuestas

• Solo HTTPS. Los cuerpos de las peticiones son JSON (Content-Type: application/json).
• Cada respuesta es JSON, en una de estas dos formas:

{ "success": true,  "result": { ... } }
{ "success": false, "error": "Readable error message" }

Límites

4. Créditos

Las solicitudes se pagan con sus créditos prepago de e-signature.eu. El precio de un método se obtiene con getMethods (tiene en cuenta sus precios específicos). Su saldo lo devuelven requestBalance y cada objeto solicitud (credits_balance).

Recarga automática de créditos

Para no quedarse nunca sin créditos, su cuenta puede recargarse automáticamente. Se configura una vez en Mi cuenta > Firmas API, no mediante la API:

1. Elija un umbral (en créditos) y el paquete de créditos que se pedirá.
2. Guarde un método de pago con nuestro proveedor de pagos Mollie (tarjeta, o adeudo directo SEPA mediante Bancontact, iDEAL…). Se solicita una sola vez un pago de verificación de 0,01 €.
3. Cada vez que se descuentan créditos y su saldo baja del umbral, se crea un pedido del paquete elegido y se paga automáticamente con el método de pago guardado. La factura se le envía por email.

5. Cómo funciona una solicitud de firma

1. Usted crea la solicitud con el PDF, los firmantes y los métodos de firma aceptados. Se descuentan los créditos.
2. Cada firmante recibe un email con un enlace de firma personal (o usted envía el signature_link cuando send_email es false).
3. El firmante verifica su identidad con uno de los métodos aceptados (itsme®, Evrotrust, Veriff, OTP…) y firma.
4. Cuando todos han firmado, la solicitud pasa a finished: el PDF firmado (PAdES) está disponible con getRequest y se envía en el callback.

Orden de firma

Por defecto, todos los firmantes firman en paralelo. Para definir un orden, indique sign_first: true en los firmantes del primer grupo: se les invita de inmediato, varios en paralelo si es necesario. Los demás firmantes solo se invitan cuando todo el primer grupo ha firmado. Dos grupos como máximo.

Dos modos de integración

No consulte la API en bucle

No llame a getRequest repetidamente para seguir el estado de una solicitud: utilice los callbacks, enviados automáticamente en cada cambio. Las llamadas excesivas activan una limitación automática que suspende temporalmente el tratamiento de sus peticiones.

6. Crear una solicitud de firma

{
  "title": "Sales agreement 2026-114",
  "lang": "en",
  "methods": [
    "itsme-qes-signature",
    "evrotrust-signature"
  ],
  "signature_place": "position_auto",
  "reminder": 3,
  "send_email": true,
  "email_notification": false,
  "note_html": "Please sign the agreement before Friday.",
  "signature_redirect": "https://www.example.com/thank-you",
  "external_reference": "QUOTE-2026-114",
  "metadata": {
    "crm_deal_id": 8812
  },
  "callback_url": "https://erp.example.com/hooks/esignature",
  "signers": [
    {
      "firstname": "Ann",
      "lastname": "Peeters",
      "email": "[email protected]",
      "phone": "+32475111222",
      "sign_first": true
    },
    {
      "firstname": "Marc",
      "lastname": "Dubois",
      "email": "[email protected]",
      "sign_first": false
    }
  ],
  "pdf_file_base64": "JVBERi0xLjcKJeLjz9MK..."
}

Métodos de firma

Son los precios estándar: getMethods devuelve los métodos disponibles y los precios de su cuenta. Solo una firma electrónica cualificada (QES) equivale legalmente a una firma manuscrita según el Reglamento eIDAS. otp-email-non-qualified cubre email y SMS: el código se envía por SMS si el firmante tiene phone, si no por email, al mismo precio.

Campos del cuerpo de la petición

Campos de un firmante

Coste

Precio del método más caro de methods × número de firmantes. Los créditos se descuentan al crear la solicitud. Los de los firmantes que no hayan firmado se reembolsan si la solicitud se cancela o se detiene.

Respuesta 201 Created

{
  "success": true,
  "result": {
    "id_sign": 4521,
    "lang": "en",
    "doc_name": "Sales-agreement-2026-114",
    "send_email": true,
    "from_api": true,
    "signature_redirect": "https://www.example.com/thank-you",
    "status_id": "pending",
    "date_status": "2026-10-20 10:15:02",
    "last_reminder": null,
    "timezone": "Europe/Brussels",
    "credits": 2,
    "credits_balance": 38.4,
    "signers": {
      "1": {
        "firstname": "Ann",
        "lastname": "Peeters",
        "email": "[email protected]",
        "phone": "+32475111222",
        "sign_first": true,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      },
      "2": {
        "firstname": "Marc",
        "lastname": "Dubois",
        "email": "[email protected]",
        "sign_first": false,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      }
    },
    "external_reference": "QUOTE-2026-114",
    "metadata": {
      "crm_deal_id": 8812
    }
  }
}

7. Colocación de las firmas

position_auto (por defecto)

Coloque los marcadores #SIG01, #SIG02… (también se acepta #SIG01#) como texto en su documento, donde cada firmante debe firmar (#SIG01 = primer firmante del array signers). La firma se coloca arriba a la izquierda del marcador. Si un mismo marcador aparece varias veces, se usa su primera aparición. Un marcador se omite si su zona de firma cubriría una firma ya colocada (o una firma existente): el firmante toma entonces el siguiente marcador libre. Un marcador tan cerca del borde de la página que la firma deba desplazarse solo se usa como último recurso.

Documento aún no firmado

Si el documento no contiene ningún marcador, o falta el marcador de un firmante, se añade al final del documento una página de firmas con los marcadores y todas las firmas se colocan en esa página (6 firmantes en la primera página añadida, luego 10 por página adicional).

Documento ya firmado

No se puede añadir ninguna página a un PDF ya firmado electrónicamente: invalidaría las firmas existentes. Con position_auto, las firmas se colocan en los marcadores libres, es decir, los marcadores cuya zona de firma no cubre ninguna firma existente. Los marcadores libres se asignan a los firmantes por orden (#SIG01, #SIG02…).

position_manual

Indique la posición de la firma, en centímetros, para cada firmante:

{ "lastname": "Peeters", "email": "[email protected]", "sign_page": 3, "sign_left": 2.5, "sign_bottom": 6 }

sign_left y sign_bottom indican la esquina superior izquierda de la firma. La firma se coloca debajo y a la derecha de este punto.

Los límites dependen del tamaño real de la página y del tamaño del sello visual: toda la firma debe quedar al menos a 2 cm de cada borde de la página. Si se aceptan varios métodos de firma, se toma el sello más grande. Si un valor está fuera de los límites, el mensaje de error indica el rango permitido para esa página.

Una firma no puede cubrir otra firma de la solicitud, ni una firma existente si el documento ya está firmado.

8. El objeto solicitud de firma

Devuelto por request, getRequest, cancel, skip, remind, delete y enviado en los callbacks.

Firmante

{
  "1": {
    "firstname": "Ann",
    "lastname": "Peeters",
    "email": "[email protected]",
    "status": "signed",
    "signing_time": "2026-10-20 11:02:47",
    "signing_method": "itsme-qes-signature",
    "verified_firstname": "Ann",
    "verified_lastname": "Peeters"
  }
}

9. Otros endpoints

Todos los endpoints reciben userid en la URL y x-api-key en las cabeceras. id_sign se pasa en la URL.

Listar las solicitudes

status_id (opcional): pending, finished o skipped. external_reference (opcional): solo las solicitudes con esta referencia.

{
  "success": true,
  "result": [
    {
      "id_sign": 4521,
      "status_id": "pending",
      "external_reference": "QUOTE-2026-114"
    },
    {
      "id_sign": 4498,
      "status_id": "finished"
    }
  ]
}

Obtener una solicitud

Devuelve el objeto solicitud de firma, con el PDF firmado una vez finalizada la solicitud. Para seguir el estado, use los callbacks en lugar de llamadas repetidas.

Enviar un recordatorio

Envía un email de recordatorio a los firmantes con status: pending del grupo invitado actualmente (primero el grupo sign_first). Solo solicitudes pending. Funciona también con solicitudes creadas con send_email: false.

Detener una solicitud (conservando las firmas ya realizadas)

Posible cuando al menos un firmante ha firmado y al menos otro no. La solicitud pasa a skipped, el PDF firmado parcialmente está disponible y se reembolsan los créditos de los firmantes que no firmaron.

Cancelar una solicitud

Posible mientras nadie haya firmado; para terminar una solicitud firmada parcialmente, use skip. La respuesta contiene la solicitud con status_id: cancelled; después, la solicitud y su documento se eliminan de su panel, los enlaces de firma dejan de funcionar y se reembolsan los créditos.

Eliminar una solicitud

Solo solicitudes finished o skipped. Elimina los documentos y la solicitud. La respuesta contiene la solicitud una última vez, con status_id: deleted: descargue el PDF firmado antes de eliminar.

Descargar el audit trail

No disponible mientras la solicitud está en curso (HTTP 412). Devuelve el objeto solicitud con audit_trail_base64: un PDF con el historial de la solicitud (fechas, métodos, identidades verificadas).

Obtener el saldo de créditos

{ "success": true, "result": { "credits_balance": 38.4 } }

Listar los métodos de firma

Métodos aceptados en methods, con el precio en créditos por firmante para su cuenta. lang (opcional) traduce las etiquetas.

{
  "success": true,
  "result": [
    {
      "id": "itsme-qes-signature",
      "label": "itsme® | QES",
      "credits": 1
    },
    {
      "id": "evrotrust-signature",
      "label": "Evrotrust | QES",
      "credits": 1
    },
    {
      "id": "veriff-advanced-signature",
      "label": "Veriff | AES",
      "credits": 0.7
    },
    {
      "id": "otp-email-non-qualified",
      "label": "OTP by Email/SMS | SES",
      "credits": 0.4
    }
  ]
}

10. Callbacks (webhooks)

Defina su URL de callback en Mi cuenta > Firmas API (HTTPS, accesible públicamente). También puede indicar una callback_url por solicitud. El callback es un POST con un cuerpo JSON que contiene el estado completo actual de la solicitud (mismo formato que getRequest), enviado para las solicitudes creadas mediante la API.

Campos del evento

Tipos de eventos

El cuerpo contiene siempre el estado completo actual: su integración puede basarse en status_id y en el estado de cada firmante en lugar de solo en el tipo de evento.

Cabeceras

Verificar la firma

Su secreto de firma aparece en Mi cuenta > Firmas API, donde también puede regenerarlo. v1 es el HMAC-SHA256 de "<t>.<raw request body>" con su secreto, codificado en hexadecimal. Use el cuerpo bruto, antes de cualquier lectura JSON, y rechace los callbacks de más de 5 minutos.

PHP

$body   = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_ESIG_SIGNATURE'] ?? '';
preg_match( '/t=(\d+),v1=([a-f0-9]{64})/', $header, $m );
$valid = $m
    && abs( time() - (int) $m[1] ) <= 300
    && hash_equals( hash_hmac( 'sha256', $m[1] . '.' . $body, $secret ), $m[2] );

Node.js

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

C# (.NET)

using System.Security.Cryptography; using System.Text; using System.Text.RegularExpressions;
static bool Verify(string rawBody, string header, string secret) {
    var m = Regex.Match(header ?? "", @"t=(\d+),v1=([a-f0-9]{64})");
    if (!m.Success || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(m.Groups[1].Value)) > 300) return false;
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(m.Groups[1].Value + "." + rawBody))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(m.Groups[2].Value));
}

Respuestas y reintentos

• Responda HTTP 2xx en cuanto reciba el callback y trátelo de forma asíncrona si es necesario.
• En caso de error de red, tiempo agotado (30 s), HTTP 429 o 5xx, el callback se reenvía cada hora con el mismo event_id, hasta 24 intentos. Las demás respuestas 4xx se consideran definitivas. Si la solicitud vuelve a cambiar antes de una entrega correcta, el siguiente callback lleva un nuevo evento y el estado completo actual. El estado actual sigue disponible en todo momento con getRequest.
• Se siguen las redirecciones (se mantiene el método POST). No se pueden usar localhost ni direcciones privadas.

11. Errores

Los errores se devuelven con "success": false y un mensaje error legible. Base su lógica en el código HTTP: los mensajes pueden mejorar con el tiempo.

Errores por endpoint

Mensajes de validación al crear (request, HTTP 400)

El mensaje indica el campo o el problema; … representa un valor de su petición. Base su código en el código HTTP y muestre el mensaje para ayudar a corregir la petición.

12. Conservación

Los documentos firmados pueden descargarse durante 30 días tras la finalización, con getRequest o el callback request.completed. El audit trail se conserva durante el periodo definido en nuestro DPA. Archive el documento firmado y el audit trail por su parte en un plazo de 30 días.

13. Changelog

API v3 — diferencias con la API v2

La API v2 (https://api.e-signature.eu/v2/signature/) sigue disponible y sin cambios. Los endpoints, parámetros y la autenticación son idénticos en ambas versiones: para pasar a la API v3, sustituya la URL base por https://api.e-signature.eu/v3/signature/. Puede migrar endpoint por endpoint.

Las URL anteriores (https://www.e-signature.eu/wp-json/signature/ para la API v2 y https://www.e-signature.eu/wp-json/esig/v3/signature/ para la API v3) siguen siendo válidas. Recomendamos utilizar las URL de api.e-signature.eu.

Los callbacks siguen la versión usada para crear la solicitud: una solicitud creada con la API v2 sigue recibiendo callbacks de la API v2.