Consultar guías de despacho del SII

{
  "$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
    }
  }
}

{
  "$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ó."
          },
          "fechaEmisionDate": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "x-emisso-formato": "AAAA-MM-DD",
            "description": "La misma fecha de emisión en formato AAAA-MM-DD, o null si no se pudo parsear. Es un día calendario sin zona horaria: compáralo como texto o con Date.UTC, porque new Date('2026-09-07') es medianoche UTC y en Chile se muestra como el 6. Es el campo que conviene usar para ordenar y filtrar."
          },
          "fechaEmision": {
            "type": "string",
            "deprecated": true,
            "x-emisso-formato": "DD/MM/AAAA",
            "x-emisso-canonico": "fechaEmisionDate",
            "x-emisso-admite-vacio": false,
            "description": "No la pases por new Date(). Es la fecha tal cual la manda el SII, en formato chileno DD/MM/AAAA. JavaScript la lee como MM/DD: '07/09/2026' te da el 9 de julio y '28/08/2026' te da Invalid Date. Usa 'fechaEmisionDate': AAAA-MM-DD, null cuando no se pudo parsear. Es un día calendario sin zona horaria: compáralo como texto o con Date.UTC, porque new Date('2026-09-07') es medianoche UTC y en Chile se muestra como el 6."
          },
          "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",
          "fechaEmisionDate",
          "fechaEmision",
          "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 cargó entero. 'false' = quedaron casillas sin traer. 'null' = se está cargando o 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 en esa sincronización, con su código de error. La pueblan las guías de despacho y las 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. Con 'periodo', 'null' y una lista vacía significa que ese mes no está cargado: dilo, no lo informes como cero (revisa 'historico' en 'conexiones.estado.consultar'). Sin 'periodo' siempre es 'null': usa ese bloque para saber qué meses hay."
    }
  },
  "required": [
    "documentos",
    "cursor",
    "sincronizacion"
  ],
  "additionalProperties": false
}