# Sincronizar conexión SUNAT
> Sincroniza el catálogo de períodos y las propuestas de compras RCE o ventas RVIE mediante la API de SUNAT, usando una sola sesión.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `sunat_beta.conexion.sincronizar` |
| **Nombre MCP** | `sunat_beta__conexion__sincronizar` |
| **Conector** | `sunat_beta` |
| **Plano** | `read` |
| **Alcances** | `periodos`, `compras`, `ventas` |
| **Scope (permiso)** | `sunat_beta:read` |
| **Auth** | `connection_credentials` |
| **Versión** | `1` |
| **Sensible** | sí |
| **Deprecado** | no |
| **Comportamiento** | readOnly=false, destructive=false, idempotent=true, openWorld=true |
> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST y campo `connectionId` en el `execute_write` 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]
Descarga y valida la exportación completa antes de conservar un alcance. Un ticket pendiente o un archivo incompleto es un fallo, nunca cero comprobantes. No acepta propuestas, registra libros, presenta declaraciones ni emite comprobantes.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción | |
| ---------- | ------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `periodo` | string \`^\d{4}-(0\[1-9] | 1\[0-2])$\` | sí | Período tributario de SUNAT, AAAA-MM. |
| `alcances` | lista de `"periodos"` · `"compras"` · `"ventas"` | sí | Alcances habilitados que se leerán. periodos conserva el catálogo completo; compras y ventas leen el mes solicitado. | |
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodo": {
"type": "string",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
"description": "Período tributario de SUNAT, AAAA-MM."
},
"alcances": {
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"enum": [
"periodos",
"compras",
"ventas"
]
},
"description": "Alcances habilitados que se leerán. periodos conserva el catálogo completo; compras y ventas leen el mes solicitado."
}
},
"required": [
"periodo",
"alcances"
]
}
```
## Ejemplo [#ejemplo]
```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/sunat_beta.conexion.sincronizar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"periodo":"2026-10","alcances":["periodos","compras","ventas"]}}'
```
```json title="MCP · meta-tool execute_write"
{
"tool": "sunat_beta.conexion.sincronizar",
"params": {
"periodo": "2026-10",
"alcances": [
"periodos",
"compras",
"ventas"
]
},
"connectionId": "conn_9tKfR2mQx4Vb"
}
```
**Salida esperada (200):**
```json
{
"data": {
"periodo": "2026-10",
"estado": "encolado",
"jobId": "sjb_1c3v5b7n9m2k4j6h8g0f1",
"yaEnCurso": false
},
"meta": {
"request_id": "req_…",
"tool_id": "sunat_beta.conexion.sincronizar",
"plane": "read",
"latency_ms": 58240,
"audit_status": "recorded"
}
}
```
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | |
| ------------------------- | --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `periodo` | string \`^\d{4}-(0\[1-9] | 1\[0-2])$\` | sí | Período tributario de SUNAT, AAAA-MM. |
| `estado` | `"encolado"` · `"completado"` | sí | 'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync abre una sesión real contra el sistema externo y puede tardar minutos, así que no se te hace esperar por él. | |
| `jobId` | string | null | no | El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/\{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.succeeded' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado', porque ahí el resultado ya está en la respuesta, y cuando 'yaEnCurso' es true y esa sincronización ya está corriendo. |
| `yaEnCurso` | booleano | no | 'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período. | |
| `results` | lista de objeto | no | El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada. | |
| `results[].alcance` | `"periodos"` · `"compras"` · `"ventas"` | sí | Alcance solicitado, en el orden canónico del conector. | |
| `results[].status` | `"ok"` · `"failed"` | sí | ok: lectura completa recibida para conservar. failed: no se pudo leer; no significa cero documentos. | |
| `results[].recordsSynced` | entero | sí | Registros completos recibidos para conservar en este alcance. | |
| `results[].error` | string | no | Código de error del catálogo, presente cuando el alcance falla. | |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"periodo": {
"type": "string",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
"description": "Período tributario de SUNAT, AAAA-MM."
},
"estado": {
"type": "string",
"enum": [
"encolado",
"completado"
],
"description": "'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync abre una sesión real contra el sistema externo y puede tardar minutos, así que no se te hace esperar por él."
},
"jobId": {
"description": "El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.succeeded' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado', porque ahí el resultado ya está en la respuesta, y cuando 'yaEnCurso' es true y esa sincronización ya está corriendo.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"yaEnCurso": {
"description": "'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período.",
"type": "boolean"
},
"results": {
"description": "El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada.",
"type": "array",
"items": {
"type": "object",
"properties": {
"alcance": {
"type": "string",
"enum": [
"periodos",
"compras",
"ventas"
],
"description": "Alcance solicitado, en el orden canónico del conector."
},
"status": {
"type": "string",
"enum": [
"ok",
"failed"
],
"description": "ok: lectura completa recibida para conservar. failed: no se pudo leer; no significa cero documentos."
},
"recordsSynced": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Registros completos recibidos para conservar en este alcance."
},
"error": {
"description": "Código de error del catálogo, presente cuando el alcance falla.",
"type": "string"
}
},
"required": [
"alcance",
"status",
"recordsSynced"
],
"additionalProperties": false
}
}
},
"required": [
"periodo",
"estado"
],
"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. |
| `too_many_pending` | 429 | sí | Deja terminar los trabajos en curso antes de encolar más. |
La llamada solo encola: las fallas del sistema externo (credencial, sesión, caída del portal) no llegan en esta respuesta, sino en el trabajo: en `outcomes` y `last_error` de `GET /v1/syncs/{jobId}`, o en los webhooks `sync.succeeded` (un alcance que falló junto a otros que terminaron) y `sync.failed`.
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.periodos.consultar`](/docs/referencia/sunat_beta/periodos-consultar): lee el alcance `periodos` que esta sincronización escribe.
* [`sunat_beta.compras.consultar`](/docs/referencia/sunat_beta/compras-consultar): lee el alcance `compras` que esta sincronización escribe.
* [`sunat_beta.ventas.consultar`](/docs/referencia/sunat_beta/ventas-consultar): lee el alcance `ventas` que esta sincronización escribe.