# 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`: ```sh 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](calendario.md) 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](consulta-ruc.md#evidencia)). ```sh curl -s https://api.eurekia.pe/v1/health/live # {"status": "alive"} ``` ## Primer request El mismo request, en cada dominio. Ambas respuestas son reales. ### Tipo de cambio La tasa vigente más reciente de la serie `publicado` (SUNAT, USD): ```sh 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. ```json { "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" } ``` ### Consulta RUC El estado de un RUC en la edición corriente del padrón reducido de SUNAT (el RUC de la propia SUNAT): ```sh 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. ```json { "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](registro-de-cambios.md)). | **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](tipo-de-cambio.md#que-es-y-que-no)). | | `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](consulta-ruc.md#que-es-y-que-no)). | | `confiabilidad` | consulta RUC | Si esa edición fue contrastada RUC por RUC contra el artefacto original ([Consulta RUC](consulta-ruc.md#integridad)). | Los estados posibles de cada campo, con un ejemplo por valor, están en [El modelo de evidencia](modelo-de-evidencia.md#tabla-de-estados-completa). ## 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`. ```sh curl -s -H "Authorization: Bearer $EKIA_TOKEN" https://api.eurekia.pe/v1/usage ``` ```json {"cliente": "su-instalacion", "meses": [...], "permisos": {"personas_naturales": true, "descarga_artefactos": false}, ...} ``` ## Buenas prácticas - Guarde `observacion_id` y `dataset_revision` con cada dato que su sistema tome de la API; en el padrón RUC, también `edicion.ordinal` y `edicion.fecha_padron` ([qué guardar](modelo-de-evidencia.md#que-guardar-en-su-sistema)). - Pase el token por variable de entorno (`$EKIA_TOKEN`), jamás literal en scripts o comandos. - Ante un `429`, respete el encabezado `Retry-After`. Límites de uso, cuota de descarga y caché: [Errores y límites](errores-y-limites.md). Siguiente paso: compruebe usted mismo que la evidencia es real — [Verifique la evidencia en 60 segundos](verificar-evidencia.md).