El modelo de evidencia

Esta es la página que explica qué hace distinto a este servicio: no sirve números ni estados, sirve observaciones — con su evidencia, su historia y una línea de tiempo consultable. El modelo es uno para todos los dominios; los ejemplos alternan entre el tipo de cambio y la consulta RUC, y cada campo con estados viene con un ejemplo por valor posible.

El problema

Un tipo de cambio alimenta asientos contables, facturas y declaraciones; el estado de un RUC decide si una factura se acepta. Años después, un auditor pregunta: ¿de dónde salió este dato? Si la API que lo sirvió solo entregaba el valor del día, no hay respuesta: el dato pudo cambiar, la fuente no expone histórico de sus correcciones y el rastro se perdió. Este servicio está construido para que esa pregunta siempre tenga respuesta.

La observación: inmutable por diseño

Cada vez que el servicio observa una fuente oficial, crea una observación: qué publicó la fuente, para qué fecha, de qué fuente y con qué consulta exacta (identidad_consulta), en qué instante (capturado_en), con qué versión del parser, y con qué bytes crudos de respaldo (la evidencia y, en el tipo de cambio, el fragmento exacto del payload del que se parseó el valor).

Ninguno de esos campos se edita jamás. Si la fuente corrige un valor, el servicio no reescribe la observación: crea una nueva que la supersede y lo registra como evento. La observación corregida queda consultable para siempre en /v1/observations/{id}, con su cadena completa de ancestros y sucesoras.

• En el tipo de cambio, la observación es un valor (compra/venta) de una fecha y una serie; nace en cada captura.
• En la consulta RUC, la observación es el estado de un RUC en una edición del padrón; se materializa cuando se responde y es única por RUC y edición: la prueba de lo que se respondió.

El campo fuente: de dónde salió

La revisión: la línea de tiempo del registro

Toda escritura al registro — una captura nueva, una recaptura idéntica, una corrección, la publicación de una edición del padrón — avanza una revisión global, común a todos los dominios. La revisión N es el estado del registro tras el commit número N. Toda respuesta declara en dataset_revision con qué revisión respondió, y as_of_revision=N congela cualquier consulta en ella: la respuesta es siempre la misma, byte a byte.

Ejemplo ilustrativo: el asiento anclado a una revisión

El caso completo de por qué guardar dataset_revision (escenario ilustrativo — el registro real aún no tiene correcciones):

1. El 26/08 su sistema contable toma la venta del día para un asiento: la API responde venta: "3.350", observacion_id: aaaa…, dataset_revision: 731. Su sistema guarda los tres.
2. Días después la fuente corrige ese valor. El servicio no edita nada: crea una observación nueva (venta: "3.355") que supersede a aaaa…, en una revisión posterior (digamos la 810), y abre una alerta.
3. Un auditor cuestiona el asiento. Su respaldo es exacto y reproducible: GET /v1/rates?currency=USD&series=publicado&from=2026-08-26&to=2026-08-26&as_of_revision=731 devuelve exactamente lo que la API le respondió aquel día — venta: "3.350", la misma observación, byte a byte (por eso viaja con ETag y Cache-Control: immutable).
4. Y la misma consulta sin as_of_revision — o /v1/observations/aaaa… — muestra la corrección posterior: superseded_por apunta a la observación nueva. Usted decide si el asiento se ajusta; el servicio le da ambas verdades con fecha y revisión.

Ejemplo real: un auditor en 2028 reconstruye el 1 de septiembre de 2026

Paso 1: mapear el instante a una revisión.

curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  'https://api.eurekia.pe/v1/revisions?at=2026-09-01T23:59:59-05:00'

Respuesta real (2026-09-28, revisión 4414): al cierre del 01/09/2026 en Lima regía la revisión 3479.

{
  "revision": 3479,
  "ts_commit": "2026-09-02T02:00:19.176263Z",
  "dataset_revision": 4414,
  "request_id": "8e783a05-c7a4-43df-81a1-a7c923e2f27f",
  "schema_version": "1.0"
}

Paso 2: consultar anclado a esa revisión. En el tipo de cambio, /v1/rates?…&as_of_revision=3479 devuelve solo las fechas que el registro conocía entonces — ni más ni menos. En el padrón, /v1/ruc/{ruc}?as_of_revision=3479 responde NO_DATA_AT_REVISION: el dominio RUC publicó su primera edición después de esa revisión, y el servicio lo dice en lugar de inventar un estado (la forma en Consulta RUC).

Las marcas: qué le pasó a una observación (tipo de cambio)

marcas lista los eventos que la observación acumuló hasta la revisión consultada. Un escenario por valor:

Las transiciones: qué le pasó a un RUC (consulta RUC)

El padrón no tiene marcas ni supersesión: SUNAT publica cada día la edición entera, y el servicio la compara con la anterior. Cada diferencia por RUC es una transición (estado_anterior → estado_nuevo, los dos snapshots, campos_cambiados), con la revisión desde la que existe. Una edición corregida por SUNAT no reescribe la anterior: aparece como una transición más, en la edición siguiente. La historia completa de un RUC (/v1/ruc/{ruc}/history) es su estado inicial más sus transiciones — la forma en Consulta RUC.

Los controles de integridad

"Controles de integridad" es el paraguas de todo mecanismo con que el servicio contrasta lo que sirve. Cada dominio tiene el suyo, con su alcance declarado en su página:

El cotejo, el día normal — ambas fuentes coinciden (cotejo real del publicado del 25/08/2026 contra el cierre del 24/08/2026):

"cotejos": [
  {
    "cotejo_id": "5c3d6be3-f5cd-4633-b5ee-193523d6791a",
    "contraparte": "3b6f2c09-6897-4730-a84e-1fe72775cbff",
    "resultado": "ok",
    "regla": "publicado_vs_cierre_prev_habil-1.0",
    "revision": 2843,
    "ts": "2026-08-28T22:00:26.894339Z"
  }
],
"tiene_discrepancia_abierta": false

El cotejo, el día discrepante — las fuentes no coinciden (ilustrativo: aún no ha ocurrido en el registro real):

"cotejos": [
  {"contraparte": "1f2e3d4c-…", "resultado": "discrepante",
   "regla": "publicado_vs_cierre_prev_habil-1.0", "revision": 995}
],
"tiene_discrepancia_abierta": true

Ante una discrepancia el servicio no arbitra cuál fuente manda: la expone y deja la decisión al consumidor. La decisión típica: un sistema contable conservador retiene el dato marcado hasta que un cotejo posterior vuelva a ok o un humano decida con constancia. tiene_discrepancia_abierta es el derivado ya calculado: existe un cotejo discrepante posterior al último ok contra la misma contraparte.

La confiabilidad tiene tres valores. verificada significa exactamente esto: la edición reconstruida desde el baseline y las transiciones se contrastó RUC por RUC (18,4 millones de comparaciones) contra el artefacto original. Con el levantamiento exhaustivo tras cada publicación, verificada es el estado normal de toda edición publicada; sin_verificar es la ventana entre publicar y terminar ese levantamiento; fallida es una inconsistencia conocida, con alerta_ref. La respuesta real de Empezar lo muestra.

La supersesión: correcciones sin reescribir el pasado

Dos campos del ítem de tipo de cambio cuentan la historia de vigencia, y no significan lo mismo:

• superseded es relativo a la revisión consultada: false significa "a esa revisión, este era el valor vigente". En un ítem de /v1/rates siempre es false por construcción.
• superseded_por mira el presente: si el dataset actual ya corrigió esa observación, aquí aparece el UUID de la sucesora.

La cadena completa vive en /v1/observations/{id}: cadena.ancestros (las observaciones que esta corrigió) y cadena.sucesoras (las que la corrigieron a ella). Las correcciones son encadenables sin límite: A supersedida por B, B por C — y las tres siguen consultables para siempre.

Sin relleno: nunca otra fecha como si fuera la pedida

El principio es uno: si una fecha no tiene dato, la API lo dice, con la razón del hueco, y jamás entrega otra fecha en lugar de la pedida. Si su sistema recibe un valor, es de la fecha que pidió. La forma cambia por dominio:

La evidencia: verifique el hash usted mismo

Cada captura guarda los bytes exactos que la fuente respondió y su SHA-256. Un solo contrato para toda evidencia: /v1/evidence/{id} da los metadatos (tipo, sha256, bytes, fuente, fecha, descarga_url) y /v1/evidence/{id}/descarga los bytes — directos para una captura pequeña (tipo: observacion, con ETag = sha256), por redirect firmado para un artefacto grande (tipo: artefacto, el ZIP del padrón). La receta completa, ejecutada real en los dos dominios: Verifique la evidencia en 60 segundos.

¿Qué garantiza «inmutable»?

Tres capas, cada una con su alcance declarado — la honestidad del límite es el argumento de confianza, no su debilidad:

1. La aplicación no puede editar. Los roles de base de datos del servicio no tienen privilegios UPDATE ni DELETE sobre las tablas del registro: observaciones, eventos, evidencia, transiciones y revisiones solo se insertan. No es una política de código — es un permiso revocado en la base, probado por los tests del servicio.
2. El administrador de la base de datos podría — y se declara. Un administrador con acceso directo podría alterar filas; ese límite está escrito en la especificación del servicio en vez de escondido. El control compensatorio son las copias de seguridad externas, versionadas y sin borrado desde el servidor, y el archivo de artefactos en un bucket con bloqueo de objetos: contra ellos se detecta una alteración local.
3. Usted puede verificar sin confiar en nadie. Cada respuesta que su sistema guardó se verifica por hash: la evidencia por su SHA-256, las respuestas ancladas a revisión por su ETag, y el servicio registra el hash de cada body servido — ante un body que usted aporte, puede probarse su identidad e integridad.

Retención: indefinida. Ni las observaciones ni la evidencia se borran. Los artefactos del padrón viven en un archivo inmutable con un bloqueo mínimo renovable de 1095 días (el bloqueo impide borrar incluso a quien tenga la clave; se renueva antes de vencer): el bloqueo es el mínimo, no el plazo de retención.

Tabla de estados completa

Los límites, declarados

• El alcance de cada control de integridad está declarado arriba: el cotejo no ve un error común a ambas fuentes; la confiabilidad no ve un error del padrón mismo.
• El alcance exacto de "inmutable" está declarado capa por capa.
• Una corrección de la fuente posterior a la última consulta del día solo se detecta de forma indirecta (por cotejo posterior, o por la transición de la edición siguiente): las fuentes no exponen su propio histórico.

Qué guardar en su sistema

Con cada dato que tome de la API, guarde lo que permite reconstruirlo años después — qué observación lo respaldaba, qué evidencia tenía y qué contenía el registro cuando lo tomó: