En esta página
Webhooks
Recibe en tu servidor un aviso firmado cuando el SRI autoriza o rechaza un comprobante, o cuando no se pudo emitir, sin consultar el seguimiento.
Cuando emites un comprobante, el resultado del SRI llega minutos después. En lugar de preguntar por él una y otra vez, puedes pedirnos que te avisemos. Configuras en el portal una URL de tu servidor y, cada vez que hay un resultado, te enviamos a esa URL un mensaje firmado con los datos del comprobante.
Esta página explica cómo configurar ese destino en el portal, qué eventos recibes y qué hacer ante cada uno, cómo se reintentan las entregas y cómo escribir el endpoint que las recibe, con ejemplos en cada lenguaje. Al terminar tendrás un endpoint que verifica la firma, descarta los duplicados y responde a tiempo, probado primero en tu computador.
Importante
Ambiente de pruebas: sin validez fiscal. Configura y prueba tu destino primero
en el portal, https://portal.mynexusapi.com.
Para agentes#
Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.
Pega este prompt en un agente de programación con acceso a la terminal:
Implementa en este proyecto el receptor de webhooks de Ecuafact con verificación de firma y pruébalo en local. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/webhooks.md antes de escribir código; no inventes campos. Reutiliza el framework web y el lenguaje del proyecto y recomiéndame usar el verificador de webhooks del SDK de Ecuafact de ese lenguaje, con una frase de motivo (si prefiero no usarlo, impleméntalo según la guía); no inventes el formato de la firma, tómalo de la guía webhooks-firma. El endpoint debe leer el cuerpo crudo, verificar la firma de Ecuafact-Signature con el secreto del destino, rechazar firmas inválidas o con marca de tiempo fuera de tolerancia, deduplicar por eventType y resourceId, guardar el evento y responder 2xx rápido, procesando después. Lee el secreto del webhook de la variable ECUAFACT_WEBHOOK_SECRET sin mostrarlo; si falta, pídeme que lo copie del portal de pruebas (el destino de webhooks) y lo configure yo mismo en mi entorno o en un .env ignorado por git; nunca lo pegues en el chat ni lo imprimas. Decide por estado y codEstado del cuerpo, no por el texto de los mensajes. Prueba con el evento de prueba, con una firma válida y con una alterada, siguiendo la sección Probar en local de la guía. Reutiliza ECUAFACT_API_KEY sin mostrarla si necesitas emitir un comprobante que genere eventos. Ejecuta las pruebas e informa solo qué casos pasaron, la ruta del receptor y cualquier acción que yo deba hacer.
Conceptos#
Cuando emites, la API responde 202 Accepted. Eso significa que el comprobante
quedó recibido, pero todavía no tiene resultado del
SRI, que llega minutos después. Tienes dos formas de
conocer ese resultado:
- Seguimiento. Tu sistema pregunta cada cierto tiempo con
GET /v1/operaciones/{idOperacion}, como se explica en Seguimiento de una operación. - Webhook. Te enviamos un
POSTa una URL tuya, el destino, cuando el resultado está listo. Cada envío es un evento y va firmado con un secreto que solo conocen tu servidor y nuestro servicio.
Con los webhooks te ahorras las consultas repetidas y te enteras en cuanto hay resultado. Aun así, te recomendamos conservar el seguimiento como respaldo, porque un webhook puede llegar tarde, llegar repetido o no llegar si tu destino está pausado.
Un destino puede recibir los eventos de todos los contribuyentes de tu
integración o solo los de un RUC. En el portal, el destino nuevo queda para
todos; por API puedes indicar un RUC concreto. Para saber a qué comprobante
corresponde cada evento, usa el idOperacion y el ruc del cuerpo.
Prerequisitos#
- Acceso al portal del cliente con permiso para editar Eventos. En
pruebas y producción, el portal es
https://portal.mynexusapi.com. - Un endpoint HTTPS público en el puerto 443 que acepte
POST. Para desarrollar en tu computador, publícalo con un túnel, como se explica en Probar en local. - Una API Key de pruebas para emitir comprobantes que generen eventos. Si todavía no tienes una, crea tu sandbox.
- Un lugar seguro para guardar el secreto del destino, como la variable de
entorno
ECUAFACT_WEBHOOK_SECRETo tu gestor de secretos.
Cómo funciona#
Desde que emites hasta que tu servidor procesa el resultado pasan estos pasos:
- Emites un comprobante y recibes un 202 con el
idOperacion. - Enviamos el comprobante al SRI y esperamos su resultado.
- Con el resultado, te enviamos un evento (
document.authorized,document.rejectedodocument.failed) a cada destino activo suscrito a ese evento. - Tu servidor lee el cuerpo crudo, verifica la firma, guarda el evento y responde un 2xx en menos de 15 segundos.
- Si tu servidor no responde a tiempo, no se puede conectar o responde 408, 429 o 5xx, reintentamos con esperas crecientes, hasta 8 intentos. Si responde otro 4xx o un 3xx, la entrega queda rechazada por tu servidor y no se reintenta. El detalle está en Reintentos y qué se considera fallo.
Configurar el destino en el portal#
Un destino es la URL de tu servidor que recibe los eventos. Créalo desde el portal del cliente siguiendo estos pasos:
- Entra al portal del cliente y abre Integración > Eventos.
- Pulsa Nuevo destino.
- En URL escribe la dirección completa de tu endpoint, por ejemplo
https://erp.tu-empresa.com/webhooks/ecuafact. - Marca los eventos que quieres recibir: Documento autorizado
(
document.authorized), Documento rechazado (document.rejected), Documento no emitido (document.failed) y Operación requiere atención (operation.requires_attention), que avisa una sola vez cuando un comprobante siguerecibidosin resultado confirmado. Los cuatro vienen marcados y debes dejar al menos uno. - Pulsa Crear. El portal muestra el secreto del destino.
- Copia el secreto y guárdalo en la variable
ECUAFACT_WEBHOOK_SECRETde tu servidor. - Pulsa Probar para recibir un evento de prueba y confirma en Entregas que su estado es Entregado y que la columna HTTP muestra 200.
Atención
El secreto se muestra una sola vez, al crear el destino o al rotarlo. Si lo pierdes, usa Rotar secreto y actualiza tu servidor. Nunca lo publiques en tu repositorio, en logs ni en el código del navegador, porque con él cualquiera puede falsificar eventos.
Cada ambiente tiene su propio portal y sus propios destinos, así que configura
un destino en pruebas y otro en producción. Como el cuerpo del evento no indica
el ambiente, usa una URL distinta para cada uno, por ejemplo
/webhooks/ecuafact/pruebas y /webhooks/ecuafact/produccion.
Requisitos de la URL#
La URL del destino debe cumplir estos requisitos. El portal rechaza al crear el destino una URL que no cumpla alguno de los cinco primeros; las redirecciones, en cambio, se detectan en cada entrega.
| Requisito | Detalle |
|---|---|
| Esquema | Solo se admite https://. |
| Puerto | Solo se admite el 443, que es el puerto por defecto de HTTPS. |
| Credenciales en la URL | No se admiten (https://usuario:clave@...). Tu servidor autentica cada entrega con la firma. |
| Formato | Hasta 2048 caracteres, sin espacios ni caracteres de control. |
| Red | El nombre debe resolver a una IP pública. Se rechazan localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, 0.0.0.0/8, el resto de rangos reservados, y las IPv6 locales, de enlace local o multicast. |
| Redirecciones | No se siguen. Una respuesta 3xx, por ejemplo 301 o 302, deja la entrega rechazada por tu servidor, sin reintentos. Registra la URL final. |
Acciones del portal#
Cada destino tiene estas acciones en Integración > Eventos.
| Acción | Qué hace |
|---|---|
| Nuevo destino | Crea un destino con su URL, sus eventos y un secreto nuevo. Para cambiar la URL de un destino, crea uno nuevo y deshabilita el anterior. |
| Probar | Envía a ese destino el evento de prueba operation.requires_attention, descrito en Evento de prueba. |
| Entregas | Muestra las últimas 50 entregas del destino, con la fecha, el evento, el estado, el número de intento y el código HTTP que respondió tu servidor. |
| Intentos | En la tabla de Entregas, muestra el historial de intentos de esa entrega, con la fecha, el número de intento, el resultado, el código HTTP, la causa del error y la duración en milisegundos. |
| Reenviar | En la tabla de Entregas, vuelve a enviar ese evento ahora, con el mismo cuerpo y una firma nueva. |
| Rotar secreto | Genera un secreto nuevo y lo muestra una vez. Las entregas siguientes se firman con el nuevo, como se explica en Rotación del secreto. |
| Pausar / Reanudar | Detiene o reactiva la entrega de eventos nuevos a ese destino. Las entregas que ya estaban programadas antes de la pausa siguen con sus reintentos. Un destino pausado no recibe el evento de Probar. |
| Deshabilitar | Da de baja el destino. Un destino deshabilitado no se puede reactivar; para volver a recibir eventos, crea uno nuevo. |
Administrar destinos por API#
Puedes administrar los destinos desde el Portal del Cliente (Integración > Eventos), con el CLI (ecuafact webhooks), con el servidor MCP o con la API REST. Los SDK no administran destinos: solo verifican la firma de los webhooks que recibes.
Si tu integración administra varios RUC o quieres automatizar el alta de
destinos, usa los endpoints de webhooks con la cabecera X-Api-Key. Son la misma
capacidad del portal, expuesta para clientes y socios, así que no necesitas una
sesión del portal. Puedes listar, crear y consultar destinos, cambiar los eventos
a los que están suscritos, rotar su secreto, probarlos, pausarlos, reanudarlos y
deshabilitarlos, además de revisar sus entregas y reintentar una.
La URL base es https://api-sandbox.mynexusapi.com en pruebas y
https://api.mynexusapi.com en producción. Las operaciones que envían un cuerpo
usan Content-Type: application/json.
| Método y ruta | Para qué | Scope |
|---|---|---|
GET /v1/webhooks/destinos |
Lista los destinos que puede ver la llave | webhooks:leer |
GET /v1/webhooks/destinos/{id} |
Consulta un destino | webhooks:leer |
POST /v1/webhooks/destinos |
Crea un destino y devuelve el secreto una vez | webhooks:gestionar |
PUT /v1/webhooks/destinos/{id}/eventos |
Reemplaza los eventos suscritos | webhooks:gestionar |
POST /v1/webhooks/destinos/{id}/rotar-secreto |
Rota el secreto y lo devuelve una vez | webhooks:gestionar |
POST /v1/webhooks/destinos/{id}/probar |
Envía el evento de prueba | webhooks:probar |
POST /v1/webhooks/destinos/{id}/pausar |
Pausa las entregas nuevas | webhooks:gestionar |
POST /v1/webhooks/destinos/{id}/reanudar |
Reactiva el destino | webhooks:gestionar |
POST /v1/webhooks/destinos/{id}/deshabilitar |
Da de baja el destino | webhooks:gestionar |
GET /v1/webhooks/destinos/{id}/entregas |
Lista las últimas 50 entregas | webhooks:leer |
GET /v1/webhooks/destinos/{id}/entregas/{entregaId}/intentos |
Lista los intentos de una entrega | webhooks:leer |
POST /v1/webhooks/destinos/{id}/entregas/{eventoId}/reintentar |
Reenvía un evento ahora | webhooks:reintentar |
La columna Scope aplica a los agentes que se conectan con OAuth, como los de nuestro servidor MCP, que solo pueden usar las operaciones cuyo scope les concediste. Una API Key no necesita scopes: con ella puedes usar las doce operaciones sobre los destinos de los RUC que tiene permitidos.
Parámetros de ruta#
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id |
UUID | Sí, salvo al listar y al crear | El publicId del destino, tal como lo devuelven la creación y el listado. |
entregaId |
UUID | Sí, al listar intentos | El publicId de la entrega, tal como lo devuelve el listado de entregas. |
eventoId |
UUID | Sí, al reintentar | El eventId de la entrega, tal como lo devuelve el listado de entregas. Identifica el evento que se reenvía. |
Crear un destino#
El cuerpo para crear un destino es:
{
"url": "https://erp.tu-empresa.com/webhooks/ecuafact",
"eventos": ["document.authorized", "document.rejected", "document.failed"],
"ruc": "0123456789001"
}
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
url |
string | Sí | URL HTTPS de tu endpoint, de hasta 2048 caracteres y sin espacios. Debe cumplir los requisitos de la URL. |
eventos |
arreglo de string | Sí | Al menos uno de document.authorized, document.rejected, document.failed y operation.requires_attention. Los repetidos se ignoran. |
ruc |
string | No | RUC de 13 dígitos. Si lo omites, el destino recibe los eventos de todos los RUC. |
Si envías ruc, el destino solo recibe los eventos de ese contribuyente. Una API
Key limitada a uno o varios RUC no puede crear un destino para todos ni para un
RUC que no tenga permitido. La respuesta incluye ruc para que puedas distinguir
ambos casos.
La respuesta es un 201 Created con la cabecera Location del destino:
{
"publicId": "3f2b8c1e-5a47-4d0e-9b61-0c7d2e8f1a90",
"url": "https://erp.tu-empresa.com/webhooks/ecuafact",
"secretoUnaVez": "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=",
"ruc": "0123456789001"
}
| Campo | Tipo | Descripción |
|---|---|---|
publicId |
string (UUID) | Identificador del destino, el id de las demás operaciones. |
url |
string | URL registrada. |
secretoUnaVez |
string | Secreto de firma. Solo se muestra en esta respuesta y en la rotación. |
ruc |
string o null |
RUC del destino, o null si recibe todos. |
La rotación del secreto devuelve esta misma forma, con el secreto nuevo en
secretoUnaVez. El secreto se muestra una sola vez, en la respuesta de
creación o de rotación, así que guárdalo en cuanto lo recibas.
Consultar y listar destinos#
GET /v1/webhooks/destinos devuelve un arreglo con los destinos de tu
integración que tu API Key puede ver, y GET /v1/webhooks/destinos/{id} devuelve
uno solo. Un destino deshabilitado no aparece en el listado y su consulta
responde 404.
{
"publicId": "3f2b8c1e-5a47-4d0e-9b61-0c7d2e8f1a90",
"url": "https://erp.tu-empresa.com/webhooks/ecuafact",
"state": "active",
"fallosConsecutivos": 0,
"ultimoFallo": null,
"creado": "2026-11-13T15:04:05.123Z",
"eventos": ["document.authorized", "document.rejected", "document.failed"],
"ruc": "0123456789001"
}
| Campo | Tipo | Descripción |
|---|---|---|
publicId |
string (UUID) | Identificador del destino. |
url |
string | URL registrada. |
state |
string | active si recibe eventos, o paused si está pausado, por ti o por fallos consecutivos. |
fallosConsecutivos |
integer | Fallos seguidos que cuentan para la pausa automática. Un 2xx lo reinicia. |
ultimoFallo |
string o null |
Fecha y hora del último fallo, en UTC. |
creado |
string | Fecha y hora de creación, en UTC. |
eventos |
arreglo de string | Eventos a los que está suscrito. |
ruc |
string o null |
RUC del destino, o null si recibe todos. |
Cambiar los eventos de un destino#
PUT /v1/webhooks/destinos/{id}/eventos reemplaza la lista completa de eventos.
Envía todos los que quieres recibir, no solo los nuevos.
{
"eventos": ["document.authorized", "document.failed"]
}
La operación responde 204 sin cuerpo. Con una lista vacía o con un evento que no existe, responde 400.
Probar, pausar, reanudar, deshabilitar y reintentar#
Las operaciones probar y reintentar responden 202 sin cuerpo, porque la
entrega ocurre después; revisa su resultado en las entregas del destino. Las
operaciones pausar, reanudar y deshabilitar responden 204 sin cuerpo.
Pausar detiene los eventos nuevos, reanudar reinicia el contador de fallos y
deshabilitar da de baja el destino de forma definitiva. El efecto de cada una es
el de la acción del portal con el mismo nombre, que se describe en
Acciones del portal. Las entregas, los reintentos y el
reenvío siguen las reglas de Entrega y de
Reintentos. El evento de prueba conserva
probe en "true" y, si el destino es de un RUC, incluye ese ruc.
Entregas e intentos#
GET /v1/webhooks/destinos/{id}/entregas devuelve las últimas 50 entregas del
destino.
[
{
"publicId": "8a1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"eventId": "5b6c7d8e-9f01-4a2b-8c3d-4e5f6a7b8c9d",
"intento": 1,
"estado": "sent",
"programado": "2026-11-13T15:04:05Z",
"enviado": "2026-11-13T15:04:06Z",
"httpStatus": 200,
"codigoError": null,
"tipoEvento": "document.authorized"
}
]
| Campo | Tipo | Descripción |
|---|---|---|
publicId |
string (UUID) | Identificador de la entrega, el entregaId de los intentos. |
eventId |
string (UUID) | Identificador del evento, el eventoId del reintento. Es el mismo valor que viaja en webhook-id. |
intento |
integer | Número del intento de esta entrega. |
estado |
string | pending espera su envío, leased se está enviando, sent se entregó, failed falló y se reintentará, rejected la rechazó tu servidor y dead agotó los intentos. Corresponden a los estados que el portal muestra en Estados de una entrega. |
programado |
string | Fecha y hora, en UTC, para la que se programó el envío. |
enviado |
string o null |
Fecha y hora del envío, en UTC. |
httpStatus |
integer o null |
Código HTTP que respondió tu servidor. null si no hubo respuesta. |
codigoError |
string o null |
error_servicio cuando hubo un error y null si no. La causa exacta está en los intentos. |
tipoEvento |
string | Tipo del evento entregado. |
GET /v1/webhooks/destinos/{id}/entregas/{entregaId}/intentos devuelve hasta 20
intentos de una entrega.
[
{
"intento": 1,
"fecha": "2026-11-13T15:04:06Z",
"httpStatus": 503,
"codigoError": null,
"duracionMs": 412,
"resultado": "retry"
}
]
| Campo | Tipo | Descripción |
|---|---|---|
intento |
integer | Número del intento. |
fecha |
string | Fecha y hora del intento, en UTC. |
httpStatus |
integer o null |
Código HTTP que respondió tu servidor. null si no hubo respuesta. |
codigoError |
string o null |
Causa cuando no hubo respuesta HTTP: webhook_timeout, webhook_dns, webhook_conexion, webhook_tls o webhook_transporte. Cualquier otro error del envío se informa como error_servicio. |
duracionMs |
integer o null |
Duración del intento en milisegundos. |
resultado |
string | delivered si tu servidor respondió 2xx, retry si falló y se reintentará, rejected si tu servidor rechazó la entrega y dead si agotó los intentos. |
Administrar destinos desde el CLI#
El grupo ecuafact webhooks destinos usa la API Key del perfil y el entorno
actuales, así que no necesitas una sesión del portal. Cada subcomando indica su
método y su ruta, y respeta los mismos scopes de la tabla anterior.
# Lista los destinos que puede ver la llave y consulta uno.
ecuafact webhooks destinos listar --entorno sandbox
ecuafact webhooks destinos ver <idDestino> --entorno sandbox
# Crea un destino para todos los RUC con los cuatro eventos.
ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact --entorno sandbox
# Crea un destino limitado a un RUC y a dos eventos.
ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact \
--eventos document.authorized,document.failed --ruc 0123456789001 --entorno sandbox
# Reemplaza los eventos suscritos de un destino.
ecuafact webhooks destinos eventos <idDestino> --eventos document.authorized,document.failed --entorno sandbox
# Pide a la plataforma que envíe el evento de prueba a un destino.
ecuafact webhooks destinos probar-destino <idDestino> --entorno sandbox
# Pausa, reanuda, rota el secreto o da de baja el destino.
ecuafact webhooks destinos pausar <idDestino> --entorno sandbox
ecuafact webhooks destinos reanudar <idDestino> --entorno sandbox
ecuafact webhooks destinos rotar <idDestino> --entorno sandbox
ecuafact webhooks destinos deshabilitar <idDestino> --entorno sandbox
# Consulta las últimas 50 entregas, los intentos de una y reenvía un evento.
ecuafact webhooks destinos entregas <idDestino> --entorno sandbox
ecuafact webhooks destinos intentos <idDestino> <entregaId> --entorno sandbox
ecuafact webhooks destinos reintentar <idDestino> <eventoId> --entorno sandbox
crear y rotar devuelven el secreto una sola vez. En la salida de tabla se
muestra; con --salida json o --salida csv solo aparece si agregas
--mostrar-secreto. El CLI nunca guarda el secreto en un archivo ni lo escribe
en un mensaje. Si usas --eventos, sepáralos con coma y elige entre
document.authorized, document.rejected, document.failed y
operation.requires_attention; si lo omites, se suscriben los cuatro.
Administrar destinos en Postman#
La colección trae la carpeta 08 · Webhooks con una petición por operación:
08.1 · Crear destino, 08.2 · Listar destinos, 08.3 · Pausar destino,
08.4 · Reanudar destino, 08.5 · Rotar secreto, 08.6 · Entregas,
08.7 · Reintentar entrega, 08.8 · Deshabilitar destino, 08.9 · Consultar destino, 08.10 · Cambiar eventos del destino, 08.11 · Probar destino y 08.12 · Intentos de una entrega. Usa {{baseUrl}} y
{{apiKey}} del environment, y {{identificacion}} en el ruc del destino.
Al crear un destino, la prueba guarda su publicId en {{idDestino}}; al
listar entregas, guarda el primer eventId en {{eventoId}} para el reintento.
La colección no guarda ni imprime el secreto: cópialo de la respuesta de
08.1 o 08.5 y guárdalo en tu servidor.
Estados de este endpoint#
Todas las respuestas de error usan el cuerpo plano con estado, codEstado,
msgError y errores, como se explica en Errores. En las
validaciones, errores trae el detalle del campo.
codEstado |
HTTP | Operación | Cuándo ocurre | Qué hacer |
|---|---|---|---|---|
| - | 200, 201, 202, 204 | Todas | La operación se aceptó: 200 en consultas y rotación, 201 en la creación, 202 en probar y reintentar, y 204 en el resto. |
Usa la respuesta. En la creación y la rotación, guarda secretoUnaVez. |
3003 (solicitud_invalida) |
400 | Crear | La url falta, no es HTTPS, usa un puerto distinto del 443, trae credenciales, supera 2048 caracteres, no resuelve o apunta a una red no pública. También ocurre si ruc no tiene 13 dígitos o si eventos está vacío o trae un evento desconocido. |
Corrige el campo indicado en errores. Los requisitos están en Requisitos de la URL. |
3003 (solicitud_invalida) |
400 | Reemplazar eventos | eventos está vacío o trae un evento desconocido. |
Envía al menos uno de los cuatro eventos del contrato. |
3009 (credenciales_invalidas) |
401 | Todas | La API Key falta o no es válida. | Revisa la API Key, como se explica en Autenticación. |
3010 (ip_no_autorizada) |
403 | Todas | La IP no está permitida o no se pudo identificar. | Registra tu IP en Cuenta > IP permitidas. |
3011 (acceso_denegado) |
403 | Crear | Tu API Key no tiene alcance para el ruc indicado, o para todos los RUC cuando lo omites. |
Usa un RUC de /v1/contexto o una API Key con alcance para todos los RUC. |
3011 (acceso_denegado) |
403 | Todas | Un agente conectado con OAuth no tiene concedido el scope de la operación. | Concede al agente el scope de la tabla de operaciones. |
3013 (no_encontrado) |
404 | Las que reciben {id} |
El destino no existe, está deshabilitado o pertenece a un RUC que tu API Key no puede ver. | Verifica el id con el listado de destinos. |
3003 (solicitud_invalida) |
400 | Crear, reanudar | En el ambiente de pruebas ya tienes 10 destinos sin deshabilitar. errores lo indica. |
Deshabilita uno de los destinos que ya no uses. |
3006 (cuerpo_excedido) |
413 | Crear, reemplazar eventos | El cuerpo supera el tamaño permitido. | Envía un cuerpo más pequeño. |
| sin cuerpo | 415 | Crear, reemplazar eventos | El Content-Type no es application/json. |
Envía el Content-Type correcto. |
5005 (limite_solicitudes) |
429 | Todas | Superaste el límite de solicitudes. | Espera los segundos que indica Retry-After y reintenta. |
Entrega#
Cada entrega es una petición HTTP con estas características.
| Elemento | Valor |
|---|---|
| Método | POST a la URL del destino. |
Content-Type |
application/json; charset=utf-8 |
Ecuafact-Signature |
t=<epoch_segundos>,v1=<hmac_sha256_hex>. Cómo verificarla: Verificación de firma. |
webhook-id, webhook-timestamp y webhook-signature |
La misma entrega firmada según el estándar abierto Standard Webhooks, que puedes verificar con sus librerías oficiales en lugar de Ecuafact-Signature. webhook-id es el mismo en todos los reintentos y reenvíos del evento. Cómo verificarlas: Standard Webhooks. |
| Cuerpo | Objeto JSON compacto, sin espacios ni saltos de línea, codificado en UTF-8. |
| Tiempo de espera | 15 segundos. Si tu servidor no termina de responder en ese tiempo, la entrega cuenta como fallo y se reintenta. |
| Éxito | Cualquier código 2xx. El cuerpo de tu respuesta se ignora. |
| Fallo que se reintenta | La falta de respuesta (tiempo de espera agotado, dominio que no resuelve, conexión rechazada o error TLS), un 408, un 429 o cualquier 5xx. |
| Rechazo de tu servidor | Cualquier otro 4xx o un 3xx. Es final y no se reintenta; el detalle está en Reintentos y qué se considera fallo. |
Eventos#
Te enviamos tres tipos de evento con el resultado final de una emisión, uno
por cada clase de resultado, y un aviso cuando un comprobante necesita tu
atención antes de tener resultado. El eventType te dice de qué se trata, y
los campos estado y codEstado del cuerpo te dicen exactamente qué pasó.
eventType |
En el portal | Cuándo ocurre | estado y codEstado en el cuerpo |
|---|---|---|---|
document.authorized |
Documento autorizado | El SRI autorizó el comprobante. | autorizado, 2001 |
document.rejected |
Documento rechazado | El SRI rechazó el comprobante (rechazo fiscal). | rechazado con 3001, o rechazo_configuracion con 4002 si la firma electrónica del emisor no se acepta |
document.failed |
Documento no emitido | El comprobante no se emitió: no cumplió una regla de la validación fiscal, falta o está mal una configuración del emisor, o algo impidió definitivamente su autorización. | rechazado con 3002, rechazo_configuracion con 4001 a 4004, o error con 5001, 5006 o 5007 |
operation.requires_attention |
Operación requiere atención | Todavía no tenemos el resultado del comprobante y no pudimos confirmarlo a tiempo. Es un aviso, no un resultado final. | recibido, 1001 o 1002 |
Los tres eventos document.* traen un estado final, con los mismos valores del
seguimiento. Decide siempre
con estado y codEstado, y no solo con eventType.
En cambio, operation.requires_attention no es final: el comprobante sigue
recibido, con el codEstado 1001 o 1002 según ya tenga clave de acceso, y el
motivo del aviso llega en errores. Cuando tengamos su resultado, te llega el
evento document.* que corresponda de la misma operación. El mismo eventType
es también el del evento de prueba que envía el botón
Probar solo al destino probado; lo distingues porque trae probe en
"true".
Una operación que termina en cancelado no genera evento. Si una emisión
lleva más tiempo del esperado sin que te llegue ningún evento, consulta su
estado en el seguimiento.
Si recibes un eventType que tu sistema no reconoce, responde un 2xx e
ignóralo; así un tipo de evento que no procesas no acumula fallos ni pausa tu
destino.
Campos del cuerpo#
Los valores del cuerpo son cadenas de texto, incluso las fechas, salvo
codEstado, que es un número entero, y errores, que es un arreglo de textos.
El orden de las claves no está garantizado, así que lee cada campo por su nombre
y no rechaces el evento si trae un campo que tu sistema no reconoce.
| Campo | Tipo | Presente en | Descripción |
|---|---|---|---|
eventType |
string | Todos | Tipo de evento (tabla anterior). |
resourceId |
string (UUID) | Todos | Recurso del evento. En los eventos document.* y en el aviso operation.requires_attention es el idOperacion. En el evento de prueba es el identificador del destino. |
occurredAtUtc |
string | Todos | Momento en que se registró el evento, en UTC e ISO 8601 con 7 decimales (2026-10-07T15:04:05.1234567Z). No cambia en los reintentos. |
idOperacion |
string (UUID) | document.* y aviso |
Identificador de la operación que devolvió la emisión. Úsalo para ubicar el comprobante en tu sistema. |
estado |
string | document.* y aviso |
En los eventos document.*, el estado final de la operación: autorizado, rechazado, rechazo_configuracion o error. En el aviso, recibido. Son los mismos valores del seguimiento. |
tipoDocumento |
string | document.* y aviso |
Tipo de comprobante: 01, 03, 04, 05, 06 o 07. |
ruc |
string | document.* y aviso |
Identificación del contribuyente emisor, la misma identificacion de la ruta y de infoTributaria.ruc. Te permite enrutar un destino compartido por varios RUC. |
claveAcceso |
string | document.authorized, document.rejected; en document.failed y en el aviso, solo si ya se había asignado |
Clave de acceso de 49 dígitos. |
fhAutorizacion |
string | document.authorized |
Fecha y hora de autorización, en ISO 8601 con zona horaria, igual a la del seguimiento. |
codEstado |
integer | document.* y aviso |
Código de resultado de 4 dígitos del catálogo de codEstado, por ejemplo 2001 en una autorización, 3001 en un rechazo del SRI o 4002 si la firma no es válida; en el aviso, 1001 o 1002. Su primer dígito coincide con el estado. Cada valor y qué hacer ante él están en Qué hacer ante cada evento y en Códigos de resultado de una operación. Trata un valor que no reconozcas según su primer dígito y como un problema que debes revisar. |
msgError |
string | document.rejected y document.failed |
Descripción fija del código, en español. No viene cuando no hay error, es decir, en document.authorized ni en el aviso. Muéstralo o regístralo, pero no lo compares en tu código. |
errores |
array de string | document.* y aviso |
Detalle específico del resultado, por ejemplo el mensaje del SRI en un rechazo fiscal o el campo que no cumplió una validación. En el aviso trae el motivo. Viene siempre y es [] cuando no hay detalle. Muéstralo o regístralo, pero no lo compares en tu código. |
probe |
string | Evento de prueba | Siempre "true". |
document.authorized#
{
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"estado": "autorizado",
"codEstado": 2001,
"errores": [],
"tipoDocumento": "01",
"ruc": "0123456789001",
"claveAcceso": "0710202601012345678900110010010000001231234567811",
"fhAutorizacion": "2026-10-07T10:04:05-05:00",
"eventType": "document.authorized",
"resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"occurredAtUtc": "2026-10-07T15:04:05.1234567Z"
}
document.rejected#
{
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"estado": "rechazado",
"tipoDocumento": "01",
"claveAcceso": "0710202601012345678900110010010000001231234567811",
"codEstado": 3001,
"msgError": "El SRI rechazó el comprobante.",
"errores": [
"CLAVE ACCESO REGISTRADA"
],
"eventType": "document.rejected",
"resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"occurredAtUtc": "2026-10-07T15:04:05.1234567Z"
}
document.failed#
{
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"estado": "rechazo_configuracion",
"tipoDocumento": "01",
"codEstado": 4002,
"msgError": "La firma electrónica no es válida.",
"errores": [],
"eventType": "document.failed",
"resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"occurredAtUtc": "2026-10-07T15:04:05.1234567Z"
}
Los ejemplos se muestran indentados para leerlos. El cuerpo real llega en una sola línea y la firma se calcula sobre esos bytes exactos.
operation.requires_attention#
{
"idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"estado": "recibido",
"tipoDocumento": "01",
"codEstado": 1001,
"errores": [
"Aun no se confirma el resultado del comprobante; se sigue consultando."
],
"eventType": "operation.requires_attention",
"resourceId": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
"occurredAtUtc": "2026-10-07T15:04:05.1234567Z"
}
Evento de prueba#
Al pulsar Probar en el portal, el destino recibe este evento aunque no esté suscrito a él. Sirve para comprobar la conexión y la firma, y no corresponde a ningún comprobante.
{
"probe": "true",
"eventType": "operation.requires_attention",
"resourceId": "9b2e4f60-1c3d-4e5f-8a7b-6c5d4e3f2a1b",
"occurredAtUtc": "2026-10-07T15:04:05.1234567Z"
}
Tu servidor solo tiene que responder un 2xx. El evento de prueba se registra una vez por destino, así que si Probar no genera una entrega nueva en Entregas, usa Reenviar sobre la entrega de prueba que ya existe.
Qué hacer ante cada evento#
Cada combinación de estado y codEstado pide una acción distinta. En la tabla,
"claves nuevas" significa una Idempotency-Key nueva y una referenciaExterna
nueva.
| Evento | estado |
codEstado |
Qué pasó | Qué hacer |
|---|---|---|---|---|
document.authorized |
autorizado |
2001 | El SRI autorizó el comprobante. | Marca el comprobante como autorizado en tu sistema, guarda claveAcceso y descarga el RIDE y el XML si los necesitas. |
document.rejected |
rechazado |
3001 (rechazo_sri) |
Es un rechazo fiscal: el SRI no aceptó el comprobante, y errores trae su mensaje. |
Corrige el comprobante según errores y la guía de su tipo, y emítelo como un comprobante nuevo, con un secuencial nuevo (u omítelo para que te asignemos el siguiente) y claves nuevas. El número rechazado por el SRI no se puede reutilizar; si lo intentas, la API responde 409 con el codEstado 3004 (comprobante_duplicado). |
document.failed |
rechazado |
3002 (comprobante_invalido) |
La validación fiscal rechazó el contenido del comprobante antes de enviarlo al SRI. errores trae el detalle por campo cuando existe. |
Corrige el comprobante y emítelo de nuevo con el mismo número y claves nuevas. |
document.failed |
rechazo_configuracion |
4001 (emisor_no_configurado) |
Al emisor le falta configuración para emitir ante el SRI. | Revisa el RUC en Cuenta > Contribuyentes del Portal del Cliente: en el ambiente en que emitiste, la columna Pruebas o Producción debe mostrar Listo o En producción. Si muestra Configurando, espera a que termine; si ya está listo, escribe a soporte con el idOperacion. Después emite de nuevo con el mismo número y claves nuevas. |
document.rejected o document.failed |
rechazo_configuracion |
4002 (firma_no_valida) |
La firma electrónica del emisor está caducada o no es válida. | En Cuenta > Contribuyentes del Portal del Cliente, pulsa Reemplazar firma en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en Cuenta > Certificados con Reemplazar certificado. Después emite de nuevo con el mismo número y claves nuevas. |
document.failed |
rechazo_configuracion |
4003 (suscripcion_inactiva) |
La suscripción del emisor no está activa. | Regulariza la suscripción y emite de nuevo con el mismo número y claves nuevas. |
document.failed |
rechazo_configuracion |
4004 (cupo_agotado) |
No quedan documentos en tus paquetes vigentes. | Compra un paquete y emite de nuevo con el mismo número y claves nuevas. |
document.failed |
error |
5006 (entrega_no_posible) |
El comprobante no se pudo emitir y confirmamos que no se creó. | Emite de nuevo el mismo comprobante con el mismo número y claves nuevas. |
document.failed |
error |
5007 (resultado_no_confirmado) |
No pudimos confirmar si el comprobante llegó a crearse. | No emitas de nuevo, porque podrías duplicarlo. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
document.failed |
error |
5001 (error_interno) |
Tuvimos un fallo inesperado y el comprobante no se completó. | Escribe a soporte con el idOperacion antes de emitir de nuevo. |
operation.requires_attention |
recibido |
1001 o 1002 | Todavía no tenemos el resultado del comprobante y no pudimos confirmarlo a tiempo; errores trae el motivo. Es un aviso, no un resultado final. |
No emitas de nuevo, porque podrías duplicarlo. Espera el evento document.* de la misma operación o consulta el seguimiento; si el aviso se prolonga, escribe a soporte con el idOperacion. |
operation.requires_attention con probe en "true" |
- | - | Es el evento de prueba del portal. | Responde un 2xx. |
Una operación cancelado, con el codEstado 6001 (operacion_cancelada), no genera
evento. La ves en el seguimiento: el
comprobante no se emitió ni consumió cupo, y puedes emitirlo de nuevo con
claves nuevas y el mismo número.
Varias filas de la tabla piden emitir de nuevo con el mismo número. Para
hacerlo, envía la Estructura del comprobante corregida con el mismo estab,
ptoEmi y secuencial de la operación anterior. Si enviaste el secuencial
al emitir, ya lo tienes en tu sistema; si dejaste que te lo asignáramos, lo
encuentras en el numeroDocumento del
seguimiento o dentro de la claveAcceso, cuando
el evento la trae. Usa siempre claves nuevas, porque con las anteriores la API
te devuelve la operación original y no emite, o responde 409 con el codEstado
3005 (conflicto_idempotencia).
La API acepta ese envío con un 202 y puede reutilizar la misma operación:
la respuesta trae el mismo idOperacion y no usa otro documento de tu
cupo. Como generamos como máximo un evento de cada eventType por operación,
confirma después el resultado con el
seguimiento. Si el reenvío termina en el mismo
tipo de evento que ya recibiste, no te llega un evento nuevo.
En resumen, un rechazado y un rechazo_configuracion exigen corregir la
causa antes de emitir de nuevo. Un error con 5006 y un cancelado con 6001
solo piden volver a emitir. En cambio, un error con 5007 o 5001 es una
notificación que exige
no emitir de nuevo hasta confirmar con soporte qué pasó.
Reintentos y qué se considera fallo#
Cada entrega espera una respuesta 2xx de tu servidor en 15 segundos como máximo, y no sigue redirecciones. Lo que hacemos después depende de lo que responda tu servidor.
| Respuesta de tu servidor | Qué hacemos | Cuenta para pausar el destino | Qué hacer |
|---|---|---|---|
| 2xx | Damos la entrega por completada. | No; reinicia el contador | No hagas nada. |
| Sin respuesta: tiempo agotado, dominio que no resuelve, conexión rechazada o error TLS | Reintentamos. | Sí | Revisa que tu endpoint esté en línea, con DNS y certificado válidos, y que responda en menos de 15 segundos. |
| 408, 429, 500, 502, 503, 504 y cualquier otro 5xx | Reintentamos. Si envías Retry-After, esperamos al menos ese tiempo, con un máximo de 60 minutos. |
Sí | Responde un 2xx en cuanto guardes el evento y procésalo después. |
| Otro 4xx (400, 401, 403, 404, 410, 422...) o un 3xx | La entrega queda rechazada por tu servidor y no reintentamos. | No | Corrige tu endpoint (ruta, autenticación, validación de la firma) y usa Reenviar en el portal. |
Ante un fallo temporal de tu lado, como una base de datos caída o un despliegue
en curso, responde 503 con Retry-After y no un 4xx. Un 4xx deja la entrega
rechazada y tendrías que reenviarla a mano desde el portal.
Reintentamos cada entrega fallida hasta 8 intentos en total, con esperas cada vez más largas que, sumadas, se extienden por varios días. Así, una caída de tu servidor de un fin de semana no te hace perder eventos. Cada entrega muestra su número de intento en Entregas, y el historial de cada intento está en Intentos.
- Si los 8 intentos fallan, la entrega queda en estado Agotado y ya no hay más reintentos automáticos. Puedes forzar un envío con Reenviar desde Entregas.
- Reenviar crea una entrega nueva que continúa la numeración de intentos de ese evento en el destino. Si el evento ya llegó al intento 8, el reenvío es un solo intento y, si falla, queda Agotado sin reintentos automáticos.
- Una entrega rechazada por tu servidor también es final. Corrige tu endpoint y usa Reenviar.
- Cada reintento lleva el mismo cuerpo, con el mismo
occurredAtUtcy el mismowebhook-id, y una firma nueva, con unty unwebhook-timestampnuevos. - Pausa del destino. Tras 8 fallos consecutivos que cuentan, es decir, sin respuesta o con 408, 429 o 5xx, sumando todos los eventos del destino, el destino pasa a Pausado y el portal muestra "Entrega pausada". Los rechazos de tu servidor (3xx y otros 4xx) no cuentan. Un 2xx posterior reinicia el contador de fallos, pero no reanuda el destino; para eso, pulsa Reanudar.
Atención
Mientras un destino está pausado, los eventos nuevos no se le entregan ni quedan en espera. Al reanudarlo, solo recibirás los eventos que ocurran desde ese momento. Por eso, después de una pausa, revisa con el seguimiento las operaciones que quedaron sin resultado en tu sistema.
Estados de una entrega#
En Integración > Eventos > Entregas ves, para cada entrega, la fecha en hora de Ecuador, el evento, el estado, el número de intento y el código HTTP.
| Estado en el portal | Qué significa | Qué hacer |
|---|---|---|
| Pendiente | La entrega espera su primer intento o el siguiente reintento. | No hagas nada. |
| Enviando | Estamos enviando la entrega en este momento. | No hagas nada. |
| Fallido | El intento falló y programamos un reintento. | Revisa la causa en Intentos y corrige tu endpoint si hace falta. |
| Entregado | Tu servidor respondió un 2xx. | No hagas nada. |
| Rechazado por tu servidor (HTTP xxx) | Tu servidor respondió un 3xx u otro 4xx. Es un estado final. | Corrige tu endpoint y usa Reenviar. |
| Agotado | Fallaron todos los intentos, sin respuesta o con 408, 429 o 5xx. Es un estado final. | Corrige la causa y usa Reenviar. |
Con Intentos ves el historial de esa entrega: la fecha, el número de intento, el resultado (Entregado, Fallido, se reintenta, Agotado o Rechazado por tu servidor), el código HTTP, la causa del error y la duración en milisegundos. Cuando no hubo respuesta HTTP, la columna de error dice cuál fue la causa:
| Causa | Qué pasó | Qué hacer |
|---|---|---|
| Tiempo de espera agotado | Tu servidor no terminó de responder en 15 segundos. | Responde un 2xx en cuanto guardes el evento y procésalo después. |
| El dominio no resuelve | El nombre de tu URL no tiene registro DNS válido. | Revisa el DNS de tu dominio. |
| Conexión rechazada | No se pudo abrir la conexión con tu servidor, por un puerto cerrado, un firewall o un servidor apagado. | Revisa que tu servidor escuche en el puerto 443 y acepte conexiones externas. |
| Error TLS | Falló la conexión segura, por un certificado vencido, autofirmado o sin la cadena completa. | Instala un certificado válido emitido por una autoridad reconocida, con su cadena completa. |
| Error de red | Ocurrió otro error de red durante el envío. | Revisa la conectividad de tu servidor; nosotros reintentamos. |
Garantías y deduplicación#
Te damos tres garantías sobre la entrega de eventos, y tu servidor debe estar preparado para cada una:
- Al menos una vez. Un mismo evento puede llegarte más de una vez, por un reintento porque tu servidor respondió tarde o por un Reenviar manual.
- Sin orden garantizado. Los eventos de operaciones distintas pueden llegar en cualquier orden. Para conocer el estado actual de una operación, consulta el seguimiento en lugar de asumir que el último evento recibido es el vigente.
- Un evento por tipo y operación. Generamos como máximo un evento
de cada
eventTypepor operación. Una misma operación sí puede recibir dos eventos distintos, por ejemplo undocument.failedcon 3002 y, después de que reenvías el comprobante corregido con el mismo número, undocument.authorizedo undocument.rejected.
Como un evento puede repetirse, descarta los duplicados con esta clave única:
| Clave única | Por qué |
|---|---|
eventType + resourceId |
Identifica un evento. Sus repeticiones (reintentos y reenvíos) traen el mismo valor, mientras t y la firma cambian. |
| Caso | eventType + resourceId |
Qué hacer |
|---|---|---|
| Reintento o Reenviar del mismo evento | Es igual al ya guardado. | Responde un 2xx sin volver a procesar. |
document.failed y, tras reenviar con el mismo número, document.authorized de la misma operación |
Es distinto, porque cambia eventType. |
Procesa ambos. El evento más reciente refleja el estado vigente; si dudas, confírmalo en el seguimiento. |
| Eventos de operaciones distintas | Es distinto, porque cambia resourceId. |
Procesa cada uno. |
Una forma simple de aplicarlo es una tabla con clave primaria compuesta. Inserta
el evento y aplica su efecto en la misma transacción; si el INSERT choca con
la clave, el evento es un duplicado.
CREATE TABLE webhook_evento (
event_type VARCHAR(80) NOT NULL,
resource_id CHAR(36) NOT NULL,
recibido_en TIMESTAMP NOT NULL,
cuerpo TEXT NOT NULL,
PRIMARY KEY (event_type, resource_id)
);
Implementación en tu servidor#
Los ejemplos de esta sección son un endpoint completo que puedes copiar y ejecutar. Todos hacen lo mismo, en este orden:
- Leen el cuerpo crudo, es decir, los bytes tal como llegaron, sin deserializarlo.
- Verifican la cabecera
Ecuafact-Signaturecon tu secreto. Si la firma no es válida, responden 401. - Solo entonces interpretan el JSON.
- Descartan los duplicados por
eventType+resourceId. - Actúan según el evento y responden 200. Si su propio guardado falla, responden 500 para que reintentemos la entrega.
Para que puedas ejecutarlos tal cual, los ejemplos guardan los eventos procesados en memoria; en producción, usa la tabla de la sección anterior. Si tu procesamiento tarda, guarda el evento, responde 200 y procesa en segundo plano, porque el tiempo de espera es de 15 segundos. Las pestañas SDK hacen lo mismo con el verificador de firma de cada SDK oficial.
Atención
Verifica la firma sobre el cuerpo crudo. Si tu framework deserializa el JSON y lo vuelves a serializar, cambian los espacios, el orden o los escapes, y la firma no coincide. Por eso, no uses el enlace automático a un objeto (modelo, DTO o POJO) antes de verificar.
// Program.cs de un proyecto creado con: dotnet new web
// Ejecuta: dotnet run --urls http://localhost:3000
using System.Collections.Concurrent;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
WebApplication app = WebApplication.CreateBuilder(args).Build();
string secreto = Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!;
ConcurrentDictionary<string, bool> procesados = new(); // Solo para el ejemplo: usa una tabla con clave unica.
app.MapPost("/webhooks/ecuafact", async (HttpRequest request) =>
{
using StreamReader lector = new(request.Body, Encoding.UTF8);
string cuerpoCrudo = await lector.ReadToEndAsync();
string cabecera = request.Headers["Ecuafact-Signature"].ToString();
if (!Verificar(secreto, cabecera, cuerpoCrudo, TimeSpan.FromMinutes(5)))
{
return Results.Unauthorized();
}
using JsonDocument documento = JsonDocument.Parse(cuerpoCrudo);
JsonElement evento = documento.RootElement;
string tipo = Texto(evento, "eventType") ?? "";
string recurso = Texto(evento, "resourceId") ?? "";
if (!procesados.TryAdd(tipo + "|" + recurso, true))
{
return Results.Ok(); // Duplicado: ya procesado.
}
switch (tipo)
{
case "document.authorized":
Console.WriteLine($"Autorizado {Texto(evento, "idOperacion")} clave {Texto(evento, "claveAcceso")}");
break;
case "document.rejected":
Console.WriteLine($"Rechazado por el SRI {Texto(evento, "idOperacion")} ({Texto(evento, "codEstado")}): {Texto(evento, "errores")}");
break;
case "document.failed":
Console.WriteLine($"No emitido {Texto(evento, "idOperacion")}: {Texto(evento, "estado")} / {Texto(evento, "codEstado")} - {Texto(evento, "msgError")} {Texto(evento, "errores")}");
break;
default:
Console.WriteLine($"Evento sin accion: {tipo}");
break;
}
return Results.Ok();
});
app.Run();
static string? Texto(JsonElement objeto, string nombre)
{
if (objeto.TryGetProperty(nombre, out JsonElement valor))
{
// codEstado es un numero y errores un arreglo: se devuelven como su JSON.
return valor.ValueKind == JsonValueKind.String ? valor.GetString() : valor.GetRawText();
}
return null;
}
static bool Verificar(string secreto, string cabecera, string cuerpoCrudo, TimeSpan tolerancia)
{
string? t = null;
string? v1 = null;
foreach (string parte in cabecera.Split(','))
{
string item = parte.Trim();
if (item.StartsWith("t=", StringComparison.Ordinal))
{
t = item.Substring(2);
}
else if (item.StartsWith("v1=", StringComparison.Ordinal))
{
v1 = item.Substring(3);
}
}
if (t == null || v1 == null || !long.TryParse(t, out long unix))
{
return false;
}
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - unix) > (long)tolerancia.TotalSeconds)
{
return false;
}
using HMACSHA256 hmac = new(Encoding.UTF8.GetBytes(secreto));
byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(t + "." + cuerpoCrudo));
string esperado = Convert.ToHexString(hash).ToLowerInvariant();
return CryptographicOperations.FixedTimeEquals(
Encoding.ASCII.GetBytes(esperado),
Encoding.ASCII.GetBytes(v1.ToLowerInvariant()));
}
# Guarda como webhook.py. Instala: pip install flask
# Ejecuta: flask --app webhook run --port 3000
import hashlib
import hmac
import json
import os
import time
from flask import Flask, request
app = Flask(__name__)
SECRETO = os.environ["ECUAFACT_WEBHOOK_SECRET"]
procesados = set() # Solo para el ejemplo: usa una tabla con clave unica.
def verificar(cabecera, cuerpo_crudo, tolerancia=300):
partes = dict(p.strip().split("=", 1) for p in cabecera.split(",") if "=" in p)
t, v1 = partes.get("t"), partes.get("v1")
if not t or not v1 or not t.isdigit():
return False
if abs(int(time.time()) - int(t)) > tolerancia:
return False
firmado = f"{t}.{cuerpo_crudo}".encode("utf-8")
esperado = hmac.new(SECRETO.encode("utf-8"), firmado, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperado, v1.lower())
@app.post("/webhooks/ecuafact")
def webhook():
cuerpo_crudo = request.get_data(as_text=True) # Cuerpo crudo, sin parsear.
if not verificar(request.headers.get("Ecuafact-Signature", ""), cuerpo_crudo):
return "", 401
evento = json.loads(cuerpo_crudo) # Solo despues de verificar la firma.
clave = (evento.get("eventType"), evento.get("resourceId"))
if clave in procesados:
return "", 200 # Duplicado: ya procesado.
procesados.add(clave)
tipo = evento.get("eventType")
if tipo == "document.authorized":
print("Autorizado", evento["idOperacion"], evento.get("claveAcceso"))
elif tipo == "document.rejected":
print("Rechazado por el SRI", evento["idOperacion"], evento.get("codEstado"), evento.get("errores"))
elif tipo == "document.failed":
print("No emitido", evento["idOperacion"], evento.get("estado"), "/", evento.get("codEstado"), "-", evento.get("msgError"), evento.get("errores"))
else:
print("Evento sin accion:", tipo)
return "", 200
// Node.js 18 o superior. Instala: npm install express
// Guarda como webhook.mjs y ejecuta: node webhook.mjs
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const SECRETO = process.env.ECUAFACT_WEBHOOK_SECRET;
const procesados = new Set(); // Solo para el ejemplo: usa una tabla con clave unica.
const app = express();
app.post('/webhooks/ecuafact', express.raw({ type: 'application/json' }), (req, res) => {
const cuerpoCrudo = Buffer.isBuffer(req.body) ? req.body.toString('utf8') : '';
if (!verificar(SECRETO, req.get('Ecuafact-Signature') ?? '', cuerpoCrudo)) {
return res.sendStatus(401);
}
const evento = JSON.parse(cuerpoCrudo); // Solo despues de verificar la firma.
const clave = `${evento.eventType}|${evento.resourceId}`;
if (procesados.has(clave)) {
return res.sendStatus(200); // Duplicado: ya procesado.
}
procesados.add(clave);
switch (evento.eventType) {
case 'document.authorized':
console.log('Autorizado', evento.idOperacion, evento.claveAcceso);
break;
case 'document.rejected':
console.log('Rechazado por el SRI', evento.idOperacion, evento.codEstado, evento.errores);
break;
case 'document.failed':
console.log('No emitido', evento.idOperacion, evento.estado, '/', evento.codEstado, '-', evento.msgError, evento.errores);
break;
default:
console.log('Evento sin accion:', evento.eventType);
}
res.sendStatus(200);
});
function verificar(secreto, cabecera, cuerpoCrudo, toleranciaSegundos = 300) {
let t = null;
let v1 = null;
for (const parte of cabecera.split(',')) {
const item = parte.trim();
if (item.startsWith('t=')) t = item.slice(2);
else if (item.startsWith('v1=')) v1 = item.slice(3).toLowerCase();
}
if (!t || !v1 || !/^\d+$/.test(t)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranciaSegundos) return false;
const esperado = createHmac('sha256', secreto).update(`${t}.${cuerpoCrudo}`, 'utf8').digest('hex');
const a = Buffer.from(esperado, 'utf8');
const b = Buffer.from(v1, 'utf8');
return a.length === b.length && timingSafeEqual(a, b);
}
app.listen(3000, () => console.log('Escuchando en http://localhost:3000/webhooks/ecuafact'));
<?php
// Guarda como webhook.php y ejecuta: php -S localhost:3000 webhook.php
$secreto = getenv('ECUAFACT_WEBHOOK_SECRET');
if ($secreto === false || $secreto === '') {
http_response_code(500); // Falta configurar el secreto: la plataforma reintenta.
exit;
}
$cuerpoCrudo = file_get_contents('php://input'); // Cuerpo crudo, sin parsear.
$cabecera = $_SERVER['HTTP_ECUAFACT_SIGNATURE'] ?? '';
if (!verificar($secreto, $cabecera, $cuerpoCrudo)) {
http_response_code(401);
exit;
}
$evento = json_decode($cuerpoCrudo, true); // Solo despues de verificar la firma.
$tipo = $evento['eventType'] ?? '';
// Solo para el ejemplo: marca en disco. En produccion usa una tabla con clave unica.
$marca = sys_get_temp_dir() . '/ecuafact-' . hash('sha256', $tipo . '|' . ($evento['resourceId'] ?? ''));
if (file_exists($marca)) {
http_response_code(200); // Duplicado: ya procesado.
exit;
}
touch($marca);
switch ($tipo) {
case 'document.authorized':
error_log('Autorizado ' . $evento['idOperacion'] . ' clave ' . ($evento['claveAcceso'] ?? ''));
break;
case 'document.rejected':
error_log('Rechazado por el SRI ' . $evento['idOperacion'] . ' (' . ($evento['codEstado'] ?? '') . '): ' . implode('; ', $evento['errores'] ?? []));
break;
case 'document.failed':
error_log('No emitido ' . $evento['idOperacion'] . ': ' . ($evento['estado'] ?? '') . ' / ' . ($evento['codEstado'] ?? '') . ' - ' . ($evento['msgError'] ?? '') . ' ' . implode('; ', $evento['errores'] ?? []));
break;
default:
error_log('Evento sin accion: ' . $tipo);
}
http_response_code(200);
function verificar(string $secreto, string $cabecera, string $cuerpoCrudo, int $tolerancia = 300): bool
{
$partes = [];
foreach (explode(',', $cabecera) as $p) {
$kv = explode('=', trim($p), 2);
if (count($kv) === 2) {
$partes[$kv[0]] = $kv[1];
}
}
$t = $partes['t'] ?? null;
$v1 = $partes['v1'] ?? null;
if ($t === null || $v1 === null || !ctype_digit($t) || abs(time() - (int) $t) > $tolerancia) {
return false;
}
$esperado = hash_hmac('sha256', $t . '.' . $cuerpoCrudo, $secreto);
return hash_equals($esperado, strtolower($v1));
}
// Spring Boot 3 con spring-boot-starter-web. Escucha en el puerto 8080 por defecto.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class WebhookController {
private static final ObjectMapper JSON = new ObjectMapper();
private final Set<String> procesados = ConcurrentHashMap.newKeySet(); // Solo para el ejemplo.
@PostMapping("/webhooks/ecuafact")
public ResponseEntity<Void> recibir(
@RequestHeader(value = "Ecuafact-Signature", defaultValue = "") String cabecera,
@RequestBody byte[] cuerpo) throws Exception {
String cuerpoCrudo = new String(cuerpo, StandardCharsets.UTF_8); // Bytes exactos recibidos.
if (!verificar(System.getenv("ECUAFACT_WEBHOOK_SECRET"), cabecera, cuerpoCrudo, 300)) {
return ResponseEntity.status(401).build();
}
JsonNode evento = JSON.readTree(cuerpoCrudo); // Solo despues de verificar la firma.
String tipo = evento.path("eventType").asText();
if (!procesados.add(tipo + "|" + evento.path("resourceId").asText())) {
return ResponseEntity.ok().build(); // Duplicado: ya procesado.
}
String idOperacion = evento.path("idOperacion").asText();
switch (tipo) {
case "document.authorized" ->
System.out.println("Autorizado " + idOperacion + " clave " + evento.path("claveAcceso").asText());
case "document.rejected" ->
System.out.println("Rechazado por el SRI " + idOperacion + " (" + evento.path("codEstado").asInt() + "): "
+ evento.path("errores"));
case "document.failed" ->
System.out.println("No emitido " + idOperacion + ": " + evento.path("estado").asText() + " / "
+ evento.path("codEstado").asInt() + " - " + evento.path("msgError").asText() + " " + evento.path("errores"));
default -> System.out.println("Evento sin accion: " + tipo);
}
return ResponseEntity.ok().build();
}
static boolean verificar(String secreto, String cabecera, String cuerpoCrudo, long tolerancia) throws Exception {
Map<String, String> partes = new HashMap<>();
for (String p : cabecera.split(",")) {
String[] kv = p.trim().split("=", 2);
if (kv.length == 2) {
partes.put(kv[0], kv[1]);
}
}
String t = partes.get("t");
String v1 = partes.get("v1");
if (t == null || v1 == null || !t.matches("\\d+")) {
return false;
}
if (Math.abs(Instant.now().getEpochSecond() - Long.parseLong(t)) > tolerancia) {
return false;
}
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secreto.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] hash = mac.doFinal((t + "." + cuerpoCrudo).getBytes(StandardCharsets.UTF_8));
StringBuilder hex = new StringBuilder();
for (byte b : hash) {
hex.append(String.format("%02x", b));
}
return MessageDigest.isEqual(
hex.toString().getBytes(StandardCharsets.US_ASCII),
v1.toLowerCase().getBytes(StandardCharsets.US_ASCII));
}
}
// Program.cs de un proyecto creado con: dotnet new web
// Agrega el SDK: dotnet add package Ecuafact.Sdk. Ejecuta: dotnet run --urls http://localhost:3000
using System.Collections.Concurrent;
using System.Text;
using System.Text.Json;
using Ecuafact.Sdk.Webhooks;
WebApplication app = WebApplication.CreateBuilder(args).Build();
string secreto = Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!;
ConcurrentDictionary<string, bool> procesados = new(); // Solo para el ejemplo.
app.MapPost("/webhooks/ecuafact", async (HttpRequest request) =>
{
using StreamReader lector = new(request.Body, Encoding.UTF8);
string cuerpoCrudo = await lector.ReadToEndAsync();
string cabecera = request.Headers["Ecuafact-Signature"].ToString();
if (!WebhookSignature.Verify(secreto, cabecera, cuerpoCrudo, DateTimeOffset.UtcNow, TimeSpan.FromMinutes(5)))
{
return Results.Unauthorized();
}
using JsonDocument documento = JsonDocument.Parse(cuerpoCrudo);
JsonElement evento = documento.RootElement;
string tipo = evento.GetProperty("eventType").GetString() ?? "";
string recurso = evento.GetProperty("resourceId").GetString() ?? "";
if (!procesados.TryAdd(tipo + "|" + recurso, true))
{
return Results.Ok();
}
switch (tipo)
{
case "document.authorized":
case "document.rejected":
case "document.failed":
Console.WriteLine($"{tipo} para la operacion {recurso}");
break;
default:
Console.WriteLine($"Evento sin accion: {tipo}");
break;
}
return Results.Ok();
});
app.Run();
# Guarda como webhook.py. Instala: pip install flask "ecuafact>=1.0.0"
# Ejecuta: flask --app webhook run --port 3000
import json
import os
from ecuafact import verify
from flask import Flask, request
app = Flask(__name__)
SECRETO = os.environ["ECUAFACT_WEBHOOK_SECRET"]
procesados = set() # Solo para el ejemplo.
@app.post("/webhooks/ecuafact")
def webhook():
cuerpo_crudo = request.get_data(as_text=True)
if not verify(SECRETO, request.headers.get("Ecuafact-Signature", ""), cuerpo_crudo, tolerance_seconds=300):
return "", 401
evento = json.loads(cuerpo_crudo)
clave = (evento.get("eventType"), evento.get("resourceId"))
if clave in procesados:
return "", 200
procesados.add(clave)
if evento["eventType"] in ("document.authorized", "document.rejected", "document.failed"):
print(evento["eventType"], "para la operacion", evento["resourceId"])
else:
print("Evento sin accion:", evento["eventType"])
return "", 200
// Node.js 18 o superior. Instala: npm install express @ecuafact/sdk
// Guarda como webhook.mjs y ejecuta: node webhook.mjs
import express from "express";
import { verify } from "@ecuafact/sdk";
const SECRETO = process.env.ECUAFACT_WEBHOOK_SECRET;
const procesados = new Set(); // Solo para el ejemplo.
const app = express();
app.post("/webhooks/ecuafact", express.raw({ type: "application/json" }), (req, res) => {
const cuerpoCrudo = Buffer.isBuffer(req.body) ? req.body.toString("utf8") : "";
if (!verify(SECRETO, req.get("Ecuafact-Signature") ?? "", cuerpoCrudo, new Date(), 300)) {
return res.sendStatus(401);
}
const evento = JSON.parse(cuerpoCrudo);
const clave = `${evento.eventType}|${evento.resourceId}`;
if (procesados.has(clave)) return res.sendStatus(200);
procesados.add(clave);
switch (evento.eventType) {
case "document.authorized":
case "document.rejected":
case "document.failed":
console.log(evento.eventType, "para la operacion", evento.resourceId);
break;
default:
console.log("Evento sin accion:", evento.eventType);
}
res.sendStatus(200);
});
app.listen(3000);
<?php
// Guarda como webhook.php (con composer require "ecuafact/sdk:^1.0") y ejecuta: php -S localhost:3000 webhook.php
require 'vendor/autoload.php';
use Ecuafact\Sdk\WebhookSignature;
$secreto = getenv('ECUAFACT_WEBHOOK_SECRET');
if ($secreto === false || $secreto === '') {
http_response_code(500); // Falta configurar el secreto: la plataforma reintenta.
exit;
}
$cuerpoCrudo = file_get_contents('php://input');
$cabecera = $_SERVER['HTTP_ECUAFACT_SIGNATURE'] ?? '';
if (!WebhookSignature::verify($secreto, $cabecera, $cuerpoCrudo, time(), 300)) {
http_response_code(401);
exit;
}
$evento = json_decode($cuerpoCrudo, true);
$tipo = $evento['eventType'] ?? '';
$marca = sys_get_temp_dir() . '/ecuafact-' . hash('sha256', $tipo . '|' . ($evento['resourceId'] ?? ''));
if (!file_exists($marca)) { // Solo para el ejemplo: en produccion, tabla con clave unica.
touch($marca);
if (in_array($tipo, ['document.authorized', 'document.rejected', 'document.failed'], true)) {
error_log($tipo . ' para la operacion ' . $evento['resourceId']);
} else {
error_log('Evento sin accion: ' . $tipo);
}
}
http_response_code(200);
// Spring Boot 3 con spring-boot-starter-web y com.ecuafact:sdk.
import com.ecuafact.sdk.WebhookSignature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class WebhookController {
private static final ObjectMapper JSON = new ObjectMapper();
private final Set<String> procesados = ConcurrentHashMap.newKeySet(); // Solo para el ejemplo.
@PostMapping("/webhooks/ecuafact")
public ResponseEntity<Void> recibir(
@RequestHeader(value = "Ecuafact-Signature", defaultValue = "") String cabecera,
@RequestBody byte[] cuerpo) throws Exception {
String cuerpoCrudo = new String(cuerpo, StandardCharsets.UTF_8);
if (!WebhookSignature.verify(System.getenv("ECUAFACT_WEBHOOK_SECRET"), cabecera, cuerpoCrudo, Instant.now(), 300)) {
return ResponseEntity.status(401).build();
}
JsonNode evento = JSON.readTree(cuerpoCrudo);
String tipo = evento.path("eventType").asText();
String recurso = evento.path("resourceId").asText();
if (procesados.add(tipo + "|" + recurso)) {
switch (tipo) {
case "document.authorized", "document.rejected", "document.failed" ->
System.out.println(tipo + " para la operacion " + recurso);
default -> System.out.println("Evento sin accion: " + tipo);
}
}
return ResponseEntity.ok().build();
}
}
Cada framework da acceso al cuerpo crudo de una forma distinta:
- ASP.NET Core. Lee
Request.Bodydirectamente. Si recibes el cuerpo como un parámetro tipado ([FromBody] MiEvento evento), el framework ya lo deserializó y no tienes los bytes originales. - Express.js. Usa el middleware
rawde Express.js con{ type: 'application/json' }, solo en la ruta del webhook. Si registrasteexpress.json()de forma global, se ejecuta antes y consume el cuerpo, así que excluye la ruta del webhook o regístrala antes. - Flask.
request.get_data()devuelve el cuerpo crudo. Llama arequest.get_json()o ajson.loadssolo después de verificar. - Spring.
@RequestBody byte[]entrega los bytes exactos, y@RequestBody Stringtambién funciona, porque Spring entrega el texto sin interpretar el JSON y lo decodifica con elcharset=utf-8de la cabecera. Lo que no funciona es un POJO como@RequestBody MiEvento evento, porque Jackson lo deserializa y pierdes el cuerpo original. - PHP. Lee
php://input. No uses$_POST, porque conapplication/jsonviene vacío.
Probar en local#
Puedes probar tu endpoint en tu computador antes de publicarlo. Como el destino exige una URL pública con HTTPS en el puerto 443, te recomendamos hacerlo en dos pasos: primero simulas una entrega firmada en tu equipo y después recibes eventos reales a través de un túnel.
1. Simula una entrega firmada contra tu servidor local, sin pasar por el
portal. Usa el mismo secreto que configuraste en tu servidor; para esta prueba
puede ser cualquier texto. Ajusta URL al puerto de tu ejemplo, que es 3000 en
Node.js, Python, PHP y .NET, y 8080 en Spring Boot. La pestaña CLI hace lo
mismo con ecuafact webhooks probar, que lee el secreto de
ECUAFACT_WEBHOOK_SECRET.
URL="${URL:-http://localhost:3000/webhooks/ecuafact}"
SECRETO="$ECUAFACT_WEBHOOK_SECRET"
T=$(date +%s)
CUERPO='{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}'
FIRMA=$(printf '%s' "$T.$CUERPO" | openssl dgst -sha256 -hmac "$SECRETO" | sed 's/^.*= //')
curl -s -i -X POST "$URL" \
-H "Content-Type: application/json; charset=utf-8" \
-H "Ecuafact-Signature: t=$T,v1=$FIRMA" \
--data-binary "$CUERPO"
import hashlib
import hmac
import os
import time
import requests
url = os.environ.get("URL", "http://localhost:3000/webhooks/ecuafact")
secreto = os.environ["ECUAFACT_WEBHOOK_SECRET"]
cuerpo = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",'
'"claveAcceso":"0710202601012345678900110010010000001231234567811",'
'"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",'
'"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}')
t = str(int(time.time()))
firma = hmac.new(secreto.encode("utf-8"), f"{t}.{cuerpo}".encode("utf-8"), hashlib.sha256).hexdigest()
r = requests.post(
url,
data=cuerpo.encode("utf-8"),
headers={"Content-Type": "application/json; charset=utf-8", "Ecuafact-Signature": f"t={t},v1={firma}"},
timeout=30,
)
print(r.status_code, r.text)
# Envía un document.authorized firmado con ECUAFACT_WEBHOOK_SECRET.
# Resultado esperado: estadoHttp 200 y resultado "correcto".
ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact
# Envía un rechazo fiscal, con codEstado 3001.
ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact --evento document.rejected
# Envía un document.failed con codEstado 4002, firma electrónica no válida.
ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact --evento document.failed --cod-estado 4002
# Envía una firma incorrecta. Resultado esperado: estadoHttp 401 y resultado "correcto".
ecuafact webhooks probar --a http://localhost:3000/webhooks/ecuafact --firma-invalida
Con los ejemplos HTTP, el resultado esperado es un 200 la primera vez, y tu
servidor imprime "Autorizado ...". Si repites el mismo cuerpo, tu servidor
responde 200 sin volver a procesarlo, porque es un duplicado. Si cambias un
solo carácter del cuerpo después de firmar o usas otro secreto, responde 401.
El CLI usa un idOperacion nuevo en cada envío; para probar un duplicado,
repite el comando con --id-operacion y el mismo valor.
2. Recibe eventos reales con un túnel. Un túnel publica tu puerto local en una URL pública con HTTPS. Hay varias herramientas gratuitas para hacerlo, por ejemplo estas:
# Con ngrok
ngrok http 3000
# Con cloudflared
cloudflared tunnel --url http://localhost:3000
- Copia la URL
https://...que muestra la herramienta y agrégale la ruta:https://<tu-tunel>/webhooks/ecuafact. - En el portal de pruebas, crea un Nuevo destino con esa URL y guarda
el secreto en la variable
ECUAFACT_WEBHOOK_SECRETde tu servidor local. Reinicia el servidor para que lo lea. - Pulsa Probar y revisa que tu servidor reciba
operation.requires_attentiony que Entregas muestre HTTP 200. - Emite un comprobante de pruebas, como en
Primeros pasos, y espera el
document.authorizedo eldocument.rejected.
La URL de muchos túneles gratuitos cambia cada vez que reinicias la herramienta. Cuando cambie, crea un destino nuevo y deshabilita el anterior, porque si no, el destino viejo acumula fallos y termina pausado.
Errores frecuentes#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| Tu servidor responde 401 a todas las entregas. | Verificas sobre el JSON re-serializado, usas otro secreto o decodificas el secreto como Base64. | Verifica sobre el cuerpo crudo y usa el secreto tal como lo mostró el portal. Más detalle en Verificación de firma. |
| El portal rechaza la URL al crear el destino. | La URL no es HTTPS, usa un puerto distinto del 443, incluye usuario y clave, o resuelve a una IP privada. | Revisa los Requisitos de la URL. |
| Entregas muestra un guion en la columna HTTP y la entrega se reintenta. | Tu servidor no respondió en 15 segundos o no se pudo conectar por DNS, TLS o firewall. La causa exacta está en Intentos. | Responde 200 antes de procesar tareas largas y revisa el certificado TLS de tu dominio. |
| Entregas muestra Rechazado por tu servidor (HTTP 301) o 302. | La URL redirige, por ejemplo porque falta o sobra una barra final o porque redirige desde www. No se reintenta. |
Crea un destino con la URL final exacta, deshabilita el anterior y usa Reenviar en las entregas rechazadas. |
| Entregas muestra Rechazado por tu servidor con 401, 403, 404 u otro 4xx. | Tu endpoint rechazó la entrega por una firma no verificada, una ruta inexistente o una autenticación propia. No se reintenta. | Corrige tu endpoint y usa Reenviar en cada entrega rechazada. |
| El destino aparece Pausado. | Hubo 8 fallos consecutivos sin respuesta o con 408, 429 o 5xx. | Corrige la causa, pulsa Reanudar y revisa en el seguimiento las operaciones que quedaron sin resultado. |
| Procesas dos veces el mismo comprobante. | Tu servidor no descarta los duplicados. | Aplica la clave única eventType + resourceId. |
Siguientes pasos#
- Verificación de firma: sigue el algoritmo paso a paso, prueba con el vector publicado y rota el secreto sin perder entregas.
- Seguimiento de una operación: consulta el estado actual de una operación cuando necesitas confirmarlo.
- Ciclo de vida del comprobante: entiende cómo se relacionan la emisión, el resultado del SRI y los eventos.
- Errores: consulta qué significa cada
codEstadoque llega en el cuerpo de un evento.