# Servicio: Consulta RUC

El segundo dominio del servicio: **qué decía el padrón reducido diario de
SUNAT sobre un RUC** en cualquier edición efectiva que este servicio
publicó — demostrable con el artefacto original, su hash y su verificación
declarada. Para las fechas sin edición efectiva, el hueco y su razón; jamás
un relleno. Esta página da la forma exacta de cada principio de la
plataforma en este dominio.

> En producción desde el 2026-09-07, con cobertura desde el 2026-09-03 (la
> primera edición archivada). Las respuestas de esta página son capturas
> reales con RUC de entidades públicas.

## Qué es y qué no

- **Es** un snapshot diario del padrón reducido de SUNAT
  (`padron_reducido_ruc.zip`, ~18,4 millones de filas, 15 campos: RUC,
  nombre o razón social, estado, condición de domicilio y el domicilio en 11
  componentes), archivado completo cada día con su ZIP original y su sha256,
  servido con historia y cobertura declarada. **Nadie más publica la serie
  diaria.**
- **No es** tiempo real: `edicion.fecha_padron` dice el día exacto de la
  edición. Para el estado de ahora mismo, la web de SUNAT.
- **No es** RENIEC ni una consulta de identidad. No trae representantes
  legales, deuda, trabajadores ni locales anexos
  ([Restricciones y límites](#restricciones-y-limites)).
- Los campos vienen **tal como SUNAT los publica**: el nombre está truncado
  a 100 caracteres y el estado y la condición a 20 (`BAJA PROV. POR OFICI`
  es literal del padrón). `dv_valido` dice si el dígito verificador cierra —
  el padrón real trae 4 excepciones y una fila con RUC no numérico; no
  rechazamos por eso.

**Los cuatro estados de una fila** (`estado_fila`):

| `estado_fila` | significado |
|---|---|
| `presente` | La fila existe y es válida: `nombre`, `estado`, `condicion`, `domicilio` en JSON canónico (`domicilio` es objeto si hay ubigeo, si no `null`; un componente vacío — `-` en el padrón — es `null`). |
| `no_interpretable` | Hay una clave RUC pero la fila es inválida (campos de menos o de más) o el RUC está duplicado en la edición; las líneas crudas vienen en `lineas` y quedan en cuarentena. |
| `ausente` | El RUC no figura en la edición y la edición no tiene líneas sin clave. **Es raro**: el padrón reducido contiene todos los RUC, incluidos los de baja; ausente suele indicar RUC inexistente o mal formado. La baja se lee en `estado` y `condicion`, no aquí. |
| `ausente_incierto` | El RUC no figura y la edición sí tiene líneas sin clave extraíble (`lineas_sin_clave_edicion` > 0): no podemos afirmar que no esté. |

El primer request, real — la SUNAT en la edición corriente — está en
[Empezar](empezar.md#primer-request). Un RUC que no existe:

<!-- ejemplo ruc_ausente: `ausente_incierto` porque la edición del día trae una línea sin clave (la fila con RUC no numérico que el padrón arrastra); `dv_valido: false`. -->
Respuesta real (2026-09-28, revisión 4414): `ausente_incierto` porque la edición del día trae una línea sin clave (la fila con RUC no numérico que el padrón arrastra); `dv_valido: false`.

```json
{
  "ruc": "00000000000",
  "dv_valido": false,
  "dataset_revision": 4414,
  "request_id": "3a2aca75-91ab-452d-ac75-4cbedb774765",
  "schema_version": "1.0",
  "estado_fila": "ausente_incierto",
  "nombre": null,
  "estado": null,
  "condicion": null,
  "domicilio": null,
  "nota": "ausente significa que el RUC no figura en el padrón reducido de esa edición; el padrón reducido contiene todos los RUC, incluidos los de baja, por lo que ausente es raro y suele indicar RUC inexistente o mal formado",
  "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": "8e8b74a9-90f4-4b3f-bd46-153a6101b9c5",
  "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": true,
  "revision_lineas": 4414,
  "ausencia_version": "1",
  "reglas_cpe": {
    "version": "1",
    "r1083": {
      "resultado": "no_cumple",
      "consecuencia": "rechazo"
    },
    "r4013": {
      "resultado": "no_evaluable",
      "consecuencia": "observacion"
    },
    "r4014": {
      "resultado": "no_evaluable",
      "consecuencia": "observacion"
    }
  },
  "sucesion": {
    "valor": null,
    "version": "1"
  }
}
```
<!-- /ejemplo -->

## Cobertura

`GET /v1/ruc-coverage` da una fila por fecha calendario desde la primera
edición efectiva (2026-09-03): `efectiva` con su `ordinal`, o la `razon`
del hueco (`causa` es su alias histórico). Dos contadores más por fecha:
`variantes_no_publicadas` (SUNAT republicó el mismo día; esta versión
archiva la variante y no la publica) y `reempaquetados` (mismo contenido,
otro ZIP). Es versionada: con `as_of_revision` devuelve la cobertura tal
como estaba a esa revisión.

| `razon` | significado |
|---|---|
| `no_capturada` | La fuente no entregó nada en la ventana del día (las fechas sin fila registrada se sintetizan con esta razón, `sintetica: true`). |
| `no_durable` | Se capturó pero no se pudo archivar de forma verificable. |
| `rechazada` | Formato inválido. |
| `retenida_pendiente` / `retenida_excepcional_pendiente` | A la espera de revisión humana. |
| `retenida_caducada` | La revisión no llegó antes del corte de las 23:59 Lima. |
| `excede_capacidad_v1` | Más cambios que el tope aprobado de esta versión. |
| `no_esperada` | Fecha posterior a la edición esperada de hoy. |

<!-- ejemplo ruc_coverage: todas las ediciones desde el 2026-09-03, efectivas. -->
Respuesta real (2026-09-28, revisión 4414): todas las ediciones desde el 2026-09-03, efectivas.

```json
{
  "cobertura": [
    {
      "fecha": "2026-09-03",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 1,
      "interpretacion_id": 1,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3564
    },
    {
      "fecha": "2026-09-04",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 2,
      "interpretacion_id": 2,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3566
    },
    {
      "fecha": "2026-09-05",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 3,
      "interpretacion_id": 3,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3568
    },
    {
      "fecha": "2026-09-06",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 4,
      "interpretacion_id": 4,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3570
    },
    {
      "fecha": "2026-09-07",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 5,
      "interpretacion_id": 5,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3572
    },
    {
      "fecha": "2026-09-08",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 6,
      "interpretacion_id": 6,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3601
    },
    {
      "fecha": "2026-09-09",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 7,
      "interpretacion_id": 7,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3630
    },
    {
      "fecha": "2026-09-10",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 8,
      "interpretacion_id": 8,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3661
    },
    {
      "fecha": "2026-09-11",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 9,
      "interpretacion_id": 9,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3694
    },
    {
      "fecha": "2026-09-12",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 10,
      "interpretacion_id": 10,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3729
    },
    {
      "fecha": "2026-09-13",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 11,
      "interpretacion_id": 11,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3766
    },
    {
      "fecha": "2026-09-14",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 12,
      "interpretacion_id": 12,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3805
    },
    {
      "fecha": "2026-09-15",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 13,
      "interpretacion_id": 13,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3846
    },
    {
      "fecha": "2026-09-16",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 14,
      "interpretacion_id": 14,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3887
    },
    {
      "fecha": "2026-09-17",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 15,
      "interpretacion_id": 15,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3929
    },
    {
      "fecha": "2026-09-18",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 16,
      "interpretacion_id": 16,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 3971
    },
    {
      "fecha": "2026-09-19",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 17,
      "interpretacion_id": 17,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4012
    },
    {
      "fecha": "2026-09-20",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 18,
      "interpretacion_id": 18,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4053
    },
    {
      "fecha": "2026-09-21",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 19,
      "interpretacion_id": 19,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4093
    },
    {
      "fecha": "2026-09-22",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 20,
      "interpretacion_id": 20,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4135
    },
    {
      "fecha": "2026-09-23",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 21,
      "interpretacion_id": 21,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4175
    },
    {
      "fecha": "2026-09-24",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 22,
      "interpretacion_id": 23,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4220
    },
    {
      "fecha": "2026-09-25",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 23,
      "interpretacion_id": 25,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4264
    },
    {
      "fecha": "2026-09-26",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 24,
      "interpretacion_id": 26,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4304
    },
    {
      "fecha": "2026-09-27",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 25,
      "interpretacion_id": 27,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4345
    },
    {
      "fecha": "2026-09-28",
      "efectiva": true,
      "causa": null,
      "razon": null,
      "ordinal": 26,
      "interpretacion_id": 28,
      "variantes_no_publicadas": 0,
      "reempaquetados": 0,
      "revision": 4386
    }
  ],
  "edicion_corriente": {
    "fecha_padron": "2026-09-28",
    "ordinal": 26,
    "interpretacion_id": 28,
    "sha256": "ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9",
    "evidence_url": "/v1/evidence/ddb8461787ac1f35bcc7f09235508808e5cdaa0e67cc6e52c9840cfdbb4c11b9"
  },
  "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"
  },
  "causas": [
    "no_capturada",
    "no_durable",
    "rechazada",
    "retenida_pendiente",
    "retenida_excepcional_pendiente",
    "retenida_caducada",
    "excede_capacidad_v1",
    "no_esperada"
  ],
  "dataset_revision": 4414,
  "request_id": "91d9cd15-fd23-45d3-8bd2-fda8d4ae9ba7",
  "schema_version": "1.0"
}
```
<!-- /ejemplo -->

**Cadencia medida.** SUNAT publica cada día — sábados y domingos incluidos,
medido desde el 2026-09-03 — entre las 02:46 y las 02:52 de Lima.

## Frescura

La edición de hoy se **espera** desde las 04:00 de Lima: `frescura` compara
la edición corriente con esa expectativa — `estado` (`al_dia`, `atrasada`
o `adelantada`), `dias_atraso` (días calendario), `fecha_esperada`
(`edicion_esperada` es su alias histórico), `hoy_lima`. El bloque viaja en
`/v1/ruc/{ruc}` y en `/v1/ruc-coverage`; el de la respuesta real de
[Empezar](empezar.md#primer-request) está `al_dia`. Una edición atrasada
tiene además su alerta abierta en `/v1/alerts`.

## Consulta histórica

Dos ejes, que no significan lo mismo:

- `as_of_revision=R` congela **todo** en la revisión R del registro: la
  edición corriente a esa revisión, la historia visible hasta ella y hasta
  la confiabilidad que existía entonces. Una revisión anterior a la primera
  publicación del dominio responde `NO_DATA_AT_REVISION`:

<!-- ejemplo error_no_data_at_revision: la revisión 1 precede al dominio; el servicio lo dice en vez de inventar un estado. -->
Respuesta real (2026-09-28): la revisión 1 precede al dominio; el servicio lo dice en vez de inventar un estado.

```json
{
  "code": "NO_DATA_AT_REVISION",
  "message": "the RUC domain has no publication at this revision",
  "request_id": "6db4f7c8-8886-47f6-add9-891396098d6d",
  "retryable": false
}
```
<!-- /ejemplo -->

- `as_of_fecha=D` pide la edición del padrón del día D. Si D es efectiva,
  la respuesta es esa edición. Si **no** lo es, la respuesta trae **solo
  metadatos** — `cobertura {efectiva: false, razon, distancia}`,
  `edicion_efectiva_anterior`, `edicion_efectiva_posterior` — y ningún
  campo de estado. El servicio jamás resuelve en silencio "la efectiva
  anterior" como si fuera la pedida: usted elige la vecina y la pide
  explícitamente. Es la forma en este dominio del principio
  [sin relleno](modelo-de-evidencia.md#sin-relleno-nunca-otra-fecha-como-si-fuera-la-pedida).

<!-- ejemplo ruc_as_of_fecha_hueco: el 2026-09-01 es anterior a la primera edición archivada — no hay edición efectiva ni anterior; solo metadatos. -->
Respuesta real (2026-09-28, revisión 4414): el 2026-09-01 es anterior a la primera edición archivada — no hay edición efectiva ni anterior; solo metadatos.

```json
{
  "ruc": "20131312955",
  "dv_valido": true,
  "dataset_revision": 4414,
  "request_id": "39fdb543-7500-45fc-95c7-900e5cea41a5",
  "schema_version": "1.0",
  "as_of_fecha": "2026-09-01",
  "cobertura": {
    "efectiva": false,
    "causa": "no_capturada",
    "razon": "no_capturada",
    "distancia": {
      "anterior_dias": null,
      "posterior_dias": 2
    }
  },
  "edicion_efectiva_anterior": null,
  "edicion_efectiva_posterior": {
    "fecha_padron": "2026-09-03",
    "ordinal": 1
  },
  "nota": "la fecha pedida no tiene edición efectiva: solo metadatos; el cliente re-consulta explícitamente la edición que elija (as_of_fecha de una vecina)"
}
```
<!-- /ejemplo -->

**La historia como diferencial.** `GET /v1/ruc/{ruc}/history` devuelve el
estado inicial (la fila del baseline, la primera edición efectiva) y cada
transición entre ediciones consecutivas en que el RUC cambió:
`estado_anterior` → `estado_nuevo`, los dos snapshots en JSON canónico,
`campos_cambiados` y la revisión desde la que existe. Una transición se
genera por diferencia exacta entre dos ediciones enteras (merge lineal de
18,4 millones de filas ordenadas por RUC); el volumen real medido es de
unas 9.000 transiciones por día en todo el padrón. La historia pagina de a
500 transiciones (`total_transiciones`, `next_page_token`; `estado_inicial`
solo en la primera página —
[paginación](errores-y-limites.md#paginacion-a-revision-fija)).

**Caché.** Las cinco rutas de este dominio (`/v1/ruc/{ruc}`, `by-dni`,
`/history`, `/v1/ruc-coverage` y los metadatos de la evidencia del padrón)
se sirven con `Cache-Control: private, no-store`, sin `ETag`, y con `Vary:
Authorization` en las que dependen del token: cada respuesta lleva valores
propios del pedido (`request_id`, `frescura`, el enlace firmado de la
evidencia) y un `304` reutilizaría los de otro pedido. Un `If-None-Match:
*` sobre un pedido que daría `200` responde `304` sin cuerpo; cualquier
otro valor, `200`; un error se responde aunque traiga la precondición. La
estabilidad de una respuesta anclada es propiedad del dato: dos llamadas
con el mismo `as_of_revision` son iguales salvo los campos que describen
el momento del pedido ([caché](errores-y-limites.md#cache)).

### Reglas del comprador, sucesión y ausencia comprobada

Desde la activación R0 de la adenda a ESP-006 (2026-09-26; en producción
con el checkpoint 3 de su construcción), cada respuesta de `/v1/ruc/{ruc}`
y de `by-dni` con campos de estado trae tres evaluaciones derivadas,
calculadas a la revisión de la respuesta y con su versión:

| campo | qué dice |
|---|---|
| `reglas_cpe` (versión `"1"`) | Las reglas de SUNAT sobre el RUC del comprador: `r1083` (el RUC no existe: la consecuencia es el **rechazo** del comprobante), `r4013` (el RUC no está activo: **observación**) y `r4014` (el RUC está no habido: **observación**), cada una `cumple`, `no_cumple` o `no_evaluable`. La consecuencia es la misma en factura, boleta, nota de crédito y nota de débito; si SUNAT la cambiara, la versión sube. |
| `ausencia_comprobada` (`ausencia_version` `"1"`) | Si el RUC no figura: `true` cuando la ausencia está comprobada —`ausente`, o `ausente_incierto` con todas las líneas sin clave de esa edición revisadas por una persona de EKIA a la revisión de la respuesta—, `false` cuando queda alguna sin revisar, `null` si el RUC figura. `revision_lineas` es la revisión de la última revisión de líneas considerada. El sistema nunca afirma una ausencia que nadie comprobó. |
| `sucesion` (versión `"1"`) | Si el nombre indica una sucesión indivisa: `true` (`SUCESION INDIVISA …`, `SUCESION …`), `null` cuando no se puede afirmar (`SUC.`, `SUC `, o la respuesta no trae el nombre) y `false` en otro caso. |

No vienen con `as_of_fecha` sin edición efectiva, ni en `/history`, ni en
una respuesta anclada a una revisión anterior a R0. Cada versión nueva de
una regla se publica como una revisión del dataset: una respuesta anclada
antes se sigue evaluando con la versión de entonces.

## Integridad

El control de integridad de este dominio es la **confiabilidad** por
verificación exhaustiva, más el dígito verificador (`dv_valido`).

| `confiabilidad` | significado |
|---|---|
| `verificada` | La edición reconstruida desde el baseline y las transiciones se contrastó **RUC por RUC** contra el artefacto original (18,4 millones de comparaciones), en el levantamiento exhaustivo que corre tras cada publicación. Es el **estado normal** de toda edición publicada. |
| `sin_verificar` | Construida desde el artefacto original sin inconsistencia conocida; el levantamiento de ese ordinal aún no terminó (la ventana entre publicar y verificar, minutos). |
| `fallida` | Hay una inconsistencia conocida en la cadena histórica: `alerta_ref` apunta a la alerta. El índice corriente no se contamina: sin `as_of`, la respuesta dice lo que el padrón dice hoy. |

En `/v1/ruc/{ruc}/history` cada transición lleva su confiabilidad,
`confiabilidad_global` es el peor valor de toda la historia y
`tramos_no_verificados` lista los ordinales afectados. Nunca verá
`verificada` global con un tramo defectuoso adentro.

Alcance declarado: **RUC no tiene cotejo**, porque la fuente es única (no
hay una segunda fuente oficial del padrón con la que comparar). Una
corrección de SUNAT no se registra como supersesión: llega como transición
en la edición siguiente. La verificación detecta cualquier diferencia entre
lo que el servicio sirve y lo que SUNAT publicó; no detecta un error del
padrón mismo ([los controles de integridad](modelo-de-evidencia.md#los-controles-de-integridad)).

## Evidencia

La evidencia de cada edición es **grande**: el ZIP original del padrón
(~392 MB), de `tipo: artefacto`, archivado en un almacén inmutable.
`edicion.evidence_url` (`/v1/evidence/{sha256}`) da los metadatos — el
sha256 del ZIP, `sha256_contenido` del TXT descomprimido, `bytes`, la
fecha de descarga, el enlace firmado — y `/v1/evidence/{sha256}/descarga`
redirige (302) a ese enlace, válido 15 minutos; el servicio nunca proxea el
archivo. Solo son descargables los artefactos con interpretación; los
descartados sin interpretación exponen metadatos pero no enlace. Cada
descarga cuenta 392 MB en la cuota diaria del token
([cuota](errores-y-limites.md#cuota-de-descarga)).

**La descarga del artefacto íntegro está restringida a tokens propios con
la marca `descarga_artefactos`** (decisión D-2026-09-08); sin la marca,
`/descarga` responde `FORBIDDEN` y los metadatos traen
`descarga_directa_url: null` (ningún enlace al ZIP, directo ni firmado,
sale hacia un token sin la marca). Motivo: el ZIP trae el padrón completo,
incluidos el nombre y el domicilio de personas naturales que la API
suprime hasta el dictamen legal — entregar el archivo entero anularía esa
supresión. Los metadatos (`/v1/evidence/{sha256}`, con ambos hashes) siguen
disponibles para todo token, y la verificación por sha256 sigue siendo
posible para quien tenga el artefacto. El rediseño de la evidencia como
extracto con prueba de inclusión (la fila del RUC consultado, el hash del
archivo y una prueba de pertenencia) está registrado como disparador de la
siguiente versión del dominio. Ejecutado real, paso a
paso: [Verifique la evidencia en 60 segundos](verificar-evidencia.md#ejecutado-real-el-padron-ruc).

El archivo conserva los artefactos de forma **indefinida**, con un bloqueo
de objetos mínimo renovable de 1095 días
([qué garantiza inmutable](modelo-de-evidencia.md#que-garantiza-inmutable)).

## Restricciones y límites

**Personas naturales: un permiso por token.** El padrón diario trae el
nombre y el domicilio de personas naturales con RUC (prefijos 10, 15, 16 y
17). Desde la activación R0 de la adenda a ESP-006, los gobierna el permiso
`personas_naturales` del token, fijo al emitirlo (para cambiar un permiso
se emite un token nuevo y se revoca el anterior): con él, la respuesta
trae `nombre`, `domicilio`, las líneas crudas y la marca `sucesion`, y
`by-dni` responde; sin él, esos campos llegan en `null` y figuran en
`campos_restringidos` con su `motivo_restriccion`, y `by-dni` responde
`FORBIDDEN`. Es **un solo permiso** porque el RUC 10 contiene el DNI: ver
los datos de un RUC 10 y buscar personas por DNI son la misma capacidad.
El parámetro `restringir_personas_naturales=true` pide la respuesta
restringida aunque el token tenga el permiso; nunca abre más de lo que el
token permite. En `/history` aplica a cada estado y cada transición, y el
cursor de continuación conserva la restricción de la primera página.
`estado`, `condicion`, `estado_fila` y toda la historia de esos campos se
sirven siempre.

Los tokens de clientes no tienen el permiso hasta el dictamen legal sobre
la Ley 29733 (prerrequisito E1) y el resto de las condiciones de la
apertura comercial. Hasta entonces, para ellos:

- para un RUC de persona natural, `nombre` y `domicilio` llegan en `null`,
  con `campos_restringidos` y `motivo_restriccion` explícitos;
- `GET /v1/ruc/by-dni/{dni}` responde `FORBIDDEN`:

<!-- ejemplo error_forbidden_by_dni: el atajo por DNI, cerrado; aquí por el pedido restringido (para un token sin el permiso, el mismo 403 con el motivo del permiso). -->
Respuesta real (2026-09-28): el atajo por DNI, cerrado; aquí por el pedido restringido (para un token sin el permiso, el mismo 403 con el motivo del permiso).

```json
{
  "code": "FORBIDDEN",
  "message": "by-dni is not available when the request restricts natural persons' data (restringir_personas_naturales=true)",
  "request_id": "0be2dce4-22a3-41c5-a020-fde020ea9cf2",
  "retryable": false
}
```
<!-- /ejemplo -->

Las personas jurídicas (prefijo 20) se sirven completas, con
`campos_restringidos` vacío. Cuando el dictamen exista, habilitar el
permiso a un tercero será emitir su token con él; esta página lo dirá.

**Qué haría `by-dni` y a cuántos RUC alcanza.** `ruc_candidato = 10 + DNI +
dígito verificador` es el RUC que SUNAT asigna a una persona natural con
ese DNI si alguna vez se inscribió; el atajo devolvería la respuesta de
`/v1/ruc/{ruc}` para ese candidato. No consulta RENIEC ni afirma identidad;
los RUC 15/16/17 quedan fuera. Cobertura del atajo, contada sobre el índice
vigente:

| índice vigente | RUC | proporción |
|---|---|---|
| edición del 2026-09-10 (ordinal 8, sha256 `9a4003d563c2ad2f3947849af1d3cb8867169fabc26c34322198f2fdafd7b765`), 18.394.155 filas | prefijo 10 (derivable de un DNI): 15.486.787 | 84,2 % |
| | prefijos 15, 16 y 17 (personas naturales sin DNI): 558.622 | 3,0 % |
| | prefijo 20 (personas jurídicas): 2.348.719 | 12,8 % |

**Pregunta abierta para el dictamen E1.** ¿Es admisible una variante mínima
de `by-dni` que devuelva solo `ruc_candidato`, `estado` y `condicion` — sin
nombre ni domicilio, es decir, sin ningún dato que el padrón no exponga ya
por RUC para toda persona natural? Hasta que el dictamen la responda, el
atajo sigue cerrado entero.

**Servicio en desarrollo.** No se otorga acceso a terceros; el dominio se
opera completo (ingesta diaria, archivo, verificación) para construir y
probar el producto ([Empezar](empezar.md#estado-del-servicio-en-desarrollo)).

**Otros límites.** El dominio no cubre representantes legales, deuda,
trabajadores ni locales anexos; no es tiempo real; la edición de un día
con más cambios que el tope aprobado de esta versión queda `excede_capacidad_v1`
hasta revisión humana. Lo que el servicio entero no hace:
[Qué no hacemos](que-no-hacemos.md).

## Qué guardar

Con cada consulta que su sistema tome: `observacion_id`, `dataset_revision`,
`edicion.ordinal` y `edicion.fecha_padron`; si va a re-verificar el
artefacto, `edicion.sha256`
([qué guardar](modelo-de-evidencia.md#que-guardar-en-su-sistema)).

## Datos Abiertos

Existe además el dataset mensual del padrón en datosabiertos.gob.pe (desde
2022-04, licencia ODC-By, 16 columnas sin nombre ni domicilio, rezago de
uno a dos meses). Este servicio archiva sus 49 ediciones disponibles y lo
declara; no lo sirve en esta versión.