# Detallar un documento respaldado del SII
> Devuelve UN documento tributario respaldado, con su detalle completo: los ítems (nombre, cantidad, unidad, precio unitario y monto), los giros, direcciones y comunas de emisor y receptor, y la forma de pago.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `sii.documentos.detallar` |
| **Nombre MCP** | `sii__documentos__detallar` |
| **Conector** | `sii` |
| **Plano** | `action` |
| **Lee el alcance** | `documentos` (debe estar habilitado en la conexión) |
| **Scope (permiso)** | `sii:read` |
| **Auth** | `none` |
| **Versión** | `2` |
| **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]
El documento se identifica con las tres partes que lo hacen único ('tipoDte', 'folio' y 'rutEmisor'), y las tres salen de una fila de 'sii.documentos.consultar'. Lectura pura: NO contacta al SII, lee el XML que ya se respaldó y lo parsea en el momento. Si ese documento no está sincronizado, devuelve 'documento: null'. No es un error: es que no lo tenemos, así que sincroniza su período con 'sii.conexion.sincronizar' y vuelve a preguntar. El XML firmado sólo viaja si se pide 'incluirXml: true'; sin eso la respuesta trae el detalle ya estructurado, que es lo que casi siempre se necesita. Un ítem con 'cantidad', 'unidad' o 'precioUnitario' en null es un ítem que no los declaró (un flete, un descuento): no debe leerse como cero.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción |
| ------------ | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tipoDte` | entero | sí | El tipo del documento, de la fila de 'sii.documentos.consultar'. |
| `folio` | string | sí | El folio del documento, TAL CUAL viene en la fila de 'sii.documentos.consultar' (es texto: un identificador, no un número). Junto con tipoDte y rutEmisor lo identifica de forma única. |
| `rutEmisor` | string | sí | El RUT de QUIEN EMITIÓ el documento, no el de la contraparte (salvo que el documento haya sido emitido por esta empresa). Con o sin puntos, da igual. |
| `incluirXml` | booleano | no · default `false` | Si es true, la respuesta incluye además el XML firmado completo. Son unos 7 KB por documento. |
JSON Schema de entrada
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"tipoDte": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "El tipo del documento, de la fila de 'sii.documentos.consultar'."
},
"folio": {
"type": "string",
"minLength": 1,
"description": "El folio del documento, TAL CUAL viene en la fila de 'sii.documentos.consultar' (es texto: un identificador, no un número). Junto con tipoDte y rutEmisor lo identifica de forma única."
},
"rutEmisor": {
"type": "string",
"minLength": 1,
"description": "El RUT de QUIEN EMITIÓ el documento, no el de la contraparte (salvo que el documento haya sido emitido por esta empresa). Con o sin puntos, da igual."
},
"incluirXml": {
"default": false,
"description": "Si es true, la respuesta incluye además el XML firmado completo. Son unos 7 KB por documento.",
"type": "boolean"
}
},
"required": [
"tipoDte",
"folio",
"rutEmisor"
]
}
```
## Ejemplo [#ejemplo]
```bash title="curl"
curl -X POST https://connect.emisso.ai/api/v1/tools/sii.documentos.detallar/execute \
-H "Authorization: Bearer connect_sk_…" \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"tipoDte":33,"folio":"4712","rutEmisor":"76111222-8"}}'
```
```ts title="SDK TypeScript"
const data = await connect.tools.sii.documentos.detallar({ tipoDte: 33, folio: "4712", rutEmisor: "76111222-8" }, { connectionId: "conn_9tKfR2mQx4Vb" });
```
```json title="MCP · meta-tool execute"
{
"tool": "sii.documentos.detallar",
"params": {
"tipoDte": 33,
"folio": "4712",
"rutEmisor": "76111222-8"
},
"connectionId": "conn_9tKfR2mQx4Vb"
}
```
**Salida esperada (200):**
```json
{
"data": {
"documento": {
"tipoDte": 33,
"folio": "4712",
"rutEmisor": "76111222-8",
"rutReceptor": "77777777-7",
"razonSocialContraparte": "Proveedor Ejemplo SpA",
"perspectiva": "recibidos",
"periodo": "2026-06",
"fechaEmision": "2026-06-14",
"montoNeto": 300000,
"iva": 57000,
"montoTotal": 357000,
"estado": "REGISTRADO",
"dteHash": "9f2c1b7a4e5d8c3f0a6b9e2d4c7f1a8b5e3d6c9f2a4b7e1d8c5f3a6b9e2d4c7f",
"ultimaLecturaEn": "2026-08-09T03:15:42.000Z",
"detalle": {
"formaPago": "2",
"razonSocialEmisor": "Proveedor Ejemplo SpA",
"giroEmisor": "Venta de materiales de construcción",
"dirEmisor": "Av. Siempre Viva 742",
"cmnaEmisor": "Providencia",
"razonSocialReceptor": "Constructora Los Robles Ltda",
"giroReceptor": "Construcción de edificios",
"dirReceptor": "Los Robles 1200",
"cmnaReceptor": "Ñuñoa",
"items": [
{
"numeroLinea": 1,
"nombre": "Cemento 25 kg",
"cantidad": 40,
"unidad": "SACO",
"precioUnitario": 6500,
"montoItem": 260000
},
{
"numeroLinea": 2,
"nombre": "Flete",
"cantidad": null,
"unidad": null,
"precioUnitario": null,
"montoItem": 40000
}
]
}
},
"xml": null
},
"meta": {
"request_id": "req_…",
"tool_id": "sii.documentos.detallar",
"plane": "action",
"latency_ms": 24,
"audit_status": "recorded"
}
}
```
> Recortado a dos ítems. 'xml' llega null porque no se pidió 'incluirXml'. El segundo ítem no declara cantidad ni precio: es un cargo de línea. Sus null son literales, no deben leerse como cero.
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | |
| --------------------------------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `documento` | objeto | null | sí | El documento pedido, con su detalle completo. 'null' significa que ese documento no está sincronizado: no es un error, sincroniza su período con 'sii.conexion.sincronizar' y vuelve a preguntar. |
| `documento.tipoDte` | entero | sí | Código del tipo de DTE: 33 factura, 34 exenta, 46 factura de compra, 52 guía, 56 nota de débito, 61 nota de crédito. | |
| `documento.folio` | string | sí | El folio del documento, en TEXTO decimal canónico (sin ceros a la izquierda). Junto con 'tipoDte' y 'rutEmisor' lo identifica de forma única, y es el valor que 'sii.documentos.detallar' espera TAL CUAL. 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. | |
| `documento.rutEmisor` | string | sí | Quien EMITIÓ el documento. Junto con tipoDte y folio identifica al documento de forma única. | |
| `documento.rutReceptor` | string | sí | Quien RECIBIÓ el documento: en una fila 'emitidos' es la contraparte, en 'recibidos' es la empresa de esta conexión. | |
| `documento.razonSocialContraparte` | string | sí | La razón social del lado que NO es la empresa de esta conexión. | |
| `documento.perspectiva` | `"emitidos"` · `"recibidos"` | sí | emitidos = esta empresa es el emisor; recibidos = es el receptor. Es DERIVADA del documento, no del filtro. | |
| `documento.periodo` | string | sí | El período tributario con que se sincronizó el documento, en formato AAAA-MM. | |
| `documento.fechaEmision` | string | null | sí | La fecha de emisión que declara el XML del documento, en formato AAAA-MM-DD. 'null' si la fila guardada no la trae. |
| `documento.montoNeto` | entero | null | sí | 'null' cuando el DTE no declaró \: un documento sólo exento no lo trae. Nunca se fabrica un 0. |
| `documento.iva` | entero | null | sí | 'null' cuando el DTE no declaró \, por el mismo motivo que montoNeto. |
| `documento.montoTotal` | entero | sí | Puede ser 0 legítimamente: una guía de traslado interno o una nota que corrige sólo texto lo exige por XSD. | |
| `documento.estado` | string | null | sí | El estado crudo del listado del portal, tal cual. Es el observado en la última sincronización, no el final. 'null' cuando el sync no pudo emparejar este documento con su fila del índice. |
| `documento.dteHash` | string | sí | sha256 del XML guardado. Un DTE firmado es inmutable: si cambia entre sincronizaciones, algo se movió. | |
| `documento.ultimaLecturaEn` | string | sí | Cuándo se observó esta fila por última vez, en ISO 8601 UTC. El 'estado' es el de esa lectura y no el final: resincroniza el período para refrescarlo. | |
| `documento.detalle` | objeto | sí | Lo que el XML firmado trae y la cabecera no: los ítems, los giros, direcciones y comunas de emisor y receptor, y la forma de pago. Se parsea al leer, no se guarda aparte. | |
| `documento.detalle.formaPago` | string | null | sí | Código de forma de pago del DTE: 1 contado, 2 crédito, 3 sin costo. 'null' significa que el documento no lo declaró: nunca asumir contado. |
| `documento.detalle.razonSocialEmisor` | string | null | sí | La razón social de quien emitió el documento, según el XML. 'null' si el documento no la declaró. |
| `documento.detalle.giroEmisor` | string | null | sí | El giro (la actividad económica) de quien emitió el documento. 'null' si no lo declaró. |
| `documento.detalle.dirEmisor` | string | null | sí | La dirección del emisor según el XML. 'null' si no la declaró. |
| `documento.detalle.cmnaEmisor` | string | null | sí | La comuna del emisor según el XML. 'null' si no la declaró. |
| `documento.detalle.razonSocialReceptor` | string | null | sí | La razón social de quien recibió el documento, según el XML. 'null' si el documento no la declaró. |
| `documento.detalle.giroReceptor` | string | null | sí | El giro (la actividad económica) de quien recibió el documento. 'null' si no lo declaró. |
| `documento.detalle.dirReceptor` | string | null | sí | La dirección del receptor según el XML. 'null' si no la declaró. |
| `documento.detalle.cmnaReceptor` | string | null | sí | La comuna del receptor según el XML. 'null' si no la declaró. |
| `documento.detalle.items` | lista de objeto | sí | Las líneas del detalle del documento, en el orden en que vienen en el XML. Un documento sin líneas legibles llega con la lista vacía. | |
| `xml` | string | null | sí | El XML firmado del DTE, tal cual se respaldó. Sólo viaja si se pidió 'incluirXml: true'. |
JSON Schema de salida
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documento": {
"anyOf": [
{
"type": "object",
"properties": {
"tipoDte": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Código del tipo de DTE: 33 factura, 34 exenta, 46 factura de compra, 52 guía, 56 nota de débito, 61 nota de crédito."
},
"folio": {
"type": "string",
"description": "El folio del documento, en TEXTO decimal canónico (sin ceros a la izquierda). Junto con 'tipoDte' y 'rutEmisor' lo identifica de forma única, y es el valor que 'sii.documentos.detallar' espera TAL CUAL. 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."
},
"rutEmisor": {
"type": "string",
"description": "Quien EMITIÓ el documento. Junto con tipoDte y folio identifica al documento de forma única."
},
"rutReceptor": {
"type": "string",
"description": "Quien RECIBIÓ el documento: en una fila 'emitidos' es la contraparte, en 'recibidos' es la empresa de esta conexión."
},
"razonSocialContraparte": {
"type": "string",
"description": "La razón social del lado que NO es la empresa de esta conexión."
},
"perspectiva": {
"type": "string",
"enum": [
"emitidos",
"recibidos"
],
"description": "emitidos = esta empresa es el emisor; recibidos = es el receptor. Es DERIVADA del documento, no del filtro."
},
"periodo": {
"type": "string",
"description": "El período tributario con que se sincronizó el documento, en formato AAAA-MM."
},
"fechaEmision": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La fecha de emisión que declara el XML del documento, en formato AAAA-MM-DD. 'null' si la fila guardada no la trae."
},
"montoNeto": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "'null' cuando el DTE no declaró : un documento sólo exento no lo trae. Nunca se fabrica un 0."
},
"iva": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "'null' cuando el DTE no declaró , por el mismo motivo que montoNeto."
},
"montoTotal": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Puede ser 0 legítimamente: una guía de traslado interno o una nota que corrige sólo texto lo exige por XSD."
},
"estado": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El estado crudo del listado del portal, tal cual. Es el observado en la última sincronización, no el final. 'null' cuando el sync no pudo emparejar este documento con su fila del índice."
},
"dteHash": {
"type": "string",
"description": "sha256 del XML guardado. Un DTE firmado es inmutable: si cambia entre sincronizaciones, algo se movió."
},
"ultimaLecturaEn": {
"type": "string",
"description": "Cuándo se observó esta fila por última vez, en ISO 8601 UTC. El 'estado' es el de esa lectura y no el final: resincroniza el período para refrescarlo."
},
"detalle": {
"type": "object",
"properties": {
"formaPago": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Código de forma de pago del DTE: 1 contado, 2 crédito, 3 sin costo. 'null' significa que el documento no lo declaró: nunca asumir contado."
},
"razonSocialEmisor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La razón social de quien emitió el documento, según el XML. 'null' si el documento no la declaró."
},
"giroEmisor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El giro (la actividad económica) de quien emitió el documento. 'null' si no lo declaró."
},
"dirEmisor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La dirección del emisor según el XML. 'null' si no la declaró."
},
"cmnaEmisor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La comuna del emisor según el XML. 'null' si no la declaró."
},
"razonSocialReceptor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La razón social de quien recibió el documento, según el XML. 'null' si el documento no la declaró."
},
"giroReceptor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El giro (la actividad económica) de quien recibió el documento. 'null' si no lo declaró."
},
"dirReceptor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La dirección del receptor según el XML. 'null' si no la declaró."
},
"cmnaReceptor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La comuna del receptor según el XML. 'null' si no la declaró."
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"numeroLinea": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
],
"description": "El número de línea del ítem dentro del detalle. 'null' si el documento no lo declaró."
},
"nombre": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El nombre del ítem tal como lo escribió el emisor. 'null' si el documento no lo declaró."
},
"cantidad": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "La cantidad del ítem. El 'null' es literal: un flete o un descuento suelen no declararla, y no debe leerse como cero."
},
"unidad": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "La unidad de medida del ítem, tal cual la escribió el emisor. 'null' si no la declaró."
},
"precioUnitario": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El precio unitario del ítem. El 'null' es literal, igual que en 'cantidad': no debe leerse como cero."
},
"montoItem": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "El monto de la línea. 'null' significa que el documento no lo declaró de forma legible, nunca un cero."
}
},
"required": [
"numeroLinea",
"nombre",
"cantidad",
"unidad",
"precioUnitario",
"montoItem"
],
"additionalProperties": false
},
"description": "Las líneas del detalle del documento, en el orden en que vienen en el XML. Un documento sin líneas legibles llega con la lista vacía."
}
},
"required": [
"formaPago",
"razonSocialEmisor",
"giroEmisor",
"dirEmisor",
"cmnaEmisor",
"razonSocialReceptor",
"giroReceptor",
"dirReceptor",
"cmnaReceptor",
"items"
],
"additionalProperties": false,
"description": "Lo que el XML firmado trae y la cabecera no: los ítems, los giros, direcciones y comunas de emisor y receptor, y la forma de pago. Se parsea al leer, no se guarda aparte."
}
},
"required": [
"tipoDte",
"folio",
"rutEmisor",
"rutReceptor",
"razonSocialContraparte",
"perspectiva",
"periodo",
"fechaEmision",
"montoNeto",
"iva",
"montoTotal",
"estado",
"dteHash",
"ultimaLecturaEn",
"detalle"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "El documento pedido, con su detalle completo. 'null' significa que ese documento no está sincronizado: no es un error, sincroniza su período con 'sii.conexion.sincronizar' y vuelve a preguntar."
},
"xml": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "El XML firmado del DTE, tal cual se respaldó. Sólo viaja si se pidió 'incluirXml: true'."
}
},
"required": [
"documento",
"xml"
],
"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.