EKIA Data Service

Empezar

Cómo se autentica la API, su primer request en cada dominio con la respuesta real que devuelve, qué mirar en esa respuesta y cómo consultar su consumo.

Estado del servicio: en desarrollo

Servicio en desarrollo, sin acceso público por ahora. La API está desplegada y esta documentación es espejo de lo que hoy responde, pero no se otorga acceso a terceros: no hay tokens de evaluación ni vía para pedir uno, y esta página no se la ofrece. La documentación se publica como material técnico, para que el contrato esté escrito antes de abrirse y no haya sorpresas ese día. La apertura tiene condiciones declaradas (empresa constituida, dictamen legal sobre el padrón, banco de datos inscrito, términos y canal de derechos operativos); hasta entonces, la API sirve solo al desarrollo del producto.

Los comandos de esta documentación usan la variable $EKIA_TOKEN. En los ejemplos que la muestran, el valor es un token ficticio, marcado como tal, que la API rechaza con UNAUTHORIZED:

export EKIA_TOKEN='TOKEN-FICTICIO-solo-para-leer-esta-documentacion'

Autenticación

Todos los endpoints exigen un token Bearer en el encabezado Authorization, con dos excepciones públicas: GET /v1/health/live (vivo o no) y GET /v1/calendario/feriados (el calendario formal del servicio). Un token identifica a una instalación (una base de datos); el servicio guarda solo su hash y registra cada respuesta que le sirve. La descarga del artefacto íntegro del padrón exige además una marca en el token (Consulta RUC).

curl -s https://api.eurekia.pe/v1/health/live
# {"status": "alive"}

Primer request

El mismo request, en cada dominio. Ambas respuestas son reales.

La tasa vigente más reciente de la serie publicado (SUNAT, USD):

curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  'https://api.eurekia.pe/v1/rates/latest?currency=USD&series=publicado'

Respuesta real (2026-09-28, revisión 4414): la tasa publicada por SUNAT hoy, al día.

{
  "fecha_serie": "2026-09-28",
  "compra": "3.416",
  "venta": "3.425",
  "fuente": "sunat_txt",
  "cotejos": [
    {
      "cotejo_id": "296edd5e-e905-46c7-a865-530de172356a",
      "contraparte": "1dab2387-8ba4-4e45-9997-4593038f6038",
      "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",
    "recaptura_identica",
    "sin_cotejo"
  ],
  "observacion_id": "9ebf8e58-8e12-49c0-ad35-d99c23436576",
  "capturado_en": "2026-09-28T07:30:22.576273Z",
  "superseded": false,
  "superseded_por": null,
  "frescura": {
    "estado": "al_dia",
    "n_dias_habiles": 0,
    "dias_atraso": 0,
    "fecha_esperada": "2026-09-28",
    "hoy_lima": "2026-09-28",
    "zona": "America/Lima"
  },
  "dataset_revision": 4414,
  "request_id": "c3f162c0-1781-4e5d-995d-b5e2be9dba28",
  "schema_version": "1.0"
}

El estado de un RUC en la edición corriente del padrón reducido de SUNAT (el RUC de la propia SUNAT):

curl -s -H "Authorization: Bearer $EKIA_TOKEN" \
  https://api.eurekia.pe/v1/ruc/20131312955

Respuesta real (2026-09-28, revisión 4414): la SUNAT en la edición corriente del padrón.

{
  "ruc": "20131312955",
  "dv_valido": true,
  "dataset_revision": 4414,
  "request_id": "0010a98b-c82d-4d52-a927-3d10b635ea83",
  "schema_version": "1.0",
  "estado_fila": "presente",
  "nombre": "SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA - SUNAT",
  "estado": "ACTIVO",
  "condicion": "HABIDO",
  "domicilio": {
    "ubigeo": "150101",
    "tipo_via": "AV.",
    "nombre_via": "GARCILASO DE LA VEGA",
    "codigo_zona": null,
    "tipo_zona": null,
    "numero": "1472",
    "interior": null,
    "lote": null,
    "departamento": null,
    "manzana": null,
    "kilometro": null
  },
  "campos_restringidos": [],
  "motivo_restriccion": null,
  "lineas_sin_clave_edicion": 1,
  "edicion": {
    "fecha_padron": "2026-09-28",
    "ordinal": 26,
    "interpretacion_id": 28,
    "sha256": "ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9",
    "evidence_url": "/v1/evidence/ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9"
  },
  "confiabilidad": "verificada",
  "alerta_ref": null,
  "observacion_id": "9704096f-7064-4b57-bf92-b9594d6fac46",
  "frescura": {
    "estado": "al_dia",
    "dias_atraso": 0,
    "fecha_esperada": "2026-09-28",
    "edicion_esperada": "2026-09-28",
    "hoy_lima": "2026-09-28",
    "zona": "America/Lima"
  },
  "ausencia_comprobada": null,
  "revision_lineas": 4414,
  "ausencia_version": "1",
  "reglas_cpe": {
    "version": "1",
    "r1083": {
      "resultado": "cumple",
      "consecuencia": "rechazo"
    },
    "r4013": {
      "resultado": "cumple",
      "consecuencia": "observacion"
    },
    "r4014": {
      "resultado": "cumple",
      "consecuencia": "observacion"
    }
  },
  "sucesion": {
    "valor": false,
    "version": "1"
  }
}

Qué mirar en la respuesta

Toda respuesta tiene dos partes: el sobre, común a todos los dominios (nombres en inglés), y los campos del dominio (nombres en español).

El sobre

campo por qué importa
dataset_revision La revisión del registro con la que se respondió. Guardada junto al dato, permite reconstruir después exactamente qué se sabía: as_of_revision congela cualquier consulta en ella.
request_id Identificador del request. El servicio registra el SHA-256 de los bytes exactos que sirvió; con este id puede demostrarse después qué respuesta se dio.
schema_version Versión del esquema de respuesta (1.0). En /v1 solo se agregan campos; un nombre reemplazado queda deprecado y sigue viajando (registro de cambios).

Los campos del dominio — el detalle de cada uno está en su página de servicio:

campo dominio por qué importa
observacion_id todos La observación inmutable que respalda el valor o el estado. Guárdelo junto al dato: es su trazabilidad de punta a punta.
frescura todos Si el registro está al día frente a la fecha esperada del dominio, en zona de Lima: estado, dias_atraso, fecha_esperada.
compra / venta tipo de cambio Texto de exactamente 3 decimales. Nunca pasan por punto flotante en el servicio; parséelos con un tipo decimal, no con float (Tipo de cambio).
estado_fila, estado, condicion consulta RUC Qué decía el padrón sobre el RUC en esa edición; edicion dice cuál (Consulta RUC).
confiabilidad consulta RUC Si esa edición fue contrastada RUC por RUC contra el artefacto original (Consulta RUC).

Los estados posibles de cada campo, con un ejemplo por valor, están en El modelo de evidencia.

Su consumo: /v1/usage

GET /v1/usage devuelve el consumo del token que consulta, por mes (hora de Lima) y por dominio (tipo_de_cambio, ruc, plataforma), contado sobre el registro de uso: toda respuesta autenticada, errores incluidos. La consulta en curso se registra al responder, así que aparece recién en la siguiente. Desde el 2026-10-12 trae además permisos: los permisos del token, fijados al emitirlo (personas_naturales, descarga_artefactos), para que su sistema los muestre en palabras en vez de descubrirlos con un 403.

curl -s -H "Authorization: Bearer $EKIA_TOKEN" https://api.eurekia.pe/v1/usage
{"cliente": "su-instalacion", "meses": [...],
 "permisos": {"personas_naturales": true, "descarga_artefactos": false}, ...}

Buenas prácticas

Siguiente paso: compruebe usted mismo que la evidencia es real — Verifique la evidencia en 60 segundos.