Consultar documentos respaldados del SII

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "description": "Período tributario AAAA-MM. Sin él, la respuesta cruza períodos y 'sincronizacion' llega null.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}$"
    },
    "perspectiva": {
      "description": "emitidos = la empresa es el emisor; recibidos = es el receptor.",
      "type": "string",
      "enum": [
        "emitidos",
        "recibidos"
      ]
    },
    "tipoDte": {
      "description": "Filtra por tipo de documento: 33, 34, 46, 52, 56 o 61. El portal no respalda boletas (39/41).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "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": {
          "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ó <MntNeto>: 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ó <IVA>, 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."
          }
        },
        "required": [
          "tipoDte",
          "folio",
          "rutEmisor",
          "rutReceptor",
          "razonSocialContraparte",
          "perspectiva",
          "periodo",
          "fechaEmision",
          "montoNeto",
          "iva",
          "montoTotal",
          "estado",
          "dteHash",
          "ultimaLecturaEn"
        ],
        "additionalProperties": false
      },
      "description": "Los documentos respaldados que calzan con el filtro, sólo con sus columnas de cabecera. Ni el XML ni el detalle de ítems viaja aquí: para eso usa 'sii.documentos.detallar'."
    },
    "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
}