Fecha del hecho, observación y procesamiento: los tres relojes de un acta

Una infracción dice que ocurrió el lunes, la fuente oficial la muestra el jueves y el webhook se entrega el jueves unos segundos después. Si el cliente compara la alerta con el lunes, concluye que la integración demoró tres días. En realidad está midiendo publicación de la fuente y procesamiento interno como si fueran el mismo tramo.

Separar tres relojes permite medir cada parte sin promesas imposibles.

Reloj uno: cuándo ocurrió el hecho informado

occurredAt representa la fecha y hora que la fuente atribuye al hecho. Debe conservarse junto con el valor original, el organismo y la precisión disponible.

No siempre existe un timestamp completo. Una fuente puede mostrar sólo fecha, otra fecha y minutos, y otra un valor con offset. La API no debería completar segundos con cero y presentarlos como precisión real. Puede usar un campo occurredAtPrecision con valores como date, minute o second.

Este reloj ordena la cronología informada de las infracciones. No indica cuándo estuvieron disponibles para ser consultadas.

Reloj dos: cuándo el integrador observó el registro

observedAt marca la primera consulta completa en la que apareció esa versión del acta. Es evidencia sobre el sistema de observación, no sobre la fecha de carga interna del organismo.

Para sostenerla hay que registrar fuente, consulta, respuesta y reglas de deduplicación. Si el portal estaba caído el martes y el acta aparece el miércoles, sólo podemos afirmar que fue observada el miércoles. No sabemos si estuvo publicada durante la caída.

Cuando una reconsulta trae un cambio de monto o de estado del acta, puede crearse una nueva versión con su propio observedAt, manteniendo firstObservedAt para el registro original.

Reloj tres: cuándo se procesó internamente

processedAt indica cuándo la plataforma validó, transformó y persistió el acta observada. En un sistema asíncrono puede ser posterior a la consulta porque hay colas, reintentos o enriquecimientos.

RFC 9110 describe 202 Accepted como una aceptación para procesamiento que todavía no concluyó. Una API que usa ese patrón debe ofrecer un recurso de estado o mecanismo equivalente. La hora del 202 no es necesariamente processedAt; es el momento de aceptación.

La diferencia processedAt - observedAt sí sirve para medir la latencia interna del sistema de detección. También puede separar persistencia y entrega si el webhook se envía más tarde.

Una línea temporal ficticia

Consideremos este caso sintético:

Hay casi tres días entre la infracción y su observación, pero sólo tres segundos de procesamiento y uno de entrega. Sin los tres relojes, el consumidor podría atribuir toda la diferencia al proveedor de API.

Los valores son ficticios y no describen un portal real.

Formato, offset y zona

RFC 3339 define timestamps con una relación explícita a UTC. OpenAPI utiliza ese perfil para el formato date-time. Es una base interoperable para la respuesta pública.

Una implementación puede normalizar a Z para comparar instantes, pero también debería conservar:

• cadena original de la fuente;
• offset que venía en ella;
• zona IANA cuando la documentación permite identificarla;
• regla y versión usada para convertir una hora local sin offset.

La base IANA mantiene reglas históricas. Clavar -03:00 en el código como una verdad eterna pierde esa capacidad y dificulta auditar fechas antiguas.

Ordenar no significa forzar una secuencia

Normalmente processedAt será posterior a observedAt. En cambio, occurredAt puede faltar, corregirse o incluso aparecer posterior por un error de la jurisdicción. El validador debe señalar la anomalía sin descartar automáticamente el registro.

También puede llegar una versión antigua después de una nueva si las consultas o colas se completan fuera de orden. Por eso cada evento necesita identificador estable, versión e idempotency key. El consumidor no debe asumir que orden de entrega equivale a orden del hecho.

Una corrección se representa como nuevo evento enlazado al anterior, no reescribiendo silenciosamente el webhook ya entregado.

Métricas que sí se pueden prometer

Con los relojes separados se calculan métricas honestas:

• latencia de procesamiento: processedAt - observedAt;
• latencia de entrega: aceptación del cliente menos processedAt;
• antigüedad al observar: observedAt - occurredAt, aclarando que incluye la publicación de la fuente;
• frecuencia de reconsulta: intervalo entre intentos completos;
• edad de datos: tiempo desde la última respuesta satisfactoria por fuente.

Un SLA de webhook debería apoyarse en observación o procesamiento, puntos que controla el integrador. Prometer segundos desde el hecho implicaría controlar cuándo publica cada jurisdicción.

Contrato recomendado

Una respuesta puede agrupar los campos bajo timeline e incluir:

{
  "occurredAt": "2026-08-10T18:42:00-03:00",
  "occurredAtPrecision": "minute",
  "firstObservedAt": "2026-08-13T12:00:08Z",
  "processedAt": "2026-08-13T12:00:11Z",
  "sourceTimeRaw": "10/08/2026 18:42"
}

El ejemplo no incluye datos personales ni identificadores reales. El schema debe declarar nulabilidad, formato y semántica de cada campo, además de qué sucede ante una corrección.

Tres relojes, tres responsabilidades

La jurisdicción es responsable del dato que publica; el integrador puede demostrar cuándo lo observó; su plataforma puede medir cuánto tardó en procesarlo. Juntar todo en date borra esas fronteras.

Exponer los tres relojes ayuda a la flota a ordenar hechos, detectar novedades y auditar la operación sin confundir una publicación tardía con una alerta lenta.

Preguntas frecuentes

¿Qué fecha debería ordenar una lista de nuevas infracciones?

Depende de la pregunta. Para cronología vial se usa el hecho; para novedades detectadas, la primera observación; para operación interna, el procesamiento. La API debe exponerlas para que el cliente elija.

¿Una alerta enviada días después del hecho siempre llegó tarde?

No. Si la fuente publicó el registro días después, el integrador no podía observarlo antes. La latencia interna se mide desde `observedAt`, no desde `occurredAt`.

¿Se puede actualizar occurredAt si la fuente corrige la fecha?

Puede publicarse una nueva versión con la corrección y su procedencia, pero conviene conservar el valor anterior y cuándo fue reemplazado para mantener auditoría.

Notas relacionadas