Consultar boletas de honorarios 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, donde esta empresa es el agente retenedor. 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": {
          "folio": {
            "type": "string",
            "description": "El número de la boleta, tal cual lo manda el SII y como texto: puede traer ceros a la izquierda o no ser numérico, y no se normaliza."
          },
          "perspectiva": {
            "type": "string",
            "enum": [
              "emitidas",
              "recibidas"
            ],
            "description": "emitidas = las boletas que emitió esta empresa; recibidas = las que le emitieron, donde esta empresa es el agente retenedor."
          },
          "periodo": {
            "type": "string",
            "description": "El período tributario de la boleta, en formato AAAA-MM."
          },
          "fechaBoleta": {
            "type": "string",
            "description": "La fecha de la boleta tal cual la manda el SII, en formato DD/MM/AAAA. Para ordenar o comparar usa 'fechaBoletaDate'."
          },
          "fechaBoletaDate": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La misma fecha en formato AAAA-MM-DD, o 'null' si no se pudo parsear."
          },
          "razonSocialContraparte": {
            "type": "string",
            "description": "El nombre o razón social del otro lado: en 'recibidas' es el profesional que emitió, en 'emitidas' es el receptor."
          },
          "codigoBarras": {
            "type": "string",
            "description": "El código de barras con que el SII identifica la boleta. Es único por boleta dentro del informe."
          },
          "honorariosBrutos": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "El honorario bruto en pesos chilenos: lo facturado antes de descontar la retención."
          },
          "retencionEmisor": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "La retención declarada por el propio emisor, en pesos chilenos. En 'recibidas' llega siempre en 0 porque ese informe no expone el campo: ahí la retención que importa es 'retencionReceptor'."
          },
          "retencionReceptor": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "La retención que hizo el receptor como agente retenedor, en pesos chilenos. Su suma es el insumo para cuadrar el código 151 del F29, no el código 151 en sí."
          },
          "honorariosLiquidos": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Lo que recibe el profesional: el bruto menos la retención, en pesos chilenos."
          },
          "estado": {
            "type": "string",
            "description": "El código de estado tal cual lo manda el SII: 'N' vigente, 'S' anulada, 'V' anulación pendiente, 'R' y 'U' observadas. El filtro tributario correcto es 'estado' distinto de 'S', porque 'V', 'R' y 'U' siguen vigentes."
          },
          "estadoNormalizado": {
            "type": "string",
            "enum": [
              "vigente",
              "anulada",
              "vigente_anulacion_pendiente",
              "observada_receptor",
              "observada_unidad",
              "desconocido"
            ],
            "description": "El mismo estado traducido a un enum estable. No lo uses para filtrar lo vigente: 'vigente_anulacion_pendiente', 'observada_receptor' y 'observada_unidad' también lo están. Un código que no reconocemos sale 'desconocido' y nunca se omite de un cómputo."
          },
          "esSocProfesional": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Si el emisor es una sociedad de profesionales, tal cual lo manda el SII. Es texto crudo, no un booleano, y puede venir 'null'."
          },
          "fechaEventoEstado": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo el SII registró el evento que dejó la boleta en su estado actual. Cubre anulación, solicitud de anulación y observación, no sólo la anulación. 'null' mientras no hubo evento."
          },
          "fechaEventoEstadoDate": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La misma fecha en formato AAAA-MM-DD, o 'null' si no vino o no se pudo parsear."
          },
          "rutContraparte": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El RUT del otro lado: en 'recibidas' es el profesional que emitió y en 'emitidas' es el receptor. 'null' cuando la boleta se emitió sin receptor, que el SII permite."
          },
          "ultimaLecturaEn": {
            "type": "string",
            "description": "Cuándo se observó esta fila por última vez, en ISO 8601 UTC. Una boleta de honorarios es mutable hasta el 1 de marzo del año siguiente: si esta marca es vieja, resincroniza el período antes de decidir sobre su estado."
          }
        },
        "required": [
          "folio",
          "perspectiva",
          "periodo",
          "fechaBoleta",
          "fechaBoletaDate",
          "razonSocialContraparte",
          "codigoBarras",
          "honorariosBrutos",
          "retencionEmisor",
          "retencionReceptor",
          "honorariosLiquidos",
          "estado",
          "estadoNormalizado",
          "esSocProfesional",
          "fechaEventoEstado",
          "fechaEventoEstadoDate",
          "rutContraparte",
          "ultimaLecturaEn"
        ],
        "additionalProperties": false
      },
      "description": "Las boletas de honorarios que calzan con el filtro, una por fila. Sale de la caché ya sincronizada, nunca de una consulta en vivo al SII."
    },
    "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
}