# Consultar guías de despacho del SII > Lee las guías de despacho electrónicas (DTE 52) ya sincronizadas para esta conexión, filtradas por período y/o perspectiva (emitidas = las que emitió esta empresa; recibidas = las que le emitieron). {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ------------------------------------------------------------------ | | **Tool ID** | `sii.guias.consultar` | | **Nombre MCP** | `sii__guias__consultar` | | **Conector** | `sii` | | **Plano** | `action` | | **Lee el alcance** | `guias` (debe estar habilitado en la conexión) | | **Scope (permiso)** | `sii:read` | | **Auth** | `none` | | **Versión** | `4` | | **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, campo `connectionId` en el `execute` de MCP y en las opciones del SDK. 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`](../conexiones/estado-consultar). ## Qué hace [#qué-hace] Lectura pura: NO dispara una sincronización nueva ni contacta al SII. Si el período nunca se sincronizó, devuelve una lista vacía y 'sincronizacion: null'. Para traer datos nuevos, use 'sii.conexion.sincronizar' primero. Ojo: el SII solo conserva el detalle de guías de los últimos 6 meses, así que un período más viejo no se puede sincronizar aunque exista. Pagina con 'cursor': cuando la respuesta trae 'cursor' distinto de null, hay más filas. reenvía ese valor tal cual en 'cursor' para pedir la página siguiente; nunca lo construyas a mano. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | ------------- | ---------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `periodo` | string `^\d{4}-\d{2}$` | no | Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato. | | `perspectiva` | `"emitidas"` · `"recibidas"` | no | emitidas = las que emitió esta empresa; recibidas = las que le emitieron. Sin este filtro vienen las dos. | | `cursor` | string | no | Paginación: el valor que devolvió la respuesta anterior, tal cual. | | `limit` | entero 1-500 | no · default `100` | Filas por página. |
JSON Schema de entrada ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "periodo": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato." }, "perspectiva": { "description": "emitidas = las que emitió esta empresa; recibidas = las que le emitieron. Sin este filtro vienen las dos.", "type": "string", "enum": [ "emitidas", "recibidas" ] }, "cursor": { "description": "Paginación: el valor que devolvió la respuesta anterior, tal cual.", "type": "string" }, "limit": { "default": 100, "description": "Filas por página.", "type": "integer", "minimum": 1, "maximum": 500 } } } ```
## Ejemplo [#ejemplo] ```bash title="curl" curl -X POST https://connect.emisso.ai/api/v1/tools/sii.guias.consultar/execute \ -H "Authorization: Bearer connect_sk_…" \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"periodo":"2026-07","perspectiva":"emitidas"}}' ``` ```ts title="SDK TypeScript" const data = await connect.tools.sii.guias.consultar({ periodo: "2026-07", perspectiva: "emitidas" }, { connectionId: "conn_9tKfR2mQx4Vb" }); ``` ```json title="MCP · meta-tool execute" { "tool": "sii.guias.consultar", "params": { "periodo": "2026-07", "perspectiva": "emitidas" }, "connectionId": "conn_9tKfR2mQx4Vb" } ``` **Salida esperada (200):** ```json { "data": { "documentos": [ { "perspectiva": "emitidas", "tipoDte": 52, "periodo": "2026-07", "folio": "1580", "rutContraparte": "76543210-3", "razonSocialContraparte": "Constructora Los Robles Ltda", "montoNeto": 830000, "montoExento": 0, "montoIva": 157700, "montoTotal": 987700, "tasaIva": 1900, "fechaEmision": "21/07/2026", "fechaEmisionDate": "2026-07-21", "fechaRecepcion": "2026-07-22", "eventoOrden": null, "eventoDescripcion": null, "dhdrCodigo": null }, { "perspectiva": "emitidas", "tipoDte": 52, "periodo": "2026-07", "folio": "1583", "rutContraparte": "78900400-5", "razonSocialContraparte": "Ferretería El Volcán SpA", "montoNeto": 240000, "montoExento": 0, "montoIva": 45600, "montoTotal": 285600, "tasaIva": 1900, "fechaEmision": "28/07/2026", "fechaEmisionDate": "2026-07-28", "fechaRecepcion": null, "eventoOrden": null, "eventoDescripcion": null, "dhdrCodigo": null } ], "cursor": null, "sincronizacion": { "sincronizadoEn": "2026-08-06T03:15:42.000Z", "completo": true, "incompletos": 0, "fueraDeVentana": 0, "perspectivasFallidas": [] } }, "meta": { "request_id": "req_…", "tool_id": "sii.guias.consultar", "plane": "action", "latency_ms": 24, "audit_status": "recorded" } } ``` > Recortado a dos guías. 'tasaIva' viaja como entero por cien (1900 = 19%); 'fueraDeVentana: 0' confirma que el período cae dentro de los 6 meses de detalle que conserva el SII. ## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | --------------------------------------------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `documentos` | lista de objeto | sí | Las guías de despacho que calzan con el filtro, una por fila. Sale de la caché ya sincronizada: el SII sólo conserva el detalle de los últimos 6 meses, así que un período más viejo no se puede traer aunque la guía exista. | | | `documentos[].perspectiva` | `"emitidas"` · `"recibidas"` | sí | emitidas = las guías que emitió esta empresa; recibidas = las que le emitieron. | | | `documentos[].tipoDte` | entero | sí | Siempre 52: guía de despacho electrónica. | | | `documentos[].periodo` | string | sí | El período tributario de la guía, en formato AAAA-MM. | | | `documentos[].folio` | string | sí | El folio de la guía, en TEXTO decimal canónico (sin ceros a la izquierda). Junto con 'perspectiva' y 'rutContraparte' la identifica. Es texto y no un número a propósito: un folio es un identificador con el que no se hace aritmética, y hay folios reales que no caben en un entero de 32 bits. Compáralo como cadena. | | | `documentos[].rutContraparte` | string | sí | El RUT del otro lado: en 'emitidas' es el cliente y en 'recibidas' es quien emitió la guía. El RUT propio no viaja en la fila porque ya lo define la conexión. | | | `documentos[].razonSocialContraparte` | string | sí | La razón social de ese mismo lado, tal como la informó el SII. | | | `documentos[].montoNeto` | entero | sí | Monto neto en pesos chilenos, entero. | | | `documentos[].montoExento` | entero | sí | Monto exento de IVA en pesos chilenos, entero. | | | `documentos[].montoIva` | entero | sí | IVA en pesos chilenos, entero. | | | `documentos[].montoTotal` | entero | sí | Monto total de la guía en pesos chilenos, entero. | | | `documentos[].tasaIva` | entero | null | sí | La tasa de IVA multiplicada por cien: 1900 es 19%. 'null' cuando el SII no la informó. | | `documentos[].fechaEmision` | string | sí | La fecha de emisión tal cual la manda el SII, en formato DD/MM/AAAA. Para ordenar o comparar usa 'fechaEmisionDate'. | | | `documentos[].fechaEmisionDate` | string | null | sí | La misma fecha en formato AAAA-MM-DD, o 'null' si no se pudo parsear. | | `documentos[].fechaRecepcion` | string | null | sí | Cuándo el SII recibió la guía, en formato AAAA-MM-DD. 'null' si no vino. | | `documentos[].eventoOrden` | string | null | sí | El código del evento que registró el receptor sobre la guía, como texto. 'null' cuando no hubo evento. | | `documentos[].eventoDescripcion` | string | null | sí | La descripción de ese mismo evento, por ejemplo 'Acuse recibo'. 'null' cuando no hubo evento o el SII no la mandó. | | `documentos[].dhdrCodigo` | string | null | sí | Un identificador interno del SII para la guía. Sirve para correlacionar contra el portal, pero su estabilidad entre sincronizaciones no está verificada: no lo uses para identificar el documento. | | `cursor` | string | null | sí | El cursor de la página siguiente, opaco. 'null' significa que no hay más filas; cualquier otro valor se reenvía tal cual en 'cursor' de la próxima llamada y nunca se construye a mano. | | `sincronizacion` | objeto | null | sí | Completitud del último sync del período consultado. Es 'null' por DOS motivos distintos, y ninguno significa que las filas devueltas sean inválidas: (a) la consulta no filtró por 'periodo', así que no hay un sync único al que mirar (pide un 'periodo' concreto para obtener el bloque); o (b) ese período nunca se sincronizó. Un 'null' junto a una lista CON documentos es siempre el caso (a). | | `sincronizacion.sincronizadoEn` | string | sí | Cuándo terminó la última sincronización de este período, en ISO 8601 UTC. Es la frescura del dato que estás leyendo. | | | `sincronizacion.completo` | booleano | null | sí | 'true' = el período se sincronizó entero. 'false' = quedaron casillas sin traer, así que puede faltar información. 'null' = no se puede saber, porque no hay registro de ese intento. | | `sincronizacion.incompletos` | entero | null | sí | Cuántas casillas quedaron sin traer en esa sincronización. 'null' cuando no se puede saber. | | `sincronizacion.fueraDeVentana` | entero | null | sí | Sólo aplica a guías: cuántas direcciones cayeron fuera de la ventana de 6 meses que el SII conserva. Un 0 dice que se verificó y no aplicó; 'null', que no aplica o no se conoce. | | `sincronizacion.perspectivasFallidas` | lista de objeto | sí | Qué direcciones fallaron enteras en esa sincronización, con su código de error. Hoy sólo la puebla el alcance de boletas de honorarios; para los demás llega vacía. | | | `sincronizacion.perspectivasFallidas[].perspectiva` | `"emitidas"` · `"recibidas"` | sí | Qué lado falló: 'emitidas' son las que emitió esta empresa y 'recibidas' las que le emitieron. | | | `sincronizacion.perspectivasFallidas[].code` | string | sí | El código del catálogo de errores que explica por qué falló ese lado. Decide por el código, nunca por el texto. | |
JSON Schema de salida ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentos": { "type": "array", "items": { "type": "object", "properties": { "perspectiva": { "type": "string", "enum": [ "emitidas", "recibidas" ], "description": "emitidas = las guías que emitió esta empresa; recibidas = las que le emitieron." }, "tipoDte": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Siempre 52: guía de despacho electrónica." }, "periodo": { "type": "string", "description": "El período tributario de la guía, en formato AAAA-MM." }, "folio": { "type": "string", "description": "El folio de la guía, en TEXTO decimal canónico (sin ceros a la izquierda). Junto con 'perspectiva' y 'rutContraparte' la identifica. Es texto y no un número a propósito: un folio es un identificador con el que no se hace aritmética, y hay folios reales que no caben en un entero de 32 bits. Compáralo como cadena." }, "rutContraparte": { "type": "string", "description": "El RUT del otro lado: en 'emitidas' es el cliente y en 'recibidas' es quien emitió la guía. El RUT propio no viaja en la fila porque ya lo define la conexión." }, "razonSocialContraparte": { "type": "string", "description": "La razón social de ese mismo lado, tal como la informó el SII." }, "montoNeto": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Monto neto en pesos chilenos, entero." }, "montoExento": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Monto exento de IVA en pesos chilenos, entero." }, "montoIva": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "IVA en pesos chilenos, entero." }, "montoTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Monto total de la guía en pesos chilenos, entero." }, "tasaIva": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "La tasa de IVA multiplicada por cien: 1900 es 19%. 'null' cuando el SII no la informó." }, "fechaEmision": { "type": "string", "description": "La fecha de emisión tal cual la manda el SII, en formato DD/MM/AAAA. Para ordenar o comparar usa 'fechaEmisionDate'." }, "fechaEmisionDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La misma fecha en formato AAAA-MM-DD, o 'null' si no se pudo parsear." }, "fechaRecepcion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cuándo el SII recibió la guía, en formato AAAA-MM-DD. 'null' si no vino." }, "eventoOrden": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El código del evento que registró el receptor sobre la guía, como texto. 'null' cuando no hubo evento." }, "eventoDescripcion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "La descripción de ese mismo evento, por ejemplo 'Acuse recibo'. 'null' cuando no hubo evento o el SII no la mandó." }, "dhdrCodigo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Un identificador interno del SII para la guía. Sirve para correlacionar contra el portal, pero su estabilidad entre sincronizaciones no está verificada: no lo uses para identificar el documento." } }, "required": [ "perspectiva", "tipoDte", "periodo", "folio", "rutContraparte", "razonSocialContraparte", "montoNeto", "montoExento", "montoIva", "montoTotal", "tasaIva", "fechaEmision", "fechaEmisionDate", "fechaRecepcion", "eventoOrden", "eventoDescripcion", "dhdrCodigo" ], "additionalProperties": false }, "description": "Las guías de despacho que calzan con el filtro, una por fila. Sale de la caché ya sincronizada: el SII sólo conserva el detalle de los últimos 6 meses, así que un período más viejo no se puede traer aunque la guía exista." }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "El cursor de la página siguiente, opaco. 'null' significa que no hay más filas; cualquier otro valor se reenvía tal cual en 'cursor' de la próxima llamada y nunca se construye a mano." }, "sincronizacion": { "anyOf": [ { "type": "object", "properties": { "sincronizadoEn": { "type": "string", "description": "Cuándo terminó la última sincronización de este período, en ISO 8601 UTC. Es la frescura del dato que estás leyendo." }, "completo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "'true' = el período se sincronizó entero. 'false' = quedaron casillas sin traer, así que puede faltar información. 'null' = no se puede saber, porque no hay registro de ese intento." }, "incompletos": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Cuántas casillas quedaron sin traer en esa sincronización. 'null' cuando no se puede saber." }, "fueraDeVentana": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Sólo aplica a guías: cuántas direcciones cayeron fuera de la ventana de 6 meses que el SII conserva. Un 0 dice que se verificó y no aplicó; 'null', que no aplica o no se conoce." }, "perspectivasFallidas": { "type": "array", "items": { "type": "object", "properties": { "perspectiva": { "type": "string", "enum": [ "emitidas", "recibidas" ], "description": "Qué lado falló: 'emitidas' son las que emitió esta empresa y 'recibidas' las que le emitieron." }, "code": { "type": "string", "description": "El código del catálogo de errores que explica por qué falló ese lado. Decide por el código, nunca por el texto." } }, "required": [ "perspectiva", "code" ], "additionalProperties": false }, "description": "Qué direcciones fallaron enteras en esa sincronización, con su código de error. Hoy sólo la puebla el alcance de boletas de honorarios; para los demás llega vacía." } }, "required": [ "sincronizadoEn", "completo", "incompletos", "fueraDeVentana", "perspectivasFallidas" ], "additionalProperties": false }, { "type": "null" } ], "description": "Completitud del último sync del período consultado. Es 'null' por DOS motivos distintos, y ninguno significa que las filas devueltas sean inválidas: (a) la consulta no filtró por 'periodo', así que no hay un sync único al que mirar (pide un 'periodo' concreto para obtener el bloque); o (b) ese período nunca se sincronizó. Un 'null' junto a una lista CON documentos es siempre el caso (a)." } }, "required": [ "documentos", "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. | | `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](../errores). ## Próximos pasos [#próximos-pasos] * [`sii.conexion.sincronizar`](./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.