Referencia del API

Registra un evento declarado en el canal que identifica la clave de API. El acuse síncrono es el justificante del cliente: fija la posición del evento en la secuencia del canal.

Idempotencia: client_ref debe ser único por canal. Reintentar con el mismo client_ref y el mismo contenido devuelve 200 con el evento original; el mismo client_ref con contenido distinto devuelve 409 y nunca sobrescribe.

Saldo agotado: los eventos se siguen registrando, sellando y encadenando con status: unpaid, hasta el límite de impagados de la cuenta; superado, 402 unpaid_limit_exceeded.

Solo en la modalidad contenido (modality: content): devuelve el contenido declarado tal como lo custodia Safe Creative: el JSON en su forma canónica, la que se usó para la huella, o el fichero, con su nombre original en Content-Disposition. Su huella es el hash del evento. Un evento de solo huella no tiene contenido: 404 not_found.

Permite a los sistemas del cliente vigilarse solos (saldo bajo, impagados, estado operativo).

Inicia la emisión de los informes de certificación firmados (uno en español y otro en inglés) y de su archivo de evidencias para un rango de este canal, por fechas o por números de secuencia.

Se rechaza con 402 account_not_operational mientras la cuenta titular tenga algún evento impagado («cuenta sin saldo operativo»).

La certificación está completed: los informes, el ZIP de evidencias y el código de verificación están listos. Trae data.verification_code; consulta GET /certifications/{certification_id} para obtener URL de descarga vigentes. mode es el de la certificación.

No se ha podido emitir la certificación (status: failed): se devuelve el precio de emisión, si lo hubo, y data.incident_id identifica la incidencia para soporte. Se puede volver a solicitar el mismo rango. mode es el de la certificación.

Se envía una vez por cada cruce a la baja de cada umbral de aviso definido en la consola; el umbral se rearma cuando una compra o un ajuste devuelven el saldo por encima. Siempre live.

El saldo se ha agotado y un evento ha quedado registrado como unpaid (sigue sellado y encadenado). Desde ahora las certificaciones se rechazan con 402 account_not_operational hasta que una compra liquide los impagados. Se envía una vez por agotamiento. Siempre live.

La cuenta ha alcanzado su límite de impagados: desde ahora POST /events responde 402 unpaid_limit_exceeded hasta que una compra liquide la deuda. Siempre live.

Un límite de consumo definido en la consola (por canal o por clave, diario o mensual en UTC) ha llegado a su máximo. Con la acción block, los registros siguientes responden 422 limit_blocked hasta el periodo siguiente; con warn, siguen entrando. Se envía una vez por límite y periodo. Los eventos test no cuentan. Siempre live.

El saldo ha bajado del umbral de recarga automática configurado en la consola y se ha comprado el pack elegido con el medio de pago por defecto en Safe Creative; sus créditos ya están en el saldo (después de liquidar los impagados, si los había). Safe Creative envía la factura. Siempre live.

No se ha podido hacer la recarga automática (data.reason) y se ha desactivado conservando su configuración: se puede volver a activar en la consola. Si la compra se creó pero no se cobró, data.payment_url permite pagarla a mano. Siempre live.

Solo se envía cuando el titular de la cuenta pide desde la consola una entrega de prueba a un endpoint: un único intento, sin reintentos, y nunca cuenta para desactivar el endpoint. Siempre live.

Modalidad contenido: token JSON generado por el proceso del cliente.

Modalidad solo-huella: el contenido nunca sale del perímetro del cliente.

Modalidad contenido: fichero adjunto. 10 MB como máximo.

Cobertura de un evento por un sello de tiempo cualificado (Event.timestamp).

Una versión de la configuración, sellada e inmutable. Los cambios crean versiones nuevas; ninguna se reescribe.

Rango por fechas o por números de secuencia (exactamente un par).

Un informe PDF firmado de una certificación (Certification.reports).

Rango de una certificación (Certification.range), tal como se solicitó: tiene exactamente un par, las fechas de recepción (from, to) o los números de secuencia (seq_from, seq_to); el otro par es nulo.

Una parte ZIP del contenido declarado de una certificación (Certification.content_parts).

Saldo en créditos. Cada evento live consume un crédito; los créditos se compran en packs en la consola, con precio por región y moneda. El saldo en sí no tiene moneda.

Cuerpo común de los webhooks, enviado como POST con Content-Type: application/json. Cabeceras: X-SC-Webhook-Id (el id del sobre, igual en todos los reintentos: úsalo para deduplicar), X-SC-Timestamp (segundos Unix) y X-SC-Signature: v1=<hex>, donde <hex> es HMAC-SHA256 con el secreto del endpoint sobre <X-SC-Timestamp>.<raw body> (el cuerpo tal cual). Verifica la firma y rechaza marcas de tiempo antiguas (p. ej. de más de 5 minutos) antes de procesarlo. Cualquier 2xx confirma la recepción; si no, se reintenta con retroceso exponencial (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h). Un endpoint cuyas entregas siguen fallando se desactiva y se avisa a la cuenta por correo. webhook.test solo se envía cuando el titular de la cuenta pide una entrega de prueba desde la consola: un único intento, sin reintentos, y nunca cuenta para desactivar el endpoint.

El modelo de data depende de type. Con el tiempo pueden añadirse campos a data: ignora los que no conozcas.

Ejemplo (balance.low):

{"id": "ntc_…", "type": "balance.low", "created_at": "2026-09-28T07:00:16.526317Z", "mode": "live",
 "data": {"threshold_id": "thr_…", "threshold": 1000, "balance": 999}}

data de certification.completed y certification.failed.

data de balance.low.

data de balance.exhausted.

data de events.unpaid_limit_reached.

data de consumption.limit_reached.

data de recharge.auto_completed y recharge.auto_failed.

data de webhook.test.