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
| Necesitas | Usa |
|---|---|
| Enviar a firmar a muchas personas, cada una con sus documentos (liquidaciones, contratos, anexos), con o sin un firmante de la empresa que firma todos | V2 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 sistema | V2 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 firmado | GET /documentos/{idDocumento}, una vez, cuando ya firmaron todos. Sirve para la v1 y la v2 |
Dirección base
| Versión | URL base | Descripción |
|---|---|---|
| V2 | https://escritorio.firmaweb.app/apifw/v2 | Firma masiva (lotes) y firma desatendida. Es la que describe esta página. |
| V1 | https://escritorio.firmaweb.app/apifw/v1 | La 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
Antes de empezar (una vez, en la consola)
- Administrar → Clave de API → Generar credenciales. Aparecen el
APIUSERy laAPIKEY. La clave se muestra una sola vez. - Administrar → Firmantes registrados: registra a quienes firmarán por la empresa. Cada uno activa su firma desde su propia consola.
- 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.
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.
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
- 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.
- Ponerlo como firmante: en los lotes, en
firmantesComunes; en los procesos de/apifw/v1, agregándolo al final conagregar_firmante, con el mismo RUT y correo de su registro. - Mostrarle lo pendiente:
GET /firmas_pendientes. - El botón:
POST /firmar.
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.
Parámetros (en la dirección)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
rutFirmante | string | REQ | RUT del firmante registrado de tu cuenta. |
idLote | integer | OPC | Para ver solo lo pendiente de un lote. |
Respuestas
demasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
rutFirmante | string | REQ | RUT del firmante registrado de tu cuenta. |
codigo | string (6 dígitos) | SEGÚN | El 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. |
idLote | integer | OPC | Para firmar solo lo de un lote. |
procesos | array de integer | OPC | Lista de idProceso, para firmar solo esos. |
Respuestas
demasiados_codigos: más de 5 intentos de código para el mismo firmante en 15 minutos, correctos o no (trae Retry-After)/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
{
"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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
nombre | string ≤80 | REQ | Nombre del lote. Lo ven tus usuarios en la consola. |
referencia | string ≤100 | OPC | Tu 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. |
firmantesComunes | array de string | OPC | RUT de los firmantes registrados que firman todos los procesos, en el orden en que deben firmar. |
urlNotifica | string (URL) | OPC | Direcció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. |
idEmpresa | integer | OPC | Si tu cuenta tiene varias empresas, a cuál corresponde. |
enviar | boolean | OPC | true para enviarlo ahora. Sin él queda en borrador. |
personas[].referencia | string ≤100 | OPC | Tu identificador de la persona (id de trabajador, de contrato…). Vuelve en las respuestas y en los avisos. |
personas[].nombres | string | REQ | Nombres de quien firma. |
personas[].apellidoPaterno | string | REQ | Apellido paterno. apellidoMaterno es opcional. |
personas[].rut | string | REQ | RUT con dígito verificador (se valida). Con o sin puntos. |
personas[].email | string | REQ | Correo 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[] | array | REQ | De 1 a 30 documentos: nombre y pdf (el PDF en Base64, hasta 10 MB cada uno). |
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
{
"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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
personas[].referencia | string ≤100 | OPC | Tu identificador de la persona (id de trabajador, de contrato…). Vuelve en las respuestas y en los avisos. |
personas[].nombres | string | REQ | Nombres de quien firma. |
personas[].apellidoPaterno | string | REQ | Apellido paterno. apellidoMaterno es opcional. |
personas[].rut | string | REQ | RUT con dígito verificador (se valida). Con o sin puntos. |
personas[].email | string | REQ | Correo 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[] | array | REQ | De 1 a 30 documentos: nombre y pdf (el PDF en Base64, hasta 10 MB cada uno). |
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
{
"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.
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
| Estado | Significa |
|---|---|
borrador | Todavía no se envía. |
en_firma | Enviado; 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. |
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
Respuestas
/tokendemasiadas_solicitudes: más de 300 solicitudes por minuto a la v2, sumando todas sus llamadas (límite de solicitudes). Trae Retry-AfterPetición de ejemplo
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.
Eventos
| Evento | Cuándo | Datos |
|---|---|---|
firma | Alguien firmó un documento (cada firmante, cada documento). | idProceso, referencia, idDocumento, documento, firmante |
proceso_completado | Firmaron todos los de una persona: sus documentos ya se pueden descargar. | idProceso, referencia |
proceso_anulado | El proceso de una persona se anuló. | idProceso, referencia |
lote_completado | Ya no queda ninguna persona en firma. | completados, anulados |
Qué debe hacer tu sistema
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.
| HTTP | error | Qué hacer |
|---|---|---|
| 400 | solicitud_invalida | El cuerpo no es un JSON válido. |
| 401 | no_autorizado | Falta el token, no es válido o venció: pide uno nuevo. |
| 402 | saldo_insuficiente | No alcanzan las firmas. Trae necesarias y disponibles. |
| 402 | cuenta_suspendida | La cuenta está suspendida por pago pendiente y toda llamada responde esto: Cuenta suspendida por pago pendiente. Para regularizar, escriba a felipe@certifika.app. |
| 403 | codigo_invalido | El código del firmante no es válido o ya se usó: pídele uno nuevo. |
| 404 | lote_no_existe, documento_no_existe | Revisa el número. |
| 409 | lote_ya_enviado | El lote ya se envió: no admite cambios. |
| 409 | documento_sin_firmar | Todavía faltan firmas. |
| 413 | solicitud_muy_grande | Más de 30 MB: crea el lote en borrador y agrega las personas por tandas. |
| 413 | tope_sin_enviar | La 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. |
| 422 | filas_con_errores | Corrige las filas de filas y reenvía. |
| 422 | firmante_comun_no_registrado | Ese RUT no es un firmante registrado y activo de tu cuenta. |
| 422 | falta_codigo | Envía el código del firmante, o que él dé la autorización permanente. |
| 422 | falta_secreto_avisos | Genera el secreto de avisos en la consola. |
| 422 | falta_nombre, sin_personas, lote_vacio, demasiadas_personas, empresa_no_existe, url_notifica_invalida | Lo explica el mensaje. |
| 429 | demasiadas_solicitudes | Má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. |
| 429 | demasiados_codigos | Solo en /firmar: más de 5 intentos de código para el mismo firmante en 15 minutos. |
| 500 | error_interno | Reintenta. 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ímite | Qué llamadas | Tope | Se cuenta por |
|---|---|---|---|
| General | Todas 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 aparte | IP de origen y cuenta, cada una por separado: basta que una pase el tope |
| Token | POST /apifw/v1/token | 5 por minuto | IP de origen y APIUSER. Cuentan también las que fallan |
| Código del firmante | POST /apifw/v2/firmar con codigo | 5 intentos cada 15 minutos | Firmante 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-Afterdice 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_firmantee/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 /lotesenvía hasta 200 personas en una sola llamada. - Descarga cada PDF una vez, cuando ya está firmado. Para saberlo usa los avisos a tu
urlNotificaen vez de consultar una y otra vez. - Ante un 429, espera los segundos de
Retry-Afterantes 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
- Hasta 1.000 personas por lote (hasta 200 por solicitud: las demás, por tandas sobre el borrador) y 30 documentos por persona; cada PDF, hasta 10 MB.
- Hasta 30 MB por solicitud (unos 20 MB de PDF, porque el Base64 ocupa un tercio más) y 300 solicitudes por minuto (detalle en Límite de solicitudes).
- Una persona aparece una sola vez en el lote (junta todos sus documentos en ella) y no puede ser a la vez firmante común.
- Cobro: una firma por cada firmante y cada documento. Un lote de 200 contratos con un firmante común descuenta 400 firmas. Se descuentan al enviar; las de un proceso anulado que no se usaron vuelven al saldo.
- El enlace de cada firmante dura el plazo de la cuenta desde que le toca firmar (por defecto 7 días; se cambia en Administrar → Opciones), igual que lo enviado desde la consola, y el correo se lo dice. En
/apifw/v1puedes pedir otro plazo conhorasCaduca. - Si el firmante en turno deja vencer su enlace sin firmar, el proceso se anula solo y el saldo vuelve.
- Lo que no se envía a firma tiene tope y plazo: hasta 2 GB en documentos y 10.000 procesos por cuenta, entre borradores y procesos de
/apifw/v1sin iniciar. Los que llevan 30 días sin enviarse se borran solos, con sus documentos.
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
- Todas las llamadas son
POSTcon JSON ahttps://escritorio.firmaweb.app/apifw/v1, y todas menos/tokenllevanAuthorization: Bearer <token>. - Una llamada que llega al motor responde HTTP 200, también cuando hay un error de negocio: el resultado va en
Estado(1si salió bien) yMensajelo explica. Cada llamada tiene su tabla de valores más abajo. - Solo la autenticación responde otro HTTP:
401conEstado 401yMensaje "Acceso denegado"si falta el token, no es válido o se revocó;403conEstado 403y"Token expirado"si venció (pide otro);429conEstado 429y"Demasiadas solicitudes"si pasas de 300 llamadas por minuto a la v1 desde una IP o con una cuenta, en cualquier llamada (espera los segundos deRetry-After; detalle en Límite de solicitudes); y402conEstado 402si la cuenta está suspendida por pago pendiente. - Un cuerpo que no es JSON válido responde
500sin cuerpo. - El orden es
/crear_proceso→/agregar_documento(uno por PDF) →/agregar_firmante(uno por persona, después de los documentos) →/iniciar_proceso. Luego tu sistema recibe el aviso de cada firma y baja el PDF con/descargar_documento.
- Dirección base:
https://escritorio.firmaweb.app/apifw/v1. Los dominiostesting.firmaweb.appysistema.firmaweb.appson 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
APIUSERy laAPIKEYen Administrar → Clave de API. El token de/tokensirve también para la v2. horasCaducasin 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_enviene en epoch Unix, en segundos.- El aviso a
urlNotificallega 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_movilno existe en el motor nuevo. Las demás llamadas conservan sus campos, sus valores deEstadoy 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.
Respuestas
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
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Correcto | Trae Token, Token_tipo y Expira_en. |
| 97 | Acceso no autorizado | HTTP 401. Si la cabecera no viene, el cuerpo es { "error_code": 97, "error": "Acceso no autorizado" }. |
| 98 | Acceso bloqueado | HTTP 423. El usuario de API está bloqueado. |
| 429 | Demasiadas solicitudes | HTTP 429. Espera los segundos de Retry-After. |
Petición de ejemplo
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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
nombre | string | REQ | Nombre del proceso. Lo ven tus usuarios en la consola. No se valida el largo. |
etiqueta | string | OPC | Texto libre para que tu sistema reconozca el proceso. |
notificar | integer (1 o 2) | OPC | 1: 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. |
geolocalizar | integer (0 o 1) | OPC | Con 1, el firmante debe compartir su ubicación al firmar. Por defecto 0. Un proceso con ubicación no se puede firmar con /firmar. |
hojaFinal | integer (0 o 1) | OPC | Con 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
Retry-AfterValores de Estado
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Proceso creado | Trae IdProceso e IdGrupo. |
| 99 | Datos faltantes | Falta un campo obligatorio, viene vacío o viene en null. |
| 96 | La 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
{ "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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
idProceso | integer | REQ | El IdProceso de /crear_proceso. |
idGrupo | integer | REQ | El IdGrupo de /crear_proceso. |
nombre | string | REQ | Nombre del archivo, con extensión. Es el que ve el firmante. |
documento | string (Base64) | REQ | El PDF en Base64. |
Respuestas
Retry-AfterValores de Estado
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Documento cargado | Trae IdDocumento. |
| 99 | Datos faltantes | Falta un campo obligatorio, viene vacío o viene en null. |
| 97 | Proceso no encontrado | No existe o es de otra cuenta. |
| 96 | Proceso ya iniciado | A un proceso iniciado no se le agregan documentos. |
| 96 | La cuenta tiene … MB en documentos sin enviar a firma y el tope es … MB | La 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
{ "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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
idProceso | integer | REQ | El IdProceso de /crear_proceso. |
idGrupo | integer | REQ | El IdGrupo de /crear_proceso. |
nombre | string | REQ | Nombres del firmante. |
apellidoPaterno | string | REQ | Apellido paterno. apellidoMaterno es opcional. |
rut | string | REQ | RUT con o sin puntos y guion. No se valida el dígito verificador. |
email | string | REQ | Correo donde recibe el enlace y el PIN. |
tipoFirma | integer | OPC | 1 = FAO, 2 = FES (por defecto). Cualquier otro valor se trata como FES. |
paginaFirma | integer | OPC | Solo con hojaFinal = 0: página (desde 1) donde va el sello visible. |
firmaPosX | integer | OPC | Solo con hojaFinal = 0: posición horizontal del sello, en puntos PDF desde la esquina inferior izquierda. |
firmaPosY | integer | OPC | Solo con hojaFinal = 0: posición vertical del sello, en puntos PDF desde abajo. Sin los tres, la firma no lleva sello visible. |
Respuestas
Retry-AfterValores de Estado
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Firmante creado | Trae IdFirmante. |
| 99 | Datos faltantes | Falta un campo obligatorio, viene vacío o viene en null. |
| 97 | Proceso no encontrado | No existe o es de otra cuenta. |
| 96 | Error creando el firmante (FIR) | Ese RUT ya está en el proceso, o el proceso ya se inició. |
Petición de ejemplo
{
"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.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
idProceso | integer | REQ | El IdProceso de /crear_proceso. |
urlCorrecto | string (URL) | REQ | Adonde se lleva al firmante después de firmar. |
urlCancelado | string (URL) | REQ | Adonde se lleva al firmante si cancela. |
urlNotifica | string (URL) | REQ | Dirección de tu sistema que recibe el aviso de cada firma. |
horasCaduca | integer | OPC | Vigencia 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
Retry-AfterValores de Estado
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Proceso iniciado | Trae Firmantes: por cada firmante y documento, Email, Url y Notificado (SI con notificar = 1, NO si no). |
| 99 | Datos faltantes | Falta un campo obligatorio, viene vacío o viene en null. |
| 97 | Proceso no existe | No existe o es de otra cuenta. |
| 93 | Error al iniciar el proceso | El proceso ya se había iniciado (o ya terminó). |
| 96 | Proceso sin firmantes | No tiene firmantes asociados a un documento. Se revisa antes que los documentos: agrega los firmantes después de los documentos. |
| 95 | Proceso sin documentos | No tiene documentos. |
| 94 | Firmas insuficientes | El saldo no alcanza. Nada se descuenta. |
| 93 | Un firmante tiene sus datos bloqueados a petición suya | Esa persona pidió a FirmaWeb no recibir más procesos. |
Petición de ejemplo
{
"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}.
Cuerpo de la petición (JSON)
| Campo | Tipo | Req. | Descripción |
|---|---|---|---|
idDocumento | integer | REQ | El IdDocumento de /agregar_documento. |
Respuestas
Retry-AfterValores de Estado
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Correcto | Trae Documento: el PDF firmado en Base64. |
| 99 | Datos faltantes | Falta un campo obligatorio, viene vacío o viene en null. |
| 97 | Documento no existe | No existe o es de otra cuenta. |
| 96 | Documento no apto para descarga | Todavía le faltan firmas. |
Petición de ejemplo
{ "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.
Respuestas
Retry-AfterValores de Estado
| Estado | Mensaje | Cuándo |
|---|---|---|
| 1 | Correcto | Trae fes_disponibles y fao_disponibles. |
Petición de ejemplo
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.
Qué debe hacer tu sistema
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