EKIA Data Service

Servicio: Tipo de cambio

El primer dominio del servicio: las series oficiales de tipo de cambio del Perú — publicado (SUNAT) y cierre (SBS vía BCRP) — con cobertura y frescura reales, cotejo diario entre ambas y evidencia descargable por valor. Esta página da la forma exacta de cada principio de la plataforma en este dominio.

Qué es y qué no

Cobertura

Ambas series empiezan el 2026-08-21, el día que el registro entró en producción (cierre entró en producción el 2026-08-28 con la semana en curso). La fuente de la verdad sobre cobertura es /v1/coverage: primera y última fecha por serie y la lista de huecos, cada uno con su razón.

Respuesta real (2026-09-28, revisión 4414): ambas series desde el 2026-08-21, sin huecos.

{
  "series": [
    {
      "moneda": "USD",
      "serie": "cierre",
      "primera": "2026-08-21",
      "ultima": "2026-09-25",
      "total_fechas": 26,
      "huecos": [],
      "criterio_huecos": "dias habiles lun-vie menos feriados, entre primera y ultima"
    },
    {
      "moneda": "USD",
      "serie": "publicado",
      "primera": "2026-08-21",
      "ultima": "2026-09-28",
      "total_fechas": 39,
      "huecos": [],
      "criterio_huecos": "dias habiles lun-vie menos feriados, entre primera y ultima"
    }
  ],
  "dataset_revision": 4414,
  "request_id": "013a1650-843d-48aa-8668-36778d0c7989",
  "schema_version": "1.0"
}

Un hueco es un día hábil sin observación vigente entre la primera y la última fecha de la serie:

huecos[].razon significado
fallo La fuente falló ese día y quedó el evento que lo prueba (fuente no disponible o payload inválido).
nd_fuente La propia fuente declara no tener dato para esa fecha.
sin_dato No hay dato ni causa registrada.

El criterio de día hábil usa el calendario formal de feriados nacionales del servicio; los "días no laborables" decretados ad hoc no cuentan como feriados.

Cadencia medida. publicado se captura todos los días — SUNAT publica también sábados y domingos — en la madrugada de Lima, con re-consultas durante el día para detectar correcciones. cierre existe solo para días hábiles y la fuente lo publica al día hábil siguiente, por la tarde: medido entre el 01/09 y el 04/09/2026, siempre en D+1 hábil, entre las 11:00 y las 17:00 de Lima, nunca en D. En una frase: el cierre de hoy está disponible mañana por la tarde.

Histórico profundo. Llegará por observación retroactiva (backfill): el BCRP publica sus series hacia atrás por API, y el colector las observará con exactamente el mismo mecanismo que las capturas diarias — cada valor histórico será una observación con sus bytes de evidencia, su hash y su procedencia (fuente: bcrp), y su capturado_en dirá honestamente cuándo se observó. Se anunciará aquí cuando exista, no antes.

Frescura

/v1/rates/latest incluye el bloque frescura, que compara la última fecha_serie vigente contra la fecha esperada de la serie, en zona America/Lima: estado (al_dia o atrasada), dias_atraso (días hábiles; n_dias_habiles es su alias histórico), fecha_esperada, hoy_lima.

El día normal — la serie cierre, real:

Respuesta real (2026-09-28, revisión 4414): un miércoles, el cierre esperado es el del martes y está.

{
  "fecha_serie": "2026-09-25",
  "compra": "3.416",
  "venta": "3.425",
  "fuente": "bcrp",
  "cotejos": [
    {
      "cotejo_id": "b659afc7-4689-40e2-8bcc-0e24700fd657",
      "contraparte": "da733871-75f8-41a9-8536-68d9b8bfcf41",
      "resultado": "ok",
      "regla": "publicado_vs_cierre_prev_habil-1.0",
      "revision": 4411,
      "ts": "2026-09-28T23:30:03.291488Z"
    },
    {
      "cotejo_id": "a25934c1-f2b4-42c0-8c0a-113b2bda4c6c",
      "contraparte": "b749c174-6b6c-410b-abff-6fbbc5819054",
      "resultado": "ok",
      "regla": "publicado_vs_cierre_prev_habil-1.0",
      "revision": 4411,
      "ts": "2026-09-28T23:30:03.291488Z"
    },
    {
      "cotejo_id": "296edd5e-e905-46c7-a865-530de172356a",
      "contraparte": "9ebf8e58-8e12-49c0-ad35-d99c23436576",
      "resultado": "ok",
      "regla": "publicado_vs_cierre_prev_habil-1.0",
      "revision": 4411,
      "ts": "2026-09-28T23:30:03.291488Z"
    }
  ],
  "tiene_discrepancia_abierta": false,
  "marcas": [
    "capturada"
  ],
  "observacion_id": "1dab2387-8ba4-4e45-9997-4593038f6038",
  "capturado_en": "2026-09-28T23:30:02.000000Z",
  "superseded": false,
  "superseded_por": null,
  "frescura": {
    "estado": "al_dia",
    "n_dias_habiles": 0,
    "dias_atraso": 0,
    "fecha_esperada": "2026-09-25",
    "hoy_lima": "2026-09-28",
    "zona": "America/Lima"
  },
  "dataset_revision": 4414,
  "request_id": "a0082e21-76c4-49f0-8088-51655c394ddc",
  "schema_version": "1.0"
}

El domingo — ejemplo ilustrativo con la forma exacta de la respuesta y la regla vigente: un domingo (2026-09-06), la serie cierre con dato del jueves (2026-09-03) está al_dia, porque el viernes recién se espera el lunes desde las 17:30:

"frescura": {"estado": "al_dia", "n_dias_habiles": 0, "dias_atraso": 0,
             "fecha_esperada": "2026-09-03", "hoy_lima": "2026-09-06",
             "zona": "America/Lima"}

El registro atrasado — si la última fecha vigente está detrás de la esperada, el servicio lo dice en vez de ocultarlo (ilustrativo: la fuente lleva dos días hábiles sin poder capturarse):

"frescura": {"estado": "atrasada", "n_dias_habiles": 2, "dias_atraso": 2,
             "fecha_esperada": "2026-08-27", "hoy_lima": "2026-08-27",
             "zona": "America/Lima"}

Un registro atrasado tiene además sus alertas abiertas (/v1/alerts); para monitoreo continuo de todas las series existe /v1/health/freshness (plataforma).

Consulta histórica

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

Respuesta real (2026-09-28): un 404 honesto, distinto por diseño de UNSUPPORTED_CURRENCY.

{
  "code": "NO_OBSERVATIONS",
  "message": "no observations in the requested range",
  "request_id": "41799456-0758-4f8a-b9e8-e8ab6572e14f",
  "retryable": false
}

Integridad

El control de integridad de este dominio es el cotejo entre fuentes (cotejos[], tiene_discrepancia_abierta en cada ítem). En producción desde el 28/08/2026: la regla publicado_vs_cierre_prev_habil-1.0 compara el publicado de cada día D contra el cierre del último día hábil anterior a D — el mismo número por construcción, así que un cotejo ok confirma ambas cadenas de captura y uno discrepante delata un error de transmisión, parseo o publicación.

Alcance declarado: SUNAT y BCRP comparten cadena de origen (la tabla de la SBS); el cotejo no detecta un error aguas arriba, común a ambas fuentes. Los valores posibles, el día discrepante y qué hacer con él están en los controles de integridad. Además, cada valor nuevo pasa un control de plausibilidad (marca plausibilidad_baja, sin descartar el dato).

Evidencia

La evidencia de cada valor es pequeña: los bytes exactos del payload de la fuente (24 bytes del tipoCambio.txt; el paquete sellado del colector para cierre), de tipo: observacion. /v1/observations/{id} da evidencia_id y el fragmento exacto del que se parseó el valor; /v1/evidence/{id} los metadatos y /v1/evidence/{id}/descarga los bytes directos con ETag = sha256. Cada descarga cuenta apenas sus bytes en la cuota. Ejecutado real, paso a paso: Verifique la evidencia en 60 segundos.

Restricciones y límites

Qué guardar

observacion_id y dataset_revision con cada valor que tome (qué guardar). Con ellos, /v1/observations/{id} reconstruye la evidencia y as_of_revision lo que contenía el registro cuando lo tomó.

Publicado vs cierre: qué serie usar

No existe "el tipo de cambio oficial" a secas: existen series distintas con usos normativos distintos. Esta guía describe usos típicos; no es asesoría legal ni tributaria — la elección para un caso concreto valídela con su contador.

publicado cierre
Usos típicos Obligaciones que la norma ancla al valor "publicado" en una fecha: IGV (nacimiento de la obligación), detracciones, retenciones, percepciones. Obligaciones ancladas al cierre de una fecha: valuación de saldos en moneda extranjera al cierre del ejercicio (Impuesto a la Renta), estados financieros.
Columna La norma de cada obligación indica compra o venta; la API siempre entrega ambas y usted elige la columna que su regla exige. (ídem)
Disponibilidad El día D en la madrugada de Lima. El día hábil siguiente a D, por la tarde (medido: entre 11:00 y 17:00 de Lima). Fines de semana y feriados no tienen cierre propio.

La consecuencia práctica de la diferencia: el publicado del martes y el cierre del lunes hábil son el mismo número por construcción — pero se citan distinto. Cuando una norma dice "publicado en la fecha X", la serie correcta es publicado en X, no el cierre de X−1, aunque coincidan: ante una fiscalización usted sustenta la serie y la fecha que la norma nombra. Por eso el servicio las sirve separadas y con nombre, en lugar de una sola serie ambigua.