4. Registrar eventos

4.1 La llamada

POST /events con tu clave del canal. Según la modalidad del canal:

• Contenido (JSON): client_ref + payload (hasta 256 KB).
• Contenido (fichero): multipart con client_ref + file (hasta 10 MB).
• Solo-huella: client_ref + hash + hash_alg (sha-256 o sha-512). Calcula la huella del dato que custodias; el dato no se envía.

occurred_at es opcional y es parte de tu declaración: dice cuándo afirmas que ocurrió el hecho. Lo que Safe Creative acredita con el sello es received_at — cuándo se recibió. El informe siempre distingue ambas cosas.

4.2 Idempotencia: reintenta sin miedo

client_ref es tu identificador único del evento (por canal). Si reintentas la misma llamada —timeout, corte de red— el evento no se duplica: recibirás 200 con el evento original. Si reutilizas un client_ref con contenido distinto, 409: nada se sobreescribe jamás.

Regla práctica: genera el client_ref antes de llamar (id de tu transacción, UUID persistido) y reintenta con retroceso exponencial ante 5xx o timeout. Con eso, tu integración es a prueba de cortes. Y si tu proceso no puede permitirse perder declaraciones ante un corte largo, añade una cola local de salida (un búfer persistente desde el que reenvías): tus eventos entrarán cuando el servicio vuelva, cada uno con su fecha real de recepción.

4.3 Secuencia y orden

La secuencia la asigna el servicio al recibir: estrictamente creciente y sin huecos por canal. El orden probatorio es el orden de recepción, no occurred_at. Si el orden de tus eventos importa, envíalos ordenados o serializa tus llamadas.