Webhooks

Base: https://api.facturia.cl/v1. Todos los endpoints de este capítulo se autentican con Authorization: Bearer salvo que se diga lo contrario, y el sobre de error es el de Errores.

GET /webhook_endpoints

Lista los endpoints de webhook

Los endpoints de webhook configurados para la cuenta, con sus enabled_events y la salud de entrega; los secretos nunca se incluyen.

curl -sS https://api.facturia.cl/v1/webhook_endpoints \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

POST /webhook_endpoints

Registra un endpoint de webhook

El secret se devuelve una sola vez, al crearlo, y nunca más.

curl -sS -X POST https://api.facturia.cl/v1/webhook_endpoints \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.miempresa.cl/hooks/facturia"}'

Parámetros

Cuerpo

GET /webhook_endpoints/{webhook_endpoint_id}

Devuelve un endpoint de webhook

La configuración y la salud de entrega de un endpoint de webhook, sin su secreto de firma.

curl -sS https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

PATCH /webhook_endpoints/{webhook_endpoint_id}

Actualiza un endpoint de webhook

Actualiza url, enabled_events o description. El secreto de firma no cambia — usa rotate_secret para eso.

curl -sS -X PATCH https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.miempresa.cl/hooks/facturia","description":"…"}'

Parámetros

Cuerpo

DELETE /webhook_endpoints/{webhook_endpoint_id}

Elimina un endpoint de webhook

Elimina el endpoint y destruye su secreto de firma (el actual y el anterior) en la bóveda; se eliminan juntos para que no quede un secreto huérfano después de borrar la fila.

curl -sS -X DELETE https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

POST /webhook_endpoints/{webhook_endpoint_id}/ping

Envía un evento sintético para verificar la conexión

Envía un evento ping sintético a la URL actual del endpoint, para que quien integra pueda verificar la validación de firma antes de depender de un evento real.

curl -sS -X POST https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W/ping \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

POST /webhook_endpoints/{webhook_endpoint_id}/rotate_secret

Rota el secreto de firma

El secreto anterior sigue firmando 24 horas, así que puedes desplegar sin corte.

curl -sS -X POST https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W/rotate_secret \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

GET /webhook_endpoints/{webhook_endpoint_id}/deliveries

Inspecciona los intentos de entrega

Los intentos de entrega de este endpoint, del más nuevo al más antiguo, con el estado de respuesta de cada uno y si se va a reintentar.

curl -sS https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W/deliveries \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

POST /webhook_endpoints/{webhook_endpoint_id}/deliveries/{delivery_id}/retry

Reenvía un evento

Limitado a 20/min por cuenta, no por credencial (ticket #152): una llave filtrada convertiría esto en un amplificador gratis de peticiones salientes desde nuestras propias IP. Hay además un techo duro de 20 intentos de entrega por par (endpoint, evento), que se responde como 409 too_many_replays.

curl -sS -X POST https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W/deliveries/whd_01K2RG1P4M7X01/retry \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

GET /events

Consulta el libro de eventos (retención de 12 meses)

La retención es de 12 meses — a propósito más larga que un libro de webhooks típico, para que un ciclo tributario completo de F29 siga siendo reproducible. La entrega de webhooks es al-menos-una-vez y sin orden garantizado; deduplica por id.

Polling en vez de webhooks. Si no puedes exponer un endpoint HTTPS —un agente personal, un notebook, cualquier cosa detrás de NAT—, este endpoint es el sustituto soportado, y ?after= es el parámetro que lo hace funcionar:

GET /v1/events?after=evt_01K2RG1P4M7X&limit=100

after pagina HACIA ADELANTE: del más antiguo al más nuevo, estrictamente posteriores al id que nombras, con next_cursor alejándose de él. El loop es after = next_cursor ?? after, procesando data en orden; nunca relee una fila y no necesita un conjunto de ids ya vistos. after acepta tanto un id evt_… (el último evento que procesaste) como un valor cur_… de next_cursor, así que tu checkpoint guardado y el token que te entregamos son intercambiables. Cuando has_more es false, next_cursor es null: guarda el id del último evento que procesaste y manda ese la próxima vez.

cursor es la dirección contraria y es el default: del más nuevo al más antiguo, «más viejo que esto», que es lo que quiere un panel leyendo un libro. Mandar los dos es 400 en vez de una precedencia silenciosa: nombran posiciones en órdenes opuestos, y honrar cualquiera de los dos saltaría filas para la mitad de quienes llaman sin decirles nada.

curl -sS https://api.facturia.cl/v1/events \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

GET /events/{event_id}

Devuelve un evento

Un evento del registro propio de la cuenta — el mismo objeto que lleva una entrega de webhook — para quien concilia por id en vez de por suscripción.

curl -sS https://api.facturia.cl/v1/events/evt_01K2RG1P4M7X \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas