# Verifique la evidencia en 60 segundos

No nos crea: compruébelo. Cuatro pasos llevan de un valor servido por la API
a los bytes exactos que la fuente oficial respondió, con el hash verificado
en su propia máquina. Los pasos son los mismos en todo dominio; cambia solo
el tamaño de la evidencia.

## Los cuatro pasos

1. **Pida un dato.** Toda respuesta trae la observación que lo respalda
   (`observacion_id`) y, en los dominios de archivo, la edición
   (`edicion.sha256`).
2. **Pida la observación** (`GET /v1/observations/{id}`) o use la edición:
   ahí está el identificador de la evidencia (`evidencia_id` o `sha256`).
3. **Pida los metadatos de la evidencia** (`GET /v1/evidence/{id}`):
   `sha256`, `bytes`, `fuente`, `identidad_consulta`, `fecha` y
   `descarga_url`. Un solo contrato para toda evidencia.
4. **Descargue y compare** (`GET /v1/evidence/{id}/descarga`): `sha256sum`
   de lo descargado debe dar exactamente el `sha256` de los metadatos.

## La forma en cada dominio

| paso | tipo de cambio | consulta RUC |
|---|---|---|
| 1. el dato | Un ítem de `/v1/rates` con `observacion_id`. | `/v1/ruc/{ruc}` con `observacion_id` y `edicion.sha256`. |
| 2. el respaldo | `/v1/observations/{observacion_id}` → `evidencia_id` y el `fragmento` exacto del payload del que se parseó el valor. | La edición ya trae el `sha256` del ZIP; la observación materializada (`/v1/observations/{observacion_id}`) apunta a la misma edición. |
| 3. los metadatos | `/v1/evidence/{evidencia_id}` → `tipo: observacion`, 24 bytes de `text/plain`. | `/v1/evidence/{sha256}` → `tipo: artefacto`, ~392 MB de `application/zip`, más `sha256_contenido` del TXT descomprimido y, solo con la marca `descarga_artefactos`, el enlace firmado (`descarga_directa_url`; sin la marca, `null`). |
| 4. la descarga | Los bytes viajan directos, con `X-Sha256` y `ETag`. | Redirect (302) a un enlace firmado de 15 minutos al archivo inmutable; `curl -L` lo sigue. Cuenta en la cuota diaria de descarga y exige un token con la marca `descarga_artefactos` (sin ella, `FORBIDDEN`). |

## Ejecutado real: el tipo de cambio

Paso 1 — el `publicado` del 21 de agosto de 2026:

```sh
curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  'https://api.eurekia.pe/v1/rates?currency=USD&series=publicado&from=2026-08-21&to=2026-08-21'
```

<!-- ejemplo rates_dia: un solo ítem; tome su `observacion_id`. -->
Respuesta real (2026-09-28, revisión 4414): un solo ítem; tome su `observacion_id`.

```json
{
  "items": [
    {
      "fecha_serie": "2026-08-21",
      "compra": "3.351",
      "venta": "3.361",
      "fuente": "sunat_txt",
      "cotejos": [],
      "tiene_discrepancia_abierta": false,
      "marcas": [
        "capturada",
        "recaptura_identica"
      ],
      "observacion_id": "f39403ae-c387-4045-8091-c901973f8feb",
      "capturado_en": "2026-08-21T17:06:47.880642Z",
      "superseded": false,
      "superseded_por": null
    }
  ],
  "total": 1,
  "next_page_token": null,
  "dataset_revision": 4414,
  "request_id": "ac77c194-516e-4ab7-b3ac-6683998cb0b2",
  "schema_version": "1.0"
}
```
<!-- /ejemplo -->

Paso 2 — la observación:

```sh
curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  https://api.eurekia.pe/v1/observations/f39403ae-c387-4045-8091-c901973f8feb
```

<!-- ejemplo observation: declara de qué consulta exacta salió el valor y qué evidencia lo respalda (eventos abreviados); tome `observacion.evidencia_id`. -->
Respuesta real (2026-09-28, revisión 4414): declara de qué consulta exacta salió el valor y qué evidencia lo respalda (eventos abreviados); tome `observacion.evidencia_id`.

```json
{
  "observacion": {
    "id": "f39403ae-c387-4045-8091-c901973f8feb",
    "fecha_serie": "2026-08-21",
    "moneda": "USD",
    "serie": "publicado",
    "compra": "3.351",
    "venta": "3.361",
    "compra_cruda": "3.351",
    "venta_cruda": "3.361",
    "fuente": "sunat_txt",
    "identidad_consulta": "GET https://www.sunat.gob.pe/a/txt/tipoCambio.txt",
    "evidencia_id": "f4a7a1c6-e1a4-4999-b175-7191e90c77c6",
    "fragmento": "21/08/2026|3.351|3.361|",
    "capturado_en": "2026-08-21T17:06:47.880642Z",
    "ejecucion_id": "bccdd8ab-6bcb-4953-a593-3ae237315cb3",
    "version_parser": "sunat_txt-1.0",
    "revision_creada": 217,
    "superseded_por": null
  },
  "superseded": false,
  "cadena": {
    "ancestros": [],
    "sucesoras": []
  },
  "eventos": [
    {
      "id": "f37f595b-5145-4df1-99c0-338777bff447",
      "tipo": "capturada",
      "detalle": {
        "venta": "3.361",
        "compra": "3.351",
        "sha256": "40dad22e26fe688bd700781111a10212e3725ae1bf9c14df92de36787f3d5a59"
      },
      "evidencia_id": "f4a7a1c6-e1a4-4999-b175-7191e90c77c6",
      "ejecucion_id": "bccdd8ab-6bcb-4953-a593-3ae237315cb3",
      "revision": 217,
      "ts": "2026-08-21T17:06:47.867368Z"
    },
    {
      "…": "2 eventos más"
    }
  ],
  "cotejos": [],
  "dataset_revision": 4414,
  "request_id": "aff42acd-a6a5-41f1-80b5-5fc5408ffe66",
  "schema_version": "1.0"
}
```
<!-- /ejemplo -->

Paso 3 — los metadatos de la evidencia:

```sh
curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  https://api.eurekia.pe/v1/evidence/f4a7a1c6-e1a4-4999-b175-7191e90c77c6
```

<!-- ejemplo evidence_observacion: 24 bytes de `text/plain`; el `sha256` es lo que va a comprobar. -->
Respuesta real (2026-09-28, revisión 4414): 24 bytes de `text/plain`; el `sha256` es lo que va a comprobar.

```json
{
  "id": "f4a7a1c6-e1a4-4999-b175-7191e90c77c6",
  "tipo": "observacion",
  "sha256": "40dad22e26fe688bd700781111a10212e3725ae1bf9c14df92de36787f3d5a59",
  "bytes": 24,
  "content_type": "text/plain",
  "fuente": "sunat_txt",
  "identidad_consulta": "GET https://www.sunat.gob.pe/a/txt/tipoCambio.txt",
  "fecha": "2026-08-21T17:06:47.880642Z",
  "descarga_url": "/v1/evidence/f4a7a1c6-e1a4-4999-b175-7191e90c77c6/descarga",
  "observacion_id": "f39403ae-c387-4045-8091-c901973f8feb",
  "fecha_serie": "2026-08-21",
  "moneda": "USD",
  "serie": "publicado",
  "verificacion": "descargue los bytes y compare: sha256sum <archivo> debe dar exactamente `sha256`",
  "dataset_revision": 4414,
  "request_id": "2d81924c-5560-4a4f-aa7e-5bbea032ede5",
  "schema_version": "1.0"
}
```
<!-- /ejemplo -->

Paso 4 — descargue y compare:

```sh
curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  -D encabezados.txt -o evidencia.txt \
  https://api.eurekia.pe/v1/evidence/f4a7a1c6-e1a4-4999-b175-7191e90c77c6/descarga

cat evidencia.txt
# 21/08/2026|3.351|3.361|

sha256sum evidencia.txt
# 40dad22e26fe688bd700781111a10212e3725ae1bf9c14df92de36787f3d5a59  evidencia.txt

grep -i x-sha256 encabezados.txt
# x-sha256: 40dad22e26fe688bd700781111a10212e3725ae1bf9c14df92de36787f3d5a59
```

**Coinciden.** Esos 24 bytes son el `tipoCambio.txt` que SUNAT publicó ese
día, tal cual llegó por HTTP; el hash que usted calculó es el que el
servicio registró al capturarlo y el que viaja como `ETag`.

## Ejecutado real: el padrón RUC

Pasos 1 y 2 — la edición viene en la respuesta de `/v1/ruc/{ruc}`
([primer request](empezar.md#primer-request)): tome `edicion.sha256`.

Paso 3 — los metadatos del artefacto (enlace firmado abreviado; capturado
con un token que lleva la marca `descarga_artefactos` — sin ella,
`descarga_directa_url` y `descarga_expira_en` vienen en `null`):

```sh
curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  https://api.eurekia.pe/v1/evidence/399fcfa5568b531259420a3dce56152c89a5bbe23883ff3ff60596d641690d03
```

<!-- ejemplo evidence_artefacto: el ZIP del padrón de una edición, con el sha256 del ZIP y el del TXT descomprimido. -->
Respuesta real (2026-09-28, revisión 4414): el ZIP del padrón de una edición, con el sha256 del ZIP y el del TXT descomprimido.

```json
{
  "id": "ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9",
  "tipo": "artefacto",
  "sha256": "ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9",
  "bytes": 392899559,
  "content_type": "application/zip",
  "fuente": "sunat_padron_reducido",
  "identidad_consulta": "https://www2.sunat.gob.pe/padron_reducido_ruc.zip",
  "fecha": "2026-09-28T08:30:09.240463Z",
  "descarga_url": "/v1/evidence/ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9/descarga",
  "fecha_padron": "2026-09-28",
  "sha256_contenido": "19fc944d450767fba4adc761a3aa784b165b67a7e25834c1d9c25b25d2ba25b0",
  "descargado_en": "2026-09-28T08:30:09.240463Z",
  "http_last_modified": "2026-09-28T07:36:30.000000Z",
  "http_etag": "6aba18fe-176b2be7",
  "durable_verificado_en": "2026-09-28T08:30:09.240463Z",
  "cf_cache_status": "HIT",
  "cf_ray": "a421626db92b803e-CDG",
  "txt_mtime": "2026-09-28T07:30:14.000000Z",
  "capturado_por": "colector",
  "interpretaciones": [
    {
      "interpretacion_id": 28,
      "resultado": "aceptada"
    }
  ],
  "decision": {
    "decision": "publicada",
    "motivo": "aceptada",
    "ts": "2026-09-28T08:30:09.240463Z"
  },
  "descargable": true,
  "descarga_directa_url": "https://s3.eu-central-003.backblazeb2.com/ekia-archivo-01/padron-ruc/2026/09/28/ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20260929T012901Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=…",
  "descarga_expira_en": "2026-09-29T01:44:01.606695Z",
  "verificacion": "descargue el artefacto y compare: sha256sum <archivo> debe dar exactamente `sha256`; unzip -p <archivo> | sha256sum debe dar `sha256_contenido`",
  "dataset_revision": 4414,
  "request_id": "392c1416-beea-4ff4-be52-f1155c11f945",
  "schema_version": "1.0"
}
```
<!-- /ejemplo -->

Paso 4 — descargue (392 MB, unos 20 segundos) siguiendo el redirect y
compare los dos hashes. Solo con un token propio que lleve la marca
`descarga_artefactos`; el artefacto íntegro trae los campos que la API
suprime para personas naturales ([por qué](consulta-ruc.md#evidencia)):

```sh
curl -sL -o padron.zip -H "Authorization: Bearer $EKIA_TOKEN" \
  https://api.eurekia.pe/v1/evidence/399fcfa5568b531259420a3dce56152c89a5bbe23883ff3ff60596d641690d03/descarga

sha256sum padron.zip                    # = sha256
unzip -p padron.zip | sha256sum         # = sha256_contenido
```

> Esto funciona para *cualquier* dato del registro, hoy y dentro de diez
> años: la evidencia es inmutable por diseño y se conserva de forma
> indefinida. Qué hay detrás — observaciones, revisiones, supersesión,
> transiciones — está en [El modelo de evidencia](modelo-de-evidencia.md).