Consultar boletas electrónicas 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."
    },
    "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": {
          "period": {
            "type": "string",
            "description": "El período tributario del agregado, en formato AAAA-MM."
          },
          "documentType": {
            "type": "string",
            "description": "Tipo de boleta, como texto: '39' es la boleta afecta y '41' la exenta."
          },
          "day": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "El día del mes que resume esta fila. Cada fila es el agregado de un día y un tipo de boleta, nunca una boleta individual."
          },
          "date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El mismo día en formato AAAA-MM-DD, o 'null' si el SII mandó un día fuera de rango."
          },
          "totalDocumentos": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuántas boletas de ese tipo se emitieron ese día. 'null' significa que el SII no informó el conteo, distinto de un 0 informado."
          },
          "netAmount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Monto neto del día en pesos chilenos, entero."
          },
          "exemptAmount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Monto exento del día en pesos chilenos, entero."
          },
          "vatAmount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "IVA del día en pesos chilenos, entero."
          },
          "totalAmount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Monto total del día en pesos chilenos, entero."
          },
          "currency": {
            "type": "string",
            "description": "Siempre 'CLP': este resumen del SII sólo viene en pesos chilenos."
          },
          "channel": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Canal de venta: 'presencial' o 'internet'. 'null' cuando el SII no desglosa por canal, que es lo habitual en boletas 39 y 41."
          }
        },
        "required": [
          "period",
          "documentType",
          "day",
          "date",
          "totalDocumentos",
          "netAmount",
          "exemptAmount",
          "vatAmount",
          "totalAmount",
          "currency",
          "channel"
        ],
        "additionalProperties": false
      },
      "description": "El resumen diario de boletas electrónicas que calza con el filtro. Cada fila es el agregado de un día y un tipo de boleta (39 afecta, 41 exenta), nunca una boleta individual. Los montos son enteros en pesos chilenos, y un monto que el SII no informó llega como 0, no como 'null'."
    },
    "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
}