{
  "openapi": "3.1.0",
  "info": {
    "title": "Vintu API pública",
    "description": "API REST de solo lectura para llevar a tus sistemas los comprobantes, avisos de buzón y vencimientos que Vintu ya tiene de tus empresas.\n\n- Autenticación con clave de API en `Authorization: Bearer vk_live_…`. La creas en `app.vintu.io`, Configuración → API y webhooks; se muestra una sola vez.\n- Campos en español; importes como cadenas decimales con punto (`1180.00`); instantes ISO 8601 con zona horaria.\n- Paginación por cursor; `actualizado_desde` permite sincronizar solo lo cambiado.\n- Una clave revocada deja de funcionar en un máximo de 60 segundos, incluidos los enlaces de archivo que ya hubiera emitido.\n- No se exponen datos que entraron por Gmail ni de origen desconocido.\n- Retirar un campo requiere aviso de seis meses.",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://api.vintu.io",
      "description": "Producción"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Salud"
        ],
        "summary": "Comprobar que el proceso responde",
        "description": "No consulta dependencias ni requiere clave.",
        "operationId": "salud",
        "responses": {
          "200": {
            "description": "El proceso responde.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "tags": [
          "Salud"
        ],
        "summary": "Comprobar que el servicio puede atender",
        "description": "Consulta el servicio de datos y la coordinación. No requiere clave.",
        "operationId": "disponibilidad",
        "responses": {
          "200": {
            "description": "Listo para atender.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadyStatus"
                }
              }
            }
          },
          "503": {
            "description": "El servicio de datos no responde.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadyStatus"
                }
              }
            }
          }
        }
      }
    },
    "/v1/cuenta": {
      "get": {
        "tags": [
          "Cuenta"
        ],
        "summary": "Ver la cuenta, sus límites y su uso",
        "description": "Sirve cualquier clave válida, tenga los permisos que tenga. Úsala para comprobar una clave nueva y para conocer los límites que aplican a tu cuenta.",
        "operationId": "obtener_cuenta",
        "responses": {
          "200": {
            "description": "Correcto.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                },
                "examples": {
                  "cuenta": {
                    "summary": "Cuenta de ejemplo: los límites de tu cuenta los devuelve esta operación",
                    "value": {
                      "id": "00000000-0000-4000-8000-0000000000a1",
                      "plan": "contador",
                      "limites": {
                        "api_rpm": 100,
                        "concurrency": 5,
                        "max_api_keys": 3,
                        "max_webhooks": 3
                      },
                      "uso": {
                        "solicitudes": 1520,
                        "errores": 4,
                        "subidas": 0
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "x-vintu-permisos": []
      }
    },
    "/v1/empresas": {
      "get": {
        "tags": [
          "Empresas"
        ],
        "summary": "Listar empresas",
        "description": "Empresas de la cuenta, de la más antigua a la más reciente.",
        "operationId": "listar_empresas",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "minimum": 1,
              "description": "Elementos por página, de 1 a 100.",
              "default": 25,
              "title": "Limite"
            },
            "description": "Elementos por página, de 1 a 100."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 4096
                },
                {
                  "type": "null"
                }
              ],
              "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas.",
              "title": "Cursor"
            },
            "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas."
          },
          {
            "name": "actualizado_desde",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`.",
              "title": "Actualizado Desde"
            },
            "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page_Company_"
                },
                "examples": {
                  "pagina": {
                    "summary": "Una página",
                    "value": {
                      "datos": [
                        {
                          "id": "00000000-0000-4000-8000-0000000000c1",
                          "ruc": "20000000002",
                          "razon_social": "Comercial Ejemplo S.A.C.",
                          "creado_en": "2026-11-10T14:32:05.120000+00:00",
                          "actualizado_en": "2026-11-10T14:32:05.120000+00:00"
                        }
                      ],
                      "siguiente_cursor": "CURSOR_DE_EJEMPLO",
                      "marca_superior": "2026-11-12T09:15:41.004000+00:00"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "empresas:leer"
        ]
      }
    },
    "/v1/empresas/{id}": {
      "get": {
        "tags": [
          "Empresas"
        ],
        "summary": "Ver una empresa",
        "description": "Una empresa de la cuenta por su `id`.",
        "operationId": "obtener_empresa",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Identificador público del recurso.",
              "title": "Id"
            },
            "description": "Identificador público del recurso."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                },
                "examples": {
                  "empresa": {
                    "summary": "Una empresa",
                    "value": {
                      "id": "00000000-0000-4000-8000-0000000000c1",
                      "ruc": "20000000002",
                      "razon_social": "Comercial Ejemplo S.A.C.",
                      "creado_en": "2026-11-10T14:32:05.120000+00:00",
                      "actualizado_en": "2026-11-10T14:32:05.120000+00:00"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "El recurso no existe o no es de esta cuenta (`NOT_FOUND`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "empresas:leer"
        ]
      }
    },
    "/v1/comprobantes": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Listar comprobantes",
        "description": "Comprobantes recibidos por correo, WhatsApp o Drive, del más antiguo al más reciente. Los importes llegan como cadenas decimales; `archivo_url` permite descargar el original durante una hora.",
        "operationId": "listar_comprobantes",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "minimum": 1,
              "description": "Elementos por página, de 1 a 100.",
              "default": 25,
              "title": "Limite"
            },
            "description": "Elementos por página, de 1 a 100."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 4096
                },
                {
                  "type": "null"
                }
              ],
              "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas.",
              "title": "Cursor"
            },
            "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas."
          },
          {
            "name": "empresa_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "uuid"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo los de esta empresa (su `id`).",
              "title": "Empresa Id"
            },
            "description": "Solo los de esta empresa (su `id`)."
          },
          {
            "name": "actualizado_desde",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`.",
              "title": "Actualizado Desde"
            },
            "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page_Document_"
                },
                "examples": {
                  "pagina": {
                    "summary": "Una página",
                    "value": {
                      "datos": [
                        {
                          "id": "00000000-0000-4000-8000-0000000000d1",
                          "empresa_id": "00000000-0000-4000-8000-0000000000c1",
                          "tipo": "factura",
                          "serie": "F001",
                          "numero": "1234",
                          "ruc_emisor": "20000000003",
                          "fecha_emision": "2026-11-09",
                          "moneda": "PEN",
                          "base_imponible": "1000.00",
                          "igv": "180.00",
                          "total": "1180.00",
                          "estado": "extraido",
                          "creado_en": "2026-11-10T14:32:05.120000+00:00",
                          "actualizado_en": "2026-11-12T09:15:41.004000+00:00",
                          "archivo_url": "https://api.vintu.io/v1/archivos/ENLACE_DE_EJEMPLO"
                        }
                      ],
                      "siguiente_cursor": "CURSOR_DE_EJEMPLO",
                      "marca_superior": "2026-11-12T09:15:41.004000+00:00"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "comprobantes:leer"
        ]
      }
    },
    "/v1/comprobantes/{id}": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Ver un comprobante",
        "description": "Un comprobante por su `id`, con un enlace de descarga nuevo.",
        "operationId": "obtener_comprobante",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Identificador público del recurso.",
              "title": "Id"
            },
            "description": "Identificador público del recurso."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "examples": {
                  "comprobante": {
                    "summary": "Un comprobante",
                    "value": {
                      "id": "00000000-0000-4000-8000-0000000000d1",
                      "empresa_id": "00000000-0000-4000-8000-0000000000c1",
                      "tipo": "factura",
                      "serie": "F001",
                      "numero": "1234",
                      "ruc_emisor": "20000000003",
                      "fecha_emision": "2026-11-09",
                      "moneda": "PEN",
                      "base_imponible": "1000.00",
                      "igv": "180.00",
                      "total": "1180.00",
                      "estado": "extraido",
                      "creado_en": "2026-11-10T14:32:05.120000+00:00",
                      "actualizado_en": "2026-11-12T09:15:41.004000+00:00",
                      "archivo_url": "https://api.vintu.io/v1/archivos/ENLACE_DE_EJEMPLO"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "El recurso no existe o no es de esta cuenta (`NOT_FOUND`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "comprobantes:leer"
        ]
      }
    },
    "/v1/avisos": {
      "get": {
        "tags": [
          "Avisos"
        ],
        "summary": "Listar avisos de buzón",
        "description": "Notificaciones leídas de los buzones SUNAT y SUNAFIL de tus empresas, de la más antigua a la más reciente.",
        "operationId": "listar_avisos",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "minimum": 1,
              "description": "Elementos por página, de 1 a 100.",
              "default": 25,
              "title": "Limite"
            },
            "description": "Elementos por página, de 1 a 100."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 4096
                },
                {
                  "type": "null"
                }
              ],
              "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas.",
              "title": "Cursor"
            },
            "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas."
          },
          {
            "name": "empresa_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "uuid"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo los de esta empresa (su `id`).",
              "title": "Empresa Id"
            },
            "description": "Solo los de esta empresa (su `id`)."
          },
          {
            "name": "actualizado_desde",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`.",
              "title": "Actualizado Desde"
            },
            "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page_Notice_"
                },
                "examples": {
                  "pagina": {
                    "summary": "Una página",
                    "value": {
                      "datos": [
                        {
                          "id": "00000000-0000-4000-8000-0000000000e1",
                          "empresa_id": "00000000-0000-4000-8000-0000000000c1",
                          "entidad": "sunat",
                          "buzon": "notificaciones",
                          "tipo": "VALORES",
                          "asunto": "Notificación de ejemplo",
                          "fecha_notificacion": "2026-11-11T13:00:00+00:00",
                          "creado_en": "2026-11-10T14:32:05.120000+00:00",
                          "actualizado_en": "2026-11-10T14:32:05.120000+00:00"
                        }
                      ],
                      "siguiente_cursor": "CURSOR_DE_EJEMPLO",
                      "marca_superior": "2026-11-12T09:15:41.004000+00:00"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "avisos:leer"
        ]
      }
    },
    "/v1/avisos/{id}": {
      "get": {
        "tags": [
          "Avisos"
        ],
        "summary": "Ver un aviso de buzón",
        "description": "Un aviso por su `id`.",
        "operationId": "obtener_aviso",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Identificador público del recurso.",
              "title": "Id"
            },
            "description": "Identificador público del recurso."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Notice"
                },
                "examples": {
                  "aviso": {
                    "summary": "Un aviso",
                    "value": {
                      "id": "00000000-0000-4000-8000-0000000000e1",
                      "empresa_id": "00000000-0000-4000-8000-0000000000c1",
                      "entidad": "sunat",
                      "buzon": "notificaciones",
                      "tipo": "VALORES",
                      "asunto": "Notificación de ejemplo",
                      "fecha_notificacion": "2026-11-11T13:00:00+00:00",
                      "creado_en": "2026-11-10T14:32:05.120000+00:00",
                      "actualizado_en": "2026-11-10T14:32:05.120000+00:00"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "El recurso no existe o no es de esta cuenta (`NOT_FOUND`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "avisos:leer"
        ]
      }
    },
    "/v1/vencimientos": {
      "get": {
        "tags": [
          "Vencimientos"
        ],
        "summary": "Listar próximos vencimientos",
        "description": "Vencimientos futuros de IGV y Renta mensual y de PLAME de cada empresa, según el cronograma general de SUNAT por último dígito del RUC. No incluye regímenes con fechas propias ni la Renta anual.",
        "operationId": "listar_vencimientos",
        "security": [
          {
            "VintuApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "minimum": 1,
              "description": "Elementos por página, de 1 a 100.",
              "default": 25,
              "title": "Limite"
            },
            "description": "Elementos por página, de 1 a 100."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 4096
                },
                {
                  "type": "null"
                }
              ],
              "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas.",
              "title": "Cursor"
            },
            "description": "Valor de `siguiente_cursor` de la página anterior. Caduca a las 24 horas."
          },
          {
            "name": "empresa_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "uuid"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo los de esta empresa (su `id`).",
              "title": "Empresa Id"
            },
            "description": "Solo los de esta empresa (su `id`)."
          },
          {
            "name": "actualizado_desde",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`.",
              "title": "Actualizado Desde"
            },
            "description": "Solo lo creado o modificado desde este instante, ISO 8601 con zona horaria. Con este filtro el orden pasa a ser por `actualizado_en`."
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page_Deadline_"
                },
                "examples": {
                  "pagina": {
                    "summary": "Una página",
                    "value": {
                      "datos": [
                        {
                          "id": "00000000-0000-5000-8000-0000000000f1",
                          "empresa_id": "00000000-0000-4000-8000-0000000000c1",
                          "obligacion": "IGV_RENTA",
                          "fecha_vencimiento": "2026-12-16",
                          "periodo": "2026-11",
                          "creado_en": "2026-11-10T14:32:05.120000+00:00",
                          "actualizado_en": "2026-11-10T14:32:05.120000+00:00"
                        }
                      ],
                      "siguiente_cursor": "CURSOR_DE_EJEMPLO",
                      "marca_superior": "2026-11-12T09:15:41.004000+00:00"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Vintu-Mode": {
                "description": "`lectura_degradada` cuando la coordinación no responde y los límites se aplican por réplica.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Clave ausente, mal formada, inexistente o revocada (`INVALID_API_KEY`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "La clave no tiene el permiso de la operación (`SCOPE_REQUIRED`), el plan no incluye la API (`API_PLAN_REQUIRED`) o la cuenta no tiene acceso activo (`ACCESS_DENIED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Parámetro inválido (`VALIDATION_ERROR`), cursor de otra consulta (`INVALID_CURSOR`) o cursor caducado a las 24 horas (`CURSOR_EXPIRED`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "vencimientos:leer"
        ]
      }
    },
    "/v1/archivos/{token}": {
      "get": {
        "tags": [
          "Archivos"
        ],
        "summary": "Descargar el original de un comprobante",
        "description": "Usa la URL completa de `archivo_url`; no lleva la cabecera `Authorization`. El enlace vale una hora y deja de valer si se revoca la clave que lo obtuvo; entonces responde 401 `INVALID_FILE_TOKEN` y basta con volver a pedir el comprobante. Un archivo de más de 25 MiB responde 422 `FILE_TOO_LARGE` sin empezar a enviarse.",
        "operationId": "descargar_archivo",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Parte final de `archivo_url`.",
              "title": "Token"
            },
            "description": "Parte final de `archivo_url`."
          }
        ],
        "responses": {
          "200": {
            "description": "El archivo original, como adjunto.",
            "content": {
              "application/json": {
                "schema": {}
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "description": "Siempre `attachment`.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "401": {
            "description": "Enlace inválido, vencido o de una clave revocada (`INVALID_FILE_TOKEN`). Vuelve a pedir el comprobante para obtener uno nuevo.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "El recurso no existe o no es de esta cuenta (`NOT_FOUND`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "El archivo supera los 25 MiB (`FILE_TOO_LARGE`) o el enlace está mal formado (`VALIDATION_ERROR`).",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Se superó el límite de peticiones (`RATE_LIMITED`). Espera lo que indica `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Limit": {
                "description": "Peticiones por minuto admitidas.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Peticiones que quedan en la ventana.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos hasta que se recupera el cupo.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible temporalmente (`DEPENDENCY_UNAVAILABLE` o `LOCAL_CAPACITY`). Reintenta tras `Retry-After`.",
            "headers": {
              "X-Request-ID": {
                "description": "Identificador de la petición; cítalo al pedir soporte.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Segundos que conviene esperar antes de reintentar.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-vintu-permisos": [
          "comprobantes:leer"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Account": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id",
            "description": "Identificador público de la cuenta."
          },
          "plan": {
            "type": "string",
            "title": "Plan",
            "description": "Plan contratado."
          },
          "limites": {
            "$ref": "#/components/schemas/AccountLimits",
            "description": "Límites vigentes para esta cuenta."
          },
          "uso": {
            "$ref": "#/components/schemas/Usage"
          },
          "cuota_documentos": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Allowance"
              },
              {
                "type": "null"
              }
            ]
          },
          "creditos": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Allowance"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "id",
          "plan",
          "limites",
          "uso"
        ],
        "title": "Account"
      },
      "AccountLimits": {
        "properties": {
          "api_rpm": {
            "type": "integer",
            "maximum": 100000.0,
            "minimum": 1.0,
            "title": "Api Rpm",
            "description": "Peticiones por minuto que admite la cuenta."
          },
          "concurrency": {
            "type": "integer",
            "maximum": 5.0,
            "minimum": 1.0,
            "title": "Concurrency",
            "description": "Operaciones simultáneas por clave.",
            "default": 5
          },
          "max_api_keys": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Max Api Keys",
            "description": "Claves activas que admite la cuenta."
          },
          "max_webhooks": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Max Webhooks",
            "description": "Destinos de webhook que admitirá la cuenta cuando existan."
          }
        },
        "type": "object",
        "required": [
          "api_rpm",
          "max_api_keys",
          "max_webhooks"
        ],
        "title": "AccountLimits"
      },
      "Allowance": {
        "properties": {
          "limite": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Limite",
            "description": "Nulo si no hay límite."
          },
          "usados": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Usados"
          },
          "disponibles": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Disponibles",
            "description": "Nulo si no hay límite."
          },
          "renueva_en": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Renueva En",
            "description": "Próxima renovación."
          }
        },
        "type": "object",
        "required": [
          "usados"
        ],
        "title": "Allowance"
      },
      "Company": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id",
            "description": "Identificador público de la empresa."
          },
          "ruc": {
            "type": "string",
            "title": "Ruc",
            "description": "RUC de 11 dígitos."
          },
          "razon_social": {
            "type": "string",
            "title": "Razon Social",
            "description": "Razón social registrada en la cuenta."
          },
          "creado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Creado En",
            "description": "Alta de la empresa en Vintu."
          },
          "actualizado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Actualizado En",
            "description": "Último cambio de la empresa."
          }
        },
        "type": "object",
        "required": [
          "id",
          "ruc",
          "razon_social",
          "creado_en",
          "actualizado_en"
        ],
        "title": "Company"
      },
      "Deadline": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id",
            "description": "Identificador estable de la empresa y la obligación."
          },
          "empresa_id": {
            "type": "string",
            "format": "uuid",
            "title": "Empresa Id",
            "description": "Empresa cuyo RUC determina el vencimiento."
          },
          "obligacion": {
            "type": "string",
            "title": "Obligacion",
            "description": "`IGV_RENTA` o `PLAME`."
          },
          "fecha_vencimiento": {
            "type": "string",
            "format": "date",
            "title": "Fecha Vencimiento",
            "description": "Fecha límite según el cronograma de SUNAT."
          },
          "periodo": {
            "type": "string",
            "title": "Periodo",
            "description": "Periodo tributario en formato `AAAA-MM`."
          },
          "creado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Creado En",
            "description": "Alta del dato en Vintu."
          },
          "actualizado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Actualizado En",
            "description": "Último cambio del dato."
          }
        },
        "type": "object",
        "required": [
          "id",
          "empresa_id",
          "obligacion",
          "fecha_vencimiento",
          "periodo",
          "creado_en",
          "actualizado_en"
        ],
        "title": "Deadline"
      },
      "Document": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id",
            "description": "Identificador público del comprobante."
          },
          "empresa_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "title": "Empresa Id",
            "description": "Empresa a la que se atribuyó; nulo si aún no tiene."
          },
          "tipo": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tipo",
            "description": "`factura`, `boleta`, `recibo_honorarios`, `nota_credito`, `nota_debito`, `recibo_servicios`, `boleto_aereo` u `otro`; nulo si no se pudo leer."
          },
          "serie": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Serie",
            "description": "Serie del comprobante."
          },
          "numero": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Numero",
            "description": "Número correlativo, como texto."
          },
          "ruc_emisor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ruc Emisor",
            "description": "RUC de quien emitió el comprobante."
          },
          "fecha_emision": {
            "anyOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ],
            "title": "Fecha Emision",
            "description": "Fecha de emisión."
          },
          "moneda": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Moneda",
            "description": "Código de moneda, p. ej. `PEN`."
          },
          "base_imponible": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Base Imponible",
            "description": "Importe decimal como cadena, con punto: `1000.00`."
          },
          "igv": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Igv",
            "description": "Importe decimal como cadena, con punto: `180.00`."
          },
          "total": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Total",
            "description": "Importe decimal como cadena, con punto: `1180.00`."
          },
          "estado": {
            "type": "string",
            "title": "Estado",
            "description": "`recibido`, `extraido`, `requiere_revision`, `confirmado` o `descartado`. `confirmado` significa que el contador lo revisó."
          },
          "creado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Creado En",
            "description": "Llegada del comprobante a Vintu."
          },
          "actualizado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Actualizado En",
            "description": "Último cambio del comprobante."
          },
          "archivo_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Archivo Url",
            "description": "Enlace de descarga del original, válido 1 hora y ligado a la clave que lo pidió. No lleva la cabecera `Authorization`."
          }
        },
        "type": "object",
        "required": [
          "id",
          "estado",
          "creado_en",
          "actualizado_en"
        ],
        "title": "Document"
      },
      "ErrorDetails": {
        "properties": {
          "codigo": {
            "type": "string",
            "enum": [
              "INVALID_API_KEY",
              "FORBIDDEN",
              "NOT_FOUND",
              "CONFLICT",
              "VALIDATION_ERROR",
              "INVALID_CURSOR",
              "CURSOR_EXPIRED",
              "INVALID_FILE_TOKEN",
              "RATE_LIMITED",
              "DEPENDENCY_UNAVAILABLE",
              "COORDINATION_UNAVAILABLE",
              "LOCAL_CAPACITY",
              "REQUEST_REJECTED",
              "SCOPE_REQUIRED",
              "API_PLAN_REQUIRED",
              "ACCESS_DENIED",
              "FILE_TOO_LARGE"
            ],
            "title": "Codigo",
            "description": "Código estable del error; compara contra este valor, no contra el mensaje. `FORBIDDEN` solo aparece si el motivo no es uno de los tres específicos (`SCOPE_REQUIRED`, `API_PLAN_REQUIRED`, `ACCESS_DENIED`). `CONFLICT` y `COORDINATION_UNAVAILABLE` solo aplican a escrituras, que v1 aún no tiene."
          },
          "mensaje": {
            "type": "string",
            "title": "Mensaje",
            "description": "Explicación en español para personas; puede cambiar."
          },
          "id_peticion": {
            "type": "string",
            "format": "uuid",
            "title": "Id Peticion",
            "description": "Identificador de la petición; coincide con la cabecera `X-Request-ID`."
          }
        },
        "type": "object",
        "required": [
          "codigo",
          "mensaje",
          "id_peticion"
        ],
        "title": "ErrorDetails"
      },
      "ErrorEnvelope": {
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetails"
          }
        },
        "type": "object",
        "required": [
          "error"
        ],
        "title": "ErrorEnvelope"
      },
      "HealthStatus": {
        "properties": {
          "estado": {
            "type": "string",
            "const": "ok",
            "title": "Estado"
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Versión de la pasarela."
          }
        },
        "type": "object",
        "required": [
          "estado",
          "version"
        ],
        "title": "HealthStatus"
      },
      "Notice": {
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id",
            "description": "Identificador público del aviso."
          },
          "empresa_id": {
            "type": "string",
            "format": "uuid",
            "title": "Empresa Id",
            "description": "Empresa a la que llegó el aviso."
          },
          "entidad": {
            "type": "string",
            "title": "Entidad",
            "description": "`sunat` o `sunafil`."
          },
          "buzon": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Buzon",
            "description": "Buzón de origen: `notificaciones` o `mensajes` en SUNAT; `fiscalizacion`, `cobranza`, `acciones_previas`, `formalizacion`, `sst` u `orientaciones` en SUNAFIL. Nulo en avisos antiguos que no lo registraron."
          },
          "tipo": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tipo",
            "description": "Tipo de notificación tal como lo clasifica el buzón."
          },
          "asunto": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Asunto",
            "description": "Asunto del aviso."
          },
          "fecha_notificacion": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Fecha Notificacion",
            "description": "Fecha en que la entidad lo notificó; nula si no la publica."
          },
          "creado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Creado En",
            "description": "Primera vez que Vintu lo leyó."
          },
          "actualizado_en": {
            "type": "string",
            "format": "date-time",
            "title": "Actualizado En",
            "description": "Último cambio del aviso."
          }
        },
        "type": "object",
        "required": [
          "id",
          "empresa_id",
          "entidad",
          "creado_en",
          "actualizado_en"
        ],
        "title": "Notice"
      },
      "Page_Company_": {
        "properties": {
          "datos": {
            "items": {
              "$ref": "#/components/schemas/Company"
            },
            "type": "array",
            "title": "Datos",
            "description": "Elementos de esta página."
          },
          "siguiente_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Siguiente Cursor",
            "description": "Pásalo en `cursor` para pedir la página siguiente; nulo en la última. Caduca a las 24 horas y solo vale para la misma consulta."
          },
          "marca_superior": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Marca Superior",
            "description": "Instante en que empezó el recorrido; lo que cambie después no entra en él. Úsalo como `actualizado_desde` de la sincronización siguiente; como ese filtro incluye el propio instante, deduplica por `id`."
          }
        },
        "type": "object",
        "required": [
          "datos"
        ],
        "title": "Page[Company]"
      },
      "Page_Deadline_": {
        "properties": {
          "datos": {
            "items": {
              "$ref": "#/components/schemas/Deadline"
            },
            "type": "array",
            "title": "Datos",
            "description": "Elementos de esta página."
          },
          "siguiente_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Siguiente Cursor",
            "description": "Pásalo en `cursor` para pedir la página siguiente; nulo en la última. Caduca a las 24 horas y solo vale para la misma consulta."
          },
          "marca_superior": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Marca Superior",
            "description": "Instante en que empezó el recorrido; lo que cambie después no entra en él. Úsalo como `actualizado_desde` de la sincronización siguiente; como ese filtro incluye el propio instante, deduplica por `id`."
          }
        },
        "type": "object",
        "required": [
          "datos"
        ],
        "title": "Page[Deadline]"
      },
      "Page_Document_": {
        "properties": {
          "datos": {
            "items": {
              "$ref": "#/components/schemas/Document"
            },
            "type": "array",
            "title": "Datos",
            "description": "Elementos de esta página."
          },
          "siguiente_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Siguiente Cursor",
            "description": "Pásalo en `cursor` para pedir la página siguiente; nulo en la última. Caduca a las 24 horas y solo vale para la misma consulta."
          },
          "marca_superior": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Marca Superior",
            "description": "Instante en que empezó el recorrido; lo que cambie después no entra en él. Úsalo como `actualizado_desde` de la sincronización siguiente; como ese filtro incluye el propio instante, deduplica por `id`."
          }
        },
        "type": "object",
        "required": [
          "datos"
        ],
        "title": "Page[Document]"
      },
      "Page_Notice_": {
        "properties": {
          "datos": {
            "items": {
              "$ref": "#/components/schemas/Notice"
            },
            "type": "array",
            "title": "Datos",
            "description": "Elementos de esta página."
          },
          "siguiente_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Siguiente Cursor",
            "description": "Pásalo en `cursor` para pedir la página siguiente; nulo en la última. Caduca a las 24 horas y solo vale para la misma consulta."
          },
          "marca_superior": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "title": "Marca Superior",
            "description": "Instante en que empezó el recorrido; lo que cambie después no entra en él. Úsalo como `actualizado_desde` de la sincronización siguiente; como ese filtro incluye el propio instante, deduplica por `id`."
          }
        },
        "type": "object",
        "required": [
          "datos"
        ],
        "title": "Page[Notice]"
      },
      "ReadyStatus": {
        "properties": {
          "estado": {
            "type": "string",
            "enum": [
              "ok",
              "no_disponible"
            ],
            "title": "Estado"
          },
          "cps": {
            "type": "boolean",
            "title": "Cps",
            "description": "Si el servicio de datos responde."
          },
          "redis": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Redis",
            "description": "Si la coordinación responde."
          },
          "modo": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "completo",
                  "lectura_degradada"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Modo",
            "description": "`lectura_degradada`: los límites se aplican por réplica, más estrictos."
          }
        },
        "type": "object",
        "required": [
          "estado",
          "cps"
        ],
        "title": "ReadyStatus"
      },
      "Usage": {
        "properties": {
          "solicitudes": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Solicitudes",
            "description": "Peticiones del mes en curso (UTC)."
          },
          "errores": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Errores",
            "description": "Peticiones con error del mes en curso (UTC)."
          },
          "subidas": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Subidas",
            "description": "Comprobantes subidos por API este mes."
          }
        },
        "type": "object",
        "required": [
          "solicitudes",
          "errores",
          "subidas"
        ],
        "title": "Usage"
      }
    },
    "securitySchemes": {
      "VintuApiKey": {
        "type": "http",
        "description": "Clave de API con formato `vk_live_<8 caracteres>_<32 caracteres>` en la cabecera `Authorization: Bearer`. No existen claves de prueba.",
        "scheme": "bearer",
        "bearerFormat": "vk_live_…"
      }
    }
  },
  "tags": [
    {
      "name": "Cuenta",
      "description": "Plan, límites y uso de la cuenta dueña de la clave."
    },
    {
      "name": "Empresas",
      "description": "Empresas (RUC) registradas en la cuenta."
    },
    {
      "name": "Comprobantes",
      "description": "Comprobantes recibidos por correo, WhatsApp o Drive y extraídos."
    },
    {
      "name": "Avisos",
      "description": "Notificaciones de los buzones SUNAT y SUNAFIL."
    },
    {
      "name": "Vencimientos",
      "description": "Próximos vencimientos tributarios según el último dígito del RUC."
    },
    {
      "name": "Archivos",
      "description": "Descarga del original de un comprobante."
    },
    {
      "name": "Salud",
      "description": "Estado del servicio; no requieren clave."
    }
  ]
}
