Registro de cambios del contrato

Todo cambio del contrato de la API queda anotado aquí, con fecha de Lima, antes de desplegarse. En /v1 solo se agregan campos y rutas: ningún campo cambia de significado ni desaparece; un nombre reemplazado se declara deprecado y sigue viajando. Las entradas anteriores al 2026-09-07 se reconstruyeron desde el registro de decisiones del repositorio.

2026-10-12 — /v1/usage informa los permisos del token (ESP-009, decisión 11 del fundador)

Cambio de contrato, aditivo. GET /v1/usage trae un objeto nuevo, permisos, con los dos permisos del token que consulta, fijados al emitirlo (adenda a ESP-006 A.1): personas_naturales (datos de personas naturales y by-dni) y descarga_artefactos (descarga de artefactos del padrón). Un consumidor —el módulo de consulta de RUC de EKIA en su paso del setup— los muestra en palabras sin provocar un 403. Nada más cambia: los campos existentes conservan su significado; schema_version sigue en "1.0". Un cliente que no conoce permisos lo ignora.

2026-09-28 — Consulta RUC: permiso de personas naturales, reglas del comprador, sucesión, ausencia comprobada y caché sin ETag (adenda a ESP-006 del 2026-09-26)

Cambio de contrato, aditivo, que rige desde la activación R0, registrada en producción el 2026-09-28 (hora de Lima) en la revisión 4413 del dataset. Hasta esa revisión el servicio respondió exactamente como antes, y una respuesta anclada a una revisión anterior sigue sin los campos nuevos. schema_version sigue en "1.0".

• Permiso personas_naturales por token (A.1), fijo al emitir el token: reemplaza la restricción fija de E1. Sin él, para un RUC de persona natural nombre, domicilio, lineas y sucesion van en null y en campos_restringidos, con motivo_restriccion; by-dni responde FORBIDDEN. campos_restringidos viene siempre (vacío si no restringe). Parámetro nuevo restringir_personas_naturales=true: pide la respuesta restringida. En /history aplica a cada estado y cada transición (cada uno con su campos_restringidos) y el cursor conserva la restricción de la primera página; 400 si el parámetro lo contradice.
• Campos nuevos en /v1/ruc/{ruc} y by-dni con campos de estado: reglas_cpe (A.2, versión "1"), sucesion (A.3, "1"), ausencia_comprobada, revision_lineas y ausencia_version (A.5, "1"). Nunca en /history ni con as_of_fecha sin edición efectiva. Una respuesta anclada a una revisión anterior a R0 no los trae y conserva su contenido resuelto.
• Caché (A.7) de las cinco rutas del dominio, ancladas o no: private, no-store, sin ETag, Vary: Authorization (salvo ruc-coverage); If-None-Match: * sobre un 200 → 304 sin cuerpo con los mismos encabezados; otro valor → 200; los errores se responden aunque traigan la precondición. Sustituye a ETag: "rev-N" + no-cache y a immutable en este dominio; el tipo de cambio no cambia.
• Un solo reloj por respuesta (A.6): frescura, la edición esperada, las filas sintéticas de ruc-coverage, la razón de una fecha sin edición y el vencimiento del enlace firmado salen del mismo instante.
• 503 SERVICE_UNAVAILABLE con Retry-After si una activación vigente nombra una versión de regla que la instancia no conoce (A.6).
• Nuevo aviso del servicio linea_sin_clave_sin_revisar (A.5), uno por línea sin número de RUC del padrón que ninguna persona de EKIA revisó; su detalle.mensaje está en palabras de usuario y no requiere acción.

2026-09-26 — Corrección: el enlace firmado de los metadatos del artefacto respeta la marca descarga_artefactos

No es un cambio de contrato: alinea el código con la decisión D-2026-09-08 ya publicada el 2026-09-10. Hallazgo del dictamen de ESP-009 v0.3 (N-3).

• GET /v1/evidence/{sha256} (metadatos de un artefacto del padrón) entregaba descarga_directa_url —el enlace firmado de 15 minutos al ZIP íntegro— a todo token, aunque /descarga ya respondiera FORBIDDEN al mismo token sin la marca. Desde hoy, sin la marca descarga_artefactos esos dos campos (descarga_directa_url, descarga_expira_en) son null y no se firma enlace alguno; con la marca, todo sigue igual. Los demás metadatos (ambos hashes, fecha, tamaño, interpretaciones, decisión) no cambian para nadie.
• Las capturas del tipo de cambio (/v1/evidence/{uuid}) no cambian: se siguen descargando con cualquier token de lectura.

Cambio de contrato, aditivo: GET /v1/calendario/feriados con year agrega cinco campos; ningún campo existente cambia de valor ni de significado, y la llamada sin year responde exactamente lo de antes.

• Nuevos con year: contract_version (1), year, coverage (complete | unsupported, declarada por año, nunca deducida de las filas: una lista vacía con complete es un año sin feriados; unsupported es "el servicio no declara cobertura"), declarations[] (fecha, nombre, fuente, dataset_revision de la declaración) y tombstones[] (retiros explícitos: fecha, nombre, fuente que retira, motivo, dataset_revision del retiro, retira_revision de la declaración retirada; se sirven sin plazo).
• feriados[] se conserva como alias permanente de declarations sin dataset_revision; criterio y zona no cambian. Sin year: respuesta original (todas las vigentes de todos los años), sin los cinco campos nuevos, porque no hay año al que referirlos; un cliente que sincroniza manda year siempre.
• Datos: 2027 cargado (16 feriados, norma por fila; Semana Santa del calendario litúrgico 2027 identificado por su SHA-256, cotejada con el histórico de gob.pe 2022-2026) y cobertura declarada complete para 2026 y 2027. Los 16 feriados de 2026 pasan al registro de actos con origen "migración": su revisión es la de la migración 010, no la de la declaración original (existen desde la migración 003 del 2026-08-21).
• Alcance escrito: solo feriados nacionales por ley; los días no laborables por decreto supremo y los feriados regionales no entran (página del dominio). Los cambios del calendario dejan de ser migraciones: son actos de declaración y retiro con revisión propia.
• Ejemplo de la referencia y de la página: proyectado desde un servicio local con la migración aplicada; se recaptura de producción tras el despliegue.

2026-09-10 — Modo desarrollo cerrado (D-2026-09-08): descarga de artefactos restringida por marca en el token

• GET /v1/evidence/{sha256}/descarga (artefactos del padrón) responde FORBIDDEN a todo token sin la marca descarga_artefactos; la marca se otorga solo a tokens propios de lectura, nunca a uno de evaluación. Las capturas del tipo de cambio (/v1/evidence/{uuid}/descarga, 24 bytes) no cambian. Los metadatos de todo artefacto siguen disponibles.
• La credencial pública de evaluación queda revocada; no se emiten tokens a terceros. El servicio opera igual (ingesta, archivo, verificación, vigilancias, backup): se cierra la puerta, no el motor.

2026-09-10 — Calendario documentado como tercer dominio; modo desarrollo

Sin cambio de contrato. GET /v1/calendario/feriados (público desde el 2026-09-07) pasa a tener página de servicio propia (Calendario) con la plantilla de 8 H2 y se documenta como parte del servicio en desarrollo. Cobertura del calendario: el año 2026 completo (16 feriados: Decreto Legislativo 713 art. 6, Ley 31381, Ley 31788); un año nuevo o un feriado nuevo entran por migración del servicio y se anotan aquí.

La documentación deja de ofrecer acceso (modo desarrollo): no muestra credenciales ni invita a pedir un token; la referencia interactiva va sin consola. El contrato no cambia.

2026-09-07 — Consolidación del contrato tras el segundo dominio

Cambio pre-cliente-externo: el único consumidor de la API a esta fecha es el módulo de Odoo de Eurekia, que no lee /v1/evidence (lee /v1/rates, /v1/rates/latest, /v1/alerts y /v1/health/live), así que ningún consumidor se adapta.

• Evidencia unificada. GET /v1/evidence/{id} responde SIEMPRE los metadatos JSON de la evidencia, con un bloque común (id, tipo, sha256, bytes, content_type, fuente, identidad_consulta, fecha, descarga_url) más los campos propios de cada tipo. Los bytes se piden en GET /v1/evidence/{id}/descarga: directos para una captura (tipo: observacion; ETag = sha256, immutable) y redirect firmado de 15 minutos para un artefacto (tipo: artefacto). Antes, la ruta con UUID devolvía los bytes y la ruta con sha256 los metadatos. En los metadatos del artefacto, descarga_url pasa a ser la ruta /descarga (como en toda evidencia) y el enlace firmado se llama descarga_directa_url; descarga_redirect se retira (había nacido el mismo día, sin consumidores).
• Cuota de bytes de descarga por token y día en /descarga: demo 2 GB; token propio 20 GB (propuesto a partir del egreso medido). Al agotarse, DOWNLOAD_QUOTA (429, retryable: true) con Retry-After. El redirect de un artefacto cuenta por el tamaño del artefacto.
• Paginación de /v1/ruc/{ruc}/history: máximo 500 transiciones por página; total_transiciones y next_page_token (mismo cursor opaco a revisión fija que /v1/rates, parámetro page_token); estado_inicial solo en la primera página.
• Caché del dominio RUC: las respuestas corrientes (sin as_of_*) de /v1/ruc/* y /v1/ruc-coverage llevan ETag: "rev-N" y Cache-Control: no-cache; If-None-Match responde 304 mientras el registro no avance. Las ancladas siguen immutable.
• Nombres canónicos de frescura y huecos (glosario de la documentación): frescura.dias_atraso y frescura.fecha_esperada en todo dominio; cobertura[].razon y cobertura.razon en RUC. Se agregan de forma aditiva. Deprecados (siguen viajando con el mismo valor): frescura.n_dias_habiles (tipo de cambio), frescura.edicion_esperada y causa (RUC).
• Errores: la tabla completa vive en Errores y límites; DOWNLOAD_QUOTA es nuevo.
• Referencia: tags por servicio en el orden del catálogo (/v1/revisions pasa de Cobertura a Revisiones); /v1/evidence/{id} y /descarga se documentan una sola vez bajo Observaciones y evidencia.

2026-09-07 — Dominio Consulta RUC en producción

• Rutas nuevas: GET /v1/ruc/{ruc} (as_of_revision, as_of_fecha), GET /v1/ruc/{ruc}/history, GET /v1/ruc-coverage, GET /v1/ruc/by-dni/{dni} (responde FORBIDDEN hasta el dictamen legal E1), GET /v1/usage, GET /v1/calendario/feriados (público, sin token), GET /v1/evidence/{sha256} y GET /v1/evidence/{sha256}/descarga.
• Códigos nuevos: FORBIDDEN (403), NO_DATA_AT_REVISION (404), SERVICE_UNAVAILABLE (503 con Retry-After; antes un fallo de base de datos era INTERNAL).
• Frescura del padrón: edicion_esperada desde las 04:00 de Lima.

2026-09-06 — Frescura de la serie cierre

• fecha_esperada de cierre: el mayor día hábil cuyo siguiente día hábil ya pasó las 17:30 de Lima (sábado y domingo esperan el jueves; el lunes antes de las 17:30 el jueves y desde las 17:30 el viernes). Reemplaza la regla del 2026-09-04, que pedía el viernes ya el sábado.

2026-08-28 — Serie cierre y cotejos

• series=cierre (USD, SBS vía BCRP) en producción, cobertura desde el 2026-08-21.
• Campos aditivos del ítem: cotejos[] (contraparte, resultado, regla, revision, ts, cotejo_id) y tiene_discrepancia_abierta; regla publicado_vs_cierre_prev_habil-1.0.
• /v1/health/freshness y /v1/coverage incluyen ambas series.

2026-08-27 — Token demo público

• Credencial pública de evaluación con límite compartido (30/min y 500/día entre todos sus usuarios); rotable sin aviso.

2026-08-21 — v1 en producción

• GET /v1/rates (paginación a revisión fija, 366 ítems, rango máximo 5 años), GET /v1/rates/latest (bloque frescura), GET /v1/observations/{id}, GET /v1/evidence/{id}, GET /v1/coverage, GET /v1/revisions?at=, GET /v1/alerts, GET /v1/annotations, GET /v1/health/{live,ready,freshness}.
• Sobre común (dataset_revision, request_id, schema_version: "1.0"), contrato de errores {code, message, request_id, retryable}, límites 60/min y 5 000/día por token, campos aditivos del ítem superseded y superseded_por.