# Listar los documentos emitidos > Lista los documentos que esta empresa emitió a través de Notta, con filtros por tipo de documento, folio, RUT del receptor, rango de fechas de emisión, estado en el SII y estado del receptor, y paginación por cursor. {/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */} | | | | ------------------- | ----------------------------------------------------------------- | | **Tool ID** | `notta.dte.listar` | | **Nombre MCP** | `notta__dte__listar` | | **Conector** | `notta` | | **Plano** | `action` | | **Scope (permiso)** | `notta:read` | | **Auth** | `connection_credentials` | | **Versión** | `3` | | **Sensible** | sí | | **Deprecado** | no | | **Comportamiento** | readOnly=true, destructive=false, idempotent=true, openWorld=true | > **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] Cada fila trae folio, montos, el estado en el SII y los enlaces del documento. Para el detalle completo de uno, con sus items y su historial, usa notta.dte.obtener. También sirve como red antes de reintentar una emisión que falló por transporte o timeout: si el documento ya aparece, no lo vuelvas a emitir. ## Entrada [#entrada] | Campo | Tipo | Requerido | Descripción | | | --------------------- | --------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | entero 1-100 | no | Default 20, máx 100 | | | `cursor` | string | no | `next_cursor` de la página anterior. Opaco: no lo construyas ni lo modifiques. | | | `sort` | `"folio"` · `"monto_total"` · `"fecha_emision"` · `"sii_status"` · `"created_at"` | no | Campo por el que se ordena. Default `created_at`. El cursor se emite atado a este orden: cambiarlo a mitad de recorrido devuelve 422 en vez de saltarse filas en silencio. | | | `dir` | `"asc"` · `"desc"` | no | Sentido del orden. Default `desc`, o sea lo más reciente primero. | | | `sii_status` | string | no | Estados SII a incluir, separados por coma (p. ej. `queued,sending,SOK`). Un valor fuera del vocabulario devuelve 422. Clasificación GENERADA del mismo catálogo que usa el runtime, no una lista escrita a mano que pueda contradecirlo: `terminal: true` (el SII ya dio su veredicto; volver a consultar no puede devolver otra cosa) → EPR, RPR, aceptado\_con\_reparos, accepted, RFR, RCT, RSC, RCH `terminal: false` (el estado todavía puede cambiar) → queued, sending, signed, awaiting\_sii, SOK, CRT, FOK, PDR, PRD, -11, stuck, sin\_permiso\_sii `stuck` y `sin_permiso_sii` NO son terminales aunque ya no haya un poll detrás: el SII nunca llegó a juzgar el documento, así que `POST /dtes/\{id\}/refresh-status` vuelve a consultar y responde 202, no `already_terminal` (en `sin_permiso_sii`, después de enrolar el RUT del certificado en Mi SII → Usuarios autorizados). `accepted` son los documentos importados del Respaldo del SII: el Servicio ya los aceptó en su momento y no tienen envío que consultar. `signed` es el DTE ya firmado y todavía sin subir. `awaiting_sii` y `aceptado_con_reparos` están DEPRECADOS: ningún proceso de Notta los escribe hoy. Este filtro los sigue aceptando para no romper a quien ya los consultaba; en código nuevo usa `RPR`. La glosa y la acción sugerida de cada estado viajan en el bloque `estado` de cada documento. | | | `tipo_dte` | entero 0-9999 | null | no | Código SII del tipo de documento (33 factura, 34 exenta, 52 guía de despacho, 56 nota de débito, 61 nota de crédito). Un valor no numérico o fuera de rango devuelve 422 `dte.list.tipo_invalido`. Alcanza también los documentos importados del Respaldo del SII. | | `folio` | string | null | no | Folio exacto. NO identifica un documento por sí solo: el mismo folio existe una vez por `tipo_dte` (y por ambiente), así que la respuesta es una lista, súmale `tipo_dte` para la coordenada exacta. Un valor no numérico o fuera de rango devuelve 422 `dte.list.folio_invalido`. | | `rut_receptor` | string | no | RUT del receptor. Acepta puntos, espacios y la `k` en minúscula (se normaliza a `BODY-DV`). El dígito verificador NO se valida: la columna es lo que declaró el emisor, y un DV que no cierra igual corresponde a documentos reales. Una forma que no es un RUT devuelve 422 `dte.list.rut_receptor_invalido`. | | | `fecha_emision_desde` | string | no | `fecha_emision >=` (YYYY-MM-DD, inclusive) | | | `fecha_emision_hasta` | string | no | `fecha_emision \<=` (YYYY-MM-DD, inclusive) | | | `polled_since` | string | no | Instante ISO-8601. Filtra por `sii_last_polled >=`, o sea TOCADO desde. Esa columna se estampa en cada escritura de estado, incluidas las de la emisión (`queued`, `sending`, `signed`), no solo en los polls al SII. Nunca pierde un cambio; sí devuelve documentos cuyo estado no cambió. | | | `receptor_estado` | `"reclamado"` · `"aceptado"` · `"en_plazo"` · `"aceptado_tacito"` · `"sin_info"` | no | Filtra por lo que hizo el receptor con el documento (no es `sii_status`). Acepta los mismos cinco valores que publica el campo `receptor_estado` de cada fila. `reclamado` y `aceptado` son HECHOS que el SII registró y no se mueven; `en_plazo`, `aceptado_tacito` y `sin_info` se calculan contra el instante del request, así que un documento puede cambiar de bucket entre la página 1 y la 2 de una misma consulta paginada. Si necesitas una foto estable, filtra en tu lado con `fecha_recepcion_sii` y `plazo_reclamo_cierra`, que vienen en cada fila. Un valor fuera de esos cinco devuelve 422 `dte.list.receptor_estado_invalido`. | |
JSON Schema de entrada ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Default 20, máx 100" }, "cursor": { "type": "string", "description": "`next_cursor` de la página anterior. Opaco: no lo construyas ni lo modifiques." }, "sort": { "type": "string", "enum": [ "folio", "monto_total", "fecha_emision", "sii_status", "created_at" ], "description": "Campo por el que se ordena. Default `created_at`. El cursor se emite atado a este orden: cambiarlo a mitad de recorrido devuelve 422 en vez de saltarse filas en silencio." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sentido del orden. Default `desc`, o sea lo más reciente primero." }, "sii_status": { "type": "string", "description": "Estados SII a incluir, separados por coma (p. ej. `queued,sending,SOK`). Un valor fuera del vocabulario devuelve 422.\n\nClasificación GENERADA del mismo catálogo que usa el runtime, no una lista escrita a mano que pueda contradecirlo:\n\n`terminal: true` (el SII ya dio su veredicto; volver a consultar no puede devolver otra cosa) → EPR, RPR, aceptado_con_reparos, accepted, RFR, RCT, RSC, RCH\n\n`terminal: false` (el estado todavía puede cambiar) → queued, sending, signed, awaiting_sii, SOK, CRT, FOK, PDR, PRD, -11, stuck, sin_permiso_sii\n\n`stuck` y `sin_permiso_sii` NO son terminales aunque ya no haya un poll detrás: el SII nunca llegó a juzgar el documento, así que `POST /dtes/{id}/refresh-status` vuelve a consultar y responde 202, no `already_terminal` (en `sin_permiso_sii`, después de enrolar el RUT del certificado en Mi SII → Usuarios autorizados). `accepted` son los documentos importados del Respaldo del SII: el Servicio ya los aceptó en su momento y no tienen envío que consultar. `signed` es el DTE ya firmado y todavía sin subir.\n\n`awaiting_sii` y `aceptado_con_reparos` están DEPRECADOS: ningún proceso de Notta los escribe hoy. Este filtro los sigue aceptando para no romper a quien ya los consultaba; en código nuevo usa `RPR`.\n\nLa glosa y la acción sugerida de cada estado viajan en el bloque `estado` de cada documento." }, "tipo_dte": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9999 }, { "type": "null" } ], "description": "Código SII del tipo de documento (33 factura, 34 exenta, 52 guía de despacho, 56 nota de débito, 61 nota de crédito). Un valor no numérico o fuera de rango devuelve 422 `dte.list.tipo_invalido`. Alcanza también los documentos importados del Respaldo del SII." }, "folio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Folio exacto. NO identifica un documento por sí solo: el mismo folio existe una vez por `tipo_dte` (y por ambiente), así que la respuesta es una lista, súmale `tipo_dte` para la coordenada exacta. Un valor no numérico o fuera de rango devuelve 422 `dte.list.folio_invalido`." }, "rut_receptor": { "type": "string", "description": "RUT del receptor. Acepta puntos, espacios y la `k` en minúscula (se normaliza a `BODY-DV`). El dígito verificador NO se valida: la columna es lo que declaró el emisor, y un DV que no cierra igual corresponde a documentos reales. Una forma que no es un RUT devuelve 422 `dte.list.rut_receptor_invalido`." }, "fecha_emision_desde": { "type": "string", "description": "`fecha_emision >=` (YYYY-MM-DD, inclusive)" }, "fecha_emision_hasta": { "type": "string", "description": "`fecha_emision <=` (YYYY-MM-DD, inclusive)" }, "polled_since": { "type": "string", "description": "Instante ISO-8601. Filtra por `sii_last_polled >=`, o sea TOCADO desde. Esa columna se estampa en cada escritura de estado, incluidas las de la emisión (`queued`, `sending`, `signed`), no solo en los polls al SII. Nunca pierde un cambio; sí devuelve documentos cuyo estado no cambió." }, "receptor_estado": { "type": "string", "enum": [ "reclamado", "aceptado", "en_plazo", "aceptado_tacito", "sin_info" ], "description": "Filtra por lo que hizo el receptor con el documento (no es `sii_status`). Acepta los mismos cinco valores que publica el campo `receptor_estado` de cada fila. `reclamado` y `aceptado` son HECHOS que el SII registró y no se mueven; `en_plazo`, `aceptado_tacito` y `sin_info` se calculan contra el instante del request, así que un documento puede cambiar de bucket entre la página 1 y la 2 de una misma consulta paginada. Si necesitas una foto estable, filtra en tu lado con `fecha_recepcion_sii` y `plazo_reclamo_cierra`, que vienen en cada fila. Un valor fuera de esos cinco devuelve 422 `dte.list.receptor_estado_invalido`." } } } ```
## Salida [#salida] | Campo | Tipo | Requerido | Descripción | | | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | lista de objeto | sí | Documentos de esta página, en el orden que piden `sort` y `dir`. | | | | `data[].id` | string \`^(\[0-9a-fA-F]{8}-\[0-9a-fA-F]{4}-\[1-8]\[0-9a-fA-F]{3}-\[89abAB]\[0-9a-fA-F]{3}-\[0-9a-fA-F]{12} | 00000000-0000-0000-0000-000000000000 | ffffffff-ffff-ffff-ffff-ffffffffffff)$\` | sí | UUID del documento en Notta. Es el identificador que piden `GET /dtes/\{id\}`, `/pdf-url`, `/xml-url`, `/events` y `/refresh-status`. No es el folio ni el TrackID del SII. | | `data[].folio` | string | sí | Folio que el SII asignó desde el CAF. La numeración corre por (RUT emisor, tipo de documento, ambiente), así que el folio SOLO no identifica un documento: el mismo número existe en otro tipo y en el otro ambiente. Para ubicarlo por folio, filtra también por `tipo_dte`. | | | | `data[].tipo_dte` | `33` · `34` · `39` · `41` · `46` · `52` · … | sí | Código SII del tipo de documento: 33 factura afecta, 34 factura exenta, 46 factura de compra, 52 guía de despacho, 56 nota de débito, 61 nota de crédito, 110/112 exportación. | | | | `data[].rut_emisor` | string | sí | RUT de la empresa que emitió, en formato `CUERPO-DV` sin puntos (`76123456-0`). | | | | `data[].rut_receptor` | string | sí | RUT del receptor del documento, en formato `CUERPO-DV` sin puntos (`76123456-0`). | | | | `data[].razon_social_receptor` | string | sí | Razón social del receptor, tal como quedó en el documento emitido. | | | | `data[].monto_neto` | entero | sí | Monto neto afecto EN PESOS CHILENOS, siempre. 0 en un documento exento, y también en una exportación (110/112), donde el total va en `monto_exento`. | | | | `data[].monto_exento` | entero | sí | Monto exento del documento EN PESOS CHILENOS, siempre. 0 cuando no hay. En una exportación (110/112) NO es lo que declara la factura: el total exportado se registra aquí ya convertido, y el monto en su moneda viaja en `monto_moneda` con la moneda en `moneda_documento`. Vivía sólo en el DETALLE, así que cuadrar una exenta (34), o el exento de una 33 mixta, desde el listado costaba un `GET /dtes/\{id\}` por fila, que es el motivo por el que `monto_neto` e `iva` ya viajaban aquí. | | | | `data[].iva` | entero | sí | IVA del documento EN PESOS CHILENOS. 0 cuando no hay monto afecto (documento exento o exportación). | | | | `data[].monto_total` | entero | sí | Total del documento EN PESOS CHILENOS, siempre: es lo que consumen el Libro de Ventas, las cuotas y el F29. En una exportación (110/112) es el EQUIVALENTE en pesos: lo que declara la factura viene en `monto_moneda`, y la moneda en `moneda_documento`. | | | | `data[].moneda_documento` | string | no | Sólo en exportación (110/112): la moneda del documento, con la glosa del catálogo del SII ("DOLAR USA", "EURO"). Ausente en un documento en pesos, donde `monto_total` ya lo dice todo. | | | | `data[].monto_moneda` | número | no | Sólo en exportación: el total EN la moneda del documento, con hasta 4 decimales. Es la cifra que dice la factura; `monto_total` es su equivalente en pesos al tipo de cambio del día. | | | | `data[].sii_status` | `"queued"` · `"sending"` · `"awaiting_sii"` · `"SOK"` · `"CRT"` · `"FOK"` · … | sí | Vocabulario de `dtes.sii_status`, generado del catálogo de estados. Cada valor con su glosa, si tiene VEREDICTO del SII (`terminal`) y la acción sugerida. La descripción larga de cada uno viaja en el bloque `estado` de esta misma respuesta: `queued`: en cola · terminal: no · acción: `esperar` `sending`: enviando · terminal: no · acción: `esperar` `signed`: firmado, sin subir al SII · terminal: no · acción: `esperar` `awaiting_sii`: esperando al SII · terminal: no · acción: `esperar` · DEPRECADO `SOK`: schema del envío validado · terminal: no · acción: `esperar` `CRT`: carátula del envío validada · terminal: no · acción: `esperar` `FOK`: firma del envío validada · terminal: no · acción: `esperar` `PDR`: envío en proceso · terminal: no · acción: `esperar` `PRD`: envío en proceso · terminal: no · acción: `esperar` `-11`: procesando en el SII · terminal: no · acción: `esperar` `EPR`: aceptado · terminal: sí · acción: `ninguna` `RPR`: aceptado con reparos · terminal: sí · acción: `ninguna` `aceptado_con_reparos`: aceptado con reparos · terminal: sí · acción: `ninguna` · DEPRECADO `accepted`: aceptado (importado del Respaldo del SII) · terminal: sí · acción: `ninguna` `RFR`: rechazo por firma · terminal: sí · acción: `contactar_soporte` `RCT`: rechazo por carátula · terminal: sí · acción: `contactar_soporte` `RSC`: rechazo por schema · terminal: sí · acción: `contactar_soporte` `RCH`: documento rechazado · terminal: sí · acción: `reemitir` `stuck`: atascado en SII · terminal: no · acción: `reintentar_consulta` `sin_permiso_sii`: sin permiso para consultar en el SII · terminal: no · acción: `accion_en_sii` Corta cualquier bucle de espera por `estado.terminal`, NUNCA por `sii_status === "EPR"`: un rechazo (`RFR`, `RCT`, `RSC` y `RCH`) también es final, y ese bucle no saldría nunca. `stuck` y `sin_permiso_sii` no son terminales (el SII no llegó a juzgar el documento) pero tampoco avanzan solos: los destraba `POST /dtes/\{id\}/refresh-status`. | | | | `data[].estado` | objeto | sí | La clasificación de `sii_status`, publicada. `sii_status` NO cambia y NO se reemplaza: el código crudo sigue siendo el contrato y este bloque lo AGREGA. Sirve para decidir sin adivinar: `terminal` corta los bucles de espera, `accion` dice qué hacer, y un código que el catálogo no conoce igual cae en una casilla accionable. | | | | `data[].estado.code` | string | sí | El mismo valor que `sii_status`, repetido aquí para que el bloque se explique solo. NO es un enum cerrado a propósito: el SII no publica una lista cerrada de códigos. Su instructivo termina la tabla con «Otros (no enumerados)», y Notta guarda verbatim lo que responde, así que puede traer uno que el catálogo no conozca (en producción ya aparecieron `106` y `107`). Un código desconocido llega clasificado como NO terminal, `en_proceso` y `contactar_soporte`, nunca como éxito. | | | | `data[].estado.label` | string | sí | Glosa corta en español, para mostrar. AGREGA información al código, no lo reemplaza. | | | | `data[].estado.descripcion` | string | sí | Qué pasó y qué significa, en prosa. Está para que no haya que inferir la causa: un `-11` es el código con que FALLA la consulta de estado mientras el SII todavía no registra el envío recién subido, no un estado del documento, y es el camino normal. | | | | `data[].estado.terminal` | booleano | sí | `true` ⇒ el SII ya dio su veredicto y volver a preguntar no puede devolver otra cosa. Es la CONDICIÓN DE CORTE de cualquier bucle de espera: cortar por `sii_status === "EPR"` deja el bucle vivo para siempre ante un rechazo. `stuck` y `sin_permiso_sii` son `false` a propósito (no hay veredicto), pero tampoco avanzan solos: mira `accion`. | | | | `data[].estado.poll_activo` | booleano | sí | `true` ⇒ Notta tiene un poll durable consultando al SII por este documento ahora mismo; no hay nada que hacer más que volver a leer. `false` junto con `terminal: false` significa que nadie está mirando este documento: ahí `accion` dice qué lo destraba. | | | | `data[].estado.categoria` | `"en_proceso"` · `"aceptado"` · `"rechazado"` · `"requiere_accion"` · `"archivistico"` | sí | Cómo terminó, o por qué no terminó: `en_proceso`: el SII todavía no dio veredicto; `aceptado`: veredicto favorable: el documento vale; `rechazado`: veredicto desfavorable: el SII no aceptó el documento; `requiere_accion`: no hay veredicto y no lo va a haber sin que alguien haga algo; `archivistico`: el SII ya lo aceptó en su momento; no hay envío que consultar. | | | | `data[].estado.accion` | `"esperar"` · `"reintentar_consulta"` · `"reemitir"` · `"contactar_soporte"` · `"accion_en_sii"` · `"ninguna"` | sí | Qué hacer, en un enum ESTABLE pensado para que un agente ramifique sin leer la prosa, el equivalente de `next_action` en el contrato de errores: `esperar`: el poll converge solo; vuelve a leer más tarde; `reintentar_consulta`: `POST /dtes/\{id\}/refresh-status` destraba el caso; `reemitir`: el folio quedó quemado; emite uno nuevo corregido (nunca una Nota de Crédito: un documento rechazado no fue aceptado y no hay nada que anular); `contactar_soporte`: el dueño del problema es Notta; el emisor no puede corregirlo solo; `accion_en_sii`: el emisor tiene que hacer algo en el portal del SII; `ninguna`: terminal favorable: no hay nada que hacer. | | | | `data[].sii_glosa` | string | null | sí | Glosa con que el SII explica `sii_status`, en sus palabras. null mientras no haya respuesta del Servicio. Es texto para leer, no un código: lo estable es `sii_status`. | | | `data[].track_id` | string | null | sí | TrackID que devolvió el SII al recibir el envío. Sirve para rastrear ESE envío en el portal del Servicio; no identifica el documento en esta API (para eso está `id`). null hasta que el DTE se sube. | | | `data[].sii_env` | `"cert"` · `"prod"` | sí | Ambiente al que pertenece ESTE documento: `cert` (maullin, documento de prueba sin valor tributario) o `prod` (palena). Es del documento y no de la empresa: una organización ya autorizada en producción sigue teniendo documentos de certificación, y cada ambiente lleva su propia secuencia de folios. | | | | `data[].sii_last_polled` | string | null | sí | Última ESCRITURA de estado, no solo consultas al SII: se estampa tanto en cada poll (haya cambio o no) como en las transiciones de la emisión (`queued`, `sending`, `signed`). Un DTE recién emitido ya la trae. Nunca pierde un cambio; sí devuelve documentos cuyo estado no cambió. Es el ancla de `?polled_since=`. | | | `data[].forma_pago` | `1` · `2` · `3` | null | sí | Forma de pago que se declaró al emitir (`\`): 1 contado, 2 crédito, 3 sin costo. Es el campo que necesitas para volver a emitir un documento a partir de otro, porque `POST /dtes` lo exige en 33/34/46. `null` significa que ESTE documento no la declara, y hay dos motivos: el tipo no la lleva (guía 52, notas 56/61, exportación) o el documento se importó del Respaldo del SII, donde lo emitió otro sistema. `null` NO es contado: no lo colapses a un número ni asumas un default. | | | `data[].fecha_emision` | string | sí | `FchEmis` del documento: fecha calendario chilena `YYYY-MM-DD`. Es la fecha TRIBUTARIA, la que decide el período del IVA, no el instante en que se creó el registro (ese es `created_at`, y puede caer en otro día). | | | | `data[].documento_disponible` | booleano | sí | `true` = hay XML firmado y `/dtes/\{id\}/pdf\|xml\|pdf-url` responden. Distingue “existe y se puede bajar” de “existe pero aún no está firmado”, sin gastar un request en un 409. | | | | `data[].created_at` | string | sí | Instante ISO-8601 en que Notta registró el documento. | | | | `data[].receptor_estado` | `"reclamado"` · `"aceptado"` · `"en_plazo"` · `"aceptado_tacito"` · `"sin_info"` | sí | Qué hizo TU CLIENTE con el documento. NO es `sii_status`: el SII puede haberlo aceptado (`EPR`) y el receptor reclamarlo igual: son dos máquinas de estado distintas. Se decide en este orden, el mismo que aplica el servidor: (1) `reclamado`: el receptor lo reclamó ante el SII; es un HECHO registrado y es IRREVERSIBLE: no existe forma de deshacerlo por esta API ni por el portal, y la salida comercial es emitir una nota de crédito. (2) `aceptado`: el receptor otorgó recibo, o el SII informó que el plazo se cumplió sin reclamo; también es un hecho registrado. (3) `en_plazo`: todavía corre la ventana, y cierra en el instante que indica `plazo_reclamo_cierra`. (4) `aceptado_tacito`: esa ventana ya cerró sin reclamo (Ley 19.983). (5) `sin_info`: el SII aún no informó `fecha_recepcion_sii`, así que el plazo no empezó a correr y no se sabe nada del receptor; NO significa que no haya respondido. Los tres últimos se DERIVAN contra el instante del request y cambian solos con el reloj: no los caches. | | | | `data[].receptor_reclamado_at` | string | null | sí | `YYYY-MM-DD` del reclamo, tal como lo informa el registro del SII. `null` = no hay reclamo registrado, o el reclamo llegó sólo como código y sin su fecha (mira `receptor_estado`, que es el campo que decide). Un `null` aquí nunca significa por sí solo que el cliente no haya reclamado. | | | `data[].receptor_acuse_at` | string | null | sí | `YYYY-MM-DD` del acuse de recibo del receptor. `null` = no lo otorgó, o llegó sin fecha. Igual que su hermano, no es el campo con el que se decide: ése es `receptor_estado`. | | | `data[].fecha_recepcion_sii` | string | null | sí | Instante ISO-8601 (con hora) en que el SII recibió el documento y lo dejó a disposición del receptor. Es el ANCLA del plazo de reclamo: `fecha_emision` NO lo ancla, y contar desde ahí ya fechó un vencimiento cuatro días antes de tiempo. `null` = el SII todavía no lo informó (por eso el plazo no corre y `receptor_estado` vale `sin_info`); se puebla solo cuando el registro del SII lo entrega. | | | `data[].plazo_reclamo_cierra` | string | null | sí | Instante ISO-8601 EXACTO en que el receptor pierde el derecho a reclamar: `fecha_recepcion_sii` + 192 horas (Ley 19.983, Art. 3). Es una HORA, no un día de calendario: el SII cuenta fecha-hora a fecha-hora y a partir de ese instante rechaza el reclamo, así que tratar el día entero como disponible le regala al receptor horas que ya no tiene. `null` cuando no hay ancla (`fecha_recepcion_sii` en `null`): sin fecha de recepción no hay plazo que calcular, y una fecha derivada de `fecha_emision` sería sencillamente errónea. Este plazo corre contra el RECEPTOR; al emisor no le abre ninguna ventana ni le exige ninguna acción. | | | `data[].references` | lista de objeto | sí | `\` del documento: correctivas (NC/ND) y comerciales (orden de compra…). Un documento sin referencias trae `[]`, nunca `null`. | | | | `data[].references[].line_num` | entero | sí | `\` del XML: identidad de la línea dentro del documento. Admite saltos. | | | | `data[].references[].tipo_doc_ref` | valor | sí | Código SII del documento referenciado (correctiva) o el string original (comercial). | | | | `data[].references[].folio_ref` | valor | sí | Folio del documento referenciado. Número en una referencia correctiva (la NC o ND sobre un DTE) y puede venir como texto en una comercial, donde el identificador es el del documento de origen (una orden de compra, un contrato). | | | | `data[].references[].fecha_ref` | string | sí | `\`: fecha del documento REFERENCIADO, no la de éste. Desambigua cuando el mismo (tipo, folio) existe en más de un período: el folio se reinicia por emisor y por ambiente. | | | | `data[].references[].cod_ref` | entero | null | sí | 1 anula · 2 corrige texto · 3 corrige montos · null = referencia comercial | | | `data[].references[].razon_ref` | string | null | sí | `\`: texto libre con el motivo de la referencia. null si no se declaró. | | | `data[].links` | objeto | sí | Rutas relativas bajo `/api/v1` para seguir este documento. | | | | `data[].links.self` | string | sí | Ruta de este documento: `GET /api/v1/dtes/\{id\}`. | | | | `next_cursor` | string | null | sí | Cursor de la página siguiente: pásalo tal cual en `?cursor=`, sin cambiar `sort` ni `dir`. `null` = ya estás en la última página. | |
JSON Schema de salida ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "UUID del documento en Notta. Es el identificador que piden `GET /dtes/{id}`, `/pdf-url`, `/xml-url`, `/events` y `/refresh-status`. No es el folio ni el TrackID del SII." }, "folio": { "type": "string", "description": "Folio que el SII asignó desde el CAF. La numeración corre por (RUT emisor, tipo de documento, ambiente), así que el folio SOLO no identifica un documento: el mismo número existe en otro tipo y en el otro ambiente. Para ubicarlo por folio, filtra también por `tipo_dte`." }, "tipo_dte": { "type": "number", "enum": [ 33, 34, 39, 41, 46, 52, 56, 61, 110, 112 ], "description": "Código SII del tipo de documento: 33 factura afecta, 34 factura exenta, 46 factura de compra, 52 guía de despacho, 56 nota de débito, 61 nota de crédito, 110/112 exportación." }, "rut_emisor": { "type": "string", "description": "RUT de la empresa que emitió, en formato `CUERPO-DV` sin puntos (`76123456-0`)." }, "rut_receptor": { "type": "string", "description": "RUT del receptor del documento, en formato `CUERPO-DV` sin puntos (`76123456-0`)." }, "razon_social_receptor": { "type": "string", "description": "Razón social del receptor, tal como quedó en el documento emitido." }, "monto_neto": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Monto neto afecto EN PESOS CHILENOS, siempre. 0 en un documento exento, y también en una exportación (110/112), donde el total va en `monto_exento`." }, "monto_exento": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Monto exento del documento EN PESOS CHILENOS, siempre. 0 cuando no hay. En una exportación (110/112) NO es lo que declara la factura: el total exportado se registra aquí ya convertido, y el monto en su moneda viaja en `monto_moneda` con la moneda en `moneda_documento`. Vivía sólo en el DETALLE, así que cuadrar una exenta (34), o el exento de una 33 mixta, desde el listado costaba un `GET /dtes/{id}` por fila, que es el motivo por el que `monto_neto` e `iva` ya viajaban aquí." }, "iva": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "IVA del documento EN PESOS CHILENOS. 0 cuando no hay monto afecto (documento exento o exportación)." }, "monto_total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Total del documento EN PESOS CHILENOS, siempre: es lo que consumen el Libro de Ventas, las cuotas y el F29. En una exportación (110/112) es el EQUIVALENTE en pesos: lo que declara la factura viene en `monto_moneda`, y la moneda en `moneda_documento`." }, "moneda_documento": { "type": "string", "description": "Sólo en exportación (110/112): la moneda del documento, con la glosa del catálogo del SII (\"DOLAR USA\", \"EURO\"). Ausente en un documento en pesos, donde `monto_total` ya lo dice todo." }, "monto_moneda": { "type": "number", "description": "Sólo en exportación: el total EN la moneda del documento, con hasta 4 decimales. Es la cifra que dice la factura; `monto_total` es su equivalente en pesos al tipo de cambio del día." }, "sii_status": { "type": "string", "enum": [ "queued", "sending", "awaiting_sii", "SOK", "CRT", "FOK", "PDR", "PRD", "-11", "EPR", "RPR", "aceptado_con_reparos", "RFR", "RCT", "RSC", "RCH", "stuck", "signed", "accepted", "sin_permiso_sii" ], "description": "Vocabulario de `dtes.sii_status`, generado del catálogo de estados. Cada valor con su glosa, si tiene VEREDICTO del SII (`terminal`) y la acción sugerida. La descripción larga de cada uno viaja en el bloque `estado` de esta misma respuesta:\n\n`queued`: en cola · terminal: no · acción: `esperar`\n`sending`: enviando · terminal: no · acción: `esperar`\n`signed`: firmado, sin subir al SII · terminal: no · acción: `esperar`\n`awaiting_sii`: esperando al SII · terminal: no · acción: `esperar` · DEPRECADO\n`SOK`: schema del envío validado · terminal: no · acción: `esperar`\n`CRT`: carátula del envío validada · terminal: no · acción: `esperar`\n`FOK`: firma del envío validada · terminal: no · acción: `esperar`\n`PDR`: envío en proceso · terminal: no · acción: `esperar`\n`PRD`: envío en proceso · terminal: no · acción: `esperar`\n`-11`: procesando en el SII · terminal: no · acción: `esperar`\n`EPR`: aceptado · terminal: sí · acción: `ninguna`\n`RPR`: aceptado con reparos · terminal: sí · acción: `ninguna`\n`aceptado_con_reparos`: aceptado con reparos · terminal: sí · acción: `ninguna` · DEPRECADO\n`accepted`: aceptado (importado del Respaldo del SII) · terminal: sí · acción: `ninguna`\n`RFR`: rechazo por firma · terminal: sí · acción: `contactar_soporte`\n`RCT`: rechazo por carátula · terminal: sí · acción: `contactar_soporte`\n`RSC`: rechazo por schema · terminal: sí · acción: `contactar_soporte`\n`RCH`: documento rechazado · terminal: sí · acción: `reemitir`\n`stuck`: atascado en SII · terminal: no · acción: `reintentar_consulta`\n`sin_permiso_sii`: sin permiso para consultar en el SII · terminal: no · acción: `accion_en_sii`\n\nCorta cualquier bucle de espera por `estado.terminal`, NUNCA por `sii_status === \"EPR\"`: un rechazo (`RFR`, `RCT`, `RSC` y `RCH`) también es final, y ese bucle no saldría nunca. `stuck` y `sin_permiso_sii` no son terminales (el SII no llegó a juzgar el documento) pero tampoco avanzan solos: los destraba `POST /dtes/{id}/refresh-status`." }, "estado": { "type": "object", "properties": { "code": { "type": "string", "description": "El mismo valor que `sii_status`, repetido aquí para que el bloque se explique solo. NO es un enum cerrado a propósito: el SII no publica una lista cerrada de códigos. Su instructivo termina la tabla con «Otros (no enumerados)», y Notta guarda verbatim lo que responde, así que puede traer uno que el catálogo no conozca (en producción ya aparecieron `106` y `107`). Un código desconocido llega clasificado como NO terminal, `en_proceso` y `contactar_soporte`, nunca como éxito." }, "label": { "type": "string", "description": "Glosa corta en español, para mostrar. AGREGA información al código, no lo reemplaza." }, "descripcion": { "type": "string", "description": "Qué pasó y qué significa, en prosa. Está para que no haya que inferir la causa: un `-11` es el código con que FALLA la consulta de estado mientras el SII todavía no registra el envío recién subido, no un estado del documento, y es el camino normal." }, "terminal": { "type": "boolean", "description": "`true` ⇒ el SII ya dio su veredicto y volver a preguntar no puede devolver otra cosa. Es la CONDICIÓN DE CORTE de cualquier bucle de espera: cortar por `sii_status === \"EPR\"` deja el bucle vivo para siempre ante un rechazo. `stuck` y `sin_permiso_sii` son `false` a propósito (no hay veredicto), pero tampoco avanzan solos: mira `accion`." }, "poll_activo": { "type": "boolean", "description": "`true` ⇒ Notta tiene un poll durable consultando al SII por este documento ahora mismo; no hay nada que hacer más que volver a leer. `false` junto con `terminal: false` significa que nadie está mirando este documento: ahí `accion` dice qué lo destraba." }, "categoria": { "type": "string", "enum": [ "en_proceso", "aceptado", "rechazado", "requiere_accion", "archivistico" ], "description": "Cómo terminó, o por qué no terminó: `en_proceso`: el SII todavía no dio veredicto; `aceptado`: veredicto favorable: el documento vale; `rechazado`: veredicto desfavorable: el SII no aceptó el documento; `requiere_accion`: no hay veredicto y no lo va a haber sin que alguien haga algo; `archivistico`: el SII ya lo aceptó en su momento; no hay envío que consultar." }, "accion": { "type": "string", "enum": [ "esperar", "reintentar_consulta", "reemitir", "contactar_soporte", "accion_en_sii", "ninguna" ], "description": "Qué hacer, en un enum ESTABLE pensado para que un agente ramifique sin leer la prosa, el equivalente de `next_action` en el contrato de errores: `esperar`: el poll converge solo; vuelve a leer más tarde; `reintentar_consulta`: `POST /dtes/{id}/refresh-status` destraba el caso; `reemitir`: el folio quedó quemado; emite uno nuevo corregido (nunca una Nota de Crédito: un documento rechazado no fue aceptado y no hay nada que anular); `contactar_soporte`: el dueño del problema es Notta; el emisor no puede corregirlo solo; `accion_en_sii`: el emisor tiene que hacer algo en el portal del SII; `ninguna`: terminal favorable: no hay nada que hacer." } }, "required": [ "code", "label", "descripcion", "terminal", "poll_activo", "categoria", "accion" ], "additionalProperties": false, "description": "La clasificación de `sii_status`, publicada. `sii_status` NO cambia y NO se reemplaza: el código crudo sigue siendo el contrato y este bloque lo AGREGA. Sirve para decidir sin adivinar: `terminal` corta los bucles de espera, `accion` dice qué hacer, y un código que el catálogo no conoce igual cae en una casilla accionable." }, "sii_glosa": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Glosa con que el SII explica `sii_status`, en sus palabras. null mientras no haya respuesta del Servicio. Es texto para leer, no un código: lo estable es `sii_status`." }, "track_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TrackID que devolvió el SII al recibir el envío. Sirve para rastrear ESE envío en el portal del Servicio; no identifica el documento en esta API (para eso está `id`). null hasta que el DTE se sube." }, "sii_env": { "type": "string", "enum": [ "cert", "prod" ], "description": "Ambiente al que pertenece ESTE documento: `cert` (maullin, documento de prueba sin valor tributario) o `prod` (palena). Es del documento y no de la empresa: una organización ya autorizada en producción sigue teniendo documentos de certificación, y cada ambiente lleva su propia secuencia de folios." }, "sii_last_polled": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Última ESCRITURA de estado, no solo consultas al SII: se estampa tanto en cada poll (haya cambio o no) como en las transiciones de la emisión (`queued`, `sending`, `signed`). Un DTE recién emitido ya la trae. Nunca pierde un cambio; sí devuelve documentos cuyo estado no cambió. Es el ancla de `?polled_since=`." }, "forma_pago": { "anyOf": [ { "type": "number", "enum": [ 1, 2, 3 ] }, { "type": "null" } ], "description": "Forma de pago que se declaró al emitir (``): 1 contado, 2 crédito, 3 sin costo. Es el campo que necesitas para volver a emitir un documento a partir de otro, porque `POST /dtes` lo exige en 33/34/46. `null` significa que ESTE documento no la declara, y hay dos motivos: el tipo no la lleva (guía 52, notas 56/61, exportación) o el documento se importó del Respaldo del SII, donde lo emitió otro sistema. `null` NO es contado: no lo colapses a un número ni asumas un default." }, "fecha_emision": { "type": "string", "description": "`FchEmis` del documento: fecha calendario chilena `YYYY-MM-DD`. Es la fecha TRIBUTARIA, la que decide el período del IVA, no el instante en que se creó el registro (ese es `created_at`, y puede caer en otro día)." }, "documento_disponible": { "type": "boolean", "description": "`true` = hay XML firmado y `/dtes/{id}/pdf|xml|pdf-url` responden. Distingue “existe y se puede bajar” de “existe pero aún no está firmado”, sin gastar un request en un 409." }, "created_at": { "type": "string", "description": "Instante ISO-8601 en que Notta registró el documento." }, "receptor_estado": { "type": "string", "enum": [ "reclamado", "aceptado", "en_plazo", "aceptado_tacito", "sin_info" ], "description": "Qué hizo TU CLIENTE con el documento. NO es `sii_status`: el SII puede haberlo aceptado (`EPR`) y el receptor reclamarlo igual: son dos máquinas de estado distintas. Se decide en este orden, el mismo que aplica el servidor: (1) `reclamado`: el receptor lo reclamó ante el SII; es un HECHO registrado y es IRREVERSIBLE: no existe forma de deshacerlo por esta API ni por el portal, y la salida comercial es emitir una nota de crédito. (2) `aceptado`: el receptor otorgó recibo, o el SII informó que el plazo se cumplió sin reclamo; también es un hecho registrado. (3) `en_plazo`: todavía corre la ventana, y cierra en el instante que indica `plazo_reclamo_cierra`. (4) `aceptado_tacito`: esa ventana ya cerró sin reclamo (Ley 19.983). (5) `sin_info`: el SII aún no informó `fecha_recepcion_sii`, así que el plazo no empezó a correr y no se sabe nada del receptor; NO significa que no haya respondido. Los tres últimos se DERIVAN contra el instante del request y cambian solos con el reloj: no los caches." }, "receptor_reclamado_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`YYYY-MM-DD` del reclamo, tal como lo informa el registro del SII. `null` = no hay reclamo registrado, o el reclamo llegó sólo como código y sin su fecha (mira `receptor_estado`, que es el campo que decide). Un `null` aquí nunca significa por sí solo que el cliente no haya reclamado." }, "receptor_acuse_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`YYYY-MM-DD` del acuse de recibo del receptor. `null` = no lo otorgó, o llegó sin fecha. Igual que su hermano, no es el campo con el que se decide: ése es `receptor_estado`." }, "fecha_recepcion_sii": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Instante ISO-8601 (con hora) en que el SII recibió el documento y lo dejó a disposición del receptor. Es el ANCLA del plazo de reclamo: `fecha_emision` NO lo ancla, y contar desde ahí ya fechó un vencimiento cuatro días antes de tiempo. `null` = el SII todavía no lo informó (por eso el plazo no corre y `receptor_estado` vale `sin_info`); se puebla solo cuando el registro del SII lo entrega." }, "plazo_reclamo_cierra": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Instante ISO-8601 EXACTO en que el receptor pierde el derecho a reclamar: `fecha_recepcion_sii` + 192 horas (Ley 19.983, Art. 3). Es una HORA, no un día de calendario: el SII cuenta fecha-hora a fecha-hora y a partir de ese instante rechaza el reclamo, así que tratar el día entero como disponible le regala al receptor horas que ya no tiene. `null` cuando no hay ancla (`fecha_recepcion_sii` en `null`): sin fecha de recepción no hay plazo que calcular, y una fecha derivada de `fecha_emision` sería sencillamente errónea. Este plazo corre contra el RECEPTOR; al emisor no le abre ninguna ventana ni le exige ninguna acción." }, "references": { "type": "array", "items": { "type": "object", "properties": { "line_num": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "`` del XML: identidad de la línea dentro del documento. Admite saltos." }, "tipo_doc_ref": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "Código SII del documento referenciado (correctiva) o el string original (comercial)." }, "folio_ref": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "Folio del documento referenciado. Número en una referencia correctiva (la NC o ND sobre un DTE) y puede venir como texto en una comercial, donde el identificador es el del documento de origen (una orden de compra, un contrato)." }, "fecha_ref": { "type": "string", "description": "``: fecha del documento REFERENCIADO, no la de éste. Desambigua cuando el mismo (tipo, folio) existe en más de un período: el folio se reinicia por emisor y por ambiente." }, "cod_ref": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "1 anula · 2 corrige texto · 3 corrige montos · null = referencia comercial" }, "razon_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "``: texto libre con el motivo de la referencia. null si no se declaró." } }, "required": [ "line_num", "tipo_doc_ref", "folio_ref", "fecha_ref", "cod_ref", "razon_ref" ], "additionalProperties": false, "description": "Una referencia a otro documento: que documento corrige, anula o cita este." }, "description": "`` del documento: correctivas (NC/ND) y comerciales (orden de compra…). Un documento sin referencias trae `[]`, nunca `null`." }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "Ruta de este documento: `GET /api/v1/dtes/{id}`." } }, "required": [ "self" ], "additionalProperties": false, "description": "Rutas relativas bajo `/api/v1` para seguir este documento." } }, "required": [ "id", "folio", "tipo_dte", "rut_emisor", "rut_receptor", "razon_social_receptor", "monto_neto", "monto_exento", "iva", "monto_total", "sii_status", "estado", "sii_glosa", "track_id", "sii_env", "sii_last_polled", "forma_pago", "fecha_emision", "documento_disponible", "created_at", "receptor_estado", "receptor_reclamado_at", "receptor_acuse_at", "fecha_recepcion_sii", "plazo_reclamo_cierra", "references", "links" ], "additionalProperties": false, "description": "Un documento del listado, en su version resumida. El detalle completo se pide con notta.dte.obtener." }, "description": "Documentos de esta página, en el orden que piden `sort` y `dir`." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor de la página siguiente: pásalo tal cual en `?cursor=`, sin cambiar `sort` ni `dir`. `null` = ya estás en la última página." } }, "required": [ "data", "next_cursor" ], "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_credential_required` | 428 | no | Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior. | | `connection_busy` | 409 | sí | Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez. | | `upstream_error` | 502 | sí | Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración. | | `timeout` | 504 | sí | Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo. | 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).