API FirmaWeb

Integración de Firma Electrónica Simple (FES) y Firma Electrónica Avanzada (FAO) mediante FirmaWeb.

Introducción

El API REST de FirmaWeb permite integrar flujos de firma electrónica en tu plataforma. Todas las peticiones utilizan JSON, requieren autenticación mediante JWT Bearer Token y son controladas por Acceso IP. Las IPs de origen deben estar registradas previamente en tu cuenta FirmaWeb.

Entornos disponibles

Entorno	URL base	Descripción
DEV	https://testing.firmaweb.app/apifw/v1	Servidor de pruebas para desarrollo e integración. Los datos no son reales.
PROD	https://sistema.firmaweb.app/apifw/v1	Servidor productivo. Utilizar credenciales reales y datos válidos.

Flujo de integración típico

Paso 1

Autenticar

Obtener un JWT Token con tus credenciales de cliente.

Paso 2

Crear proceso

Crear el proceso de firma y guardar IdProceso e IdGrupo.

Paso 3

Agregar documentos

Cargar los PDFs en Base64 al proceso.

Paso 4

Agregar firmantes

Registrar cada firmante con RUT, email y tipo de firma.

Paso 5

Iniciar proceso

Generar las URLs de firma y activar notificaciones.

Paso 6

Descargar documento

Obtener el PDF firmado (disponible 20 días).

Autenticación

Todas las solicitudes protegidas requieren un JWT Bearer Token en el encabezado HTTP:

Authorization: Bearer <token>

Para obtener el token, envía tus credenciales codificadas en Base64 al endpoint POST /token:

Authorization: Bearer base64(usuario:clave)

El token tiene una validez de 15 minutos. Pasado ese tiempo debes solicitar uno nuevo.

Códigos de estado del API

El campo Estado en las respuestas JSON indica el resultado de la operación, independiente del HTTP status code.

1 Éxito

93 Credenciales inválidas

94 IP no autorizada

95 Proceso sin documentos

96 Documento no disponible

97 Recurso no encontrado

98 Sin saldo suficiente

99 Datos inválidos

100 Error interno

Autenticación

POST /token

Generar token de acceso

Autentica al cliente API con credenciales codificadas en Base64 (usuario:clave). Retorna un JWT Bearer Token válido por 15 minutos, requerido en todas las solicitudes protegidas.

Requiere Bearer Token

Encabezados HTTP

Nombre	Tipo	Req.	Descripción
Authorization	string	req	Credenciales en formato `Bearer base64(usuario:clave)`.
Content-Type	string	req	Tipo de contenido de la petición.

Respuestas

200 Token generado correctamente

401 Credenciales inválidas o IP no autorizada

Encabezados de ejemplo

Authorization: Bearer dXN1YXJpbzpwYXNzd29yZA==
Content-Type: application/json

Respuestas

Procesos

POST /crear_proceso

Crear proceso de firma

Crea el contenedor principal que agrupará documentos y firmantes. Retorna IdProceso e IdGrupo necesarios en los pasos siguientes.

Requiere Bearer Token

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
nombre	string ≤100	req	Nombre descriptivo del proceso.
notificar	integer	req	Enviar correos a los firmantes. `1` = Sí \| `2` = No.
etiqueta	string ≤15	opt	Etiqueta para clasificar el proceso (opcional).
geolocalizar	integer	opt	Solicitar geolocalización al firmar. `1` = Sí \| `0` = No.
hojaFinal	integer	req	Agregar hoja final con firmas y QR. `1` = Sí \| `0` = No.

Respuestas

200 Proceso creado correctamente

200 Sin saldo de firmas disponible

401 Token inválido o expirado

Petición de ejemplo

Respuestas

POST /iniciar_proceso

Iniciar proceso de firma

Activa el flujo de firma: genera URLs temporales únicas para cada firmante y, si notificar=1, envía correos automáticos. Requisito: el proceso debe tener al menos un documento y un firmante.

Requiere Bearer Token

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
idProceso	integer	req	ID del proceso a iniciar.
urlCorrecto	string ≤250	req	URL de redirección al completar la firma exitosamente.
urlCancelado	string ≤250	req	URL de redirección cuando el firmante cancela el proceso.
urlNotifica	string ≤250	req	Endpoint de tu servidor que recibirá las notificaciones webhook.
horasCaduca	integer	opt	Validez del enlace de firma en horas (1–360). Por defecto: 48.

Respuestas

200 Proceso iniciado — retorna URLs de firma por firmante

200 Proceso sin documentos o sin firmantes

401 Token inválido o expirado

Petición de ejemplo

Respuestas

Documentos

POST /agregar_documento

Agregar documento al proceso

Agrega un PDF codificado en Base64 al proceso. Retorna el IdDocumento para referenciarlo en la descarga. Se pueden agregar múltiples documentos por proceso.

Requiere Bearer Token

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
idProceso	integer	req	ID del proceso.
idGrupo	integer	req	ID del grupo del proceso.
nombre	string ≤150	req	Nombre del archivo con extensión `.pdf`.
documento	string	req	Contenido del PDF codificado en Base64.

Respuestas

200 Documento cargado exitosamente

200 Proceso no encontrado

401 Token inválido o expirado

Petición de ejemplo

Respuestas

POST /descargar_documento

Descargar documento firmado

Descarga el PDF firmado codificado en Base64. Disponible durante 20 días desde la fecha de firma. Pasado ese período el documento no estará disponible para descarga.

Requiere Bearer Token

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
idDocumento	integer	req	ID del documento firmado a descargar.

Respuestas

200 Documento disponible — retorna el PDF en Base64

200 Documento no disponible para descarga

401 Token inválido o expirado

Petición de ejemplo

Respuestas

Firmantes

POST /agregar_firmante

Agregar firmante al proceso

Agrega un firmante al proceso y lo asocia a todos los documentos pendientes del grupo. El campo tipoFirma determina el tipo de saldo que se consumirá (FES o FAO).

Requiere Bearer Token

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
idProceso	integer	req	ID del proceso.
idGrupo	integer	req	ID del grupo del proceso.
nombre	string ≤100	req	Nombre del firmante.
apellidoPaterno	string ≤60	req	Apellido paterno del firmante.
apellidoMaterno	string ≤60	opt	Apellido materno (opcional).
rut	string	req	RUT del firmante en formato `11111111-1`.
email	string	req	Correo electrónico del firmante.
tipoFirma	integer	req	Tipo de firma. `1` = Firma Avanzada (FAO) \| `2` = Firma Simple (FES).
paginaFirma	integer	opt	Página donde se imprimirá la firma (cuando `hojaFinal=0`).
firmaPosX	integer	opt	Posición X de la firma en la página.
firmaPosY	integer	opt	Posición Y de la firma en la página.

Respuestas

200 Firmante agregado correctamente

200 Proceso no encontrado

401 Token inválido o expirado

Petición de ejemplo

Respuestas

Saldos

POST /consultar_saldos

Consultar saldos disponibles

Retorna la cantidad de firmas FES (Firma Simple) y FAO (Firma Avanzada) disponibles para el cliente. No requiere cuerpo en la petición.

Requiere Bearer Token

Respuestas

200 Saldos obtenidos

401 Token inválido o expirado

Respuestas

Notificaciones

POST /notificar_movil

Notificar via APP movil

Envía una notificación push al firmante mediante la APP móvil de FirmaWeb. Útil cuando el firmante tiene la app instalada y prefiere firmar desde su dispositivo móvil.

Requiere Bearer Token

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
idProceso	integer	req	ID del proceso.
Email	string	req	Correo del firmante registrado en el proceso.

Respuestas

200 Notificación enviada correctamente

200 Firmante sin app instalada o proceso no encontrado

401 Token inválido o expirado

Petición de ejemplo

Respuestas

Webhooks

POST /webhook_test

Prueba de recepcion de webhook

Endpoint de prueba para simular la recepción de webhooks. FirmaWeb enviará un POST a tu urlNotifica cada vez que un documento sea firmado o rechazado. Usa este endpoint para validar tu implementación antes de ir a producción.

Sin autenticación

Cuerpo de la petición (JSON)

Campo	Tipo	Req.	Descripción
IdProceso	integer	req	ID del proceso.
IdDocumento	integer	req	ID del documento.
Estado	integer	req	Estado del documento. `1` = Firmado \| `2` = Rechazado.

Respuestas

200 Webhook recibido correctamente

Petición de ejemplo