Facturiadocs
Referencia API

Webhooks

Endpoints, el libro de eventos, inspección de entregas y reintento manual.

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.

MétodoRutaQué hace
GET/webhook_endpointsLista los endpoints de webhook
POST/webhook_endpointsRegistra un endpoint de webhook
GET/webhook_endpoints/{webhook_endpoint_id}Devuelve un endpoint de webhook
PATCH/webhook_endpoints/{webhook_endpoint_id}Actualiza un endpoint de webhook
DELETE/webhook_endpoints/{webhook_endpoint_id}Elimina un endpoint de webhook
POST/webhook_endpoints/{webhook_endpoint_id}/pingEnvía un evento sintético para verificar la conexión
POST/webhook_endpoints/{webhook_endpoint_id}/rotate_secretRota el secreto de firma
GET/webhook_endpoints/{webhook_endpoint_id}/deliveriesInspecciona los intentos de entrega
POST/webhook_endpoints/{webhook_endpoint_id}/deliveries/{delivery_id}/retryReenvía un evento
GET/eventsConsulta el libro de eventos (retención de 12 meses)
GET/events/{event_id}Devuelve un evento

GET /webhook_endpoints

Lista los endpoints de webhook

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

Parámetros

ParámetroEnRequeridoTipoNotas
limitquery—integer
cursorquery—stringCursor opaco tomado del next_cursor de una respuesta anterior.

Respuestas

CódigoSignificadoCuerpo
200Una lista de endpoints.lista de WebhookEndpoint

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

ParámetroEnRequeridoTipoNotas
Idempotency-Keyheader—stringLlave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con Facturia-Idempotent-Replay: true. Misma llave y cuerpo distinto → 409.

Cuerpo

CampoTipoRequeridoNotas
urlstringsí
descriptionstring—
enabled_eventsstring[]—Tipos de evento, o ["*"] para todo, incluidos los tipos futuros. Por defecto: ["*"].
empresasRut[]—Restringe las entregas a estas empresas. Por defecto, todas las que la llave puede ver.
Respuestas
CódigoSignificadoCuerpo
201El endpoint creado, con su secreto de firma.WebhookEndpointWithSecret

GET /webhook_endpoints/{webhook_endpoint_id}

Devuelve un endpoint de webhook

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

Parámetros

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring

Respuestas

CódigoSignificadoCuerpo
200El endpoint.WebhookEndpoint

PATCH /webhook_endpoints/{webhook_endpoint_id}

Actualiza un endpoint de webhook

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

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring

Cuerpo

CampoTipoRequeridoNotas
urlstring—
descriptionstring—
enabled_eventsstring[]—
empresasRut[]—
statusenabled · disabled—
Respuestas
CódigoSignificadoCuerpo
200El endpoint actualizado.WebhookEndpoint

DELETE /webhook_endpoints/{webhook_endpoint_id}

Elimina un endpoint de webhook

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

Parámetros

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring

Respuestas

CódigoSignificadoCuerpo
204Eliminado.—

POST /webhook_endpoints/{webhook_endpoint_id}/ping

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

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

Parámetros

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring

Respuestas

CódigoSignificadoCuerpo
202El intento de entrega.WebhookDelivery

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

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring

Respuestas

CódigoSignificadoCuerpo
200El endpoint con su secreto nuevo.WebhookEndpointWithSecret

GET /webhook_endpoints/{webhook_endpoint_id}/deliveries

Inspecciona los intentos de entrega

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

Parámetros

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring
limitquery—integer
cursorquery—stringCursor opaco tomado del next_cursor de una respuesta anterior.
statusquery—pending · succeeded · failed
event_idquery—string

Respuestas

CódigoSignificadoCuerpo
200Una lista de entregas.lista de WebhookDelivery

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

Reenvía un evento

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

Parámetros

ParámetroEnRequeridoTipoNotas
webhook_endpoint_idpathsístring
delivery_idpathsístring

Respuestas

CódigoSignificadoCuerpo
202El nuevo intento de entrega.WebhookDelivery

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 es al-menos-una-vez y sin orden garantizado; deduplica por id.

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

Parámetros

ParámetroEnRequeridoTipoNotas
limitquery—integer
cursorquery—stringCursor opaco tomado del next_cursor de una respuesta anterior.
typequery—string
empresa_rutquery—Rut
created_at[gte]query—string

Respuestas

CódigoSignificadoCuerpo
200Una lista de eventos.lista de Event

GET /events/{event_id}

Devuelve un evento

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

Parámetros

ParámetroEnRequeridoTipoNotas
event_idpathsístring

Respuestas

CódigoSignificadoCuerpo
200El evento.Event

Conectores

Las fuentes de primera parte que alimentan el libro de gastos: Fintoc y la carga de cartolas.

Consumo

El libro de medición inmutable del que sale tu factura.

En esta página

GET /webhook_endpointsPOST /webhook_endpointsGET /webhook_endpoints/{webhook_endpoint_id}PATCH /webhook_endpoints/{webhook_endpoint_id}DELETE /webhook_endpoints/{webhook_endpoint_id}POST /webhook_endpoints/{webhook_endpoint_id}/pingPOST /webhook_endpoints/{webhook_endpoint_id}/rotate_secretGET /webhook_endpoints/{webhook_endpoint_id}/deliveriesPOST /webhook_endpoints/{webhook_endpoint_id}/deliveries/{delivery_id}/retryGET /eventsGET /events/{event_id}