# Consultar períodos de SUNAT
> Lista los períodos RVIE y RCE conservados por la última sincronización de esta conexión.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `sunat_beta.periodos.consultar` |
| **Nombre MCP** | `sunat_beta__periodos__consultar` |
| **Conector** | `sunat_beta` |
| **Plano** | `action` |
| **Lee el alcance** | `periodos` (debe estar habilitado en la conexión) |
| **Scope (permiso)** | `sunat_beta:read` |
| **Auth** | `none` |
| **Versión** | `1` |
| **Sensible** | sí |
| **Deprecado** | no |
| **Comportamiento** | readOnly=true, destructive=false, idempotent=true, openWorld=false |
> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST y campo `connectionId` en el `execute` de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](/docs/referencia/conexiones/estado-consultar).
## Qué hace [#qué-hace]
No llama a SUNAT. Un período disponible no confirma que sus comprobantes estén cargados. Si sincronizacion es null, aún no hay una lectura conservada del catálogo.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción |
| -------- | ------------------ | ------------------ | --------------------------------------------------------------- |
| `libro` | `"rvie"` · `"rce"` | no | Filtra por libro; omítelo para consultar ambos. |
| `limite` | entero 1-500 | no · default `100` | Filas por página, entre 1 y 500; 100 por defecto. |
| `cursor` | string | no | Cursor opaco de la respuesta anterior, reenviado sin modificar. |
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"libro": {
"description": "Filtra por libro; omítelo para consultar ambos.",
"type": "string",
"enum": [
"rvie",
"rce"
]
},
"limite": {
"default": 100,
"description": "Filas por página, entre 1 y 500; 100 por defecto.",
"type": "integer",
"minimum": 1,
"maximum": 500
},
"cursor": {
"description": "Cursor opaco de la respuesta anterior, reenviado sin modificar.",
"type": "string",
"minLength": 1,
"maxLength": 2048
}
}
}
```
## Ejemplo [#ejemplo]
```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/sunat_beta.periodos.consultar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"libro":"rvie","limite":100}}'
```
```json title="MCP · meta-tool execute"
{
"tool": "sunat_beta.periodos.consultar",
"params": {
"libro": "rvie",
"limite": 100
},
"connectionId": "conn_9tKfR2mQx4Vb"
}
```
**Salida esperada (200):**
```json
{
"data": {
"periodos": [],
"cursor": null,
"sincronizacion": null
},
"meta": {
"request_id": "req_…",
"tool_id": "sunat_beta.periodos.consultar",
"plane": "action",
"latency_ms": 24,
"audit_status": "recorded"
}
}
```
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | | | | | | | | | | | | | | | | |
| ------------------------------- | --------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------- | ------------------ | ------- | ------- | ---------- | -------------- | ------- | --- | ----------------- | --- | ------------------------ | ------------------------------------------------- | -- | --------------------------------------------- |
| `periodos` | lista de objeto | sí | Períodos conservados que coinciden con el filtro. | | | | | | | | | | | | | | | | |
| `periodos[].libro` | `"rvie"` · `"rce"` | sí | Libro al que pertenece el período. | | | | | | | | | | | | | | | | |
| `periodos[].periodo` | string \`^\d{4}-(0\[1-9] | 1\[0-2])$\` | sí | Período tributario de SUNAT, AAAA-MM. | | | | | | | | | | | | | | | |
| `periodos[].estado` | string `^[^\p{Cc}]+$` | sí | Código de estado del período informado por SUNAT. | | | | | | | | | | | | | | | | |
| `periodos[].descripcion` | string | sí | Descripción de ese estado; no confirma que sus documentos estén sincronizados. | | | | | | | | | | | | | | | | |
| `cursor` | string | null | sí | Cursor para la página siguiente. null significa que no hay más filas. | | | | | | | | | | | | | | | |
| `sincronizacion` | objeto | null | sí | null: no hay evidencia de una lectura conservada. Una lista vacía con null no significa cero documentos. | | | | | | | | | | | | | | | |
| `sincronizacion.sincronizadoEn` | string \`^(?:(?:\d\d\[2468]\[048] | \d\d\[13579]\[26] | \d\d0\[48] | \[02468]\[048]00 | \[13579]\[26]00)-02-29 | \d{4}-(?:(?:0\[13578] | 1\[02])-(?:0\[1-9] | \[12]\d | 3\[01]) | (?:0\[469] | 11)-(?:0\[1-9] | \[12]\d | 30) | (?:02)-(?:0\[1-9] | 1\d | 2\[0-8])))T(?:(?:\[01]\d | 2\[0-3]):\[0-5]\d(?::\[0-5]\d(?:.\d+)?)?(?:Z))$\` | sí | Instante UTC de la última lectura conservada. |
| `sincronizacion.completo` | booleano | sí | true sólo si se descargó y validó todo el alcance. false no acredita ausencia de documentos. | | | | | | | | | | | | | | | | |
| `sincronizacion.cantidad` | entero | sí | Registros de la última lectura conservada, antes de paginar. Si completo es false, esta cantidad histórica no acredita el total vigente del período. | | | | | | | | | | | | | | | | |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"libro": {
"type": "string",
"enum": [
"rvie",
"rce"
],
"description": "Libro al que pertenece el período."
},
"periodo": {
"type": "string",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
"description": "Período tributario de SUNAT, AAAA-MM."
},
"estado": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"pattern": "^[^\\p{Cc}]+$",
"description": "Código de estado del período informado por SUNAT."
},
"descripcion": {
"type": "string",
"maxLength": 512,
"description": "Descripción de ese estado; no confirma que sus documentos estén sincronizados."
}
},
"required": [
"libro",
"periodo",
"estado",
"descripcion"
],
"additionalProperties": false
},
"description": "Períodos conservados que coinciden con el filtro."
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cursor para la página siguiente. null significa que no hay más filas."
},
"sincronizacion": {
"anyOf": [
{
"type": "object",
"properties": {
"sincronizadoEn": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"description": "Instante UTC de la última lectura conservada."
},
"completo": {
"type": "boolean",
"description": "true sólo si se descargó y validó todo el alcance. false no acredita ausencia de documentos."
},
"cantidad": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Registros de la última lectura conservada, antes de paginar. Si completo es false, esta cantidad histórica no acredita el total vigente del período."
}
},
"required": [
"sincronizadoEn",
"completo",
"cantidad"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "null: no hay evidencia de una lectura conservada. Una lista vacía con null no significa cero documentos."
}
},
"required": [
"periodos",
"cursor",
"sincronizacion"
],
"additionalProperties": false
}
```
## Errores de esta tool [#errores-de-esta-tool]
| Código | HTTP | Reintentable | Qué hacer |
| ---------------------- | ---- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled` | 403 | no | Reactívala en /connections o usa otra conexión del mismo sistema. |
| `connection_not_found` | 404 | no | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
| `alcance_not_enabled` | 403 | no | Habilita el alcance en /connections o quítalo del input de la sincronización. |
Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](/docs/referencia/errores).
## Próximos pasos [#próximos-pasos]
* [`sunat_beta.conexion.sincronizar`](/docs/referencia/sunat_beta/conexion-sincronizar): la tool que escribe los datos que esta lectura devuelve.
* [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar): por qué leer datos reales son dos pasos.