API de FirmaWeb

Firma masiva y firma desatendida desde tu propio sistema (ERP, remuneraciones, RR.HH.).

Introducción

Con la API tu sistema envía a firmar lotes (muchas personas de una vez, cada una con sus documentos) y hace que el firmante de tu empresa (el gerente, el representante legal) firme todo lo pendiente con un botón, sin salir de tu sistema. Todas las peticiones usan JSON y un token de corta duración.

Si tu integración es nueva, no necesitas la v1, salvo para un documento que firman varias personas que no son firmantes registrados (ver la tabla). La v1 está al final.

Qué llamada usar

NecesitasUsa
Enviar a firmar a muchas personas, cada una con sus documentos (liquidaciones, contratos, anexos), con o sin un firmante de la empresa que firma todosV2 POST /lotes: una llamada para todo el lote
Un documento que firman varias personas, una tras otra (un acta de directorio, un contrato con varias partes)V1 /crear_proceso, /agregar_documento, /agregar_firmante una vez por persona, en el orden en que firman, e /iniciar_proceso
Que el gerente o el representante legal firme todo lo pendiente desde tu sistemaV2 POST /firmar
Saber quién firmóLotes: avisos o GET /lotes/{idLote}. V1: el aviso de cada firma. No descargues los PDF para saberlo.
Bajar el PDF firmadoGET /documentos/{idDocumento}, una vez, cuando ya firmaron todos. Sirve para la v1 y la v2

Dirección base

VersiónURL baseDescripción
V2https://escritorio.firmaweb.app/apifw/v2Firma masiva (lotes) y firma desatendida. Es la que describe esta página.
V1https://escritorio.firmaweb.app/apifw/v1La API anterior: sigue funcionando, con las mismas credenciales, y se puede usar junto con la v2. Está documentada en API v1 (compatibilidad).

No hay una dirección de pruebas aparte. Pruebas y producción usan esta misma dirección; lo que las separa es la cuenta: una cuenta de pruebas tiene sus propias credenciales y su propio saldo.

Flujo de integración típico

Paso 1AutenticarPedir un token con tus credenciales de API.
Paso 2Enviar el lotePersonas, documentos y firmantes comunes, en una llamada.
Paso 3Firman las personasCada una recibe su correo y firma con su PIN.
Paso 4Firma desatendidaTu firmante firma todo lo pendiente con un botón en tu sistema.
Paso 5Recibir avisosTu sistema se entera de cada firma y de cada lote terminado.
Paso 6DescargarBajar los PDF firmados y guardarlos en tu sistema.

Antes de empezar (una vez, en la consola)

  1. Administrar → Clave de API → Generar credenciales. Aparecen el APIUSER y la APIKEY. La clave se muestra una sola vez.
  2. Administrar → Firmantes registrados: registra a quienes firmarán por la empresa. Cada uno activa su firma desde su propia consola.
  3. Si quieres recibir avisos: en la misma página de la clave, Generar secreto de avisos.

Autenticación

Todas las llamadas llevan un token en la cabecera:

Authorization: Bearer <token>

El token se pide con el usuario y la clave de API, unidos por dos puntos y en Base64, en POST /apifw/v1/token (el mismo token sirve para las dos versiones; no existe /apifw/v2/token):

Authorization: Bearer base64(APIUSER:APIKEY)

El token dura 15 minutos (Expira_en). Pide uno y úsalo en todas las llamadas hasta que venza: /token admite 5 solicitudes por minuto, así que pedir un token por llamada termina en HTTP 429. Vencido, la v2 responde 401 y la v1 403 con "Token expirado": pide otro.

Petición de ejemplo
curl -X POST https://escritorio.firmaweb.app/apifw/v1/token \
  -H "Authorization: Bearer $(printf '%s' 'APIUSER:APIKEY' | base64)"
Respuesta
{
  "Estado": 1, "Mensaje": "Correcto",
  "Token": "eyJhbGciOi...",
  "Token_tipo": "Bearer",
  "Expira_en": 1791234567
}

Firma desatendida Nuevo

El firmante de tu empresa firma todo lo que le toca, de una vez, con un botón en tu propio sistema: sin entrar a FirmaWeb, sin abrir un enlace por documento y sin PIN por correo. Con 200 contratos, es una sola acción.

Modo 1 · por defectoCon código

Junto al botón, tu sistema le pide al firmante el código de 6 dígitos de su aplicación de autenticación (la misma con que entra a la consola) y lo envía en codigo. Un código firma todo lo pendiente: no se pide por documento.

Modo 2 · firma desatendidaCon autorización permanente

El firmante entra una vez a su consola, en Documentos → Sin firmar → Firmar desde el sistema de tu empresa, acepta la autorización permanente y la confirma con un código. Desde entonces tu sistema llama a /firmar sin código, incluso de forma automática. La retira ahí mismo cuando quiera.

Cómo se arma

  1. Inscribir la firma (una vez): un administrador registra al firmante en Administrar → Firmantes registrados, y él la activa en su consola con su RUT y un código de su aplicación.
  2. Ponerlo como firmante: en los lotes, en firmantesComunes; en los procesos de /apifw/v1, agregándolo al final con agregar_firmante, con el mismo RUT y correo de su registro.
  3. Mostrarle lo pendiente: GET /firmas_pendientes.
  4. El botón: POST /firmar.
La clave de API por sí sola nunca firma por una persona: hace falta su código o su autorización permanente, que solo él puede dar. Cada firma queda registrada con la forma en que se autorizó.
Un aviso por lote, no por documento. En los lotes, el firmante común no recibe un correo por cada documento: le llega uno cuando ya tiene documentos listos y otro cuando todo el lote lo espera. El avance (cuántos están listos, cuántos faltan) lo ve en su consola, y tu sistema lo consulta con GET /lotes/{idLote} o GET /firmas_pendientes.

Firma desatendida

GET /firmas_pendientes

Lo que le toca firmar al firmante registrado

Devuelve los procesos en que el firmante registrado ya puede firmar: aquellos en que firmaron todos los anteriores. Úsala para mostrarle la lista en tu sistema antes del botón, y para saber si hay que pedirle el código.

Requiere Bearer Token

Parámetros (en la dirección)

CampoTipoReq.Descripción
rutFirmantestringREQRUT del firmante registrado de tu cuenta.
idLoteintegerOPCPara ver solo lo pendiente de un lote.

Respuestas

200Lista de procesos pendientes (puede venir vacía)
422Ese RUT no es un firmante registrado y activo de la cuenta
401Token inválido o vencido
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
GET https://escritorio.firmaweb.app/apifw/v2/firmas_pendientes?rutFirmante=12.345.678-5
Respuestas

200 — Correcto

{
  "firmante": { "rut": "12345678-5", "nombre": "Ana Pérez Soto", "autorizacionPermanente": false },
  "pideCodigo": true, "total": 2, "documentos": 3,
  "procesos": [
    { "idProceso": 1000345, "referencia": "trabajador-0041", "idLote": 1000012, "nombre": "Liquidaciones septiembre 2026 · Jorge Díaz", "documentos": 2 },
    { "idProceso": 1000346, "referencia": "trabajador-0042", "idLote": 1000012, "nombre": "Liquidaciones septiembre 2026 · María Soto", "documentos": 1 }
  ]
}

422 — No registrado

{ "error": "firmante_comun_no_registrado", "mensaje": "Ese RUT no es un firmante registrado y activo de la cuenta. Consulta GET /firmantes_registrados." }

POST /firmar

Firmar todo lo pendiente, de una vez

Aplica la firma del firmante registrado en todo lo que le toca, en una sola llamada: es el botón de tu sistema. Sirve para los lotes y también para los procesos creados con /apifw/v1, siempre que él figure como firmante con el RUT y el correo de su registro.

Si quedan es mayor que cero (lotes muy grandes), repite la llamada. Repetirla nunca firma ni cobra dos veces.

Si no queda nada pendiente para ese firmante, o para ese idLote, la respuesta es 200 con "firmados": [] y "quedan": 0. No es un error: ya estaba todo firmado. Lo más común es que el lote se haya completado antes, por ejemplo porque el firmante firmó desde su consola. Antes de pedirle el código, consulta GET /firmas_pendientes: un código enviado con nada pendiente se consume igual.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
rutFirmantestringREQRUT del firmante registrado de tu cuenta.
codigostring (6 dígitos)SEGÚNEl código que muestra en ese momento la aplicación de autenticación del firmante. Cada código sirve una vez y firma todo lo pendiente. No se envía si el firmante dio la autorización permanente.
idLoteintegerOPCPara firmar solo lo de un lote.
procesosarray de integerOPCLista de idProceso, para firmar solo esos.

Respuestas

200Firmado: lista de procesos firmados y, si los hay, los que no. Con nada pendiente, la lista viene vacía
422Falta el código (el firmante no ha dado la autorización permanente)
403Código no válido o ya usado
429demasiados_codigos: más de 5 intentos de código para el mismo firmante en 15 minutos, correctos o no (trae Retry-After)
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
La clave de API por sí sola nunca firma por una persona: hace falta su código o su autorización permanente. Solo se firman procesos de tu propia cuenta, y cada firma queda registrada con la forma en que se autorizó.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v2/firmar
{
  "rutFirmante": "12.345.678-5",
  "codigo": "492817"
}
Respuestas

200 — Firmado

{
  "firmante": { "rut": "12345678-5", "nombre": "Ana Pérez Soto" },
  "modo": "codigo",
  "firmados": [
    { "idProceso": 1000345, "referencia": "trabajador-0041", "idLote": 1000012, "nombre": "Liquidaciones septiembre 2026 · Jorge Díaz", "documentos": 2 }
  ],
  "noFirmados": [],
  "quedan": 0
}

200 — Nada pendiente

{
  "firmante": { "rut": "12345678-5", "nombre": "Ana Pérez Soto" },
  "modo": "codigo",
  "firmados": [],
  "noFirmados": [],
  "quedan": 0
}

422 — Falta código

{ "error": "falta_codigo", "mensaje": "Falta `codigo`: el código de 6 dígitos de la aplicación de autenticación del firmante. Solo se omite si el firmante dio la autorización permanente en su consola." }

403 — Código inválido

{ "error": "codigo_invalido", "mensaje": "El código no es válido o ya se usó. Pide al firmante uno nuevo de su aplicación." }

Lotes (firma masiva)

POST /lotes

Crear un lote (y enviarlo en la misma llamada)

Envía a firmar muchas personas de una vez, cada una con sus documentos. Con "enviar": true el lote sale en esta misma llamada. Todo o nada: si una fila tiene un error, no se crea ni se cobra nada, y la respuesta dice qué corregir en cada fila.

Sin personas ni enviar, el lote queda en borrador para llenarlo por tandas (lotes de más de 30 MB). Un borrador que no se envía en 30 días se borra solo.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
nombrestring ≤80REQNombre del lote. Lo ven tus usuarios en la consola.
referenciastring ≤100OPCTu identificador del lote. Si repites la llamada con la misma referencia, no se crea ni se cobra otro lote: recibes el que ya existe, con "repetido": true. Úsala siempre. En pruebas, cambia la referencia en cada envío (por ejemplo, con la fecha y la hora): con la misma, recibes el lote de la prueba anterior.
firmantesComunesarray de stringOPCRUT de los firmantes registrados que firman todos los procesos, en el orden en que deben firmar.
urlNotificastring (URL)OPCDirección de tu sistema que recibirá los avisos. Antes genera el secreto de avisos en la consola (Administrar → Clave de API): sin él, el lote responde 422 falta_secreto_avisos y no se crea.
idEmpresaintegerOPCSi tu cuenta tiene varias empresas, a cuál corresponde.
enviarbooleanOPCtrue para enviarlo ahora. Sin él queda en borrador.
personas[].referenciastring ≤100OPCTu identificador de la persona (id de trabajador, de contrato…). Vuelve en las respuestas y en los avisos.
personas[].nombresstringREQNombres de quien firma.
personas[].apellidoPaternostringREQApellido paterno. apellidoMaterno es opcional.
personas[].rutstringREQRUT con dígito verificador (se valida). Con o sin puntos.
personas[].emailstringREQCorreo donde recibe el enlace y el PIN. El enlace dura el plazo de la cuenta (por defecto 7 días) desde que le toca firmar; si vence sin firmar, el proceso se anula y el saldo vuelve.
personas[].documentos[]arrayREQDe 1 a 30 documentos: nombre y pdf (el PDF en Base64, hasta 10 MB cada uno).

Respuestas

201Lote creado (y enviado, si se pidió)
200Ya existía un lote con esa referencia: se devuelve, con "repetido": true
422Hay filas con errores, un firmante común no está registrado o falta el secreto de avisos: no se creó nada
402No alcanzan las firmas: no se creó nada
413Más de 30 MB: usa el borrador y agrega las personas por tandas
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v2/lotes
{
  "nombre": "Liquidaciones septiembre 2026",
  "referencia": "liq-2026-09",
  "firmantesComunes": ["12.345.678-5"],
  "urlNotifica": "https://tu-sistema.cl/firmaweb/avisos",
  "enviar": true,
  "personas": [
    {
      "referencia": "trabajador-0041",
      "nombres": "Jorge",
      "apellidoPaterno": "Díaz",
      "apellidoMaterno": "Rojas",
      "rut": "11.111.111-1",
      "email": "jorge@correo.cl",
      "documentos": [
        { "nombre": "Liquidación septiembre.pdf", "pdf": "JVBERi0xLjcK... (Base64)" },
        { "nombre": "Anexo de contrato.pdf", "pdf": "JVBERi0xLjcK... (Base64)" }
      ]
    }
  ]
}
Respuestas

201 — Creado

{
  "idLote": 1000012, "nombre": "Liquidaciones septiembre 2026", "referencia": "liq-2026-09",
  "estado": "en_firma",
  "firmantesComunes": [{ "rut": "12345678-5", "nombre": "Ana Pérez Soto" }],
  "resumen": { "personas": 1, "documentos": 2, "enFirma": 1, "faltaPersona": 1, "faltaFirmanteComun": 0, "completados": 0, "anulados": 0 },
  "personas": [{
    "referencia": "trabajador-0041", "idProceso": 1000345, "estado": "en_firma",
    "rut": "11.111.111-1", "nombre": "Jorge Díaz Rojas", "email": "jorge@correo.cl",
    "firmantes": [
      { "orden": 1, "rut": "11.111.111-1", "nombre": "Jorge Díaz Rojas", "firmo": false },
      { "orden": 2, "rut": "12345678-5", "nombre": "Ana Pérez Soto", "firmo": false }
    ],
    "documentos": [
      { "idDocumento": 1000801, "nombre": "Liquidación septiembre.pdf", "firmado": false },
      { "idDocumento": 1000802, "nombre": "Anexo de contrato.pdf", "firmado": false }
    ]
  }]
}

422 — Filas con errores

{
  "error": "filas_con_errores",
  "mensaje": "No se creó nada: hay 2 fila(s) por corregir.",
  "filas": [
    { "fila": 3, "referencia": "trabajador-0057", "error": "RUT no válido" },
    { "fila": 8, "referencia": "trabajador-0102", "error": "\"Liquidación.pdf\" no es un PDF en Base64" }
  ]
}

402 — Sin saldo

{ "error": "saldo_insuficiente", "mensaje": "No se envió nada: el lote necesita 400 firmas y la cuenta tiene 380.", "necesarias": 400, "disponibles": 380 }

POST /lotes/{idLote}/personas

Agregar personas a un borrador

Para lotes grandes: agrega las personas por tandas (por ejemplo, de 20 en 20), las veces que haga falta. Cada tanda es todo o nada: si una persona tiene un error, no se agrega ninguna de esa tanda. Nada se cobra ni se envía todavía.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
personas[].referenciastring ≤100OPCTu identificador de la persona (id de trabajador, de contrato…). Vuelve en las respuestas y en los avisos.
personas[].nombresstringREQNombres de quien firma.
personas[].apellidoPaternostringREQApellido paterno. apellidoMaterno es opcional.
personas[].rutstringREQRUT con dígito verificador (se valida). Con o sin puntos.
personas[].emailstringREQCorreo donde recibe el enlace y el PIN. El enlace dura el plazo de la cuenta (por defecto 7 días) desde que le toca firmar; si vence sin firmar, el proceso se anula y el saldo vuelve.
personas[].documentos[]arrayREQDe 1 a 30 documentos: nombre y pdf (el PDF en Base64, hasta 10 MB cada uno).

Respuestas

200Personas agregadas: devuelve el lote al día
422Hay filas con errores: no se agregó ninguna de la tanda
409El lote ya se envió: no admite cambios
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v2/lotes/1000012/personas
{
  "personas": [
    {
      "referencia": "trabajador-0042",
      "nombres": "María", "apellidoPaterno": "Soto",
      "rut": "22.222.222-2", "email": "maria@correo.cl",
      "documentos": [{ "nombre": "Liquidación septiembre.pdf", "pdf": "JVBERi0xLjcK... (Base64)" }]
    }
  ]
}
Respuestas

200 — Agregadas

{ "idLote": 1000012, "estado": "borrador", "resumen": { "personas": 2, "documentos": 3, "enFirma": 0, "completados": 0, "anulados": 0 }, "personas": [ "..." ] }

422 — Filas con errores

{
  "error": "filas_con_errores",
  "mensaje": "No se agregó nada: hay 1 fila(s) por corregir.",
  "filas": [{ "fila": 2, "referencia": "trabajador-0041", "error": "esta persona ya está en el lote" }]
}

POST /lotes/{idLote}/enviar

Enviar un borrador

Revisa el saldo, descuenta las firmas y envía los correos a las personas. Si no alcanza el saldo, el lote sigue en borrador: carga firmas y vuelve a enviarlo. No lleva cuerpo.

Requiere Bearer Token

Respuestas

200Lote enviado
402No alcanzan las firmas: el lote sigue en borrador
422El lote no tiene personas, o un firmante común ya no está disponible
409El lote ya se había enviado
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v2/lotes/1000012/enviar
Respuestas

200 — Enviado

{ "idLote": 1000012, "estado": "en_firma", "resumen": { "personas": 200, "documentos": 200, "enFirma": 200, "completados": 0, "anulados": 0 }, "personas": [ "..." ] }

GET /lotes/{idLote}

Consultar el avance de un lote

El lote al día: quién firmó (firmo), qué documentos están listos (firmado) y el estado de cada persona. En resumen viene la etapa del lote: faltaPersona (procesos que esperan a la persona), faltaFirmanteComun (ya firmó la persona; esperan al firmante común), completados y anulados.

EstadoSignifica
borradorTodavía no se envía.
en_firmaEnviado; faltan firmas.
completado (persona)Firmaron todos. Sus documentos ya se pueden descargar.
anulado (persona)El firmante en turno dejó vencer su enlace sin firmar, o alguien lo anuló en la consola. Las firmas que no se usaron vuelven al saldo.
terminado (lote)Ya no queda ninguna persona en firma.
Requiere Bearer Token

Respuestas

200El lote, con el avance por persona, por firmante y por documento
404El lote no existe
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Si recibes avisos no necesitas consultar a cada rato. Si no los usas, consulta cada varios minutos, no cada segundo.
Petición de ejemplo
GET https://escritorio.firmaweb.app/apifw/v2/lotes/1000012
Respuestas

200 — Correcto

{
  "idLote": 1000012, "nombre": "Liquidaciones septiembre 2026", "referencia": "liq-2026-09",
  "estado": "en_firma",
  "firmantesComunes": [{ "rut": "12345678-5", "nombre": "Ana Pérez Soto" }],
  "resumen": { "personas": 1, "documentos": 2, "enFirma": 1, "faltaPersona": 1, "faltaFirmanteComun": 0, "completados": 0, "anulados": 0 },
  "personas": [{
    "referencia": "trabajador-0041", "idProceso": 1000345, "estado": "en_firma",
    "rut": "11.111.111-1", "nombre": "Jorge Díaz Rojas", "email": "jorge@correo.cl",
    "firmantes": [
      { "orden": 1, "rut": "11.111.111-1", "nombre": "Jorge Díaz Rojas", "firmo": false },
      { "orden": 2, "rut": "12345678-5", "nombre": "Ana Pérez Soto", "firmo": false }
    ],
    "documentos": [
      { "idDocumento": 1000801, "nombre": "Liquidación septiembre.pdf", "firmado": false },
      { "idDocumento": 1000802, "nombre": "Anexo de contrato.pdf", "firmado": false }
    ]
  }]
}

DELETE /lotes/{idLote}

Descartar un borrador

Borra un lote que todavía no se envía, con sus documentos. Un lote enviado no se borra.

Requiere Bearer Token

Respuestas

204Borrador descartado (sin cuerpo)
409El lote ya se envió
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
DELETE https://escritorio.firmaweb.app/apifw/v2/lotes/1000012
Respuestas

409 — Ya enviado

{ "error": "lote_ya_enviado", "mensaje": "El lote ya se envió: no se puede modificar." }

Documentos

GET /documentos/{idDocumento}

Descargar un documento firmado

Devuelve el PDF firmado tal cual (Content-Type: application/pdf), no en Base64. Solo cuando ya firmaron todos. Sirve para cualquier documento de tu cuenta, también los de /apifw/v1.

Requiere Bearer Token

Respuestas

200El PDF firmado
409Al documento todavía le faltan firmas
404El documento no existe
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
GET https://escritorio.firmaweb.app/apifw/v2/documentos/1000801
Respuestas

200 — PDF

Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''Liquidaci%C3%B3n%20septiembre.pdf

%PDF-1.7 ...

409 — Sin firmar

{ "error": "documento_sin_firmar", "mensaje": "Al documento todavía le faltan firmas." }

Cuenta

GET /firmantes_registrados

Firmantes registrados de la cuenta

Quiénes pueden ir como firmantes comunes de un lote y firmar con /firmar: los firmantes registrados y activos de tu cuenta.

Requiere Bearer Token

Respuestas

200Lista de firmantes registrados
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
GET https://escritorio.firmaweb.app/apifw/v2/firmantes_registrados
Respuestas

200 — Correcto

{ "firmantes": [{ "rut": "12345678-5", "nombre": "Ana Pérez Soto", "email": "ana@tu-empresa.cl" }] }

GET /saldo

Firmas disponibles

El saldo de firmas de la cuenta. fes es firma electrónica simple.

Requiere Bearer Token

Respuestas

200Saldo de la cuenta
401Falta el token, no es válido o venció: pide otro en /token
429demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After
Petición de ejemplo
GET https://escritorio.firmaweb.app/apifw/v2/saldo
Respuestas

200 — Correcto

{ "fes": 480, "fao": 0 }

Avisos a tu sistema

POST tu urlNotifica

FirmaWeb le avisa a tu sistema

Si el lote lleva urlNotifica, FirmaWeb hace un POST con JSON a esa dirección cada vez que pasa algo. Todos los avisos traen evento, fecha, idLote y referenciaLote.

Firmado con tu secreto de avisos

Eventos

EventoCuándoDatos
firmaAlguien firmó un documento (cada firmante, cada documento).idProceso, referencia, idDocumento, documento, firmante
proceso_completadoFirmaron todos los de una persona: sus documentos ya se pueden descargar.idProceso, referencia
proceso_anuladoEl proceso de una persona se anuló.idProceso, referencia
lote_completadoYa no queda ninguna persona en firma.completados, anulados

Qué debe hacer tu sistema

2xxResponder en menos de 10 segundos. Con eso el aviso queda entregado.
OtroReintentamos a los 7 y a los 20 minutos; después dejamos de intentar.
Un mismo aviso reintentado lleva el mismo número en la cabecera X-FirmaWeb-Entrega: úsalo para no procesarlo dos veces. La cabecera X-FirmaWeb-Firma: t=…,v1=… trae el HMAC-SHA256, en hexadecimal, del texto t + punto + cuerpo tal como llegó, calculado con tu secreto de avisos (se genera en Administrar → Clave de API). Si no coincide, descarta el aviso.
Aviso de ejemplo
{
  "evento": "proceso_completado",
  "fecha": "2026-10-05T14:03:22.118Z",
  "idLote": 1000012, "referenciaLote": "liq-2026-09",
  "idProceso": 1000345, "referencia": "trabajador-0041"
}
Comprobar que el aviso es nuestro
// Node.js: cuerpoCrudo es el cuerpo recibido, sin modificar
const crypto = require('node:crypto');

function avisoValido(cabecera, cuerpoCrudo, secreto) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(cabecera || '');
  if (!m) return false;
  // más de 5 minutos de diferencia: se descarta
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const esperado = crypto.createHmac('sha256', secreto)
    .update(m[1] + '.' + cuerpoCrudo).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(m[2]));
}

Errores

Un error responde con su código HTTP y { "error": "…", "mensaje": "…" }. error es fijo, para tu programa; mensaje es para una persona.

Lee siempre el cuerpo de la respuesta, también en los 4xx. El texto que acompaña al código HTTP (por ejemplo 422 unknown en Delphi con Indy) lo pone tu librería, no FirmaWeb: la causa va en error y mensaje. En Indy, activa hoNoProtocolErrorException y hoWantProtocolErrorContent para recibir el cuerpo sin excepción.

HTTPerrorQué hacer
400solicitud_invalidaEl cuerpo no es un JSON válido.
401no_autorizadoFalta el token, no es válido o venció: pide uno nuevo.
402saldo_insuficienteNo alcanzan las firmas. Trae necesarias y disponibles.
402cuenta_suspendidaLa cuenta está suspendida por pago pendiente y toda llamada responde esto: Cuenta suspendida por pago pendiente. Para regularizar, escriba a felipe@certifika.app.
403codigo_invalidoEl código del firmante no es válido o ya se usó: pídele uno nuevo.
404lote_no_existe, documento_no_existeRevisa el número.
409lote_ya_enviadoEl lote ya se envió: no admite cambios.
409documento_sin_firmarTodavía faltan firmas.
413solicitud_muy_grandeMás de 30 MB: crea el lote en borrador y agrega las personas por tandas.
413tope_sin_enviarLa cuenta llegó a 2 GB en documentos o a 10.000 procesos sin enviar a firma: envía o descarta borradores antes de agregar más.
422filas_con_erroresCorrige las filas de filas y reenvía.
422firmante_comun_no_registradoEse RUT no es un firmante registrado y activo de tu cuenta.
422falta_codigoEnvía el código del firmante, o que él dé la autorización permanente.
422falta_secreto_avisosGenera el secreto de avisos en la consola.
422falta_nombre, sin_personas, lote_vacio, demasiadas_personas, empresa_no_existe, url_notifica_invalidaLo explica el mensaje.
429demasiadas_solicitudesMás de 300 solicitudes por minuto a la v2, en cualquier llamada. Espera los segundos de Retry-After y repite la misma llamada. Ver Límite de solicitudes.
429demasiados_codigosSolo en /firmar: más de 5 intentos de código para el mismo firmante en 15 minutos.
500error_internoReintenta. Con referencia, el lote no se duplica.

Límite de solicitudes (HTTP 429)

La API tiene tres límites. Al pasar cualquiera, la llamada responde HTTP 429 y no hace nada: no crea, no cobra, no envía y no firma. Trae la cabecera Retry-After con los segundos que faltan para poder seguir: espera esos segundos y repite la misma llamada, tal cual.

LímiteQué llamadasTopeSe cuenta por
GeneralTodas las que llevan token. En la v1: /crear_proceso, /agregar_documento, /agregar_firmante, /iniciar_proceso, /descargar_documento y /consultar_saldos. En la v2: todas.300 por minuto en la v1 y otras 300 en la v2, contadas aparteIP de origen y cuenta, cada una por separado: basta que una pase el tope
TokenPOST /apifw/v1/token5 por minutoIP de origen y APIUSER. Cuentan también las que fallan
Código del firmantePOST /apifw/v2/firmar con codigo5 intentos cada 15 minutosFirmante registrado. Cuentan los correctos y los incorrectos

El 429 del límite general no es de una llamada en particular: le toca a la que llegue después de pasar el tope, sea cual sea. Por eso aparece en todas las llamadas de esta página.

Cómo se cuenta

  • El minuto empieza con la primera llamada. Al cumplirse, el contador vuelve a cero. Retry-After dice cuántos segundos faltan para eso.
  • Cuentan todas las llamadas, también las que responden con error y las que se repiten.

Cómo no llegar al límite

  • Un token para todo: pídelo una vez y úsalo hasta que venza (15 minutos).
  • En la v1, cada persona son al menos 4 llamadas (/crear_proceso, /agregar_documento, /agregar_firmante e /iniciar_proceso), más una por cada documento extra. 300 por minuto alcanzan para unas 75 personas por minuto. Para más, usa la v2: POST /lotes envía hasta 200 personas en una sola llamada.
  • Descarga cada PDF una vez, cuando ya está firmado. Para saberlo usa los avisos a tu urlNotifica en vez de consultar una y otra vez.
  • Ante un 429, espera los segundos de Retry-After antes de repetir. Reintentar de inmediato también cuenta y alarga la espera.
Respuesta 429 en la v1
HTTP/1.1 429 Too Many Requests
Retry-After: 18

{ "Estado": 429, "Mensaje": "Demasiadas solicitudes" }
Respuesta 429 en la v2
HTTP/1.1 429 Too Many Requests
Retry-After: 18

{ "error": "demasiadas_solicitudes", "mensaje": "Demasiadas solicitudes. Reintenta en 18 segundos." }
Reintentar después de un 429
// Node.js 18 o más: repite la llamada cuando la API responde 429
async function llamarFirmaWeb(url, opciones) {
  for (let intento = 1; intento <= 5; intento++) {
    const r = await fetch(url, opciones);
    if (r.status !== 429) return r;
    const segundos = Number(r.headers.get('Retry-After')) || 1;
    await new Promise((listo) => setTimeout(listo, segundos * 1000));
  }
  throw new Error('FirmaWeb sigue respondiendo 429');
}

Límites y cobro

API v1 (compatibilidad) V1

La v1 es la API de la plataforma anterior de FirmaWeb: un proceso por persona, armado en varias llamadas. Se mantiene para que las integraciones hechas sigan funcionando sin cambios. Para una integración nueva usa la v2: envía lotes en una llamada, avisa con firma y permite la firma desatendida. Las dos versiones comparten las credenciales, el token y el saldo, y conviven en la misma cuenta.

Cómo funciona

Si vienes de la plataforma anterior. Lo que cambia al apuntar tu integración al motor nuevo:
  • Dirección base: https://escritorio.firmaweb.app/apifw/v1. Los dominios testing.firmaweb.app y sistema.firmaweb.app son de la plataforma anterior: no los uses, ni para pruebas. Tus cuentas y tu saldo están solo en esta dirección.
  • Credenciales nuevas: las de la plataforma anterior no sirven. Genera el APIUSER y la APIKEY en Administrar → Clave de API. El token de /token sirve también para la v2.
  • horasCaduca sin indicar: el enlace dura el plazo configurado en la cuenta (Administrar → Opciones; por defecto 7 días), no un número fijo de horas. Si lo indicas, se respeta, de 1 a 8760 horas.
  • Expira_en viene en epoch Unix, en segundos.
  • El aviso a urlNotifica llega por cada firma, no solo por la primera, con el mismo cuerpo de siempre y tres intentos. Detalle en Aviso de cada firma.
  • Los PDF firmados también se bajan con la v2 (GET /apifw/v2/documentos/{idDocumento}), sin Base64.
  • /notificar_movil no existe en el motor nuevo. Las demás llamadas conservan sus campos, sus valores de Estado y sus textos.

POST /token

Pedir un token

Sin cuerpo. Las credenciales van en la cabecera Authorization: el APIUSER y la APIKEY unidos por dos puntos y en Base64. El token dura 15 minutos y sirve para la v1 y para la v2.

Expira_en es la hora de vencimiento en epoch Unix, en segundos, no una fecha en texto.

Requiere Authorization: Bearer base64(APIUSER:APIKEY)

Respuestas

200Token emitido
401Sin cabecera, cabecera mal formada o credenciales incorrectas
423Usuario de API bloqueado
429Más de 5 solicitudes de token por minuto desde la misma IP o con el mismo APIUSER; cuentan también las que fallan. Trae Retry-After. Pide un token y reutilízalo sus 15 minutos (límite de solicitudes)

Valores de Estado

EstadoMensajeCuándo
1CorrectoTrae Token, Token_tipo y Expira_en.
97Acceso no autorizadoHTTP 401. Si la cabecera no viene, el cuerpo es { "error_code": 97, "error": "Acceso no autorizado" }.
98Acceso bloqueadoHTTP 423. El usuario de API está bloqueado.
429Demasiadas solicitudesHTTP 429. Espera los segundos de Retry-After.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/token
Respuestas

200 — Correcto

{ "Estado": 1, "Mensaje": "Correcto", "Token": "eyJhbGciOi...", "Token_tipo": "Bearer", "Expira_en": 1791234567 }

401 — Credenciales

{ "Estado": 97, "Mensaje": "Acceso no autorizado" }

429 — Demasiadas

{ "Estado": 429, "Mensaje": "Demasiadas solicitudes" }

POST /crear_proceso

Crear un proceso vacío

Un proceso agrupa los documentos y los firmantes de un envío. Se crea vacío; después se le agregan los documentos, luego los firmantes, y por último se inicia. Guarda IdProceso e IdGrupo: los piden las llamadas siguientes.

Un proceso que no se inicia en 30 días se borra solo, con sus documentos.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
nombrestringREQNombre del proceso. Lo ven tus usuarios en la consola. No se valida el largo.
etiquetastringOPCTexto libre para que tu sistema reconozca el proceso.
notificarinteger (1 o 2)OPC1: FirmaWeb convoca por correo a cada firmante cuando le toca. 2 (por defecto): no envía correos; tu sistema entrega a cada firmante el enlace que devuelve /iniciar_proceso, y ese enlace le sirve cuando le toca firmar, aunque haya varios firmantes.
geolocalizarinteger (0 o 1)OPCCon 1, el firmante debe compartir su ubicación al firmar. Por defecto 0. Un proceso con ubicación no se puede firmar con /firmar.
hojaFinalinteger (0 o 1)OPCCon 1 (por defecto) el PDF firmado lleva una hoja final con los sellos de cada firmante y el código de verificación. Con 0, el sello va donde diga cada firmante en /agregar_firmante.

Respuestas

200El resultado va en Estado, también cuando hay un error de negocio
401Token inválido
403Token vencido
429Más de 300 solicitudes por minuto a la v1, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After

Valores de Estado

EstadoMensajeCuándo
1Proceso creadoTrae IdProceso e IdGrupo.
99Datos faltantesFalta un campo obligatorio, viene vacío o viene en null.
96La cuenta tiene … procesos sin enviar a firma y el tope es …La cuenta llegó al tope de 10.000 procesos sin iniciar: inicia los pendientes o espera a que se borren solos.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/crear_proceso
{ "nombre": "Contrato de trabajo", "etiqueta": "RRHH-2026-0417", "notificar": 1 }
Respuestas

200 — Creado

{ "Estado": 1, "Mensaje": "Proceso creado", "IdProceso": 1000345, "IdGrupo": 1000212 }

200 — Faltan datos

{ "Estado": 99, "Mensaje": "Datos faltantes" }

POST /agregar_documento

Agregar un PDF al proceso

Una llamada por documento, antes de agregar los firmantes: cada firmante queda asociado a los documentos que el proceso tiene en ese momento.

No se comprueba al cargarlo que el archivo sea un PDF válido: si no lo es, la firma falla cuando el firmante intenta firmar. Cada solicitud admite hasta 30 MB.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
idProcesointegerREQEl IdProceso de /crear_proceso.
idGrupointegerREQEl IdGrupo de /crear_proceso.
nombrestringREQNombre del archivo, con extensión. Es el que ve el firmante.
documentostring (Base64)REQEl PDF en Base64.

Respuestas

200El resultado va en Estado, también cuando hay un error de negocio
401Token inválido
403Token vencido
429Más de 300 solicitudes por minuto a la v1, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After

Valores de Estado

EstadoMensajeCuándo
1Documento cargadoTrae IdDocumento.
99Datos faltantesFalta un campo obligatorio, viene vacío o viene en null.
97Proceso no encontradoNo existe o es de otra cuenta.
96Proceso ya iniciadoA un proceso iniciado no se le agregan documentos.
96La cuenta tiene … MB en documentos sin enviar a firma y el tope es … MBLa cuenta llegó al tope de 2 GB sin enviar a firma: inicia los procesos pendientes o espera a que se borren solos.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/agregar_documento
{ "idProceso": 1000345, "idGrupo": 1000212, "nombre": "Contrato.pdf", "documento": "JVBERi0xLjcK... (Base64)" }
Respuestas

200 — Cargado

{ "Estado": 1, "Mensaje": "Documento cargado", "IdDocumento": 1000801 }

200 — No existe

{ "Estado": 97, "Mensaje": "Proceso no encontrado" }

POST /agregar_firmante

Agregar un firmante al proceso

Una llamada por firmante, después de los documentos. Firman en el orden en que se agregan: el segundo recibe su turno cuando el primero termina. Dentro de un proceso no se repite el RUT; el correo sí puede repetirse.

Para que tu firmante registrado firme desde tu sistema con /firmar, agrégalo al final con el mismo RUT y correo de su registro.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
idProcesointegerREQEl IdProceso de /crear_proceso.
idGrupointegerREQEl IdGrupo de /crear_proceso.
nombrestringREQNombres del firmante.
apellidoPaternostringREQApellido paterno. apellidoMaterno es opcional.
rutstringREQRUT con o sin puntos y guion. No se valida el dígito verificador.
emailstringREQCorreo donde recibe el enlace y el PIN.
tipoFirmaintegerOPC1 = FAO, 2 = FES (por defecto). Cualquier otro valor se trata como FES.
paginaFirmaintegerOPCSolo con hojaFinal = 0: página (desde 1) donde va el sello visible.
firmaPosXintegerOPCSolo con hojaFinal = 0: posición horizontal del sello, en puntos PDF desde la esquina inferior izquierda.
firmaPosYintegerOPCSolo con hojaFinal = 0: posición vertical del sello, en puntos PDF desde abajo. Sin los tres, la firma no lleva sello visible.

Respuestas

200El resultado va en Estado, también cuando hay un error de negocio
401Token inválido
403Token vencido
429Más de 300 solicitudes por minuto a la v1, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After

Valores de Estado

EstadoMensajeCuándo
1Firmante creadoTrae IdFirmante.
99Datos faltantesFalta un campo obligatorio, viene vacío o viene en null.
97Proceso no encontradoNo existe o es de otra cuenta.
96Error creando el firmante (FIR)Ese RUT ya está en el proceso, o el proceso ya se inició.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/agregar_firmante
{
  "idProceso": 1000345, "idGrupo": 1000212,
  "nombre": "Jorge", "apellidoPaterno": "Díaz", "apellidoMaterno": "Rojas",
  "rut": "11.111.111-1", "email": "jorge@correo.cl", "tipoFirma": 2
}
Respuestas

200 — Creado

{ "Estado": 1, "Mensaje": "Firmante creado", "IdFirmante": 1000912 }

200 — RUT repetido

{ "Estado": 96, "Mensaje": "Error creando el firmante (FIR)" }

POST /iniciar_proceso

Enviar el proceso a firma

Revisa que haya firmantes y documentos, descuenta del saldo una firma por cada firmante y cada documento, y devuelve en Firmantes un enlace por firmante y por documento. Con notificar = 1, el primer firmante recibe su correo en el acto; los siguientes reciben un correo con un enlace nuevo cuando les toca, y el que devolvió esta llamada deja de servir. Con notificar = 2 no sale ningún correo: los enlaces de esta respuesta sirven para todos los firmantes, cada uno cuando le toca (antes de su turno, el enlace abre el portal sin documentos pendientes), y el plazo de cada uno se cuenta desde que le toca.

Si el firmante en turno deja vencer su enlace sin firmar, el proceso se anula y las firmas que no se usaron vuelven al saldo.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
idProcesointegerREQEl IdProceso de /crear_proceso.
urlCorrectostring (URL)REQAdonde se lleva al firmante después de firmar.
urlCanceladostring (URL)REQAdonde se lleva al firmante si cancela.
urlNotificastring (URL)REQDirección de tu sistema que recibe el aviso de cada firma.
horasCaducaintegerOPCVigencia del enlace de cada firmante, en horas (de 1 a 8760), contada desde que le toca. Sin este campo, o fuera de rango, se usa el plazo de la cuenta (por defecto 7 días; se cambia en Administrar → Opciones).

Respuestas

200El resultado va en Estado, también cuando hay un error de negocio
401Token inválido
403Token vencido
429Más de 300 solicitudes por minuto a la v1, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After

Valores de Estado

EstadoMensajeCuándo
1Proceso iniciadoTrae Firmantes: por cada firmante y documento, Email, Url y Notificado (SI con notificar = 1, NO si no).
99Datos faltantesFalta un campo obligatorio, viene vacío o viene en null.
97Proceso no existeNo existe o es de otra cuenta.
93Error al iniciar el procesoEl proceso ya se había iniciado (o ya terminó).
96Proceso sin firmantesNo tiene firmantes asociados a un documento. Se revisa antes que los documentos: agrega los firmantes después de los documentos.
95Proceso sin documentosNo tiene documentos.
94Firmas insuficientesEl saldo no alcanza. Nada se descuenta.
93Un firmante tiene sus datos bloqueados a petición suyaEsa persona pidió a FirmaWeb no recibir más procesos.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/iniciar_proceso
{
  "idProceso": 1000345,
  "urlCorrecto": "https://tu-sistema.cl/firmaweb/listo",
  "urlCancelado": "https://tu-sistema.cl/firmaweb/cancelado",
  "urlNotifica": "https://tu-sistema.cl/firmaweb/aviso",
  "horasCaduca": 168
}
Respuestas

200 — Iniciado

{
  "Estado": 1, "Mensaje": "Proceso iniciado",
  "Firmantes": [
    { "Email": "jorge@correo.cl", "Url": "https://escritorio.firmaweb.app/logint/1000345/8f2c1a9e_XyZ.../1", "Notificado": "SI" }
  ]
}

200 — Sin saldo

{ "Estado": 94, "Mensaje": "Firmas insuficientes" }

200 — Sin firmantes

{ "Estado": 96, "Mensaje": "Proceso sin firmantes" }

POST /descargar_documento

Descargar el PDF firmado

Devuelve el PDF firmado en Base64, solo cuando ya firmaron todos. Mientras falte una firma responde Estado 96. El mismo documento se puede bajar sin Base64 con GET /apifw/v2/documentos/{idDocumento}.

Requiere Bearer Token

Cuerpo de la petición (JSON)

CampoTipoReq.Descripción
idDocumentointegerREQEl IdDocumento de /agregar_documento.

Respuestas

200El resultado va en Estado, también cuando hay un error de negocio
401Token inválido
403Token vencido
429Más de 300 solicitudes por minuto a la v1, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After

Valores de Estado

EstadoMensajeCuándo
1CorrectoTrae Documento: el PDF firmado en Base64.
99Datos faltantesFalta un campo obligatorio, viene vacío o viene en null.
97Documento no existeNo existe o es de otra cuenta.
96Documento no apto para descargaTodavía le faltan firmas.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/descargar_documento
{ "idDocumento": 1000801 }
Respuestas

200 — Correcto

{ "Estado": 1, "Mensaje": "Correcto", "Documento": "JVBERi0xLjcK... (Base64)" }

200 — Faltan firmas

{ "Estado": 96, "Mensaje": "Documento no apto para descarga" }

POST /consultar_saldos

Firmas disponibles

Sin cuerpo. El saldo de la cuenta: fes_disponibles es firma electrónica simple y fao_disponibles, firma avanzada.

Requiere Bearer Token

Respuestas

200Saldo de la cuenta
401Token inválido
403Token vencido
429Más de 300 solicitudes por minuto a la v1, sumando todas sus llamadas (límite de solicitudes). Trae Retry-After

Valores de Estado

EstadoMensajeCuándo
1CorrectoTrae fes_disponibles y fao_disponibles.
Petición de ejemplo
POST https://escritorio.firmaweb.app/apifw/v1/consultar_saldos
Respuestas

200 — Correcto

{ "Estado": 1, "Mensaje": "Correcto", "fes_disponibles": 480, "fao_disponibles": 0 }

POST tu urlNotifica

Aviso de cada firma (v1)

Cuando alguien firma un documento de un proceso iniciado con /iniciar_proceso, FirmaWeb hace un POST con JSON a la urlNotifica de ese proceso. Llega un aviso por cada firmante y cada documento, siempre con Estado 1; no hay aviso de cierre ni de anulación. Es el cuerpo de la plataforma anterior: sin cabeceras propias y sin firma, distinto de los avisos de la v2.

Para saber si el proceso terminó, cuenta los avisos (firmantes × documentos) o llama a /descargar_documento: responde Estado 1 solo cuando firmaron todos.

Sin firma: comprueba que IdProceso e IdDocumento sean tuyos

Qué debe hacer tu sistema

2xxResponder en menos de 10 segundos. Con eso el aviso queda entregado.
OtroReintentamos a los 7 y a los 20 minutos de la firma; después dejamos de intentar.
El mismo aviso puede llegar más de una vez si tu sistema respondió tarde: trátalo como repetible, usando IdProceso e IdDocumento.
Aviso de ejemplo
{ "IdProceso": 1000345, "IdDocumento": 1000801, "Estado": 1 }

¿Dudas con la integración?

Escríbenos a ayuda@mail.firmaweb.app con la llamada que hiciste y la respuesta que recibiste (sin la clave ni el token).

Todos los derechos reservados | 2026 © FirmaWeb