{
  "openapi": "3.0.3",
  "info": {
    "title": "API Facturador Electrónico",
    "version": "1.0.0",
    "description": "API para integrar tu sistema con el facturador electrónico: emitir facturas, boletas, notas de crédito y débito, guías de remisión, retenciones y percepciones, anularlas, consultar su estado en SUNAT y descargar el PDF, XML y CDR.\n\n## Antes de empezar\n\n1. **URL de tu empresa.** Cada empresa tiene su propia dirección, por ejemplo `https://miempresa.tudominio.com`. Ponla en el selector de servidor (botón *Servers*), sin `/` al final.\n2. **Token.** Ejecuta **1. Inicio → Obtener token** con tu usuario y contraseña. Copia el `token` y pégalo en el botón *Authorize*. También puedes copiarlo desde el facturador: **Configuración → Usuarios**, campo `api_token`.\n3. **Series.** Las series (`F001`, `B001`, `T001`, …) deben estar creadas en el facturador para tu establecimiento.\n\n## Cómo se envía cada request\n\n- Cabeceras: `Authorization: Bearer <token>`, `Content-Type: application/json` y `Accept: application/json`.\n- Los campos de comprobantes, guías, retenciones y percepciones van en español (`serie_documento`, `items`, …). Notas de venta, cotizaciones, clientes y productos usan los nombres del facturador en inglés.\n- Montos con punto decimal y hasta 2 decimales (ej. `118.00`).\n- Fechas `AAAA-MM-DD` y horas `HH:MM:SS`, salvo donde se indique otro formato.\n\n## Flujo típico\n\n1. **Emitir** el comprobante (carpeta *Facturas*, *Boletas* o *Notas*). La respuesta trae `external_id`; la colección lo guarda solo en la variable `external_id`.\n2. **Facturas y notas:** se envían a SUNAT al emitirlas y la respuesta trae el resultado. **Boletas:** se envían en el resumen diario (carpeta *Resúmenes diarios*).\n3. **Descargar** el PDF, XML o CDR (carpeta *Descargas*) o usar los enlaces de `links`.\n4. **Anular** si hace falta (carpeta *Anulaciones*) y consultar el ticket hasta que SUNAT lo acepte.\n\n## Variables de la colección\n\n| Variable | Para qué sirve |\n|---|---|\n| `base_url` | URL de tu empresa. La completas tú. |\n| `token` | Token de acceso. Lo llena **Obtener token**. |\n| `external_id` | Último comprobante emitido. Lo llenan los requests de emisión. |\n| `external_id_guia` | Última guía emitida. |\n| `external_id_resumen` / `external_id_anulacion` | Último resumen y última anulación. |\n| `sale_note_id` / `item_id` | Última nota de venta y último producto creados. |\n| `fecha_hoy`, `hora_actual`, `fecha_hoy_dmy`, `fecha_vencimiento` | Se calculan solas antes de cada request para que los ejemplos usen la fecha del día (y hoy + 30 días para cuotas). |\n\n## Respuestas y errores\n\n- Correcto: `success: true` y los datos en `data`.\n- `400`: un dato no pasa la validación. El motivo va en `message`.\n- `401`: token inválido o ausente.\n- `422`: error de validación de campos; el detalle va en `errors`.\n- `500`: error al procesar o rechazo de SUNAT. El motivo va en `message`.\n\nCada request trae ejemplos de respuesta en la sección *Examples*."
  },
  "servers": [
    {
      "url": "{base_url}",
      "description": "URL de tu empresa",
      "variables": {
        "base_url": {
          "default": "https://miempresa.tudominio.com",
          "description": "URL de tu empresa, sin / al final"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Inicio"
    },
    {
      "name": "Comprobantes"
    },
    {
      "name": "Resúmenes y anulación de boletas"
    },
    {
      "name": "Anulación de facturas"
    },
    {
      "name": "Guías de remisión"
    },
    {
      "name": "Retenciones y percepciones"
    },
    {
      "name": "Notas de venta y cotizaciones"
    },
    {
      "name": "Clientes"
    },
    {
      "name": "Productos e inventario"
    },
    {
      "name": "Descargas"
    },
    {
      "name": "Consultas"
    },
    {
      "name": "Establecimientos"
    },
    {
      "name": "Series"
    },
    {
      "name": "Usuarios"
    },
    {
      "name": "Almacenes"
    },
    {
      "name": "Cuentas bancarias"
    },
    {
      "name": "Gastos e ingresos"
    },
    {
      "name": "Compras"
    },
    {
      "name": "Pedidos"
    },
    {
      "name": "Categorías y marcas"
    },
    {
      "name": "Conductores, vehículos y transportistas"
    },
    {
      "name": "Liquidaciones de compra"
    },
    {
      "name": "Caja"
    },
    {
      "name": "Pagos"
    },
    {
      "name": "Restaurante"
    },
    {
      "name": "Reportes"
    },
    {
      "name": "Configuración y empresa"
    },
    {
      "name": "Mensajería"
    },
    {
      "name": "Consignaciones y e-commerce"
    },
    {
      "name": "Catálogos"
    },
    {
      "name": "Flujo de caja"
    },
    {
      "name": "Suscripciones"
    },
    {
      "name": "Reportes en cola"
    },
    {
      "name": "Configuración SUNAT"
    },
    {
      "name": "SIRE"
    }
  ],
  "paths": {
    "/api/login": {
      "post": {
        "tags": [
          "Inicio"
        ],
        "summary": "Obtener token (login)",
        "operationId": "ObtenerTokenLogin",
        "description": "Inicia sesión con el correo y la contraseña de un usuario del facturador y devuelve su `token`. En Postman el token se guarda solo en la variable `token` y lo usan todos los demás requests.\n\nTambién puedes copiar el token desde el facturador: **Configuración → Usuarios**, campo `api_token`.\n\n**Autenticación:** no requiere token.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `email` | string | sí | Correo del usuario. |\n| `password` | string | sí | Contraseña del usuario. |\n\n### Respuesta\n\n`token` es el valor que va en `Authorization: Bearer <token>`. También devuelve datos de la empresa y del usuario. Si las credenciales son incorrectas responde `success: false` con el mensaje `No Autorizado` (con HTTP 200).",
        "responses": {
          "200": {
            "description": "Login correcto / Credenciales incorrectas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Login correcto",
                    "value": {
                      "success": true,
                      "name": "Administrador",
                      "email": "usuario@empresa.com",
                      "establishment_id": 1,
                      "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789",
                      "ruc": "20123456789",
                      "company": {
                        "name": "EMPRESA DEMO S.A.C.",
                        "address": "Av. 2 de Mayo 123, Lima",
                        "phone": "427-1148",
                        "email": "ventas@empresa.com"
                      }
                    }
                  },
                  "e2": {
                    "summary": "Credenciales incorrectas",
                    "value": {
                      "success": false,
                      "message": "No Autorizado"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "obtener_token_login": {
                  "summary": "Obtener token (login)",
                  "description": "",
                  "value": {
                    "email": "usuario@empresa.com",
                    "password": "tu-contraseña"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Emitir comprobante (factura, boleta, nota de crédito o débito)",
        "operationId": "EmitirComprobanteFacturaBoletaNotaDeCrditoODbito",
        "description": "Registra un comprobante electrónico, genera su XML firmado y su PDF y, según la configuración de la empresa, lo envía a SUNAT. El mismo endpoint emite facturas (`01`), boletas (`03`), notas de crédito (`07`) y notas de débito (`08`): cambia `codigo_tipo_documento` y los campos de cada caso. Cada request de esta carpeta es un escenario listo para copiar.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `serie_documento` | string | sí | Serie registrada en el facturador para el tipo de comprobante (ej. `F001`, `B001`). |\n| `numero_documento` | string | sí | `\"#\"` para que el sistema asigne el siguiente correlativo, o el número exacto. |\n| `fecha_de_emision` | string `AAAA-MM-DD` | sí | Fecha de emisión. SUNAT acepta un plazo máximo de envío desde esta fecha. |\n| `hora_de_emision` | string `HH:MM:SS` | sí | Hora de emisión. |\n| `codigo_tipo_documento` | string | sí | `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito. |\n| `codigo_tipo_moneda` | string | sí | `PEN` soles o `USD` dólares. |\n| `codigo_tipo_operacion` | string | sí en 01/03 | Catálogo 51: `0101` venta interna, `0200` exportación, `1001` operación con detracción, `1004` detracción por transporte. |\n| `fecha_de_vencimiento` | string `AAAA-MM-DD` | no | Fecha de vencimiento (facturas y boletas). |\n| `factor_tipo_de_cambio` | number | no | Tipo de cambio. Obligatorio en la práctica si la moneda es `USD`. Por defecto 1. |\n| `numero_orden_de_compra` | string | no | Número de orden de compra del cliente. |\n| `datos_del_cliente_o_receptor` | object | sí | Datos del cliente. Si no existe se registra; si existe se actualiza. |\n| `datos_del_cliente_o_receptor.codigo_tipo_documento_identidad` | string | sí | Catálogo 06: `0` sin documento, `1` DNI, `4` carné de extranjería, `6` RUC, `7` pasaporte. |\n| `datos_del_cliente_o_receptor.numero_documento` | string | sí | Número de documento del cliente. |\n| `datos_del_cliente_o_receptor.apellidos_y_nombres_o_razon_social` | string | sí | Nombre o razón social. |\n| `datos_del_cliente_o_receptor.codigo_pais` | string | no | Código de país (`PE`). |\n| `datos_del_cliente_o_receptor.ubigeo` | string | no | Ubigeo de 6 dígitos. Si el cliente tiene RUC se valida que exista. |\n| `datos_del_cliente_o_receptor.direccion` | string | no | Dirección del cliente. |\n| `datos_del_cliente_o_receptor.correo_electronico` | string | no | Correo del cliente (se usa si se pide enviar el comprobante por correo). |\n| `datos_del_cliente_o_receptor.telefono` | string | no | Teléfono. |\n| `totales` | object | sí | Totales del comprobante. Los calcula tu sistema y deben cuadrar con los ítems. |\n| `totales.total_operaciones_gravadas` | number | no | Suma de valores (sin IGV) de ítems gravados. |\n| `totales.total_operaciones_exoneradas / inafectas / gratuitas` | number | no | Suma de valores de ítems exonerados, inafectos y gratuitos. |\n| `totales.total_exportacion` | number | no | Valor de operaciones de exportación. |\n| `totales.total_igv` | number | no | IGV total. |\n| `totales.total_impuestos` | number | no | Suma de todos los impuestos (IGV, ISC, ICBPER, otros). |\n| `totales.total_impuestos_bolsa_plastica` | number | no | ICBPER total. |\n| `totales.total_descuentos / total_cargos / total_anticipos` | number | no | Descuentos globales, cargos globales y anticipos deducidos. |\n| `totales.total_valor` | number | no | Valor de venta (sin impuestos). |\n| `totales.total_venta` | number | sí | Importe total a pagar. |\n| `items` | array | sí | Detalle del comprobante; al menos un ítem. |\n| `items[].codigo_interno` | string | no | Código del producto en tu sistema. Si no existe en el facturador se crea. |\n| `items[].descripcion` | string | sí | Descripción del producto o servicio. |\n| `items[].codigo_producto_sunat` | string | no | Código de producto SUNAT de 8 dígitos. |\n| `items[].unidad_de_medida` | string | sí | Catálogo 03: `NIU` unidad, `ZZ` servicio, `KGM` kilogramo, etc. |\n| `items[].cantidad` | number | sí | Cantidad. |\n| `items[].valor_unitario` | number | sí | Valor unitario sin IGV. |\n| `items[].precio_unitario` | number | sí | Precio unitario con IGV. |\n| `items[].codigo_tipo_precio` | string | sí | `01` precio con IGV, `02` valor referencial (ítems gratuitos). |\n| `items[].codigo_tipo_afectacion_igv` | string | sí | Catálogo 07: `10` gravado, `20` exonerado, `30` inafecto, `40` exportación, `11`–`17` y `21`, `31`–`37` gratuitos. |\n| `items[].total_base_igv` | number | sí | Base imponible del IGV del ítem. |\n| `items[].porcentaje_igv` | number | sí | Porcentaje de IGV (18, o 10 para restaurantes acogidos a la Ley 31556). |\n| `items[].total_igv` | number | sí | IGV del ítem. |\n| `items[].total_impuestos_bolsa_plastica` | number | no | ICBPER del ítem (bolsas plásticas). |\n| `items[].total_impuestos` | number | sí | Impuestos del ítem. |\n| `items[].total_valor_item` | number | sí | Valor del ítem sin impuestos (cantidad × valor unitario − descuentos). |\n| `items[].total_item` | number | sí | Total del ítem con impuestos. |\n| `items[].descuentos[] / cargos[]` | array | no | Descuentos o cargos del ítem: `codigo`, `descripcion`, `factor`, `monto`, `base`. |\n| `items[].datos_adicionales[]` | array | no | Datos extra del ítem (ej. placa del vehículo). |\n| `descuentos[] / cargos[]` | array | no | Descuentos o cargos globales (catálogo 53): `codigo`, `descripcion`, `factor`, `monto`, `base`. |\n| `codigo_condicion_de_pago` | string | no | `01` contado (por defecto) o `02` crédito. |\n| `pagos[]` | array | no | Pagos recibidos: `codigo_metodo_pago`, `codigo_destino_pago`, `referencia`, `monto`. |\n| `cuotas[]` | array | sí si es crédito | Cuotas del crédito: `fecha`, `codigo_tipo_moneda`, `monto`. |\n| `detraccion` | object | no | Datos de la detracción: `codigo_tipo_detraccion`, `porcentaje`, `monto`, `codigo_metodo_pago`, `cuenta_bancaria`. |\n| `anticipos[]` | array | no | Anticipos que se deducen: `numero`, `codigo_tipo_documento`, `monto`, `total`. |\n| `guias[]` | array | no | Guías de remisión relacionadas: `numero`, `codigo_tipo_documento`. |\n| `relacionados[]` | array | no | Otros documentos relacionados: `numero`, `codigo_tipo_documento`, `monto`. |\n| `leyendas[]` | array | no | Leyendas (catálogo 52): `codigo`, `valor`. |\n| `codigo_tipo_nota` | string | sí en 07/08 | Motivo de la nota: catálogo 09 (crédito) o 10 (débito). Ej. `01` anulación de la operación. |\n| `motivo_o_sustento_de_nota` | string | sí en 07/08 | Texto que explica la nota. |\n| `documento_afectado` | object | sí en 07/08 | Comprobante que corrige la nota: `external_id`, o bien `serie_documento` + `numero_documento` + `codigo_tipo_documento`. |\n| `informacion_adicional` | string | no | Texto libre que se imprime en el PDF. Usa `|` para separar líneas. |\n| `acciones.enviar_email` | boolean | no | Envía el comprobante al correo del cliente. |\n| `acciones.enviar_xml_firmado` | boolean | no | `false` registra el comprobante sin enviarlo a SUNAT (se envía luego con **Enviar a SUNAT**). |\n| `acciones.formato_pdf` | string | no | Formato del PDF: `a4` (defecto), `a5`, `ticket`. |\n\n### Respuesta\n\n- `data.external_id`: identificador del comprobante. **Guárdalo**: se usa para consultar, anular, emitir notas y descargar archivos.\n- `data.number`: serie y número asignados (ej. `F001-26`).\n- `data.state_type_id`: estado (`01` registrado, `03` enviado, `05` aceptado, `07` observado, `09` rechazado, `11` anulado).\n- `links`: URLs de descarga del XML, PDF y CDR. `cdr` llega vacío si el comprobante no se envió a SUNAT.\n- `response`: respuesta de SUNAT (código y descripción). Llega vacía si no se envió.\n\nLas **boletas** no se envían una por una: SUNAT las recibe en el resumen diario (carpeta **Resúmenes diarios**).\n\n### Errores frecuentes\n\n- `400`: un dato no pasa la validación (serie que no existe, ubigeo incorrecto, falta un campo obligatorio). El motivo va en `message`.\n- `500`: SUNAT rechazó el comprobante o hubo un error al procesarlo. El motivo va en `message`.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "F001-26",
                        "filename": "20302019010-01-F001-26",
                        "external_id": "46c6ce9d-aaae-4b8d-8e94-a6f94c964b47",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "number_to_letter": "Ciento dieciocho con 00/100",
                        "hash": "jFDgOlcAShjMeA1TJzT08v+PPTw=",
                        "id": 322
                      },
                      "links": {
                        "xml": "https://{subdominio}/downloads/document/xml/{external_id}",
                        "pdf": "https://{subdominio}/downloads/document/pdf/{external_id}",
                        "cdr": "https://{subdominio}/downloads/document/cdr/{external_id}"
                      },
                      "response": {
                        "code": "0",
                        "description": "La Factura numero F001-26, ha sido aceptada",
                        "notes": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada F009, es incorrecta."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "El comprobante F001-26 fue rechazado: 2017 - El número de documento de identidad del receptor debe ser RUC"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "factura_gravada": {
                  "summary": "Factura gravada",
                  "description": "Factura con IGV 18%. Es el caso más común.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_gravada_sin_enviar_a_sunat": {
                  "summary": "Factura gravada sin enviar a SUNAT",
                  "description": "Registra la factura sin enviarla (`acciones.enviar_xml_firmado: false`). Envíala después con **Enviar a SUNAT**.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "acciones": {
                      "enviar_xml_firmado": false
                    }
                  }
                },
                "factura_gratuita": {
                  "summary": "Factura gratuita",
                  "description": "Transferencia gratuita: `codigo_tipo_precio` `02` y afectación gratuita.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 0.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 100.0,
                      "total_igv": 0.0,
                      "total_impuestos": 0.0,
                      "total_valor": 0.0,
                      "total_venta": 0.0
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 0.0,
                        "codigo_tipo_precio": "02",
                        "precio_unitario": 0.0,
                        "codigo_tipo_afectacion_igv": "16",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18.0,
                        "total_igv": 18.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 0.0,
                        "total_item": 0.0
                      }
                    ],
                    "leyendas": [
                      {
                        "codigo": "1002",
                        "valor": "TRANSFERENCIA GRATUITA"
                      }
                    ]
                  }
                },
                "factura_gravada_en_d_lares": {
                  "summary": "Factura gravada en dólares",
                  "description": "Moneda `USD` con `factor_tipo_de_cambio`.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "USD",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_exonerada": {
                  "summary": "Factura exonerada",
                  "description": "Ítems exonerados de IGV (afectación `20`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 0.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 118.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 0.0,
                      "total_impuestos": 0.0,
                      "total_valor": 118,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 59,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "20",
                        "total_base_igv": 118.0,
                        "porcentaje_igv": 18,
                        "total_igv": 0.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 118,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_de_contingencia": {
                  "summary": "Factura de contingencia",
                  "description": "Factura emitida en contingencia.",
                  "value": {
                    "serie_documento": "0001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "fecha_de_vencimiento": "2026-10-27",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "20501973522",
                      "apellidos_y_nombres_o_razon_social": "EMBOTELLADORA DON JORGE S.A.C. EN LIQUIDACION",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. Argentina 2458",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_inafecta": {
                  "summary": "Factura inafecta",
                  "description": "Ítems inafectos (afectación `30`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 0.0,
                      "total_operaciones_inafectas": 118.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 0.0,
                      "total_impuestos": 0.0,
                      "total_valor": 118,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 59,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "30",
                        "total_base_igv": 118,
                        "porcentaje_igv": 18,
                        "total_igv": 0.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 118,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_con_impuesto_a_la_bolsa_icbper": {
                  "summary": "Factura con impuesto a la bolsa (ICBPER)",
                  "description": "Factura gravada con impuesto a las bolsas plásticas.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_impuestos_bolsa_plastica": 0.6,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118.6
                    },
                    "items": [
                      {
                        "codigo_interno": "P0015",
                        "descripcion": "Pepsi 3 lt",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos_bolsa_plastica": 0.6,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_con_cargo_global": {
                  "summary": "Factura con cargo global",
                  "description": "Cargo a nivel documento en `cargos[]`.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "cargos": [
                      {
                        "codigo": "46",
                        "descripcion": "Regarco por servicios",
                        "factor": 0.1,
                        "monto": 10.0,
                        "base": 100.0
                      }
                    ],
                    "totales": {
                      "total_cargos": 10.0,
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 128.0
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_gravada_y_gratuita": {
                  "summary": "Factura gravada y gratuita",
                  "description": "Combina ítems gravados y gratuitos.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 100.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      },
                      {
                        "codigo_interno": "P0122",
                        "descripcion": "Pepsi 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 0.0,
                        "codigo_tipo_precio": "02",
                        "precio_unitario": 0.0,
                        "codigo_tipo_afectacion_igv": "16",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18.0,
                        "total_igv": 18.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 0.0,
                        "total_item": 0.0
                      }
                    ]
                  }
                },
                "factura_exonerada_con_impuesto_a_la_bolsa": {
                  "summary": "Factura exonerada con impuesto a la bolsa",
                  "description": "Ítems exonerados más ICBPER.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 0.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 150.6,
                      "total_operaciones_gratuitas": 0.0,
                      "total_impuestos_bolsa_plastica": 0.9,
                      "total_igv": 0.0,
                      "total_impuestos": 0.0,
                      "total_valor": 150.6,
                      "total_venta": 151.5
                    },
                    "items": [
                      {
                        "codigo_interno": "P00025",
                        "descripcion": "BANDEJA DE DRENAJE",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 3,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 50,
                        "codigo_tipo_afectacion_igv": "20",
                        "total_base_igv": 150.0,
                        "porcentaje_igv": 18,
                        "total_igv": 0.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 150,
                        "total_item": 150
                      },
                      {
                        "codigo_interno": "P01121",
                        "descripcion": "BOLSA PLASTICA",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 3,
                        "valor_unitario": 0.2,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 0.2,
                        "codigo_tipo_afectacion_igv": "20",
                        "total_base_igv": 0.6,
                        "porcentaje_igv": 18,
                        "total_igv": 0.0,
                        "total_impuestos_bolsa_plastica": 0.9,
                        "total_impuestos": 0.0,
                        "total_valor_item": 0.6,
                        "total_item": 0.6
                      }
                    ],
                    "informacion_adicional": "Forma de pago:EFECTIVO|Caja: "
                  }
                },
                "factura_con_detracci_n": {
                  "summary": "Factura con detracción",
                  "description": "Operación sujeta a detracción (`codigo_tipo_operacion` `1001` y objeto `detraccion`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "1001",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "leyendas": [
                      {
                        "codigo": "2006",
                        "valor": "Operación sujeta a detracción"
                      }
                    ],
                    "detraccion": {
                      "codigo_tipo_detraccion": "008",
                      "porcentaje": 4.0,
                      "monto": 4.72,
                      "codigo_metodo_pago": "001",
                      "cuenta_bancaria": "212-16547578"
                    },
                    "items": [
                      {
                        "codigo_interno": "P0150",
                        "descripcion": "Madera caoba xyz",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_con_descuento_global_y_lineal": {
                  "summary": "Factura con descuento global y lineal",
                  "description": "Descuento al documento y a un ítem.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "descuentos": [
                      {
                        "codigo": "03",
                        "descripcion": "Descuento Global no afecta a la base imponible",
                        "factor": 0.1,
                        "monto": 9.5,
                        "base": 95.0
                      }
                    ],
                    "totales": {
                      "total_descuentos": 14.5,
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 95.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 17.1,
                      "total_impuestos": 17.1,
                      "total_valor": 95,
                      "total_venta": 112.1
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "31201501",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "descuentos": [
                          {
                            "codigo": "00",
                            "descripcion": "Descuento Lineal",
                            "factor": 0.05,
                            "monto": 5.0,
                            "base": 100.0
                          }
                        ],
                        "total_base_igv": 95.0,
                        "porcentaje_igv": 18,
                        "total_igv": 17.1,
                        "total_impuestos": 17.1,
                        "total_valor_item": 95,
                        "total_item": 112.1
                      }
                    ]
                  }
                },
                "factura_con_anticipos": {
                  "summary": "Factura con anticipos",
                  "description": "Deduce anticipos facturados antes (`anticipos[]`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10417844398",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_anticipos": 20.0,
                      "total_descuentos": 20.0,
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 14.4,
                      "total_impuestos": 14.4,
                      "total_valor": 80,
                      "total_venta": 94.4
                    },
                    "descuentos": [
                      {
                        "codigo": "04",
                        "descripcion": "Descuentos globales por anticipos gravados que afectan la base imponible del IGV/IVAP",
                        "factor": 0.2,
                        "monto": 20.0,
                        "base": 100.0
                      }
                    ],
                    "anticipos": [
                      {
                        "numero": "F001-9",
                        "codigo_tipo_documento": "02",
                        "monto": 20.0,
                        "total": 23.6
                      }
                    ],
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_con_documento_relacionado": {
                  "summary": "Factura con documento relacionado",
                  "description": "Incluye documentos relacionados (`relacionados[]`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "relacionados": [
                      {
                        "numero": "12",
                        "codigo_tipo_documento": "01",
                        "monto": 150.0
                      },
                      {
                        "numero": "15",
                        "codigo_tipo_documento": "01",
                        "monto": 150.0
                      }
                    ],
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_con_descuento_global": {
                  "summary": "Factura con descuento global",
                  "description": "Descuento a nivel documento en `descuentos[]`.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "descuentos": [
                      {
                        "codigo": "02",
                        "descripcion": "Descuento Global afecta a la base imponible",
                        "factor": 0.2,
                        "monto": 20.0,
                        "base": 100.0
                      }
                    ],
                    "totales": {
                      "total_descuentos": 20.0,
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 14.4,
                      "total_impuestos": 14.4,
                      "total_valor": 80,
                      "total_venta": 94.4
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_con_placa_en_el_tem": {
                  "summary": "Factura con placa en el ítem",
                  "description": "Dato adicional de placa en el ítem.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118,
                        "datos_adicionales": [
                          {
                            "codigo": "5010",
                            "descripcion": "Numero de Placa",
                            "valor": "A7Q-986"
                          }
                        ]
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_a_cr_dito_cuotas": {
                  "summary": "Factura a crédito (cuotas)",
                  "description": "Condición de pago crédito (`02`) con `cuotas[]`.",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-11-26",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "codigo_condicion_de_pago": "02",
                    "cuotas": [
                      {
                        "fecha": "2026-11-26",
                        "codigo_tipo_moneda": "PEN",
                        "monto": 59
                      },
                      {
                        "fecha": "2026-11-26",
                        "codigo_tipo_moneda": "PEN",
                        "monto": 59
                      }
                    ],
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_al_contado": {
                  "summary": "Factura al contado",
                  "description": "Condición de pago contado (`01`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "codigo_condicion_de_pago": "01",
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "factura_con_pagos": {
                  "summary": "Factura con pagos",
                  "description": "Registra los pagos recibidos (`pagos[]`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "pagos": [
                      {
                        "codigo_metodo_pago": "02",
                        "referencia": "1",
                        "monto": "50"
                      },
                      {
                        "codigo_metodo_pago": "01",
                        "referencia": "ref",
                        "monto": "60"
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "factura_con_descuento_lineal": {
                  "summary": "Factura con descuento lineal",
                  "description": "Descuento en un ítem (`items[].descuentos[]`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_descuentos": 5.0,
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 95.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 17.1,
                      "total_impuestos": 17.1,
                      "total_valor": 95,
                      "total_venta": 112.1
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "codigo_producto_gsl": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "descuentos": [
                          {
                            "codigo": "00",
                            "descripcion": "Descuento Lineal",
                            "factor": 0.05,
                            "monto": 5.0,
                            "base": 100.0
                          }
                        ],
                        "total_base_igv": 95.0,
                        "porcentaje_igv": 18,
                        "total_igv": 17.1,
                        "total_impuestos": 17.1,
                        "total_valor_item": 95,
                        "total_item": 112.1
                      }
                    ]
                  }
                },
                "factura_de_exportaci_n": {
                  "summary": "Factura de exportación",
                  "description": "Operación de exportación (`0200`, afectación `40`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0200",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "0",
                      "numero_documento": "8901074873",
                      "apellidos_y_nombres_o_razon_social": "SUPERTIENDAS Y DROGUERIAS OLIMPICA S.A.",
                      "codigo_pais": "CO",
                      "direccion": "CALLE 53 Nro 46-192 LOCAL 3-01 C. COMERCIAL PORTAL DEL PRADO",
                      "correo_electronico": "",
                      "telefono": ""
                    },
                    "totales": {
                      "total_exportacion": 1395.0,
                      "total_operaciones_gravadas": 0.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 0.0,
                      "total_impuestos": 0.0,
                      "total_valor": 1395.0,
                      "total_venta": 1395.0
                    },
                    "items": [
                      {
                        "codigo_interno": "1055929",
                        "descripcion": "CAMISETA NIÑO MANGA CORTA 4-6-8-10-12 DKK272763",
                        "codigo_producto_sunat": "53101701",
                        "unidad_de_medida": "NIU",
                        "cantidad": 300,
                        "valor_unitario": 4.65,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 4.65,
                        "codigo_tipo_afectacion_igv": "40",
                        "total_base_igv": 1395.0,
                        "porcentaje_igv": 18,
                        "total_igv": 0.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 1395.0,
                        "total_item": 1395.0
                      }
                    ]
                  }
                },
                "factura_con_gu_a_de_remisi_n": {
                  "summary": "Factura con guía de remisión",
                  "description": "Relaciona una guía de remisión (`guias[]`).",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "guias": [
                      {
                        "numero": "T001",
                        "codigo_tipo_documento": "09"
                      },
                      {
                        "numero": "T002",
                        "codigo_tipo_documento": "09"
                      }
                    ],
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "informacion_adicional": "Forma de pago:Efectivo|Caja: 1"
                  }
                },
                "boleta_gravada": {
                  "summary": "Boleta gravada",
                  "description": "Boleta con IGV 18%.",
                  "value": {
                    "serie_documento": "B001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "03",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "0045467898",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "boleta_de_exportaci_n": {
                  "summary": "Boleta de exportación",
                  "description": "Boleta para operación de exportación.",
                  "value": {
                    "serie_documento": "B001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0200",
                    "codigo_tipo_documento": "03",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "numero_orden_de_compra": "",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "0",
                      "numero_documento": "9601074873",
                      "apellidos_y_nombres_o_razon_social": "EL OASIS S.A.",
                      "codigo_pais": "CO",
                      "direccion": "CALLE 123 Nro 50 LOCAL 44-01 C. COMERCIAL INNOVA",
                      "correo_electronico": "",
                      "telefono": ""
                    },
                    "totales": {
                      "total_exportacion": 1395.0,
                      "total_operaciones_gravadas": 0.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 0.0,
                      "total_impuestos": 0.0,
                      "total_valor": 1395.0,
                      "total_venta": 1395.0
                    },
                    "items": [
                      {
                        "codigo_interno": "1055929",
                        "descripcion": "CAMISETA NIÑO MANGA CORTA 4-6-8-10-12 DKK272763",
                        "codigo_producto_sunat": "53101701",
                        "unidad_de_medida": "NIU",
                        "cantidad": 300,
                        "valor_unitario": 4.65,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 4.65,
                        "codigo_tipo_afectacion_igv": "40",
                        "total_base_igv": 1395.0,
                        "porcentaje_igv": 18,
                        "total_igv": 0.0,
                        "total_impuestos": 0.0,
                        "total_valor_item": 1395.0,
                        "total_item": 1395.0
                      }
                    ]
                  }
                },
                "boleta_de_contingencia": {
                  "summary": "Boleta de contingencia",
                  "description": "Boleta emitida en contingencia.",
                  "value": {
                    "serie_documento": "0004",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "03",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-10-27",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "codigo_producto_gsl": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "nota_de_cr_dito_por_external_id": {
                  "summary": "Nota de crédito (por external_id)",
                  "description": "Nota de crédito que referencia el comprobante por su `external_id`.",
                  "value": {
                    "serie_documento": "FC01",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "07",
                    "codigo_tipo_nota": "01",
                    "motivo_o_sustento_de_nota": "Error al emitir comprobante",
                    "codigo_tipo_moneda": "PEN",
                    "numero_orden_de_compra": "0045467898",
                    "documento_afectado": {
                      "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "acciones": {
                      "formato_pdf": "a4"
                    }
                  }
                },
                "nota_de_cr_dito_por_serie_y_n_mero": {
                  "summary": "Nota de crédito (por serie y número)",
                  "description": "Nota de crédito que referencia el comprobante por serie, número y tipo.",
                  "value": {
                    "serie_documento": "FC01",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "07",
                    "codigo_tipo_nota": "01",
                    "motivo_o_sustento_de_nota": "Error al emitir comprobante",
                    "codigo_tipo_moneda": "PEN",
                    "numero_orden_de_compra": "0045467898",
                    "documento_afectado": {
                      "serie_documento": "F001",
                      "numero_documento": "190",
                      "codigo_tipo_documento": "01"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "acciones": {
                      "formato_pdf": "a4"
                    }
                  }
                },
                "nota_de_d_bito_por_external_id": {
                  "summary": "Nota de débito (por external_id)",
                  "description": "Nota de débito que referencia el comprobante por su `external_id`.",
                  "value": {
                    "serie_documento": "FD01",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "08",
                    "codigo_tipo_nota": "01",
                    "motivo_o_sustento_de_nota": "Error al emitir comprobante",
                    "codigo_tipo_moneda": "PEN",
                    "numero_orden_de_compra": "0045467898",
                    "documento_afectado": {
                      "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ]
                  }
                },
                "nota_de_d_bito_por_serie_y_n_mero": {
                  "summary": "Nota de débito (por serie y número)",
                  "description": "Nota de débito que referencia el comprobante por serie, número y tipo.",
                  "value": {
                    "serie_documento": "FD01",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "08",
                    "codigo_tipo_nota": "01",
                    "motivo_o_sustento_de_nota": "Error al emitir comprobante",
                    "codigo_tipo_moneda": "PEN",
                    "numero_orden_de_compra": "0045467898",
                    "documento_afectado": {
                      "serie_documento": "F001",
                      "numero_documento": "133",
                      "codigo_tipo_documento": "01"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "totales": {
                      "total_exportacion": 0.0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0.0,
                      "total_operaciones_exoneradas": 0.0,
                      "total_operaciones_gratuitas": 0.0,
                      "total_igv": 18.0,
                      "total_impuestos": 18.0,
                      "total_valor": 100,
                      "total_venta": 118
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "Inca Kola 250 ml",
                        "codigo_producto_sunat": "51121703",
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18,
                        "total_impuestos": 18,
                        "total_valor_item": 100,
                        "total_item": 118
                      }
                    ],
                    "acciones": {
                      "formato_pdf": "a4"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/send": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Enviar comprobante a SUNAT",
        "operationId": "EnviarComprobanteASunat",
        "description": "Envía a SUNAT una factura o nota que se registró sin enviar (`acciones.enviar_xml_firmado: false`) o que quedó pendiente. Las boletas no se envían con este endpoint: van en el resumen diario.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí | `external_id` devuelto al emitir el comprobante. |\n\n### Respuesta\n\nIgual que al emitir: `data` con el estado y `response` con la respuesta de SUNAT.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "F001-15",
                        "filename": "20415963255-01-F001-15",
                        "external_id": "7d9feb66-16e9-47a9-86fd-ebccdb662678"
                      },
                      "links": {
                        "cdr": "https://{subdominio}/downloads/document/cdr/{external_id}"
                      },
                      "response": {
                        "code": "0",
                        "description": "La Factura numero F001-15, ha sido aceptada",
                        "notes": []
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar / Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "El documento con código externo 0000, no se encuentra registrado."
                    }
                  },
                  "e2": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "El tipo de documento 03 es inválido, no es posible enviar."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "enviar_a_sunat": {
                  "summary": "Enviar a SUNAT",
                  "description": "Envía una factura registrada sin enviar.",
                  "value": {
                    "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/status": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Consultar estado de un comprobante",
        "operationId": "ConsultarEstadoDeUnComprobante",
        "description": "Devuelve el estado actual de un comprobante y sus enlaces de descarga. Se identifica por serie y número; opcionalmente también por `external_id`.\n\n**Autenticación:** no requiere token.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `serie_number` | string | sí | Serie y número separados por guion, ej. `F001-26`. |\n| `external_id` | string | no | `external_id` del comprobante, para precisar la búsqueda. |\n\n### Respuesta\n\n`data.status_id` (`01` registrado, `03` enviado, `05` aceptado, `07` observado, `09` rechazado, `11` anulado) y `data.status` indican el estado; `links` trae las URLs del XML, PDF y CDR.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "F001-1",
                        "filename": "20000000000-01-F001-1",
                        "external_id": "8a1b2c3d-0000-4000-8000-000000000000",
                        "status_id": "05",
                        "status": "Aceptado",
                        "qr": "iVBORw0KGgo...",
                        "number_to_letter": "CIENTO DIECIOCHO CON 00/100 "
                      },
                      "links": {
                        "xml": "https://demo.midominio.com/downloads/document/xml/8a1b2c3d-0000-4000-8000-000000000000",
                        "pdf": "https://demo.midominio.com/downloads/document/pdf/8a1b2c3d-0000-4000-8000-000000000000",
                        "cdr": "https://demo.midominio.com/downloads/document/cdr/8a1b2c3d-0000-4000-8000-000000000000"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "El documento con código externo 0000 o numero F001-999, no se encuentra registrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "consultar_estado_de_un_comprobante": {
                  "summary": "Consultar estado de un comprobante",
                  "description": "",
                  "value": {
                    "serie_number": "F001-26",
                    "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/updatedocumentstatus": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Actualizar estado de un comprobante",
        "operationId": "ActualizarEstadoDeUnComprobante",
        "description": "Cambia manualmente el estado registrado de un comprobante (por ejemplo, para marcarlo como aceptado si lo validaste directamente en SUNAT). No envía nada a SUNAT.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `externail_id` | string | sí | `external_id` del comprobante. **Importante:** el campo se escribe `externail_id` (con esa ortografía). |\n| `state_type_id` | string | sí | Nuevo estado: `01` registrado, `03` enviado, `05` aceptado, `07` observado, `09` rechazado, `11` anulado, `13` por anular. |\n\n### Errores\n\nSi el `externail_id` no existe responde `500`.",
        "responses": {
          "200": {
            "description": "Estado actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estado actualizado",
                    "value": {
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "Error al actualizar el estado."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "actualizar_estado_de_un_comprobante": {
                  "summary": "Actualizar estado de un comprobante",
                  "description": "",
                  "value": {
                    "externail_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                    "state_type_id": "05"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/lists/{fecha_inicio}/{fecha_fin}": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Listar comprobantes por fechas",
        "operationId": "ListarComprobantesPorFechas",
        "description": "Lista los comprobantes (facturas, boletas y notas) emitidos entre dos fechas, ambas incluidas.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Parámetros de ruta\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `fecha_inicio` | string `AAAA-MM-DD` | sí | Fecha de emisión inicial. |\n| `fecha_fin` | string `AAAA-MM-DD` | sí | Fecha de emisión final. |\n\n### Respuesta\n\n`data` es la lista completa, sin paginar. Cada comprobante trae número, cliente, totales, estado (`state_type_id`), `external_id` y fechas (`date_of_issue` en formato `DD-MM-AAAA`). Para rangos grandes usa periodos cortos (por ejemplo, un mes).",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "data": [
                        {
                          "id": 1,
                          "group_id": "01",
                          "soap_type_id": "01",
                          "soap_type_description": "Demo",
                          "date_of_issue": "03-10-2026",
                          "date_of_due": "03-10-2026",
                          "number": "F001-1",
                          "customer_name": "EMPRESA XYZ S.A.",
                          "customer_number": "20501973522",
                          "customer_identity_document_type_description": "RUC",
                          "customer_telephone": "427-1148",
                          "customer_email": "demo@gmail.com",
                          "custom_fields_data": null,
                          "currency_type_id": "PEN",
                          "exchange_rate_sale": "1.000",
                          "total_exportation": "0.00",
                          "total_free": "0.00",
                          "total_unaffected": "0.00",
                          "total_exonerated": "0.00",
                          "total_taxed": "100.00",
                          "total_igv": "18.00",
                          "total": "118.00",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "document_type_description": "FACTURA ELECTRÓNICA",
                          "document_type_id": "01",
                          "has_xml": true,
                          "has_pdf": true,
                          "has_cdr": true,
                          "download_xml": "https://demo.midominio.com/downloads/document/xml/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "download_pdf": "https://demo.midominio.com/downloads/document/pdf/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "download_cdr": "https://demo.midominio.com/downloads/document/cdr/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "btn_voided": true,
                          "btn_note": true,
                          "btn_guide": true,
                          "btn_resend": false,
                          "btn_consult_cdr": true,
                          "btn_constancy_detraction": false,
                          "btn_recreate_document": false,
                          "btn_change_to_registered_status": false,
                          "btn_delete_doc_type_03": false,
                          "send_server": false,
                          "affected_document": null,
                          "shipping_status": null,
                          "sunat_shipping_status": null,
                          "query_status": null,
                          "created_at": "2026-10-03 10:11:11",
                          "updated_at": "2026-10-03 10:11:15",
                          "user_name": "Administrador",
                          "user_email": "demo@gmail.com",
                          "user_id": 1,
                          "source_module": "APP",
                          "source_module_description": "App móvil",
                          "email_send_it": false,
                          "email_send_it_array": [],
                          "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "notes": [],
                          "sales_note": [],
                          "order_note": [],
                          "balance": "0.00",
                          "guides": null,
                          "message_regularize_shipping": null,
                          "regularize_shipping": false,
                          "purchase_order": null,
                          "is_editable": false,
                          "dispatches": [],
                          "soap_type": {
                            "id": "01",
                            "description": "Demo"
                          },
                          "plate_numbers": [],
                          "total_charge": "0.00",
                          "filename": "20000000000-01-F001-1",
                          "date_of_payment": "2026-10-03",
                          "btn_force_send_by_summary": false,
                          "btn_retention": false
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "fecha_inicio",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-10-27"
          },
          {
            "name": "fecha_fin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-10-27"
          }
        ]
      }
    },
    "/api/summaries": {
      "post": {
        "tags": [
          "Resúmenes y anulación de boletas"
        ],
        "summary": "Registrar resumen diario",
        "operationId": "RegistrarResumenDiario",
        "description": "Genera el resumen diario de una fecha y lo envía a SUNAT. Con `codigo_tipo_proceso: \"1\"` informa todas las boletas (y sus notas) de esa fecha que aún no se informaron; con `\"3\"` anula las boletas indicadas.\n\nSUNAT procesa el resumen de forma asíncrona: la respuesta trae un `ticket` que se consulta después con **Consultar ticket de resumen**.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `fecha_de_emision_de_documentos` | string `AAAA-MM-DD` | sí | Fecha de emisión de las boletas que se informan o anulan. |\n| `codigo_tipo_proceso` | string | sí | `\"1\"` informar las boletas pendientes de esa fecha; `\"3\"` anular boletas. Debe ir entre comillas. |\n| `documentos[]` | array | sí si es `\"3\"` | Boletas a anular. |\n| `documentos[].external_id` | string | sí | `external_id` de la boleta. |\n| `documentos[].motivo_anulacion` | string | sí | Motivo de la anulación. |\n\n### Respuesta\n\n`data.external_id` y `data.ticket` del resumen. Guárdalos para consultar el ticket.\n\n### Errores\n\n- `400` si no hay boletas pendientes en esa fecha, si no se envían boletas para anular o si un `external_id` no corresponde a la fecha.\n- `500` si SUNAT rechaza el envío.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "external_id": "aa14c769-3df8-405c-a510-e00ef3634d72",
                        "ticket": "1730915497341"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos / Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "No se encontraron documentos con fecha de emisión 2026-10-27."
                    }
                  },
                  "e2": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "El código externo 0000 no fue encontrado o la fecha indica no corresponde al documento."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "registrar_resumen_diario": {
                  "summary": "Registrar resumen diario",
                  "description": "Informa a SUNAT todas las boletas pendientes de una fecha.",
                  "value": {
                    "fecha_de_emision_de_documentos": "2026-10-27",
                    "codigo_tipo_proceso": "1"
                  }
                },
                "anular_boletas": {
                  "summary": "Anular boletas",
                  "description": "Anula boletas con un resumen de tipo `\"3\"`.",
                  "value": {
                    "fecha_de_emision_de_documentos": "2026-10-27",
                    "codigo_tipo_proceso": "3",
                    "documentos": [
                      {
                        "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                        "motivo_anulacion": "Se duplico documento"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Resúmenes y anulación de boletas"
        ],
        "summary": "Listar resúmenes diarios",
        "operationId": "ListarResumenesDiarios",
        "description": "Lista los resúmenes diarios enviados (de boletas y sus notas): de **adición** (`summary_status_type_id = 1`), **modificación** (`2`) y **anulación** (`3`), del más reciente al más antiguo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_start / date_end` | date | No | Rango de la **fecha de envío** (`date_of_issue`, `YYYY-MM-DD`). |\n| `date_of_reference` | date | No | Fecha de emisión de los comprobantes incluidos. |\n| `state_type_id` | string | No | `01`, `03`, `05` o `09`. |\n| `search` | string | No | Coincidencia parcial en el identificador (`RC-...` / `RA-...`) o el ticket. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (más recientes primero). |\n| `summary_status_type_id` | string | No | `1` adicionar, `2` modificar, `3` anular. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada fila:** `id` (para *Ver*), `external_id` y `ticket` (para `.../status`), `identifier`, `date_of_issue` (envío), `date_of_reference` (emisión de los comprobantes), `soap_type_id` (`01` demo, `02` producción), `state_type_id` / `state_type_description`, `documents_count`, `pending_ticket`, `links.xml` y `links.cdr` (el CDR solo cuando hay respuesta: `05` o `09`), `created_at`, `updated_at`. Además: `summary_status_type_id` / `summary_status_type_description`, `unknown_error_status_response` (SUNAT respondió con un error desconocido) y `manually_regularized` (regularizado a mano en el sistema).\n\nEstados (`state_type_id`): `01` registrado, `03` enviado (esperando respuesta: falta consultar el ticket), `05` aceptado, `09` rechazado. `pending_ticket: true` indica que el envío está en `03`.\n\n**Errores:**\n- `422` si una fecha no es válida o `summary_status_type_id` no es `1`, `2` ni `3`.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 12,
                          "external_id": "a65c9dcc-477e-4b3f-884a-971c56b3d923",
                          "identifier": "RC-20261107-1",
                          "date_of_issue": "2026-11-07",
                          "date_of_reference": "2026-11-06",
                          "soap_type_id": "02",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "ticket": "1793296089424",
                          "documents_count": 2,
                          "pending_ticket": false,
                          "links": {
                            "xml": "https://empresa.dominio/downloads/summary/xml/a65c9dcc-477e-4b3f-884a-971c56b3d923",
                            "cdr": "https://empresa.dominio/downloads/summary/cdr/a65c9dcc-477e-4b3f-884a-971c56b3d923"
                          },
                          "summary_status_type_id": "1",
                          "summary_status_type_description": "Adicionar",
                          "unknown_error_status_response": false,
                          "manually_regularized": false,
                          "created_at": "2026-11-07 08:30:12",
                          "updated_at": "2026-11-07 08:31:02"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Fecha inválida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Fecha inválida",
                    "value": {
                      "success": false,
                      "message": {
                        "date_start": [
                          "date start no es una fecha válida."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de envío (`YYYY-MM-DD`)."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha de envío."
          },
          {
            "name": "date_of_reference",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-06",
            "description": "Fecha de emisión de las boletas incluidas."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "03",
            "description": "`01`, `03`, `05` o `09`."
          },
          {
            "name": "summary_status_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` adicionar, `2` modificar, `3` anular."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Identificador (`RC-...`) o ticket."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/summaries/status": {
      "post": {
        "tags": [
          "Resúmenes y anulación de boletas"
        ],
        "summary": "Consultar ticket de resumen",
        "operationId": "ConsultarTicketDeResumen",
        "description": "Consulta en SUNAT el resultado de un resumen diario (también el de anulación de boletas).\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí (o `ticket`) | `external_id` del resumen. Si lo envías, se usa este y se ignora `ticket`. |\n| `ticket` | string | sí (o `external_id`) | Ticket de SUNAT. Envíalo solo si no envías `external_id`. |\n\n### Respuesta\n\n`response.code` `0` y `response.description` indican que SUNAT aceptó. Si el ticket sigue en proceso, `response` trae el mensaje de SUNAT: vuelve a consultar en unos minutos. `links` trae el XML y el CDR.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "filename": "20415963255-RA-20190126-1",
                        "external_id": "0a1382c6-e639-46fc-a8ae-d4659b63c4bd"
                      },
                      "links": {
                        "xml": "https://{subdominio}/downloads/voided/xml/{external_id}",
                        "cdr": "https://{subdominio}/downloads/voided/cdr/{external_id}"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "El código externo 0000 es inválido, no se encontró resumen relacionado"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "consultar_ticket_de_resumen": {
                  "summary": "Consultar ticket de resumen",
                  "description": "",
                  "value": {
                    "external_id": "aa14c769-3df8-405c-a510-e00ef3634d72"
                  }
                },
                "consultar_ticket_de_anulaci_n_de_boletas": {
                  "summary": "Consultar ticket de anulación de boletas",
                  "description": "La anulación de boletas se consulta como un resumen.",
                  "value": {
                    "external_id": "aa14c769-3df8-405c-a510-e00ef3634d72"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/voided": {
      "post": {
        "tags": [
          "Anulación de facturas"
        ],
        "summary": "Anular facturas (comunicación de baja)",
        "operationId": "AnularFacturasComunicacinDeBaja",
        "description": "Anula facturas y sus notas mediante una comunicación de baja a SUNAT. Todos los comprobantes del envío deben tener la misma fecha de emisión. Para anular **boletas** usa el resumen con `codigo_tipo_proceso: \"3\"`.\n\nSUNAT responde con un `ticket` que se consulta con **Consultar ticket de anulación**.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `fecha_de_emision_de_documentos` | string `DD-MM-AAAA` | sí | Fecha de emisión de los comprobantes. **Ojo:** va en formato día-mes-año, ej. `27-10-2026`. |\n| `documentos[]` | array | sí | Comprobantes a anular (al menos uno). |\n| `documentos[].external_id` | string | sí | `external_id` de la factura o nota. |\n| `documentos[].motivo_anulacion` | string | sí | Motivo de la anulación. |\n\n### Respuesta\n\n`data.external_id` y `data.ticket` de la comunicación de baja.\n\n### Errores\n\n- `400` si no se envían comprobantes, si un `external_id` no corresponde a la fecha o si la fecha no está en `DD-MM-AAAA`.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "external_id": "bcaeff82-578d-4c0b-bd2a-76a962da39a9",
                        "ticket": "1730921062042"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "El código externo 0000 no fue encontrado o la fecha indica no corresponde al documento."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "anular_factura": {
                  "summary": "Anular factura",
                  "description": "",
                  "value": {
                    "fecha_de_emision_de_documentos": "27-10-2026",
                    "documentos": [
                      {
                        "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                        "motivo_anulacion": "Se duplico documento"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Anulación de facturas"
        ],
        "summary": "Listar comunicaciones de baja",
        "operationId": "ListarComunicacionesBaja",
        "description": "Lista las comunicaciones de baja enviadas (anulación de facturas y sus notas), de la más reciente a la más antigua. Las anulaciones de **boletas** se hacen por resumen diario: consúltalas en *Listar resúmenes diarios* con `summary_status_type_id=3`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_start / date_end` | date | No | Rango de la **fecha de envío** (`date_of_issue`, `YYYY-MM-DD`). |\n| `date_of_reference` | date | No | Fecha de emisión de los comprobantes incluidos. |\n| `state_type_id` | string | No | `01`, `03`, `05` o `09`. |\n| `search` | string | No | Coincidencia parcial en el identificador (`RC-...` / `RA-...`) o el ticket. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (más recientes primero). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada fila:** `id` (para *Ver*), `external_id` y `ticket` (para `.../status`), `identifier`, `date_of_issue` (envío), `date_of_reference` (emisión de los comprobantes), `soap_type_id` (`01` demo, `02` producción), `state_type_id` / `state_type_description`, `documents_count`, `pending_ticket`, `links.xml` y `links.cdr` (el CDR solo cuando hay respuesta: `05` o `09`), `created_at`, `updated_at`.\n\nEstados (`state_type_id`): `01` registrado, `03` enviado (esperando respuesta: falta consultar el ticket), `05` aceptado, `09` rechazado. `pending_ticket: true` indica que el envío está en `03`.\n\n**Errores:**\n- `422` si una fecha no es válida.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 4,
                          "external_id": "7d3e9f10-2a4b-4c6d-8e0f-1a2b3c4d5e6f",
                          "identifier": "RA-20261107-1",
                          "date_of_issue": "2026-11-07",
                          "date_of_reference": "2026-11-06",
                          "soap_type_id": "02",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "ticket": "1793296089424",
                          "documents_count": 1,
                          "pending_ticket": false,
                          "links": {
                            "xml": "https://empresa.dominio/downloads/voided/xml/7d3e9f10-2a4b-4c6d-8e0f-1a2b3c4d5e6f",
                            "cdr": "https://empresa.dominio/downloads/voided/cdr/7d3e9f10-2a4b-4c6d-8e0f-1a2b3c4d5e6f"
                          },
                          "created_at": "2026-11-07 08:30:12",
                          "updated_at": "2026-11-07 08:31:02"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Fecha inválida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Fecha inválida",
                    "value": {
                      "success": false,
                      "message": {
                        "date_start": [
                          "date start no es una fecha válida."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de envío."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha de envío."
          },
          {
            "name": "date_of_reference",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-06",
            "description": "Fecha de emisión de las facturas incluidas."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "05",
            "description": "`01`, `03`, `05` o `09`."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Identificador (`RA-...`) o ticket."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/voided/status": {
      "post": {
        "tags": [
          "Anulación de facturas"
        ],
        "summary": "Consultar ticket de anulación",
        "operationId": "ConsultarTicketDeAnulacin",
        "description": "Consulta en SUNAT el resultado de una comunicación de baja. Cuando SUNAT la acepta, los comprobantes quedan anulados.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí (o `ticket`) | `external_id` de la anulación. Si lo envías, se usa este y se ignora `ticket`. |\n| `ticket` | string | sí (o `external_id`) | Ticket de SUNAT. Envíalo solo si no envías `external_id`. |\n\n### Respuesta\n\n`response.code` `0` y `response.description` indican que SUNAT aceptó. Si el ticket sigue en proceso, `response` trae el mensaje de SUNAT: vuelve a consultar en unos minutos. `links` trae el XML y el CDR.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "filename": "20415963255-RA-20190126-1",
                        "external_id": "0a1382c6-e639-46fc-a8ae-d4659b63c4bd"
                      },
                      "links": {
                        "xml": "https://{subdominio}/downloads/voided/xml/{external_id}",
                        "cdr": "https://{subdominio}/downloads/voided/cdr/{external_id}"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "El código externo 0000 es inválido, no se encontró anulación relacionada"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "consultar_ticket_de_anulaci_n_de_factura": {
                  "summary": "Consultar ticket de anulación de factura",
                  "description": "",
                  "value": {
                    "external_id": "bcaeff82-578d-4c0b-bd2a-76a962da39a9"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatches": {
      "post": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Emitir guía de remisión remitente",
        "operationId": "EmitirGuaDeRemisinRemitente",
        "description": "Registra una guía de remisión remitente (`09`), firma su XML y genera el PDF. **No la envía a SUNAT**: después usa **Enviar guía a SUNAT** y luego **Consultar ticket de guía**.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `serie_documento` | string | sí | Serie de guía registrada (ej. `T001`). |\n| `numero_documento` | string | sí | `\"#\"` para el siguiente correlativo. |\n| `fecha_de_emision / hora_de_emision` | string | sí | `AAAA-MM-DD` y `HH:MM:SS`. |\n| `codigo_tipo_documento` | string | sí | `09` guía remitente. |\n| `datos_del_emisor.codigo_del_domicilio_fiscal` | string | sí | Código del establecimiento emisor (ej. `0000`). |\n| `datos_del_cliente_o_receptor` | object | sí | Destinatario: `codigo_tipo_documento_identidad`, `numero_documento`, `apellidos_y_nombres_o_razon_social` y opcionales. |\n| `fecha_de_traslado` | string `AAAA-MM-DD` | sí | Fecha de inicio del traslado. |\n| `codigo_motivo_traslado` | string | sí | Catálogo 20: `01` venta, `04` traslado entre establecimientos, `13` otros, etc. |\n| `descripcion_motivo_traslado` | string | no | Descripción del motivo. |\n| `codigo_modo_transporte` | string | sí | `01` transporte público (lo hace un transportista), `02` transporte privado (vehículo propio). |\n| `unidad_peso_total / peso_total` | string / number | sí | Unidad (`KGM`, `TNE`) y peso bruto total. |\n| `numero_de_bultos` | number | no | Cantidad de bultos. |\n| `direccion_partida / direccion_llegada` | object | sí | `ubigeo`, `direccion` (máx. 100 caracteres) y `codigo_del_domicilio_fiscal`. |\n| `transportista` | object | sí si modo `01` | `codigo_tipo_documento_identidad`, `numero_documento`, `apellidos_y_nombres_o_razon_social`, `numero_mtc`. |\n| `chofer` | object | sí si modo `02` | `codigo_tipo_documento_identidad`, `numero_documento`, `nombres`, `numero_licencia`, `telefono`. |\n| `vehiculo` | object | sí si modo `02` | `numero_de_placa`, `modelo`, `marca`. |\n| `vehiculo_secundario[] / chofer_secundario[]` | array | no | Hasta 2 vehículos y 2 conductores adicionales. |\n| `documento_afectado` | object | no | Comprobante relacionado: `external_id`, o `serie_documento` + `numero_documento` + `codigo_tipo_documento`. |\n| `items[]` | array | sí | Bienes trasladados: `codigo_interno`, `descripcion`, `unidad_de_medida`, `cantidad`. |\n| `observaciones` | string | no | Observaciones. |\n\n### Respuesta\n\n`data.external_id` (guárdalo), `data.number` y `data.filename`.\n\n### Errores\n\n- `400` si la serie, el establecimiento o un ubigeo no son válidos.\n- `422` si falta la dirección de partida o de llegada.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "T001-20",
                        "filename": "11111111111-09-T001-20",
                        "external_id": "e6ed6e38-a44f-427d-9c3d-3026feb6b0e0"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos / Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada T009, es incorrecta."
                    }
                  },
                  "e2": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "El código ubigeo es incorrecto"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Error de validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error de validación",
                    "value": {
                      "message": "The given data was invalid.",
                      "errors": {
                        "delivery.address": [
                          "El campo dirección de llegada es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "gu_a_remitente": {
                  "summary": "Guía remitente",
                  "description": "Guía remitente básica.",
                  "value": {
                    "serie_documento": "T001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "09",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "observaciones": "aaaaaaaaaaaaaaa",
                    "codigo_modo_transporte": "01",
                    "codigo_motivo_traslado": "01",
                    "descripcion_motivo_traslado": "El cliente solicito envia a su trabajo en ...",
                    "fecha_de_traslado": "2026-10-27",
                    "codigo_de_puerto": "",
                    "indicador_de_transbordo": false,
                    "unidad_peso_total": "KGM",
                    "peso_total": 30.0,
                    "numero_de_bultos": 1,
                    "numero_de_contenedor": "",
                    "direccion_partida": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO A"
                    },
                    "direccion_llegada": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO 2"
                    },
                    "transportista": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10417844398",
                      "apellidos_y_nombres_o_razon_social": "aaaaaaaaa"
                    },
                    "chofer": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "4177874"
                    },
                    "numero_de_placa": "A01-1254",
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "cantidad": 2
                      }
                    ]
                  }
                },
                "gu_a_remitente_con_transporte_p_blico": {
                  "summary": "Guía remitente con transporte público",
                  "description": "Modo `01`: el traslado lo hace un transportista (requiere `transportista`).",
                  "value": {
                    "serie_documento": "T001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "09",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "20601274133",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "observaciones": "Traslado con empresa de transporte",
                    "codigo_modo_transporte": "01",
                    "codigo_motivo_traslado": "01",
                    "descripcion_motivo_traslado": "El cliente solicito envia a su trabajo en ...",
                    "fecha_de_traslado": "2026-10-27",
                    "indicador_de_transbordo": false,
                    "unidad_peso_total": "KGM",
                    "peso_total": 30.0,
                    "numero_de_bultos": 1,
                    "direccion_partida": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO A",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "direccion_llegada": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO 2",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "transportista": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "20100686814",
                      "apellidos_y_nombres_o_razon_social": "OLVA COURIER S.A.C",
                      "numero_mtc": "1518996CNG"
                    },
                    "items": [
                      {
                        "codigo_interno": "prueba",
                        "cantidad": 2
                      }
                    ],
                    "documento_afectado": {
                      "serie_documento": "F001",
                      "numero_documento": "190",
                      "codigo_tipo_documento": "01"
                    }
                  }
                },
                "gu_a_remitente_con_transporte_privado": {
                  "summary": "Guía remitente con transporte privado",
                  "description": "Modo `02`: vehículo y chofer propios (requiere `chofer` y `vehiculo`).",
                  "value": {
                    "serie_documento": "T001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "09",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "20601274133",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "codigo_modo_transporte": "02",
                    "codigo_motivo_traslado": "05",
                    "descripcion_motivo_traslado": "El cliente solicito envia a su trabajo en ...",
                    "fecha_de_traslado": "2026-10-27",
                    "indicador_de_transbordo": false,
                    "unidad_peso_total": "KGM",
                    "peso_total": 30.0,
                    "numero_de_bultos": 1,
                    "direccion_partida": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO A",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "direccion_llegada": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO 2",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "chofer": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "41784439",
                      "nombres": "JUAN",
                      "apellidos": "PEREZ",
                      "numero_licencia": "Q41784439"
                    },
                    "numero_de_placa": "A011254",
                    "items": [
                      {
                        "codigo_interno": "prueba",
                        "cantidad": 2
                      }
                    ]
                  }
                },
                "gu_a_remitente_con_datos_de_transportista": {
                  "summary": "Guía remitente con datos de transportista",
                  "description": "Guía remitente con transportista, chofer y vehículo, incluidos los secundarios.",
                  "value": {
                    "serie_documento": "T001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "09",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "codigo_modo_transporte": "01",
                    "codigo_motivo_traslado": "01",
                    "descripcion_motivo_traslado": "El cliente solicito envia a su trabajo en ...",
                    "fecha_de_traslado": "2026-10-27",
                    "indicador_de_transbordo": false,
                    "unidad_peso_total": "KGM",
                    "peso_total": 30.0,
                    "numero_de_bultos": 1,
                    "direccion_partida": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO A"
                    },
                    "direccion_llegada": {
                      "ubigeo": "150101",
                      "direccion": "PUNTO 2"
                    },
                    "transportista": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10417844398",
                      "apellidos_y_nombres_o_razon_social": "TRANSPORTES DEMO S.A.C",
                      "numero_mtc": ""
                    },
                    "chofer": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "4177874",
                      "nombres": "Juan Perez",
                      "numero_licencia": "A76023452",
                      "telefono": "923131232"
                    },
                    "vehiculo": {
                      "numero_de_placa": "A011254",
                      "certificado_habilitacion_vehicular": "1212121212",
                      "modelo": "YARIS",
                      "marca": "TOYOTA"
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "cantidad": 2
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatch-carrier": {
      "post": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Emitir guía de remisión transportista",
        "operationId": "EmitirGuaDeRemisinTransportista",
        "description": "Registra una guía de remisión transportista (`31`), la que emite la empresa de transporte. Igual que la remitente, se envía luego con **Enviar guía a SUNAT**.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\nLos mismos de la guía remitente (fechas, peso, ítems, chofer, vehículo), con `codigo_tipo_documento: \"31\"`, más:\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `datos_remitente` | object | sí | Quien envía la mercadería: `codigo_tipo_documento_identidad`, `descripcion_tipo_documento_identidad`, `numero_documento`, `apellidos_y_nombres_o_razon_social`. |\n| `datos_destinatario` | object | sí | Quien recibe la mercadería; mismas claves que `datos_remitente`. |\n| `direcciones_proveedores` | object | sí | `remitente` y `destinatario`, cada uno con `ubigeo` y `direccion`. |\n| `fecha_entrega_transporte` | string `AAAA-MM-DD` | no | Fecha de entrega de los bienes al transportista. |\n| `chofer` | object | sí | Conductor: `codigo_tipo_documento_identidad`, `numero_documento`, `nombres`, `numero_licencia`, `telefono`. |\n| `pagador_flete` | object | no | Quién paga el flete: `indicador_pagador_flete`, `codigo_tipo_documento_identidad`, `numero`, `nombres`. |\n\n### Respuesta\n\n`data.external_id` (guárdalo), `data.number` y `data.filename`.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "V001-15",
                        "filename": "11111111111-31-V001-15",
                        "external_id": "e6ed6e38-a44f-427d-9c3d-3026feb6b0e0"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada V009, es incorrecta."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "gu_a_transportista": {
                  "summary": "Guía transportista",
                  "description": "Guía que emite la empresa de transporte.",
                  "value": {
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "serie_documento": "V001",
                    "numero_documento": "#",
                    "codigo_tipo_documento": "31",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "fecha_de_traslado": "2026-10-27",
                    "unidad_peso_total": "KGM",
                    "peso_total": 30,
                    "indicador_de_transbordo": false,
                    "datos_remitente": {
                      "codigo_tipo_documento_identidad": "6",
                      "descripcion_tipo_documento_identidad": "RUC",
                      "numero_documento": "20601274133",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ"
                    },
                    "datos_destinatario": {
                      "codigo_tipo_documento_identidad": "6",
                      "descripcion_tipo_documento_identidad": "RUC",
                      "numero_documento": "20601274133",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ"
                    },
                    "chofer": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "41784439",
                      "nombres": "JUAN",
                      "apellidos": "PEREZ",
                      "numero_licencia": "Q41784439"
                    },
                    "vehiculo": {
                      "numero_de_placa": "FDA574",
                      "modelo": "MODELO 2",
                      "marca": "HYUNDAI",
                      "certificado_habilitacion_vehicular": "98745613212"
                    },
                    "direcciones_proveedores": {
                      "remitente": {
                        "direccion": "Av. 2 de Mayo",
                        "ubigeo": "150101"
                      },
                      "destinatario": {
                        "direccion": "Ac. Manco capac",
                        "ubigeo": "150115"
                      }
                    },
                    "numero_de_placa": "A011254",
                    "items": [
                      {
                        "codigo_interno": "prueba",
                        "cantidad": 2
                      }
                    ]
                  }
                },
                "gu_a_transportista_con_pagador_del_flete": {
                  "summary": "Guía transportista con pagador del flete",
                  "description": "Indica quién paga el flete (`pagador_flete`).",
                  "value": {
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "serie_documento": "V001",
                    "numero_documento": "#",
                    "codigo_tipo_documento": "31",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "fecha_de_traslado": "2026-10-27",
                    "unidad_peso_total": "KGM",
                    "peso_total": 30.0,
                    "indicador_de_transbordo": false,
                    "datos_remitente": {
                      "codigo_tipo_documento_identidad": "6",
                      "descripcion_tipo_documento_identidad": "RUC",
                      "numero_documento": "20601274133",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ"
                    },
                    "datos_destinatario": {
                      "codigo_tipo_documento_identidad": "6",
                      "descripcion_tipo_documento_identidad": "RUC",
                      "numero_documento": "20601274133",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ"
                    },
                    "chofer": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "41784439",
                      "nombres": "JUAN",
                      "apellidos": "PEREZ",
                      "numero_licencia": "Q41784439"
                    },
                    "numero_de_placa": "A011254",
                    "items": [
                      {
                        "codigo_interno": "prueba",
                        "cantidad": 2
                      }
                    ],
                    "pagador_flete": {
                      "indicador_pagador_flete": "Remitente",
                      "codigo_tipo_documento_identidad": "6",
                      "descripcion_tipo_documento_identidad": "RUC",
                      "numero": "20810001281",
                      "nombres": "EMPRESA DEMO SAC"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatches/send": {
      "post": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Enviar guía a SUNAT",
        "operationId": "EnviarGuaASunat",
        "description": "Envía a SUNAT una guía ya registrada (remitente o transportista). SUNAT responde con un ticket: la guía queda en estado enviado hasta que consultes **Consultar ticket de guía**.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí | `external_id` de la guía. |\n\n### Respuesta\n\n`success` y `message`. Los errores también llegan con HTTP 200 y `success: false`.",
        "responses": {
          "200": {
            "description": "Respuesta correcta / External id incorrecto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "message": "La guía ha sido enviada"
                    }
                  },
                  "e2": {
                    "summary": "External id incorrecto",
                    "value": {
                      "success": false,
                      "message": "El external id es incorrecto"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "enviar_gu_a_a_sunat": {
                  "summary": "Enviar guía a SUNAT",
                  "description": "",
                  "value": {
                    "external_id": "e6ed6e38-a44f-427d-9c3d-3026feb6b0e0"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatches/status_ticket": {
      "post": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Consultar ticket de guía",
        "operationId": "ConsultarTicketDeGua",
        "description": "Consulta en SUNAT el resultado del envío de una guía. Si fue aceptada, devuelve los enlaces al XML, PDF y CDR.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí | `external_id` de la guía enviada. |\n\n### Respuesta\n\n`success: true` y los enlaces de descarga si SUNAT aceptó; `success: false` con el mensaje de SUNAT si fue rechazada o sigue en proceso.",
        "responses": {
          "200": {
            "description": "Respuesta correcta / External id incorrecto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "message": "Consulta de ticket"
                    }
                  },
                  "e2": {
                    "summary": "External id incorrecto",
                    "value": {
                      "success": false,
                      "message": "El external id es incorrecto"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "consultar_ticket_de_gu_a": {
                  "summary": "Consultar ticket de guía",
                  "description": "",
                  "value": {
                    "external_id": "e6ed6e38-a44f-427d-9c3d-3026feb6b0e0"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/retentions": {
      "post": {
        "tags": [
          "Retenciones y percepciones"
        ],
        "summary": "Emitir comprobante de retención",
        "operationId": "EmitirComprobanteDeRetencin",
        "description": "Emite un comprobante de retención (`20`) y lo envía a SUNAT. Solo para empresas designadas agentes de retención.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `serie_documento` | string | sí | Serie de retención registrada. |\n| `numero_documento` | string | sí | `\"#\"` para el siguiente correlativo. |\n| `fecha_de_emision / hora_de_emision` | string | sí | `AAAA-MM-DD` y `HH:MM:SS`. |\n| `codigo_tipo_documento` | string | sí | `20`. |\n| `datos_del_proveedor` | object | sí | `codigo_tipo_documento_identidad`, `numero_documento`, `apellidos_y_nombres_o_razon_social` y opcionales (`direccion`, `ubigeo`, `correo_electronico`). |\n| `totales` | object | sí | Totales retenido y pagado. |\n| `documentos[]` | array | sí | Comprobantes relacionados: tipo, serie, número, fecha, moneda, total, `pagos[]`, `tipo_de_cambio` y montos. |\n| `observaciones` | string | no | Observaciones. |\n| `datos_del_emisor.codigo_del_domicilio_fiscal` | string | sí | Código del establecimiento emisor (ej. `0000`). |\n| `codigo_tipo_retencion` | string | sí | Catálogo 23: `01` tasa 3%. |\n\n### Respuesta\n\n`data.external_id`, `data.number` y `links` de descarga.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "R001-3",
                        "filename": "11111111111-20-R001-3",
                        "external_id": "9d997b38-92a6-42f2-b827-4b73ec5ca1a3"
                      },
                      "links": {
                        "xml": "https://{subdominio}/downloads/retention/xml/{external_id}",
                        "pdf": "https://{subdominio}/downloads/retention/pdf/{external_id}",
                        "cdr": "https://{subdominio}/downloads/retention/cdr/{external_id}"
                      },
                      "response": {
                        "code": "0",
                        "description": "El Comprobante numero R001-3 ha sido aceptado",
                        "notes": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada R009, es incorrecta."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "emitir_retenci_n": {
                  "summary": "Emitir retención",
                  "description": "",
                  "value": {
                    "serie_documento": "R001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "20",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_proveedor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "codigo_tipo_retencion": "01",
                    "observaciones": "-",
                    "totales": {
                      "total_retenido": 30.0,
                      "total_pagado": 1000.0
                    },
                    "documentos": [
                      {
                        "codigo_tipo_documento": "01",
                        "serie_documento": "F001",
                        "numero_documento": "3",
                        "fecha_de_emision": "2018-10-09",
                        "codigo_tipo_moneda": "PEN",
                        "pagos": [
                          {
                            "fecha_de_pago": "2018-10-09",
                            "total_pago": 200.0,
                            "codigo_tipo_moneda": "PEN"
                          }
                        ],
                        "tipo_de_cambio": {
                          "codigo_tipo_moneda_referencia": "PEN",
                          "codigo_tipo_moneda_objetivo": "PEN",
                          "factor": 1,
                          "fecha_tipo_de_cambio": "2018-10-09"
                        },
                        "fecha_de_retencion": "2018-10-09",
                        "total_documento": 400.0,
                        "total_retenido": 12.0,
                        "total_a_pagar": 412.0,
                        "total_pagado": 412.0
                      },
                      {
                        "codigo_tipo_documento": "01",
                        "serie_documento": "F001",
                        "numero_documento": "4",
                        "fecha_de_emision": "2018-10-09",
                        "codigo_tipo_moneda": "USD",
                        "total_documento": 200.0,
                        "pagos": [
                          {
                            "fecha_de_pago": "2018-10-09",
                            "total_pago": 200.0,
                            "codigo_tipo_moneda": "USD"
                          }
                        ],
                        "tipo_de_cambio": {
                          "codigo_tipo_moneda_referencia": "USD",
                          "codigo_tipo_moneda_objetivo": "PEN",
                          "factor": 3.0,
                          "fecha_tipo_de_cambio": "2018-10-09"
                        },
                        "fecha_de_retencion": "2018-10-09",
                        "total_retenido": 18.0,
                        "total_a_pagar": 618.0,
                        "total_pagado": 618.0
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/perceptions": {
      "post": {
        "tags": [
          "Retenciones y percepciones"
        ],
        "summary": "Emitir comprobante de percepción",
        "operationId": "EmitirComprobanteDePercepcin",
        "description": "Emite un comprobante de percepción (`40`) y lo envía a SUNAT. Solo para empresas designadas agentes de percepción.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `serie_documento` | string | sí | Serie de percepción registrada. |\n| `numero_documento` | string | sí | `\"#\"` para el siguiente correlativo. |\n| `fecha_de_emision / hora_de_emision` | string | sí | `AAAA-MM-DD` y `HH:MM:SS`. |\n| `codigo_tipo_documento` | string | sí | `40`. |\n| `datos_del_cliente_o_receptor` | object | sí | `codigo_tipo_documento_identidad`, `numero_documento`, `apellidos_y_nombres_o_razon_social` y opcionales (`direccion`, `ubigeo`, `correo_electronico`). |\n| `totales` | object | sí | Totales percibido y pagado. |\n| `documentos[]` | array | sí | Comprobantes relacionados: tipo, serie, número, fecha, moneda, total, `pagos[]`, `tipo_de_cambio` y montos. |\n| `observaciones` | string | no | Observaciones. |\n| `codigo_tipo_percepcion` | string | sí | Catálogo 22: `01` venta interna 2%, `02` combustible 1%, `03` tasa especial 0.5%. |\n\n### Respuesta\n\n`data.external_id`, `data.number` y `links` de descarga.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "F001-1",
                        "filename": "20123456789-01-F001-1",
                        "external_id": "uuid"
                      },
                      "links": {
                        "xml": "https://{subdominio}/downloads/document/xml/{external_id}",
                        "pdf": "https://{subdominio}/downloads/document/pdf/{external_id}",
                        "cdr": "https://{subdominio}/downloads/document/cdr/{external_id}"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos inválidos",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada P009, es incorrecta."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "emitir_percepci_n": {
                  "summary": "Emitir percepción",
                  "description": "",
                  "value": {
                    "serie_documento": "P001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "codigo_tipo_documento": "40",
                    "datos_del_emisor": {
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148",
                      "codigo_del_domicilio_fiscal": "0000"
                    },
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10414711225",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "nombre_comercial": "EMPRESA XYZ",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    },
                    "codigo_tipo_percepcion": "01",
                    "observaciones": "-",
                    "totales": {
                      "total_percibido": 30.0,
                      "total_pagado": 1000.0
                    },
                    "documentos": [
                      {
                        "codigo_tipo_documento": "01",
                        "serie_documento": "F001",
                        "numero_documento": "3",
                        "fecha_de_emision": "2018-10-09",
                        "codigo_tipo_moneda": "PEN",
                        "pagos": [
                          {
                            "fecha_de_pago": "2018-10-09",
                            "total_pago": 200.0,
                            "codigo_tipo_moneda": "PEN"
                          }
                        ],
                        "tipo_de_cambio": {
                          "codigo_tipo_moneda_referencia": "PEN",
                          "codigo_tipo_moneda_objetivo": "PEN",
                          "factor": 1,
                          "fecha_tipo_de_cambio": "2018-10-09"
                        },
                        "fecha_de_percepcion": "2018-10-09",
                        "total_documento": 400.0,
                        "total_percibido": 12.0,
                        "total_a_pagar": 412.0,
                        "total_pagado": 412.0
                      },
                      {
                        "codigo_tipo_documento": "01",
                        "serie_documento": "F001",
                        "numero_documento": "4",
                        "fecha_de_emision": "2018-10-09",
                        "codigo_tipo_moneda": "USD",
                        "total_documento": 200.0,
                        "pagos": [
                          {
                            "fecha_de_pago": "2018-10-09",
                            "total_pago": 200.0,
                            "codigo_tipo_moneda": "USD"
                          }
                        ],
                        "tipo_de_cambio": {
                          "codigo_tipo_moneda_referencia": "USD",
                          "codigo_tipo_moneda_objetivo": "PEN",
                          "factor": 3.0,
                          "fecha_tipo_de_cambio": "2018-10-09"
                        },
                        "fecha_de_percepcion": "2018-10-09",
                        "total_percibido": 18.0,
                        "total_a_pagar": 618.0,
                        "total_pagado": 618.0
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sale-note": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Crear nota de venta",
        "operationId": "CrearNotaDeVenta",
        "description": "Registra una nota de venta: documento interno que **no se envía a SUNAT**. Después puede convertirse en factura o boleta con **Generar comprobante desde nota de venta**.\n\nA diferencia de los comprobantes, este endpoint usa los ids internos del facturador (`series_id`, `customer_id`, `item_id`) y los campos en inglés.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `id` | number \\| null | sí | `null` para crear una nueva. |\n| `series_id` | number | sí | Id de la serie de nota de venta. |\n| `number` | number \\| null | sí | `null`: el sistema asigna el correlativo. |\n| `customer_id` | number | sí | Id del cliente (ver **Clientes**). |\n| `date_of_issue / time_of_issue` | string | sí | `AAAA-MM-DD` y `HH:MM:SS`. |\n| `currency_type_id / exchange_rate_sale` | string / number | sí | Moneda (`PEN`/`USD`) y tipo de cambio. |\n| `total_taxed, total_exonerated, total_unaffected, total_igv, total_taxes, total_value, total, …` | number | sí | Totales del documento. |\n| `type_period / quantity_period` | string \\| null / number | sí | Recurrencia: envía `null` y `0` si no aplica. |\n| `items[]` | array | sí | Líneas: `item_id`, `item` (datos del producto), `quantity`, `unit_value`, `unit_price`, `price_type_id`, `affectation_igv_type_id`, `total_base_igv`, `percentage_igv`, `total_igv`, `total_taxes`, `total_value`, `total`. |\n| `payments[]` | array | no | Pagos: `date_of_payment`, `payment_method_type_id`, `payment`, `reference`. |\n\n### Respuesta\n\n`data.id` (úsalo para generar el comprobante), `data.number` y enlaces de impresión.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 88,
                        "number": "NV01-15",
                        "external_id": "3f1c2a9e-7b1d-4c55-9a3e-0d6f5b2a1c11",
                        "filename": "NV01-15-20261003",
                        "print_ticket": "https://demo.midominio.pe/sale-notes/print/3f1c2a9e-7b1d-4c55-9a3e-0d6f5b2a1c11/ticket"
                      },
                      "print": {
                        "auto_printed": false,
                        "print_order_id": null,
                        "reason": "disabled"
                      },
                      "links": {
                        "pdf": "https://demo.midominio.pe/downloads/salenote/sale_note/3f1c2a9e-7b1d-4c55-9a3e-0d6f5b2a1c11"
                      },
                      "data_ws": {
                        "message_text": "Su comprobante de pago electrónico NV01-15 ha sido generado correctamente, puede revisarlo en el siguiente enlace: https://demo.midominio.pe/print/document/3f1c2a9e-7b1d-4c55-9a3e-0d6f5b2a1c11/ticket",
                        "pdf_a4_filename": "https://demo.midominio.pe/api/document-file/salenote/3f1c2a9e-7b1d-4c55-9a3e-0d6f5b2a1c11/a4",
                        "pdf_ticket_filename": "https://demo.midominio.pe/api/document-file/salenote/3f1c2a9e-7b1d-4c55-9a3e-0d6f5b2a1c11/ticket",
                        "full_filename": "NV01-15-20261003.pdf",
                        "customer_telephone": "999999999"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "Error al registrar la nota de venta."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "crear_nota_de_venta": {
                  "summary": "Crear nota de venta",
                  "description": "",
                  "value": {
                    "prefix": "NV",
                    "series_id": 10,
                    "establishment_id": null,
                    "date_of_issue": "2026-10-27",
                    "time_of_issue": "10:30:00",
                    "customer_id": 36,
                    "currency_type_id": "PEN",
                    "purchase_order": null,
                    "exchange_rate_sale": 0,
                    "total_prepayment": 0,
                    "total_charge": 0,
                    "total_discount": 0,
                    "total_exportation": 0,
                    "total_free": 0,
                    "total_taxed": 0,
                    "total_unaffected": 0,
                    "total_exonerated": 100,
                    "total_igv": 0,
                    "total_base_isc": 0,
                    "total_isc": 0,
                    "total_base_other_taxes": 0,
                    "total_other_taxes": 0,
                    "total_taxes": 0,
                    "total_value": 100,
                    "total": 100,
                    "operation_type_id": null,
                    "items": [
                      {
                        "item_id": 1181,
                        "item": {
                          "id": 1181,
                          "item_id": 1181,
                          "name": null,
                          "full_description": "111111111111 - agua",
                          "description": "agua",
                          "currency_type_id": "PEN",
                          "internal_id": "111111111111",
                          "item_code": null,
                          "currency_type_symbol": "S/",
                          "sale_unit_price": "100.00",
                          "purchase_unit_price": "0.000000",
                          "unit_type_id": "NIU",
                          "sale_affectation_igv_type_id": "20",
                          "purchase_affectation_igv_type_id": "10",
                          "calculate_quantity": false,
                          "has_igv": true,
                          "is_set": false,
                          "aux_quantity": 1,
                          "brand": "CIELO",
                          "category": "CIELO",
                          "stock": -145,
                          "image": "https://demo.facturalo.pro/logo/imagen-no-disponible.jpg",
                          "warehouses": [
                            {
                              "warehouse_description": "Almacén Oficina Principal",
                              "stock": "-145.0000",
                              "warehouse_id": 1
                            },
                            {
                              "warehouse_description": "Almacén - Oficina Arequipa",
                              "stock": "-1.0000",
                              "warehouse_id": 4
                            }
                          ],
                          "unit_price": "100.00",
                          "presentation": null
                        },
                        "currency_type_id": "PEN",
                        "quantity": 1,
                        "unit_value": 100,
                        "affectation_igv_type_id": "20",
                        "affectation_igv_type": {
                          "id": "20",
                          "active": 1,
                          "exportation": 0,
                          "free": 0,
                          "description": "Exonerado - Operación Onerosa"
                        },
                        "total_base_igv": 100,
                        "percentage_igv": 18,
                        "total_igv": 0,
                        "system_isc_type_id": null,
                        "total_base_isc": 0,
                        "percentage_isc": 0,
                        "total_isc": 0,
                        "total_base_other_taxes": 0,
                        "percentage_other_taxes": 0,
                        "total_other_taxes": 0,
                        "total_plastic_bag_taxes": 0,
                        "total_taxes": 0,
                        "price_type_id": "01",
                        "unit_price": 100,
                        "total_value": 100,
                        "total_discount": 0,
                        "total_charge": 0,
                        "total": 100,
                        "attributes": [],
                        "charges": [],
                        "discounts": []
                      }
                    ],
                    "charges": [],
                    "discounts": [],
                    "attributes": [],
                    "guides": [],
                    "payments": [],
                    "additional_information": null,
                    "actions": {
                      "format_pdf": "a4"
                    },
                    "apply_concurrency": false,
                    "type_period": null,
                    "quantity_period": 0,
                    "automatic_date_of_issue": null,
                    "enabled_concurrency": false,
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "10417844398",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo",
                      "correo_electronico": "demo@gmail.com",
                      "telefono": "427-1148"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sale-note/{id}/generate-cpe": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Generar comprobante desde nota de venta",
        "operationId": "GenerarComprobanteDesdeNotaDeVenta",
        "description": "Convierte una nota de venta en factura o boleta, con los mismos ítems y totales.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `id (ruta)` | number | sí | Id de la nota de venta. |\n| `codigo_tipo_documento` | string | sí | `01` factura o `03` boleta. |\n| `serie_documento` | string | sí | Serie del comprobante. |\n| `numero_documento` | string | sí | Número del comprobante. |\n| `fecha_de_emision / hora_de_emision` | string | sí | `AAAA-MM-DD` y `HH:MM:SS`. |\n| `fecha_de_vencimiento` | string `AAAA-MM-DD` | sí | Fecha de vencimiento. |\n| `codigo_condicion_de_pago` | string | no | `01` contado o `02` crédito. |\n\n### Respuesta\n\n- `data.external_id`: identificador del comprobante. **Guárdalo**: se usa para consultar, anular, emitir notas y descargar archivos.\n- `data.number`: serie y número asignados (ej. `F001-26`).\n- `data.state_type_id`: estado (`01` registrado, `03` enviado, `05` aceptado, `07` observado, `09` rechazado, `11` anulado).\n- `links`: URLs de descarga del XML, PDF y CDR. `cdr` llega vacío si el comprobante no se envió a SUNAT.\n- `response`: respuesta de SUNAT (código y descripción). Llega vacía si no se envió.\n\nLas **boletas** no se envían una por una: SUNAT las recibe en el resumen diario (carpeta **Resúmenes diarios**).",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "F001-1",
                        "filename": "20123456789-01-F001-1",
                        "external_id": "uuid"
                      },
                      "links": {
                        "xml": "https://{subdominio}/downloads/document/xml/{external_id}",
                        "pdf": "https://{subdominio}/downloads/document/pdf/{external_id}",
                        "cdr": "https://{subdominio}/downloads/document/cdr/{external_id}"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "La nota de venta asociada no existe."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "15"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "generar_comprobante_desde_nota_de_venta": {
                  "summary": "Generar comprobante desde nota de venta",
                  "description": "",
                  "value": {
                    "codigo_tipo_documento": "01",
                    "serie_documento": "F001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-10-27",
                    "hora_de_emision": "10:30:00",
                    "fecha_de_vencimiento": "2026-10-27",
                    "codigo_condicion_de_pago": "01"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quotations": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Crear cotización",
        "operationId": "CrearCotizacin",
        "description": "Registra una cotización (documento interno, no se envía a SUNAT). Usa los ids internos del facturador y los campos en inglés, igual que la nota de venta.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `customer_id` | number | sí | Id del cliente. |\n| `date_of_issue / time_of_issue` | string | sí | `AAAA-MM-DD` y `HH:MM:SS`. |\n| `currency_type_id / exchange_rate_sale` | string / number | sí | Moneda y tipo de cambio. |\n| `total_taxed, total_igv, total_value, total, …` | number | sí | Totales del documento. |\n| `items[]` | array | sí | Mismas claves que en la nota de venta. |\n| `payments[]` | array | sí | Puede ir vacío `[]`. |\n| `date_of_due / delivery_date / description / contact / phone` | varios | no | Datos opcionales de la cotización. |\n\n### Respuesta\n\n`data.id` y `data.number_full` de la cotización.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "number_full": "COT-8",
                        "external_id": "25fd5675-1ad5-4e7b-9191-9ae4b7f1dde2",
                        "filename": "COT-8-20241108",
                        "print_a4": "https://{subdominio}/quotations/print/{external_id}/a4",
                        "print_ticket": "https://{subdominio}/quotations/print/{external_id}/ticket"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error al procesar",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error al procesar",
                    "value": {
                      "success": false,
                      "message": "Error al registrar la cotización."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "crear_cotizaci_n": {
                  "summary": "Crear cotización",
                  "description": "",
                  "value": {
                    "description": "",
                    "prefix": "COT",
                    "establishment_id": 1,
                    "date_of_issue": "2026-10-27",
                    "time_of_issue": "10:30:00",
                    "customer_id": 4,
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 4.078,
                    "total_prepayment": 0,
                    "total_charge": 0,
                    "total_discount": 0,
                    "total_exportation": 0,
                    "total_free": 0,
                    "total_taxed": 29.66,
                    "total_unaffected": 0,
                    "total_exonerated": 0,
                    "total_igv": 5.34,
                    "total_taxes": 5.34,
                    "total_value": 29.66,
                    "total": 35,
                    "subtotal": 35,
                    "payment_method_type_id": "10",
                    "actions": {
                      "format_pdf": "a4"
                    },
                    "items": [
                      {
                        "item_id": 3,
                        "currency_type_id": "PEN",
                        "quantity": 1,
                        "unit_value": 29.66,
                        "affectation_igv_type_id": "10",
                        "total_base_igv": 29.66,
                        "percentage_igv": 18,
                        "total_igv": 5.34,
                        "price_type_id": "01",
                        "unit_price": 35,
                        "total_value": 29.66,
                        "total": 35
                      }
                    ],
                    "payments": [
                      {
                        "date_of_payment": "2022-02-08",
                        "payment_method_type_id": "01",
                        "payment_destination_id": "cash",
                        "payment": 35
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quotations/list": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Listar cotizaciones",
        "operationId": "ListarCotizaciones",
        "description": "Devuelve las últimas cotizaciones registradas.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Parámetros de consulta\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `input` | number | no | Filtra por id de cotización. |\n\n### Respuesta\n\n`data` con la lista de cotizaciones.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "data": [
                        {
                          "id": 20,
                          "external_id": "6012ffb7-a212-4a8b-8839-0e95374a9155",
                          "number_full": "COT-20",
                          "date_of_issue": "2023-09-21",
                          "customer_name": "ALVAREZ MORENO JHEYSON ALBER",
                          "customer_number": "10750058197",
                          "currency_type_id": "PEN",
                          "total_taxed": "132.73",
                          "total_igv": "13.27",
                          "total": "146.00",
                          "state_type_id": "01",
                          "state_type_description": "Registrado",
                          "filename": "COT-20-20230921"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filtra por id de cotización."
          }
        ]
      }
    },
    "/api/person": {
      "post": {
        "tags": [
          "Clientes"
        ],
        "summary": "Crear cliente",
        "operationId": "CrearCliente",
        "description": "Registra un cliente (o proveedor). Al emitir comprobantes no es necesario crear el cliente antes: se registra solo con `datos_del_cliente_o_receptor`.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `type` | string | sí | `customers` cliente o `suppliers` proveedor. |\n| `identity_document_type_id` | string | sí | Catálogo 06: `1` DNI, `6` RUC, etc. |\n| `number` | string | sí | Número de documento. No puede repetirse. |\n| `name` | string | sí | Nombre o razón social. No puede repetirse. |\n| `country_id` | string | sí | País (`PE`). |\n| `department_id / province_id / district_id` | string | no | Ubigeo por niveles (ej. `15`, `1501`, `150101`). |\n| `address` | string | no | Dirección. |\n| `email` | string | no | Correo válido y no repetido. |\n| `telephone` | string | no | Teléfono. |\n| `trade_name` | string | no | Nombre comercial. |\n\n### Respuesta\n\n`data.id` del cliente y el mensaje en `msg`.\n\n### Errores\n\n`422` si el número o el nombre ya existen o falta un campo obligatorio.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "msg": "Cliente registrado con éxito",
                      "data": {
                        "id": 55,
                        "description": "72346556 - Pedro Diaz",
                        "name": "Pedro Diaz",
                        "number": "72346556",
                        "identity_document_type_id": "1",
                        "address": "Urb Sesquicentenario Vipol Callao",
                        "telephone": "954533737",
                        "country_id": "PE",
                        "selected": false
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Error de validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error de validación",
                    "value": {
                      "message": "The given data was invalid.",
                      "errors": {
                        "number": [
                          "El campo número ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "crear_cliente": {
                  "summary": "Crear cliente",
                  "description": "",
                  "value": {
                    "type": "customers",
                    "identity_document_type_id": "1",
                    "number": "72346556",
                    "name": "Pedro Diaz",
                    "trade_name": "Nombre Comercial",
                    "country_id": "PE",
                    "address": "Urb Sesquicentenario Vipol Callao",
                    "telephone": "954533737",
                    "perception_agent": false,
                    "percentage_perception": 0,
                    "more_address": [],
                    "location_id": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/persons/{tipo}/records": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Listar clientes",
        "operationId": "ListarClientes",
        "description": "Lista paginada de clientes o proveedores, con búsqueda por nombre o número.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Parámetros\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `tipo (ruta)` | string | sí | `customers` clientes o `suppliers` proveedores. |\n| `input` | string | no | Texto a buscar en el nombre o el número de documento. |\n| `page` | number | no | Página. |\n\n### Respuesta\n\n`data` con los registros y `links`/`meta` con la paginación.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "data": [
                        {
                          "id": 9,
                          "description": "91241245 - ADMIN1",
                          "name": "ADMIN1",
                          "number": "91241245",
                          "identity_document_type_id": "1",
                          "address": "callao-ventanilla",
                          "telephone": "921414124",
                          "country_id": "PE",
                          "district_id": "070106",
                          "email": "joserc@gmail.com",
                          "enabled": true,
                          "identity_document_type_description": "DNI"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tipo",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "customers"
          },
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre o número a buscar."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Página.",
            "example": "1"
          }
        ]
      }
    },
    "/api/item": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Crear producto",
        "operationId": "CrearProducto",
        "description": "Registra un producto o servicio. Al emitir comprobantes, un `codigo_interno` que no existe también se crea solo.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `internal_id` | string | sí | Código interno, único. Puede ser opcional si la empresa genera códigos automáticos. |\n| `description` | string | sí | Nombre del producto. |\n| `unit_type_id` | string | sí | Unidad de medida: `NIU` unidad, `ZZ` servicio, etc. |\n| `currency_type_id` | string | sí | `PEN` o `USD`. |\n| `sale_unit_price` | number | sí | Precio de venta (mayor que 0). |\n| `purchase_unit_price` | number | sí | Precio de compra. |\n| `has_igv` | boolean | no | `true` si el precio de venta incluye IGV. |\n| `stock / stock_min` | number | sí | Stock inicial y stock mínimo. |\n| `sale_affectation_igv_type_id / purchase_affectation_igv_type_id` | string | sí | Afectación IGV en venta y compra (`10` gravado, `20` exonerado, `30` inafecto). |\n| `item_code` | string | no | Código de producto SUNAT de 8 dígitos. |\n| `barcode / model` | string | no | Código de barras y modelo. |\n\n### Respuesta\n\n`data.id` del producto y el mensaje en `msg`.\n\n### Errores\n\n`422` si el código interno ya existe o falta un campo obligatorio.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "msg": "Producto registrado con éxito",
                      "data": {
                        "id": 290,
                        "item_id": 290,
                        "name": "apk",
                        "full_description": "j2 - apk",
                        "description": "apk",
                        "currency_type_id": "PEN",
                        "internal_id": "j2",
                        "sale_unit_price": "500.00",
                        "unit_type_id": "NIU",
                        "sale_affectation_igv_type_id": "10",
                        "has_igv": true
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Error de validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error de validación",
                    "value": {
                      "message": "The given data was invalid.",
                      "errors": {
                        "internal_id": [
                          "El campo código interno ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "crear_producto": {
                  "summary": "Crear producto",
                  "description": "",
                  "value": {
                    "id": null,
                    "item_type_id": "01",
                    "internal_id": "rrr",
                    "item_code": null,
                    "item_code_gs1": null,
                    "description": "apk",
                    "name": "apk",
                    "second_name": null,
                    "unit_type_id": "NIU",
                    "currency_type_id": "PEN",
                    "sale_unit_price": "500",
                    "purchase_unit_price": 0,
                    "has_isc": false,
                    "system_isc_type_id": null,
                    "percentage_isc": 0,
                    "suggested_price": 0,
                    "sale_affectation_igv_type_id": "10",
                    "purchase_affectation_igv_type_id": "10",
                    "calculate_quantity": false,
                    "stock": 0,
                    "stock_min": 0,
                    "has_igv": true,
                    "has_perception": false,
                    "item_unit_types": [],
                    "percentage_of_profit": 0,
                    "percentage_perception": 0,
                    "image": null,
                    "image_url": null,
                    "temp_path": null,
                    "is_set": false,
                    "account_id": null,
                    "category_id": null,
                    "brand_id": null,
                    "date_of_due": null,
                    "lot_code": null,
                    "lots_enabled": false,
                    "lots": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/items/{id}/update": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Editar producto",
        "operationId": "EditarProducto",
        "description": "Actualiza los datos principales de un producto. Solo se modifican los campos de la tabla; cualquier otro campo enviado se ignora.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `id (ruta)` | number | sí | Id del producto. |\n| `internal_id` | string | sí | Código interno (máx. 30, único). |\n| `description` | string | sí | Nombre (máx. 500). |\n| `sale_unit_price` | number | sí | Precio de venta (mayor que 0). |\n| `stock_min` | number | sí | Stock mínimo. |\n| `has_igv` | boolean | no | Precio incluye IGV. |\n| `barcode` | string | no | Código de barras (máx. 150). |\n| `model` | string | no | Modelo (máx. 100). |\n| `item_code` | string | no | Código SUNAT de 8 dígitos. |\n\n### Errores\n\n`404` si el producto no existe; `422` si un campo no es válido.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "msg": "Producto actualizado con éxito",
                      "data": {
                        "id": 290,
                        "item_id": 290,
                        "name": "apk",
                        "full_description": "j2 - apk",
                        "description": "apk",
                        "currency_type_id": "PEN",
                        "internal_id": "j2",
                        "sale_unit_price": "500.00",
                        "unit_type_id": "NIU",
                        "sale_affectation_igv_type_id": "10",
                        "has_igv": true
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Error de validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error de validación",
                    "value": {
                      "message": "The given data was invalid.",
                      "errors": {
                        "sale_unit_price": [
                          "El precio de venta debe ser mayor que 0."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "290"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "editar_producto": {
                  "summary": "Editar producto",
                  "description": "",
                  "value": {
                    "id": 3946,
                    "item_type_id": "01",
                    "internal_id": "rrr",
                    "item_code": "new_code",
                    "item_code_gs1": null,
                    "description": "apk",
                    "name": "apk",
                    "second_name": null,
                    "unit_type_id": "NIU",
                    "currency_type_id": "PEN",
                    "sale_unit_price": "500",
                    "purchase_unit_price": 0,
                    "has_isc": false,
                    "system_isc_type_id": null,
                    "percentage_isc": 0,
                    "suggested_price": 0,
                    "sale_affectation_igv_type_id": "10",
                    "purchase_affectation_igv_type_id": "10",
                    "calculate_quantity": false,
                    "stock": 0,
                    "stock_min": 0,
                    "has_igv": true,
                    "has_perception": false,
                    "item_unit_types": [],
                    "percentage_of_profit": 0,
                    "percentage_perception": 0,
                    "image": null,
                    "image_url": null,
                    "temp_path": null,
                    "is_set": false,
                    "account_id": null,
                    "category_id": null,
                    "brand_id": null,
                    "date_of_due": null,
                    "lot_code": null,
                    "lots_enabled": false,
                    "lots": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/document/search-items": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Buscar productos",
        "operationId": "BuscarProductos",
        "description": "Busca productos activos por descripción o código interno, o por código de barras exacto.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Parámetros de consulta\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `input` | string | sí | Texto a buscar (o el código de barras). |\n| `search_by_barcode` | number | no | `1` busca por código de barras exacto. |\n| `category_id` | number | no | Filtra por categoría. |\n| `limit` | number | no | Máximo de resultados. |\n\n### Respuesta\n\nLista de productos con precio, stock del almacén del usuario y afectación IGV.",
        "responses": {
          "200": {
            "description": "Respuesta correcta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "data": {
                        "items": [
                          {
                            "id": 10,
                            "item_id": 10,
                            "name": null,
                            "full_description": "P0121 - Inca Kola 250 ml",
                            "description": "Inca Kola 250 ml",
                            "currency_type_id": "PEN",
                            "internal_id": "P0121",
                            "item_code": "51121703",
                            "currency_type_symbol": "S/",
                            "sale_unit_price": "59.00",
                            "purchase_unit_price": "40.000000",
                            "unit_type_id": "NIU",
                            "sale_affectation_igv_type_id": "10",
                            "purchase_affectation_igv_type_id": "10",
                            "calculate_quantity": false,
                            "has_igv": true,
                            "is_set": false,
                            "lots": [],
                            "aux_quantity": 1,
                            "brand": "Inca Kola",
                            "category": "Bebidas",
                            "item_unit_types": [
                              {
                                "id": 1,
                                "description": "Caja x 12",
                                "unit_type_id": "BX",
                                "quantity_unit": "12.00",
                                "price1": "600.00",
                                "price2": "0.00",
                                "price3": "0.00",
                                "price_default": 1
                              }
                            ],
                            "stock": "50.0000",
                            "image": "https://demo.midominio.com/logo/imagen-no-disponible.jpg",
                            "warehouses": [
                              {
                                "warehouse_id": 1,
                                "establishment_id": 1,
                                "warehouse_description": "Almacén Oficina Principal",
                                "stock": 50
                              }
                            ],
                            "favorite": false,
                            "barcode": "7750000000012",
                            "brand_id": 1,
                            "category_id": 1,
                            "has_isc": false,
                            "system_isc_type_id": null,
                            "percentage_isc": "0.00"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar.",
            "example": "inca"
          },
          {
            "name": "search_by_barcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "1 = código de barras exacto.",
            "example": "0"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Máximo de resultados.",
            "example": "20"
          }
        ]
      }
    },
    "/api/inventory/transaction": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Registrar ingreso o salida de inventario",
        "operationId": "RegistrarIngresoOSalidaDeInventario",
        "description": "Registra un ingreso o una salida de stock de un producto en un almacén.\n\n**Autenticación:** `Authorization: Bearer <token>`. El token es el `api_token` del usuario; ver la carpeta **1. Inicio**.\n\n### Campos\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `type` | string | sí | `input` ingreso u `output` salida. |\n| `inventory_transaction_id` | string | sí | Motivo del movimiento según el catálogo de motivos de inventario del facturador (ej. `02` compra, `03` ingreso por ajuste). |\n| `item_code` | string | sí | Código interno del producto. |\n| `quantity` | number | sí | Cantidad (mínimo 0.01). |\n| `warehouse_id` | number | sí | Id del almacén. |\n\n### Errores\n\nLlegan con HTTP 200 y `success: false`: producto no encontrado o, en salidas, cantidad mayor al stock del almacén.",
        "responses": {
          "200": {
            "description": "Respuesta correcta / Producto no encontrado / Stock insuficiente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Respuesta correcta",
                    "value": {
                      "success": true,
                      "message": "Ingreso registrado correctamente"
                    }
                  },
                  "e2": {
                    "summary": "Producto no encontrado",
                    "value": {
                      "success": false,
                      "message": "No se encontró un producto con el codigo ingresado"
                    }
                  },
                  "e3": {
                    "summary": "Stock insuficiente",
                    "value": {
                      "success": false,
                      "message": "La cantidad no puede ser mayor a la que se tiene en el almacén."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token inválido o ausente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Token inválido o ausente",
                    "value": {
                      "message": "Unauthenticated."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "ingreso_de_inventario": {
                  "summary": "Ingreso de inventario",
                  "description": "",
                  "value": {
                    "type": "input",
                    "inventory_transaction_id": "03",
                    "item_code": "CODPROD130",
                    "quantity": 100,
                    "warehouse_id": 1
                  }
                },
                "salida_de_inventario": {
                  "summary": "Salida de inventario",
                  "description": "",
                  "value": {
                    "type": "output",
                    "inventory_transaction_id": "01",
                    "item_code": "CODPROD130",
                    "quantity": 3,
                    "warehouse_id": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/downloads/document/pdf/{external_id}/{formato}": {
      "get": {
        "tags": [
          "Descargas"
        ],
        "summary": "Descargar PDF",
        "operationId": "DescargarPdf",
        "description": "Descarga el PDF del comprobante. Son las mismas URLs que llegan en `links` al emitirlo.\n\n**Autenticación:** no requiere token. Basta el `external_id`.\n\n### Parámetros de ruta\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí | `external_id` del comprobante. |\n| `formato` | string | no | `a4` (defecto), `a5` o `ticket`. |\n\n### Respuesta\n\nEl archivo `.pdf`. En Postman usa **Send and Download** para guardarlo.",
        "responses": {
          "200": {
            "description": "Archivo",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
          },
          {
            "name": "formato",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "a4"
          }
        ]
      }
    },
    "/downloads/document/xml/{external_id}": {
      "get": {
        "tags": [
          "Descargas"
        ],
        "summary": "Descargar XML",
        "operationId": "DescargarXml",
        "description": "Descarga el XML firmado del comprobante. Son las mismas URLs que llegan en `links` al emitirlo.\n\n**Autenticación:** no requiere token. Basta el `external_id`.\n\n### Parámetros de ruta\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí | `external_id` del comprobante. |\n\n### Respuesta\n\nEl archivo `.xml`. En Postman usa **Send and Download** para guardarlo.",
        "responses": {
          "200": {
            "description": "Archivo",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
          }
        ]
      }
    },
    "/downloads/document/cdr/{external_id}": {
      "get": {
        "tags": [
          "Descargas"
        ],
        "summary": "Descargar CDR",
        "operationId": "DescargarCdr",
        "description": "Descarga el CDR (constancia de recepción de SUNAT) del comprobante. Son las mismas URLs que llegan en `links` al emitirlo.\n\n**Autenticación:** no requiere token. Basta el `external_id`.\n\n### Parámetros de ruta\n\n| Campo | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `external_id` | string | sí | `external_id` del comprobante. |\n\n### Respuesta\n\nEl archivo `.zip` (ZIP con el CDR de SUNAT). En Postman usa **Send and Download** para guardarlo.",
        "responses": {
          "200": {
            "description": "Archivo",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
          }
        ]
      }
    },
    "/api/version": {
      "get": {
        "tags": [
          "Consultas"
        ],
        "summary": "Consultar versión de la API",
        "operationId": "ConsultarVersionApi",
        "description": "Devuelve la versión de la API y su nivel de compatibilidad (`api_level`). Consúltalo **antes de iniciar sesión** para comprobar que tu integración es compatible con el servidor: si el `api_level` del servidor es mayor que el que soporta tu integración, revisa las novedades antes de continuar.\n\n**Endpoint público:** no requiere token.\n\n**Formato de respuesta:** heredado **sin envoltura** `{version, api_level}` (sin `success`).\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `version` | string | Versión de la API. |\n| `api_level` | integer | Nivel de compatibilidad; sube cuando hay cambios que una integración debe conocer. |",
        "responses": {
          "200": {
            "description": "200 OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "200 OK",
                    "value": {
                      "version": "v9.5",
                      "api_level": 1
                    }
                  }
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/establishments": {
      "get": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Listar establecimientos",
        "operationId": "ListarEstablecimientos",
        "description": "Lista los establecimientos ordenados por id, con paginación por cursor.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 2,
                          "description": "SUCURSAL MIRAFLORES",
                          "country_id": "PE",
                          "department_id": "15",
                          "province_id": "1501",
                          "district_id": "150122",
                          "address": "AV. LARCO 456",
                          "addresses": [],
                          "telephone": "014445566",
                          "email": "miraflores@empresa.com",
                          "code": "0001",
                          "trade_address": "AV. LARCO 456 - MIRAFLORES",
                          "web_address": "https://empresa.com",
                          "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                          "customer_id": null,
                          "customer_number": null,
                          "logo": null,
                          "has_igv_31556": false,
                          "template_pdf": "default",
                          "template_ticket_pdf": "default",
                          "department": "LIMA",
                          "province": "LIMA",
                          "district": "MIRAFLORES",
                          "warehouse_id": 2
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre (`description`) o código (`code`)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Crear establecimiento",
        "operationId": "CrearEstablecimiento",
        "description": "Registra un establecimiento y crea su almacén.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Nombre del establecimiento. Único en la empresa. |\n| `code` | string | Sí (al crear) | Código de domicilio fiscal (anexo SUNAT), p. ej. `0000` para el domicilio fiscal o `0001`, `0002`... Único. **No se puede cambiar al editar** (se ignora). |\n| `country_id` | string | No | Código de país. Por defecto `PE`. |\n| `department_id` | string | Sí | Ubigeo del departamento (2 dígitos), p. ej. `15` = Lima. |\n| `province_id` | string | Sí | Ubigeo de la provincia (4 dígitos), p. ej. `1501` = Lima. |\n| `district_id` | string | Sí | Ubigeo del distrito (6 dígitos, código INEI/SUNAT), p. ej. `150122` = Miraflores, `150101` = Lima. |\n| `address` | string | Sí | Dirección. |\n| `telephone` | string | Sí | Teléfono. |\n| `email` | string | No | Correo. Debe tener formato de correo válido (salvo que la empresa haya desactivado esa validación). |\n| `trade_address` | string | No | Dirección comercial que se imprime en los comprobantes. |\n| `web_address` | string | No | Página web. |\n| `aditional_information` | string | No | Información adicional que se imprime en los comprobantes. |\n| `customer_id` | integer | No | Cliente por defecto del establecimiento (id de cliente). |\n| `template_pdf` | string | No | Plantilla PDF A4 (por defecto `default`). |\n| `template_ticket_pdf` | string | No | Plantilla PDF ticket (por defecto `default`). |\n| `has_igv_31556` | boolean | No | `true` si el establecimiento aplica la tasa de IGV reducida de la Ley 31556. |\n| `addresses` | array | No | Direcciones de partida para guías de remisión. Cada elemento: `address` (string), `location_id` (array `[departamento, provincia, distrito]`), `is_default` (bool), `is_active` (bool), `establishment_code` (string), `country_id` (string). Al editar, si se envía, **reemplaza** todas las direcciones existentes. |\n\n**Errores:**\n- `422` si falta un campo obligatorio, si `description` o `code` ya existen, o si `email` no es válido.\n\n**Almacén:** al crear el establecimiento se crea **automáticamente su almacén** (con el mismo nombre). Consulta su id con `GET /api/warehouses?establishment_id=<id>`: no asumas que es igual al id del establecimiento.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "SUCURSAL MIRAFLORES",
                        "country_id": "PE",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150122",
                        "address": "AV. LARCO 456",
                        "addresses": [
                          {
                            "id": 3,
                            "address": "AV. LARCO 456 - ALMACÉN",
                            "location_id": [
                              "15",
                              "1501",
                              "150122"
                            ],
                            "is_default": true,
                            "is_active": true,
                            "establishment_id": 2,
                            "establishment_code": "0001",
                            "country_id": "PE"
                          }
                        ],
                        "telephone": "014445566",
                        "email": "miraflores@empresa.com",
                        "code": "0001",
                        "trade_address": "AV. LARCO 456 - MIRAFLORES",
                        "web_address": "https://empresa.com",
                        "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                        "customer_id": null,
                        "customer_number": null,
                        "logo": null,
                        "has_igv_31556": false,
                        "template_pdf": "default",
                        "template_ticket_pdf": "default",
                        "department": "LIMA",
                        "province": "LIMA",
                        "district": "MIRAFLORES",
                        "warehouse_id": 2
                      },
                      "message": "Establecimiento registrado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Código repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Código repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "code": [
                          "El código de domicilio fiscal ingresado ya existe. Por favor ingrese uno nuevo"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear establecimiento",
                  "value": {
                    "description": "SUCURSAL MIRAFLORES",
                    "code": "0001",
                    "country_id": "PE",
                    "department_id": "15",
                    "province_id": "1501",
                    "district_id": "150122",
                    "address": "AV. LARCO 456",
                    "telephone": "014445566",
                    "email": "miraflores@empresa.com",
                    "trade_address": "AV. LARCO 456 - MIRAFLORES",
                    "web_address": "https://empresa.com",
                    "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                    "customer_id": null,
                    "template_pdf": "default",
                    "template_ticket_pdf": "default",
                    "has_igv_31556": false,
                    "addresses": [
                      {
                        "address": "AV. LARCO 456 - ALMACÉN",
                        "location_id": [
                          "15",
                          "1501",
                          "150122"
                        ],
                        "is_default": true,
                        "is_active": true,
                        "establishment_code": "0001",
                        "country_id": "PE"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/establishments/{establishment_id}": {
      "get": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Ver establecimiento",
        "operationId": "VerEstablecimiento",
        "description": "Devuelve un establecimiento con sus direcciones de partida, ubigeo descrito y el id de su almacén.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "SUCURSAL MIRAFLORES",
                        "country_id": "PE",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150122",
                        "address": "AV. LARCO 456",
                        "addresses": [],
                        "telephone": "014445566",
                        "email": "miraflores@empresa.com",
                        "code": "0001",
                        "trade_address": "AV. LARCO 456 - MIRAFLORES",
                        "web_address": "https://empresa.com",
                        "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                        "customer_id": null,
                        "customer_number": null,
                        "logo": null,
                        "has_igv_31556": false,
                        "template_pdf": "default",
                        "template_ticket_pdf": "default",
                        "department": "LIMA",
                        "province": "LIMA",
                        "district": "MIRAFLORES",
                        "warehouse_id": 2
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "establishment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Editar establecimiento",
        "operationId": "EditarEstablecimiento",
        "description": "Edita un establecimiento. Acepta `PUT` o `PATCH`; en ambos casos la **edición es parcial**: los campos que no envíes conservan su valor actual.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\nCampos: los mismos de *Crear establecimiento*. `code` **no se puede cambiar** (si se envía, se ignora). Si cambias `description`, el almacén del establecimiento se renombra. `addresses`, si se envía, reemplaza todas las direcciones de partida.\n\n**Errores:** `404` si no existe; `422` si el nuevo nombre ya existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "SUCURSAL MIRAFLORES 2",
                        "country_id": "PE",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150122",
                        "address": "AV. LARCO 456",
                        "addresses": [],
                        "telephone": "014445599",
                        "email": "miraflores@empresa.com",
                        "code": "0001",
                        "trade_address": "AV. LARCO 460 - MIRAFLORES",
                        "web_address": "https://empresa.com",
                        "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                        "customer_id": null,
                        "customer_number": null,
                        "logo": null,
                        "has_igv_31556": false,
                        "template_pdf": "default",
                        "template_ticket_pdf": "default",
                        "department": "LIMA",
                        "province": "LIMA",
                        "district": "MIRAFLORES",
                        "warehouse_id": 2
                      },
                      "message": "Establecimiento actualizado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Nombre repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Nombre repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "description": [
                          "description ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "establishment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar establecimiento",
                  "value": {
                    "description": "SUCURSAL MIRAFLORES 2",
                    "telephone": "014445599",
                    "trade_address": "AV. LARCO 460 - MIRAFLORES"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Eliminar establecimiento",
        "operationId": "EliminarEstablecimiento",
        "description": "Elimina un establecimiento y su almacén.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Responde `409` (no se elimina) cuando:**\n- es el único establecimiento de la empresa;\n- tiene usuarios asignados;\n- tiene series registradas (elimínalas antes en *2. Series*);\n- su almacén tiene movimientos de inventario;\n- tiene comprobantes u otros registros relacionados.\n\n`404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2
                      },
                      "message": "Establecimiento eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Con usuarios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Con usuarios",
                    "value": {
                      "success": false,
                      "message": "El establecimiento tiene usuarios asignados, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "establishment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/establishments/{establishment_id}/logo": {
      "post": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Subir logo del establecimiento",
        "operationId": "SubirLogoEstablecimiento",
        "description": "Sube o reemplaza el logo del establecimiento (se imprime en sus comprobantes en lugar del logo de la empresa).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\nSe envía como **`multipart/form-data`** (no JSON) con el campo:\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `file` | archivo | Sí | Imagen `jpeg`, `jpg`, `png` o `webp`, máximo 1 MB. Se redimensiona a 450 px de ancho y se guarda como JPG. |\n\nNo envíes `Content-Type` manualmente (lo arma el cliente con el *boundary*).\n\n**Errores:** `422` si falta el archivo, no es una imagen permitida o supera 1 MB; `404` si el establecimiento no existe.",
        "responses": {
          "200": {
            "description": "Logo actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Logo actualizado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "SUCURSAL MIRAFLORES",
                        "country_id": "PE",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150122",
                        "address": "AV. LARCO 456",
                        "addresses": [],
                        "telephone": "014445566",
                        "email": "miraflores@empresa.com",
                        "code": "0001",
                        "trade_address": "AV. LARCO 456 - MIRAFLORES",
                        "web_address": "https://empresa.com",
                        "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                        "customer_id": null,
                        "customer_number": null,
                        "logo": "https://empresa.dominio/storage/uploads/logos/1762531200.jpg",
                        "has_igv_31556": false,
                        "template_pdf": "default",
                        "template_ticket_pdf": "default",
                        "department": "LIMA",
                        "province": "LIMA",
                        "district": "MIRAFLORES",
                        "warehouse_id": 2
                      },
                      "message": "Logo actualizado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Archivo inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Archivo inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "file": [
                          "file debe ser un archivo con formato: jpeg, png, jpg, webp."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "establishment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Imagen jpeg/jpg/png/webp, máx. 1 MB"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Eliminar logo del establecimiento",
        "operationId": "EliminarLogoEstablecimiento",
        "description": "Quita el logo propio del establecimiento (vuelve a usarse el logo de la empresa).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `404` si el establecimiento no existe.",
        "responses": {
          "200": {
            "description": "Logo eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Logo eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "SUCURSAL MIRAFLORES",
                        "country_id": "PE",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150122",
                        "address": "AV. LARCO 456",
                        "addresses": [],
                        "telephone": "014445566",
                        "email": "miraflores@empresa.com",
                        "code": "0001",
                        "trade_address": "AV. LARCO 456 - MIRAFLORES",
                        "web_address": "https://empresa.com",
                        "aditional_information": "Horario: lunes a sábado de 9 a 18 h",
                        "customer_id": null,
                        "customer_number": null,
                        "logo": null,
                        "has_igv_31556": false,
                        "template_pdf": "default",
                        "template_ticket_pdf": "default",
                        "department": "LIMA",
                        "province": "LIMA",
                        "district": "MIRAFLORES",
                        "warehouse_id": 2
                      },
                      "message": "Logo eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "establishment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/establishments/change-user": {
      "post": {
        "tags": [
          "Establecimientos"
        ],
        "summary": "Cambiar mi establecimiento",
        "operationId": "CambiarMiEstablecimiento",
        "description": "Cambia el establecimiento del **usuario del token**. Desde ese momento series, almacén, caja y cliente por defecto se toman del nuevo establecimiento.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `establishment_id` | integer | Sí | Id de un establecimiento existente. |\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`. (id inexistente).",
        "responses": {
          "200": {
            "description": "Cambiado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cambiado",
                    "value": {
                      "success": true,
                      "message": "Establecimiento actualizado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": {
                        "establishment_id": [
                          "El campo establishment id seleccionado es inválido."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar mi establecimiento",
                  "value": {
                    "establishment_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/series": {
      "get": {
        "tags": [
          "Series"
        ],
        "summary": "Listar series",
        "operationId": "ListarSeries",
        "description": "Lista las series ordenadas por establecimiento y tipo de documento.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 12,
                          "establishment_id": 1,
                          "document_type_id": "01",
                          "number": "F002",
                          "contingency": false,
                          "dedicated": false,
                          "in_use": false,
                          "series_device_group_id": null,
                          "group_name": null,
                          "category": "invoice",
                          "document_type_description": "Factura electrónica",
                          "correlative": 150
                        },
                        {
                          "id": 13,
                          "establishment_id": 1,
                          "document_type_id": "03",
                          "number": "B002",
                          "contingency": false,
                          "dedicated": false,
                          "in_use": false,
                          "series_device_group_id": null,
                          "group_name": null,
                          "category": "ticket",
                          "document_type_description": "Boleta de venta electrónica",
                          "correlative": 0
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "establishment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por establecimiento (id numérico)."
          },
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Filtra por tipo de documento (`01`, `03`, `80`...)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Series"
        ],
        "summary": "Crear serie",
        "operationId": "CrearSerie",
        "description": "Registra una serie para un establecimiento.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `establishment_id` | integer | Sí | Establecimiento al que pertenece la serie (ver *1. Establecimientos*). |\n| `document_type_id` | string | Sí | Tipo de documento: `01`, `03`, `07`, `08`, `09`, `31`, `80`... |\n| `number` | string | Sí | Serie de 4 caracteres (ver tabla de formatos). |\n| `contingency` | boolean | No | `true` si es una serie de contingencia (numérica). Por defecto `false`. |\n| `dedicated` | boolean | No | `true` si la serie es dedicada (reservada a un dispositivo o punto de venta). Por defecto `false`. |\n| `series_device_group_id` | integer | No | Grupo de dispositivos al que se asigna la serie. `null` si no aplica. |\n| `correlative` | integer | No | Último número ya emitido con esta serie fuera de la plataforma (≥ 0). El primer comprobante saldrá con `correlative + 1`. `0` = empieza en 1. Solo se puede configurar mientras la serie no tenga comprobantes. |\n\n**Errores:**\n- `422` si falta un campo, el establecimiento no existe o el formato de la serie es inválido (p. ej. una factura que no empieza con `F`).\n- `409` si ya existe la misma serie para ese tipo de documento (`La serie ya ha sido registrada`) o si la empresa es NRUS y el tipo no está permitido.",
        "responses": {
          "201": {
            "description": "Creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 12,
                        "establishment_id": 1,
                        "document_type_id": "01",
                        "number": "F002",
                        "contingency": false,
                        "dedicated": false,
                        "in_use": false,
                        "series_device_group_id": null,
                        "group_name": null,
                        "category": "invoice",
                        "document_type_description": "Factura electrónica",
                        "correlative": 150
                      },
                      "message": "Serie registrada con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Formato inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Formato inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "number": [
                          "El formato de la serie es inválido - Formato del campo: [F][A-Z0-9]{3}, Ejemplo: FF01"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Serie duplicada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Serie duplicada",
                    "value": {
                      "success": false,
                      "message": "La serie ya ha sido registrada"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear serie",
                  "value": {
                    "establishment_id": 1,
                    "document_type_id": "01",
                    "number": "F002",
                    "contingency": false,
                    "dedicated": false,
                    "series_device_group_id": null,
                    "correlative": 150
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/series/{series_id}": {
      "get": {
        "tags": [
          "Series"
        ],
        "summary": "Ver serie",
        "operationId": "VerSerie",
        "description": "Devuelve una serie con su último correlativo configurado (`correlative`) y si ya está en uso.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 12,
                        "establishment_id": 1,
                        "document_type_id": "01",
                        "number": "F002",
                        "contingency": false,
                        "dedicated": false,
                        "in_use": false,
                        "series_device_group_id": null,
                        "group_name": null,
                        "category": "invoice",
                        "document_type_description": "Factura electrónica",
                        "correlative": 150
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "series_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Series"
        ],
        "summary": "Editar serie",
        "operationId": "EditarSerie",
        "description": "Edita una serie. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\nCampos: los mismos de *Crear serie*.\n\n**Errores:**\n- `409` si la serie ya tiene comprobantes y se intenta cambiar `number`, `document_type_id` o `correlative`.\n- `409` si la nueva serie ya existe para ese tipo de documento.\n- `422` por formato inválido; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 12,
                        "establishment_id": 1,
                        "document_type_id": "01",
                        "number": "F002",
                        "contingency": false,
                        "dedicated": true,
                        "in_use": false,
                        "series_device_group_id": null,
                        "group_name": null,
                        "category": "invoice",
                        "document_type_description": "Factura electrónica",
                        "correlative": 200
                      },
                      "message": "Serie editada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Serie en uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Serie en uso",
                    "value": {
                      "success": false,
                      "message": "La serie ya tiene comprobantes emitidos: no se puede cambiar su número ni su tipo de documento."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "series_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar serie",
                  "value": {
                    "correlative": 200,
                    "dedicated": true
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Series"
        ],
        "summary": "Eliminar serie",
        "operationId": "EliminarSerie",
        "description": "Elimina una serie que todavía no tiene comprobantes.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `409` si la serie ya tiene comprobantes emitidos o está asignada a usuarios/registros; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 12
                      },
                      "message": "Serie eliminada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "No se puede eliminar: la serie ya tiene comprobantes emitidos."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "series_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/establishments/series": {
      "get": {
        "tags": [
          "Series"
        ],
        "summary": "Establecimientos con sus series",
        "operationId": "EstablecimientosSusSeries",
        "description": "Devuelve **todos los establecimientos con sus series** de factura (`01`), boleta (`03`), nota de venta (`80`) y guías (`09`, `31`), más las series por defecto del usuario autenticado. Útil para que el sistema externo sepa con qué `series_id` emitir.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Las series que se devuelven pueden estar limitadas a las del dispositivo o contexto del usuario.\n\nSin parámetros. Respuesta: `data.establishments[]` (id, description, address, trade_address, code, district_id, email, telephone, `series[]` con id, document_type_id, number, is_default) y `data.default_document_types[]` (id, series_id, document_type_id).",
        "responses": {
          "200": {
            "description": "Establecimientos y series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Establecimientos y series",
                    "value": {
                      "success": true,
                      "data": {
                        "establishments": [
                          {
                            "id": 1,
                            "description": "Oficina Principal",
                            "address": "AV. PRINCIPAL 123",
                            "trade_address": null,
                            "code": "0000",
                            "district_id": "150101",
                            "email": "ventas@empresa.com",
                            "telephone": "014567890",
                            "series": [
                              {
                                "id": 1,
                                "document_type_id": "01",
                                "number": "F001",
                                "is_default": true
                              },
                              {
                                "id": 2,
                                "document_type_id": "03",
                                "number": "B001",
                                "is_default": true
                              },
                              {
                                "id": 5,
                                "document_type_id": "80",
                                "number": "NV01",
                                "is_default": false
                              }
                            ]
                          }
                        ],
                        "default_document_types": [
                          {
                            "id": 1,
                            "series_id": 1,
                            "document_type_id": "01"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document/series": {
      "get": {
        "tags": [
          "Series"
        ],
        "summary": "Series de comprobantes y guías del usuario",
        "operationId": "SeriesComprobantesGuiasUsuario",
        "description": "Devuelve las series de **factura (`01`), boleta (`03`) y guías (`09`, `31`) del establecimiento del usuario autenticado**. (Las series de nota de venta se obtienen con **GET /api/sale-note/series**.)\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nRespuesta: arreglo (sin envoltorio `success`) de `{id, document_type_id, number, is_default, establishment_id}`.",
        "responses": {
          "200": {
            "description": "Series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Series",
                    "value": [
                      {
                        "id": 1,
                        "document_type_id": "01",
                        "number": "F001",
                        "is_default": true,
                        "establishment_id": 1
                      },
                      {
                        "id": 2,
                        "document_type_id": "03",
                        "number": "B001",
                        "is_default": true,
                        "establishment_id": 1
                      },
                      {
                        "id": 7,
                        "document_type_id": "09",
                        "number": "T001",
                        "is_default": false,
                        "establishment_id": 1
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/users": {
      "get": {
        "tags": [
          "Usuarios"
        ],
        "summary": "Listar usuarios",
        "operationId": "ListarUsuarios",
        "description": "Lista los usuarios ordenados por id.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 5,
                          "name": "JUAN PEREZ",
                          "email": "jperez@empresa.com",
                          "type": "seller",
                          "active": true,
                          "locked": false,
                          "establishment_id": 1,
                          "establishment_description": "Oficina Principal",
                          "document_id": "01",
                          "series_id": 1,
                          "identity_document_type_id": "1",
                          "number": "45678912",
                          "names": "JUAN",
                          "last_names": "PEREZ GOMEZ",
                          "personal_email": "juan.perez@gmail.com",
                          "corporate_email": "jperez@empresa.com",
                          "personal_cell_phone": "987654321",
                          "corporate_cell_phone": "912345678",
                          "position": "Vendedor",
                          "photo": null
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre o correo."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "seller",
            "description": "Filtra por tipo: `admin` o `seller`."
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por estado: `1`/`true` activos, `0`/`false` inhabilitados."
          },
          {
            "name": "establishment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por establecimiento."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Usuarios"
        ],
        "summary": "Crear usuario",
        "operationId": "CrearUsuario",
        "description": "Registra un usuario.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string | Sí | Nombre visible del usuario (máx. 255). |\n| `email` | string | Sí | Correo de ingreso. Único en la empresa. |\n| `type` | string | Sí | `admin` (administrador) o `seller` (vendedor). |\n| `password` | string | Sí al crear | Mínimo 6 caracteres. Si la empresa exige contraseña segura: al menos una minúscula, una mayúscula, un número y un símbolo (`@.$!%*#?&-`). |\n| `password_confirmation` | string | Sí si envías `password` | Debe ser igual a `password`. |\n| `establishment_id` | integer | Sí | Establecimiento del usuario. |\n| `document_id` | string | No | Tipo de comprobante por defecto (`01`, `03`, `80`...). |\n| `series_id` | integer | No | Serie por defecto (id de serie). |\n| `default_document_types` | array | No | Series por defecto por tipo de documento: `[{document_type_id, series_id}]`. Si se envía, reemplaza las anteriores. |\n| `multiple_default_document_types` | boolean | No | `true` para usar varias series por defecto (`default_document_types`). |\n| `identity_document_type_id` | string | No | Tipo de documento de identidad del usuario: `1` DNI, `4` carné de extranjería, `6` RUC, `7` pasaporte. |\n| `number` | numeric | No | Número del documento de identidad. |\n| `names` | string | No | Nombres. |\n| `last_names` | string | No | Apellidos. |\n| `address` | string | No | Dirección. |\n| `position` | string | No | Cargo. |\n| `personal_email` | string | No | Correo personal (formato correo). |\n| `corporate_email` | string | No | Correo corporativo (formato correo). |\n| `personal_cell_phone` | string | No | Celular personal (máx. 30). |\n| `corporate_cell_phone` | string | No | Celular corporativo (máx. 30). |\n| `date_of_birth` | date | No | Fecha de nacimiento `YYYY-MM-DD`. |\n| `contract_date` | date | No | Fecha de contrato `YYYY-MM-DD`. |\n| `restaurant_pin` | string | No | PIN para el módulo de restaurante (máx. 20). |\n| `modules` | array<int> | No | Ids de los módulos de la plataforma a los que tendrá acceso. Solo se asignan los que la empresa tiene contratados. Pide los ids al administrador de la plataforma o cópialos de `GET /api/users/{id}` de un usuario existente. |\n| `levels` | array<int> | No | Ids de los submódulos (niveles). Misma regla que `modules`. |\n| `app_modules` | array<int> | No | Ids de los módulos visibles en la app móvil. |\n| `create_payment` | boolean | No | Permiso para registrar pagos. |\n| `delete_payment` | boolean | No | Permiso para eliminar pagos. |\n| `edit_purchase` | boolean | No | Permiso para editar compras (necesario para *Editar compra*). |\n| `annular_purchase` | boolean | No | Permiso para anular compras (necesario para *Anular compra*). |\n| `delete_purchase` | boolean | No | Permiso para eliminar compras (necesario para *Eliminar compra*). |\n| `permission_edit_cpe` | boolean | No | Permiso para editar comprobantes. |\n| `recreate_documents` | boolean | No | Permiso para regenerar comprobantes. |\n| `permission_force_send_by_summary` | boolean | No | Permiso para forzar el envío por resumen. |\n| `permission_edit_item_prices` | boolean | No | Permiso para cambiar precios de productos al vender. |\n| `bot_enabled` | boolean | No | Habilita el asistente para el usuario. |\n\n**Errores:**\n- `422` si falta un campo obligatorio, el correo ya existe, la contraseña no cumple las reglas o no coincide con la confirmación.\n- `409` si se alcanzó el límite de usuarios del plan.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 5,
                        "name": "JUAN PEREZ",
                        "email": "jperez@empresa.com",
                        "type": "seller",
                        "active": true,
                        "locked": false,
                        "establishment_id": 1,
                        "establishment_description": "Oficina Principal",
                        "document_id": "01",
                        "series_id": 1,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "names": "JUAN",
                        "last_names": "PEREZ GOMEZ",
                        "personal_email": "juan.perez@gmail.com",
                        "corporate_email": "jperez@empresa.com",
                        "personal_cell_phone": "987654321",
                        "corporate_cell_phone": "912345678",
                        "position": "Vendedor",
                        "photo": null,
                        "address": "JR. LAS FLORES 123",
                        "date_of_birth": "1990-05-20",
                        "contract_date": "2026-01-15",
                        "bot_enabled": false,
                        "recreate_documents": false,
                        "permission_edit_cpe": false,
                        "create_payment": true,
                        "delete_payment": false,
                        "edit_purchase": false,
                        "annular_purchase": false,
                        "delete_purchase": false,
                        "permission_force_send_by_summary": false,
                        "permission_edit_item_prices": true,
                        "multiple_default_document_types": true,
                        "default_document_types": [
                          {
                            "document_type_id": "01",
                            "series_id": 1
                          },
                          {
                            "document_type_id": "03",
                            "series_id": 2
                          }
                        ],
                        "modules": [
                          1,
                          2,
                          5
                        ],
                        "levels": [
                          3,
                          4
                        ],
                        "app_modules": [
                          1,
                          2
                        ]
                      },
                      "message": "Usuario registrado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Correo repetido y sin contraseña",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Correo repetido y sin contraseña",
                    "value": {
                      "success": false,
                      "message": {
                        "email": [
                          "correo electrónico ya ha sido registrado."
                        ],
                        "password": [
                          "El campo contraseña es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Límite de usuarios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Límite de usuarios",
                    "value": {
                      "success": false,
                      "message": "Ha superado el límite permitido para crear/activar usuarios."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear usuario",
                  "value": {
                    "name": "JUAN PEREZ",
                    "email": "jperez@empresa.com",
                    "type": "seller",
                    "password": "Secreta123",
                    "password_confirmation": "Secreta123",
                    "establishment_id": 1,
                    "document_id": "01",
                    "series_id": 1,
                    "multiple_default_document_types": true,
                    "default_document_types": [
                      {
                        "document_type_id": "01",
                        "series_id": 1
                      },
                      {
                        "document_type_id": "03",
                        "series_id": 2
                      }
                    ],
                    "identity_document_type_id": "1",
                    "number": "45678912",
                    "names": "JUAN",
                    "last_names": "PEREZ GOMEZ",
                    "address": "JR. LAS FLORES 123",
                    "position": "Vendedor",
                    "personal_email": "juan.perez@gmail.com",
                    "corporate_email": "jperez@empresa.com",
                    "personal_cell_phone": "987654321",
                    "corporate_cell_phone": "912345678",
                    "date_of_birth": "1990-05-20",
                    "contract_date": "2026-01-15",
                    "restaurant_pin": "1234",
                    "modules": [
                      1,
                      2,
                      5
                    ],
                    "levels": [
                      3,
                      4
                    ],
                    "app_modules": [
                      1,
                      2
                    ],
                    "create_payment": true,
                    "delete_payment": false,
                    "edit_purchase": false,
                    "annular_purchase": false,
                    "delete_purchase": false,
                    "permission_edit_cpe": false,
                    "recreate_documents": false,
                    "permission_force_send_by_summary": false,
                    "permission_edit_item_prices": true,
                    "bot_enabled": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{user_id}": {
      "get": {
        "tags": [
          "Usuarios"
        ],
        "summary": "Ver usuario",
        "operationId": "VerUsuario",
        "description": "Devuelve el usuario con sus permisos, series por defecto y módulos asignados.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 5,
                        "name": "JUAN PEREZ",
                        "email": "jperez@empresa.com",
                        "type": "seller",
                        "active": true,
                        "locked": false,
                        "establishment_id": 1,
                        "establishment_description": "Oficina Principal",
                        "document_id": "01",
                        "series_id": 1,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "names": "JUAN",
                        "last_names": "PEREZ GOMEZ",
                        "personal_email": "juan.perez@gmail.com",
                        "corporate_email": "jperez@empresa.com",
                        "personal_cell_phone": "987654321",
                        "corporate_cell_phone": "912345678",
                        "position": "Vendedor",
                        "photo": null,
                        "address": "JR. LAS FLORES 123",
                        "date_of_birth": "1990-05-20",
                        "contract_date": "2026-01-15",
                        "bot_enabled": false,
                        "recreate_documents": false,
                        "permission_edit_cpe": false,
                        "create_payment": true,
                        "delete_payment": false,
                        "edit_purchase": false,
                        "annular_purchase": false,
                        "delete_purchase": false,
                        "permission_force_send_by_summary": false,
                        "permission_edit_item_prices": true,
                        "multiple_default_document_types": true,
                        "default_document_types": [
                          {
                            "document_type_id": "01",
                            "series_id": 1
                          },
                          {
                            "document_type_id": "03",
                            "series_id": 2
                          }
                        ],
                        "modules": [
                          1,
                          2,
                          5
                        ],
                        "levels": [
                          3,
                          4
                        ],
                        "app_modules": [
                          1,
                          2
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ]
      },
      "put": {
        "tags": [
          "Usuarios"
        ],
        "summary": "Editar usuario",
        "operationId": "EditarUsuario",
        "description": "Edita un usuario. Acepta `PUT` o `PATCH`; la edición es **parcial**: `name`, `email`, `type` y `establishment_id` se completan con el valor actual si no se envían; el resto solo cambia si se envía.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\nCampos: los mismos de *Crear usuario*. `password` es opcional al editar (si la envías, también `password_confirmation`); el cambio de contraseña por API solo se aplica si la plataforma tiene habilitado el cambio de contraseña, de lo contrario se ignora sin error. `modules`/`levels` no se aplican al usuario principal de la empresa.\n\n**Errores:**\n- `409` si intentas quitarte a ti mismo el tipo administrador, o si se excede el límite de usuarios del plan.\n- `422` por validación (correo repetido, etc.); `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 5,
                        "name": "JUAN PEREZ",
                        "email": "jperez@empresa.com",
                        "type": "seller",
                        "active": true,
                        "locked": false,
                        "establishment_id": 1,
                        "establishment_description": "Oficina Principal",
                        "document_id": "01",
                        "series_id": 1,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "names": "JUAN CARLOS",
                        "last_names": "PEREZ GOMEZ",
                        "personal_email": "juan.perez@gmail.com",
                        "corporate_email": "jperez@empresa.com",
                        "personal_cell_phone": "987654321",
                        "corporate_cell_phone": "912345678",
                        "position": "Supervisor de ventas",
                        "photo": null,
                        "address": "JR. LAS FLORES 123",
                        "date_of_birth": "1990-05-20",
                        "contract_date": "2026-01-15",
                        "bot_enabled": false,
                        "recreate_documents": false,
                        "permission_edit_cpe": false,
                        "create_payment": true,
                        "delete_payment": false,
                        "edit_purchase": true,
                        "annular_purchase": false,
                        "delete_purchase": false,
                        "permission_force_send_by_summary": false,
                        "permission_edit_item_prices": true,
                        "multiple_default_document_types": true,
                        "default_document_types": [
                          {
                            "document_type_id": "01",
                            "series_id": 1
                          },
                          {
                            "document_type_id": "03",
                            "series_id": 2
                          }
                        ],
                        "modules": [
                          1,
                          2,
                          5
                        ],
                        "levels": [
                          3,
                          4
                        ],
                        "app_modules": [
                          1,
                          2
                        ]
                      },
                      "message": "Usuario actualizado"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Quitarse admin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Quitarse admin",
                    "value": {
                      "success": false,
                      "message": "No puedes quitarte el tipo administrador a ti mismo."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar usuario",
                  "value": {
                    "names": "JUAN CARLOS",
                    "position": "Supervisor de ventas",
                    "type": "seller",
                    "edit_purchase": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/users/{user_id}/toggle": {
      "post": {
        "tags": [
          "Usuarios"
        ],
        "summary": "Activar / inhabilitar usuario",
        "operationId": "ActivarInhabilitarUsuario",
        "description": "Activa o inhabilita un usuario. Un usuario inhabilitado no puede operar en la plataforma.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `active` | boolean | No | `true` activa, `false` inhabilita. Si no se envía, **invierte** el estado actual. |\n\n**Errores (`409`):**\n- No puedes inhabilitar tu propio usuario.\n- No se puede inhabilitar al usuario principal de la empresa.\n- Al activar, si se excede el límite de usuarios del plan.\n\n`422` si `active` no es booleano; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Inhabilitado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Inhabilitado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 5,
                        "name": "JUAN PEREZ (SUSPENDIDO)",
                        "email": "jperez@empresa.com",
                        "type": "seller",
                        "active": false,
                        "locked": false,
                        "establishment_id": 1,
                        "establishment_description": "Oficina Principal",
                        "document_id": "01",
                        "series_id": 1,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "names": "JUAN",
                        "last_names": "PEREZ GOMEZ",
                        "personal_email": "juan.perez@gmail.com",
                        "corporate_email": "jperez@empresa.com",
                        "personal_cell_phone": "987654321",
                        "corporate_cell_phone": "912345678",
                        "position": "Vendedor",
                        "photo": null
                      },
                      "message": "Usuario inhabilitado con éxito."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Propio usuario",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Propio usuario",
                    "value": {
                      "success": false,
                      "message": "No puedes inhabilitar tu propio usuario."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Activar / inhabilitar usuario",
                  "value": {
                    "active": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/warehouses": {
      "get": {
        "tags": [
          "Almacenes"
        ],
        "summary": "Listar almacenes",
        "operationId": "ListarAlmacenes",
        "description": "Lista los almacenes ordenados por nombre.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "Almacén - Oficina Principal",
                          "establishment_id": 1,
                          "establishment_description": "Oficina Principal"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre."
          },
          {
            "name": "establishment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por establecimiento."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Almacenes"
        ],
        "summary": "Crear almacén (solo recuperación)",
        "operationId": "CrearAlmacenSoloRecuperacion",
        "description": "**Solo para recuperación.** El almacén se crea automáticamente al crear el establecimiento, así que en el uso normal **no necesitas este endpoint**.\n\nÚsalo únicamente si un establecimiento quedó **sin almacén** (por ejemplo, establecimientos antiguos o un almacén eliminado por soporte). Antes de llamarlo, comprueba con `GET /api/warehouses?establishment_id=<id>` que de verdad no tiene uno.\n\n**Errores:** `409` *\"Solo es posible registrar un almacén por establecimiento.\"* si el establecimiento ya tiene almacén (que es lo habitual).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Nombre del almacén. |\n| `establishment_id` | integer | No | Establecimiento. Si no se envía, se usa el del usuario autenticado. |\n\n**Errores:** `409` si el establecimiento ya tiene un almacén; `422` si falta `description` o el establecimiento no existe.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "Almacén - Sucursal Miraflores",
                        "establishment_id": 2,
                        "establishment_description": "SUCURSAL MIRAFLORES"
                      },
                      "message": "Almacén registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya tiene almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya tiene almacén",
                    "value": {
                      "success": false,
                      "message": "Solo es posible registrar un almacén por establecimiento."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear almacén (solo recuperación)",
                  "value": {
                    "description": "Almacén - Sucursal Miraflores",
                    "establishment_id": 2
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/warehouses/{warehouse_id}": {
      "get": {
        "tags": [
          "Almacenes"
        ],
        "summary": "Ver almacén",
        "operationId": "VerAlmacen",
        "description": "Devuelve un almacén.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Almacén - Oficina Principal",
                        "establishment_id": 1,
                        "establishment_description": "Oficina Principal"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "warehouse_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Almacenes"
        ],
        "summary": "Editar almacén",
        "operationId": "EditarAlmacen",
        "description": "Cambia el nombre del almacén. Acepta `PUT` o `PATCH`. El establecimiento no se puede cambiar.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Nuevo nombre. |\n\n**Errores:** `404` si no existe; `422` si `description` viene vacío.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Almacén central",
                        "establishment_id": 1,
                        "establishment_description": "Oficina Principal"
                      },
                      "message": "Almacén editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "warehouse_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar almacén",
                  "value": {
                    "description": "Almacén central"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bank-accounts": {
      "get": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Listar cuentas",
        "operationId": "ListarCuentas",
        "description": "Lista las cuentas ordenadas por nombre.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "type": "bank",
                          "bank_id": 2,
                          "description": "BCP SOLES",
                          "number": "191-12345678-0-12",
                          "currency_type_id": "PEN",
                          "cci": "00219100123456780122",
                          "status": 1,
                          "initial_balance": "0.00",
                          "show_in_documents": true,
                          "establishment_id": null,
                          "receives_income": true,
                          "allows_payments": true,
                          "bank_description": "BANCO DE CREDITO DEL PERU",
                          "type_description": "Cuenta bancaria"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre o número."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "bank",
            "description": "Filtra por tipo: `bank`, `wallet`, `gateway`, `card`."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por estado: `1` activas, `0` inactivas."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Crear cuenta",
        "operationId": "CrearCuenta",
        "description": "Registra una cuenta bancaria, billetera, pasarela o tarjeta.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `type` | string | Sí | `bank` cuenta bancaria, `wallet` billetera digital (Yape, Plin...), `gateway` pasarela de pago (Culqi, Niubiz...), `card` tarjeta de la empresa. |\n| `bank_id` | integer | Sí si `type = bank` | Banco. Para otros tipos se guarda `null`. Los ids de banco se pueden ver en `bank_id`/`bank_description` de cuentas existentes (`GET /api/bank-accounts`) o pedirlos al administrador. |\n| `description` | string | Sí | Nombre de la cuenta (p. ej. `BCP SOLES`, `YAPE TIENDA`). |\n| `number` | string | Sí | Número de cuenta, celular de la billetera o código del comercio. |\n| `currency_type_id` | string | Sí | Moneda: `PEN` soles, `USD` dólares. |\n| `cci` | string | No | Código de cuenta interbancario. |\n| `initial_balance` | numeric | Sí | Saldo inicial (≥ 0). |\n| `show_in_documents` | boolean | Sí | `true` para imprimir la cuenta en los comprobantes. Solo aplica a `bank` y `wallet`; para los otros tipos se guarda `false`. |\n| `status` | integer | No | `1` activa, `0` inactiva. |\n| `establishment_id` | integer | No | Establecimiento al que pertenece. `null` = cuenta general, disponible en todos. |\n| `receives_income` | boolean | No | Si puede recibir cobros (ventas, ingresos). |\n| `allows_payments` | boolean | No | Si puede usarse para pagar (gastos, compras). |\n\n**Errores:** `422` si falta un campo obligatorio, `type` no es válido o falta `bank_id` en una cuenta bancaria.",
        "responses": {
          "201": {
            "description": "Creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "type": "bank",
                        "bank_id": 2,
                        "description": "BCP SOLES",
                        "number": "191-12345678-0-12",
                        "currency_type_id": "PEN",
                        "cci": "00219100123456780122",
                        "status": 1,
                        "initial_balance": "0.00",
                        "show_in_documents": true,
                        "establishment_id": null,
                        "receives_income": true,
                        "allows_payments": true,
                        "bank_description": "BANCO DE CREDITO DEL PERU",
                        "type_description": "Cuenta bancaria"
                      },
                      "message": "Cuenta registrada con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Falta el banco",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Falta el banco",
                    "value": {
                      "success": false,
                      "message": {
                        "bank_id": [
                          "El campo bank id es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear cuenta",
                  "value": {
                    "type": "bank",
                    "bank_id": 2,
                    "description": "BCP SOLES",
                    "number": "191-12345678-0-12",
                    "currency_type_id": "PEN",
                    "cci": "00219100123456780122",
                    "initial_balance": 0,
                    "show_in_documents": true,
                    "status": 1,
                    "establishment_id": null,
                    "receives_income": true,
                    "allows_payments": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bank-accounts/{bank_account_id}": {
      "get": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Ver cuenta",
        "operationId": "VerCuenta",
        "description": "Devuelve una cuenta.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "type": "bank",
                        "bank_id": 2,
                        "description": "BCP SOLES",
                        "number": "191-12345678-0-12",
                        "currency_type_id": "PEN",
                        "cci": "00219100123456780122",
                        "status": 1,
                        "initial_balance": "0.00",
                        "show_in_documents": true,
                        "establishment_id": null,
                        "receives_income": true,
                        "allows_payments": true,
                        "bank_description": "BANCO DE CREDITO DEL PERU",
                        "type_description": "Cuenta bancaria"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bank_account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Editar cuenta",
        "operationId": "EditarCuenta",
        "description": "Edita una cuenta. Acepta `PUT` o `PATCH`; la edición es **parcial**.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\nCampos: los mismos de *Crear cuenta*. Para desactivar una cuenta con movimientos envía `status: 0`.\n\n**Errores:** `422` por validación; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "type": "bank",
                        "bank_id": 2,
                        "description": "BCP SOLES PRINCIPAL",
                        "number": "191-12345678-0-12",
                        "currency_type_id": "PEN",
                        "cci": "00219100123456780122",
                        "status": 1,
                        "initial_balance": "0.00",
                        "show_in_documents": false,
                        "establishment_id": null,
                        "receives_income": true,
                        "allows_payments": true,
                        "bank_description": "BANCO DE CREDITO DEL PERU",
                        "type_description": "Cuenta bancaria"
                      },
                      "message": "Cuenta editada con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bank_account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar cuenta",
                  "value": {
                    "description": "BCP SOLES PRINCIPAL",
                    "status": 1,
                    "show_in_documents": false
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Eliminar cuenta",
        "operationId": "EliminarCuenta",
        "description": "Elimina una cuenta sin movimientos.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Responde `409` cuando:**\n- la cuenta ya recibió o pagó dinero (desactívala con `status: 0`);\n- es el destino por defecto de algún método de pago.\n\n`404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3
                      },
                      "message": "Cuenta eliminada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Con pagos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Con pagos",
                    "value": {
                      "success": false,
                      "message": "La cuenta tiene pagos registrados, no se puede eliminar. Desactívala (status = 0) en su lugar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bank_account_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/bank-accounts/records-scroll": {
      "get": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Listar cuentas (scroll)",
        "operationId": "ListarCuentasScroll",
        "description": "Lista las cuentas bancarias / billeteras con paginación por cursor, de la más reciente a la más antigua.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "bank_id": 2,
                          "bank_description": "BANCO DE CREDITO DEL PERU",
                          "description": "BCP SOLES",
                          "number": "191-12345678-0-12",
                          "cci": "00219100123456780122",
                          "currency_type_id": "PEN",
                          "currency_type_description": "Soles",
                          "status": 1,
                          "initial_balance": 0.0,
                          "show_in_documents": true,
                          "establishment_id": null,
                          "establishment_description": null
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por descripción, número, CCI o nombre del banco."
          },
          {
            "name": "show_in_documents",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "true",
            "description": "`true` solo las que se imprimen en los comprobantes, `false` las que no."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` activas, `0` inactivas."
          },
          {
            "name": "establishment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por establecimiento."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/bank-accounts/for-pdf": {
      "get": {
        "tags": [
          "Cuentas bancarias"
        ],
        "summary": "Cuentas que se imprimen en el comprobante",
        "operationId": "CuentasQueSeImprimenComprobante",
        "description": "Devuelve las cuentas que aparecen impresas en el PDF de los comprobantes del establecimiento del usuario autenticado (cuentas marcadas para mostrarse en documentos y, si la empresa lo configuró así, solo las de ese establecimiento). Útil para imprimir tickets propios con las mismas cuentas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Sin paginación.",
        "responses": {
          "200": {
            "description": "Cuentas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cuentas",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "bank_id": 2,
                          "bank_description": "BANCO DE CREDITO DEL PERU",
                          "description": "BCP SOLES",
                          "number": "191-12345678-0-12",
                          "cci": "00219100123456780122",
                          "currency_type_id": "PEN",
                          "currency_type_description": "Soles",
                          "status": 1,
                          "initial_balance": 0.0,
                          "show_in_documents": true,
                          "establishment_id": null,
                          "establishment_description": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/expenses": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar gastos",
        "operationId": "ListarGastos",
        "description": "Lista los gastos, del más reciente al más antiguo.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`. (en el listado, el vendedor solo ve los suyos).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 25,
                          "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
                          "number": "F001-4587",
                          "number_full": "F001-4587",
                          "date_of_issue": "2026-11-07",
                          "time_of_issue": "10:15:00",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "currency_type_id": "PEN",
                          "exchange_rate_sale": 1.0,
                          "total": 50.0,
                          "user_id": 5,
                          "establishment_id": 1,
                          "expense_type_id": 1,
                          "expense_type_description": "FACTURA",
                          "expense_reason_id": 2,
                          "expense_reason_description": "Servicios",
                          "supplier_id": 14,
                          "supplier": {
                            "name": "SERVICIOS GENERALES S.A.C.",
                            "number": "20456789123"
                          }
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Fecha inválida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Fecha inválida",
                    "value": {
                      "success": false,
                      "message": {
                        "date_start": [
                          "date start no es una fecha válida."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de emisión (`YYYY-MM-DD`)."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha de emisión."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "05",
            "description": "Filtra por estado (`01`, `05`, `11`)."
          },
          {
            "name": "expense_reason_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por motivo."
          },
          {
            "name": "expense_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por tipo."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por número del comprobante."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Registrar gasto",
        "operationId": "RegistrarGasto",
        "description": "Registra un gasto con su detalle y sus pagos. El efectivo (`cash`) sale de la caja abierta del usuario; los pagos a una cuenta salen de esa cuenta. Es la **vía recomendada** para integraciones: mismas reglas que *Registrar gasto (endpoint existente)* (`finances/expense`), con respuestas estándar y códigos HTTP reales.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con el gasto completo (ítems y pagos) y `print_url` (PDF A4 público).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `expense_type_id` | integer | Sí | Tipo de comprobante del gasto (*tipos de gasto*). El tipo `4` (\"Otros\") no exige número. |\n| `expense_reason_id` | integer | Sí | Motivo del gasto (*motivos de gasto*). |\n| `number` | string (máx. 100) | Sí salvo tipo `4` | Número del comprobante del proveedor. |\n| `supplier_id` | integer | Sí | Id del proveedor (persona registrada). |\n| `date_of_issue` | date | Sí | Fecha de emisión `YYYY-MM-DD`. |\n| `time_of_issue` | string | Sí | Hora `HH:MM:SS`. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric (≥ 0) | No | Tipo de cambio venta. Si no lo envías o envías `0`, se usa el **tipo de cambio del día** de `date_of_issue` registrado en el sistema; en soles (`PEN`) sin tipo registrado ese día se guarda `1`; en otra moneda, si no hay ninguno disponible, responde `422` pidiéndolo. |\n| `establishment_id` | integer | Sí | Establecimiento. |\n| `total` | numeric | Sí | Total, mayor que 0. |\n| `items` | array | Sí | Detalle, al menos uno: `[{description (máx. 500), total (> 0)}]`. |\n| `payments` | array | Sí | Pagos, al menos uno. La suma **no puede superar** `total` (puede ser menor: el resto queda pendiente y se paga luego con *Registrar pago de gasto*). |\n| `payments[].expense_method_type_id` | integer | No | Solo para integraciones antiguas (catálogo de métodos de gasto): `1` = caja general, se convierte en efectivo a la caja. Usa `payment_method_type_id`. |\n\nCada elemento de `payments`: `date_of_payment` (`YYYY-MM-DD`), `payment_method_type_id` (método de pago), `payment_destination_id` (`cash` = la caja abierta del usuario, o el id de una cuenta bancaria o billetera), `payment` (monto > 0) y `reference` (opcional: número de operación, voucher...).\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Reglas:**\n- Un pago con destino `cash` usa la **caja abierta del usuario** del token: sin caja abierta responde `409` y no se guarda nada.\n- Un pago a una cuenta: la cuenta debe existir, ser de la **misma moneda** del registro y estar disponible para el establecimiento; el método de pago debe estar habilitado para esa operación y ese destino (ver *Configuración del flujo de caja*). Si no, `409`.\n- Todo el registro se guarda en una sola operación: si algún pago se rechaza, no queda ni el registro ni ningún pago.\n- Si envías `id`, se ignora: este endpoint **siempre crea** un registro nuevo (para editar usa *Editar gasto* / *Editar ingreso*).\n- Un pago en efectivo no puede superar el efectivo disponible en la caja (`409`).\n\n**Errores:**\n- `409` cuando una regla de caja lo impide (sin caja abierta, cuenta de otra moneda, método no habilitado para pagos...). El `message` explica la causa y puede mostrarse tal cual.\n- `422` `{success: false, message: {campo: [errores]}}` si falta un campo, los pagos superan el total o `exchange_rate_sale` no es válido.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 25,
                        "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
                        "number": "F001-4587",
                        "number_full": "F001-4587",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:15:00",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 50.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "expense_type_id": 1,
                        "expense_type_description": "FACTURA",
                        "expense_reason_id": 2,
                        "expense_reason_description": "Servicios",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "SERVICIOS GENERALES S.A.C.",
                          "number": "20456789123"
                        },
                        "items": [
                          {
                            "id": 40,
                            "description": "Servicio de limpieza noviembre",
                            "total": 50.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 50.0
                          }
                        ],
                        "print_url": "https://empresa.dominio/print/expense/4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c"
                      },
                      "message": "Gasto registrado"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin caja abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
                    }
                  },
                  "e2": {
                    "summary": "Método no habilitado",
                    "value": {
                      "success": false,
                      "message": "\"Transferencia\" no está marcado para pagos. Actívalo en Configuración → Métodos de pago, o elige otro."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "number": [
                          "El número del comprobante es obligatorio para este tipo de gasto."
                        ],
                        "payments": [
                          "Los montos ingresados superan el monto total."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar gasto",
                  "value": {
                    "expense_type_id": 1,
                    "expense_reason_id": 2,
                    "number": "F001-4587",
                    "supplier_id": 14,
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "10:15:00",
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 0,
                    "establishment_id": 1,
                    "total": 50.0,
                    "items": [
                      {
                        "description": "Servicio de limpieza noviembre",
                        "total": 50.0
                      }
                    ],
                    "payments": [
                      {
                        "date_of_payment": "2026-11-07",
                        "payment_method_type_id": "01",
                        "payment_destination_id": "cash",
                        "payment": 50.0,
                        "reference": null
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/expenses/{expense_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver gasto",
        "operationId": "VerGasto",
        "description": "Devuelve el gasto con sus ítems y pagos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `404` si no existe; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 25,
                        "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
                        "number": "F001-4587",
                        "number_full": "F001-4587",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:15:00",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 50.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "expense_type_id": 1,
                        "expense_type_description": "FACTURA",
                        "expense_reason_id": 2,
                        "expense_reason_description": "Servicios",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "SERVICIOS GENERALES S.A.C.",
                          "number": "20456789123"
                        },
                        "items": [
                          {
                            "id": 40,
                            "description": "Servicio de limpieza noviembre",
                            "total": 50.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 50.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar gasto (datos no monetarios)",
        "operationId": "EditarGastoDatosNoMonetarios",
        "description": "Edita datos que no mueven dinero. Acepta `PUT` o `PATCH`; todos los campos son opcionales. Cualquier otro campo enviado (p. ej. `total`) se **ignora**.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `number` | string | No | Número del comprobante (máx. 255, puede ser `null`). |\n| `expense_type_id` | integer | No | Tipo de gasto existente. |\n| `expense_reason_id` | integer | No | Motivo de gasto existente. |\n| `supplier_id` | integer | No | Proveedor existente (se actualizan también su nombre y número guardados en el gasto). |\n| `items` | array | No | Solo cambia la descripción de ítems existentes: `[{id, description}]` (`id` = id del ítem del gasto, ver *Ver gasto*). El monto de cada ítem no cambia. |\n\n**Errores:** `409` si el gasto está anulado; `422` si un id no existe; `404`; `403`.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 25,
                        "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
                        "number": "F001-4588",
                        "number_full": "F001-4588",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:15:00",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 50.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "expense_type_id": 1,
                        "expense_type_description": "FACTURA",
                        "expense_reason_id": 2,
                        "expense_reason_description": "Servicios",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "SERVICIOS GENERALES S.A.C.",
                          "number": "20456789123"
                        },
                        "items": [
                          {
                            "id": 40,
                            "description": "Servicio de limpieza noviembre",
                            "total": 50.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 50.0
                          }
                        ]
                      },
                      "message": "Registro actualizado"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": false,
                      "message": "El registro está anulado y no se puede editar."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar gasto (datos no monetarios)",
                  "value": {
                    "number": "F001-4588",
                    "expense_type_id": 1,
                    "expense_reason_id": 2,
                    "supplier_id": 14,
                    "items": [
                      {
                        "id": 40,
                        "description": "Servicio de limpieza noviembre (2 turnos)"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/expenses/{expense_id}/payments": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar pagos de gasto",
        "operationId": "ListarPagosGasto",
        "description": "Devuelve los pagos registrados y el resumen de lo pagado y pendiente.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n`summary` trae `total` (total del registro), `total_paid` (suma de pagos) y `total_difference` (saldo pendiente).\n\n**Errores:** `404` si el registro no existe; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Pagos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagos",
                    "value": {
                      "success": true,
                      "data": {
                        "summary": {
                          "total": 50.0,
                          "total_paid": 20.0,
                          "total_difference": 30.0
                        },
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "04",
                            "payment_method_type_description": "Transferencia",
                            "destination_type": "BankAccount",
                            "destination_id": 3,
                            "destination_description": "BCP SOLES",
                            "reference": "OP-458721",
                            "payment": 20.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Registrar pago de gasto",
        "operationId": "RegistrarPagoGasto",
        "description": "Registra un pago (total o parcial). El dinero entra/sale del destino indicado (caja o cuenta) y queda en el libro de caja y bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_of_payment` | date | Sí | Fecha del pago `YYYY-MM-DD`. |\n| `payment_method_type_id` | string | Sí (o `expense_method_type_id`) | Método de pago (`01` efectivo, `04` transferencia...). |\n| `expense_method_type_id` | integer | No | Solo para integraciones antiguas: método del catálogo de métodos de gasto (ver sección [Catálogos de gastos e ingresos](/docs/api/tenant/catalogos-gastos-ingresos)). `1` = caja general (efectivo a caja). Usa preferentemente `payment_method_type_id`. |\n| `payment_destination_id` | string/integer | Sí (salvo `expense_method_type_id = 1`) | `cash` o id de cuenta bancaria/billetera. |\n| `payment` | numeric | Sí | Monto, mayor que 0. |\n| `reference` | string | No | Referencia: número de operación, voucher, etc. |\n| `has_card` | boolean | No | `true` si fue con tarjeta. |\n| `card_brand_id` | string | No | Marca de tarjeta: `01` Visa, `02` Mastercard... |\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Responde `409` cuando una regla de caja lo impide**, por ejemplo:\n- destino `cash` y el usuario no tiene una caja abierta;\n- el método de pago no está habilitado para ese tipo de operación o destino;\n- el pago pertenece a una caja ya cerrada (al eliminar);\n- el mismo pago (mismo monto y método) se registró hace menos de 20 segundos (protección contra doble envío);\n- el registro está anulado.\n\nEl mensaje (`message`) explica la causa y puede mostrarse al usuario tal cual.\n\n**Otros errores:** `422` si falta un campo o `payment` ≤ 0; `404` si el registro no existe; `403` si es de otro vendedor.\n\nLa respuesta trae el pago creado (`data.payment`) y el resumen actualizado (`data.summary`). `summary` trae `total` (total del registro), `total_paid` (suma de pagos) y `total_difference` (saldo pendiente).",
        "responses": {
          "201": {
            "description": "Pago registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pago registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "payment": {
                          "id": 31,
                          "date_of_payment": "2026-11-07",
                          "payment_method_type_id": "04",
                          "payment_method_type_description": "Transferencia",
                          "destination_type": "BankAccount",
                          "destination_id": 3,
                          "destination_description": "BCP SOLES",
                          "reference": "OP-458721",
                          "payment": 20.0
                        },
                        "summary": {
                          "total": 50.0,
                          "total_paid": 20.0,
                          "total_difference": 30.0
                        }
                      },
                      "message": "Pago registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Monto inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Monto inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "payment": [
                          "El campo payment debe ser mayor que 0."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin caja abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar pago de gasto",
                  "value": {
                    "date_of_payment": "2026-11-07",
                    "payment_method_type_id": "04",
                    "payment_destination_id": 3,
                    "payment": 20.0,
                    "reference": "OP-458721",
                    "has_card": false,
                    "card_brand_id": null,
                    "expense_method_type_id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/expense-payments/{expense_payment_id}": {
      "delete": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Eliminar pago de gasto",
        "operationId": "EliminarPagoGasto",
        "description": "Elimina un pago y revierte su movimiento en caja o cuenta. El id es el del **pago** (`data.payment.id` al registrarlo o `payments[].id` al listarlos).\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `409` si el pago pertenece a una caja ya cerrada; `404` si el pago no existe; `403` si el registro es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Pago eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pago eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 31,
                        "summary": {
                          "total": 50.0,
                          "total_paid": 0.0,
                          "total_difference": 50.0
                        }
                      },
                      "message": "Pago eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Caja cerrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja cerrada",
                    "value": {
                      "success": false,
                      "message": "No se puede eliminar este pago: pertenece a la caja #4, que ya está cerrada y su arqueo no puede cambiar. Si hubo un error, anula la operación: la devolución se registra en la caja abierta."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/finances/expense": {
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Registrar gasto (heredado)",
        "operationId": "RegistrarGastoHeredado",
        "description": "**Vía recomendada:** `POST /api/expenses` (mismas reglas y campos, respuesta `201` con el gasto completo y errores con código HTTP real: `409` por reglas de caja, `422` por validación). Este endpoint se mantiene por compatibilidad con la app móvil. `exchange_rate_sale` es opcional: sin él o con `0` se usa el tipo de cambio del día (en soles sin tipo registrado, `1`).\n\nRegistra un gasto con su detalle y sus pagos. Los pagos en efectivo (`cash`) salen de la caja abierta del usuario.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `expense_type_id` | integer | Sí | Tipo de comprobante del gasto (ver sección [Catálogos de gastos e ingresos](/docs/api/tenant/catalogos-gastos-ingresos), *tipos de gasto*). El tipo `4` (\"Otros\") no exige número. |\n| `expense_reason_id` | integer | Sí | Motivo del gasto (sección [Catálogos de gastos e ingresos](/docs/api/tenant/catalogos-gastos-ingresos), *motivos de gasto*). |\n| `number` | string | Sí salvo tipo `4` | Número del comprobante del proveedor (máx. 100). |\n| `supplier_id` | integer | Sí | Id del proveedor (persona registrada como proveedor). |\n| `date_of_issue` | date | Sí | Fecha `YYYY-MM-DD`. |\n| `time_of_issue` | string | Sí | Hora `HH:MM:SS`. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric | No | Sin él o con `0`, el tipo de cambio del día (en soles sin tipo registrado, `1`). |\n| `establishment_id` | integer | Sí | Establecimiento. |\n| `total` | numeric | Sí | Total, mayor que 0. Debe ser igual a la suma de `items[].total`. |\n| `items` | array | Sí | Detalle: `[{description (máx. 500), total (> 0)}]`. |\n| `payments` | array | Sí | Pagos: `[{date_of_payment, payment_method_type_id, payment_destination_id, payment, reference}]`. La suma no puede superar `total`. |\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Respuestas:**\n- `200` con `success: true` y `data` (`id`, `external_id`, `number`, `print_url` del PDF A4).\n- `422` con el formato estándar si falla la validación (p. ej. pagos que superan el total).\n- **`200` con `success: false`** y `message` cuando una regla de negocio lo impide (p. ej. pago en efectivo sin caja abierta). Revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 25,
                        "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
                        "number": "F001-4587",
                        "print_url": "https://empresa.dominio/print/expense/4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c"
                      }
                    }
                  },
                  "e2": {
                    "summary": "Regla de caja",
                    "value": {
                      "success": false,
                      "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "number": [
                          "El número del comprobante es obligatorio para este tipo de gasto."
                        ],
                        "payments": [
                          "Los montos ingresados superan el monto total."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar gasto (heredado)",
                  "value": {
                    "expense_type_id": 1,
                    "expense_reason_id": 2,
                    "number": "F001-4587",
                    "supplier_id": 14,
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "10:15:00",
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 1,
                    "establishment_id": 1,
                    "total": 50.0,
                    "items": [
                      {
                        "description": "Servicio de limpieza noviembre",
                        "total": 50.0
                      }
                    ],
                    "payments": [
                      {
                        "date_of_payment": "2026-11-07",
                        "payment_method_type_id": "01",
                        "payment_destination_id": "cash",
                        "payment": 50.0,
                        "reference": null
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/finances/expense/{expense_id}/void": {
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Anular gasto (heredado)",
        "operationId": "AnularGastoHeredado",
        "description": "**Vía recomendada:** `POST /api/expenses/{id}/void` (`409` si ya está anulado o pertenece a una caja cerrada; `403` si es de otro vendedor). Anular un gasto ya anulado responde aquí `200` con `success: false`.\n\nAnula un gasto (estado `11`) y revierte sus pagos en caja/bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nSin cuerpo.\n\n**Respuestas:** `200` con `success: true`; `200` con `success: false` si el gasto pertenece a una caja cerrada u otra regla lo impide; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 25
                      },
                      "message": "Gasto anulado exitosamente"
                    }
                  },
                  "e2": {
                    "summary": "Caja cerrada",
                    "value": {
                      "success": false,
                      "message": "No se puede anular un gasto que pertenece a una caja cerrada"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/expenses/{expense_id}/void": {
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Anular gasto",
        "operationId": "AnularGasto",
        "description": "Anula el gasto (estado `11`): sus pagos dejan de contar y el dinero vuelve a la caja o a la cuenta de donde salió. No se puede deshacer.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `200` con el gasto anulado (ítems y pagos).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `expense_id` | integer | Sí | Id del gasto. |\n\nSin cuerpo.\n\n**Reglas:**\n- No se puede anular un gasto cuya fecha y hora caen dentro de una **caja ya cerrada** del usuario: su arqueo ya se contó (`409`). Si hubo un error, registra un ingreso por la diferencia en la caja abierta.\n- Un gasto ya anulado no se anula otra vez (`409`).\n\n**Errores:**\n- `409` si ya está anulado o pertenece a una caja cerrada.\n- `403` si el gasto es de otro vendedor.\n- `404` si no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 25,
                        "external_id": "4f1c2b8e-7a9d-4d1e-9a3b-2c6e8f0a1b2c",
                        "number": "F001-4587",
                        "number_full": "F001-4587",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:15:00",
                        "state_type_id": "11",
                        "state_type_description": "Anulado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 50.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "expense_type_id": 1,
                        "expense_type_description": "FACTURA",
                        "expense_reason_id": 2,
                        "expense_reason_description": "Servicios",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "SERVICIOS GENERALES S.A.C.",
                          "number": "20456789123"
                        },
                        "items": [
                          {
                            "id": 40,
                            "description": "Servicio de limpieza noviembre",
                            "total": 50.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 50.0
                          }
                        ]
                      },
                      "message": "Gasto anulado exitosamente"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya anulado",
                    "value": {
                      "success": false,
                      "message": "El gasto ya está anulado."
                    }
                  },
                  "e2": {
                    "summary": "Caja cerrada",
                    "value": {
                      "success": false,
                      "message": "No se puede anular un gasto que pertenece a una caja cerrada"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/incomes": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar ingresos",
        "operationId": "ListarIngresos",
        "description": "Lista los ingresos, del más reciente al más antiguo.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`. (en el listado, el vendedor solo ve los suyos).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 8,
                          "external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
                          "number": "1",
                          "number_full": "ING-1",
                          "date_of_issue": "2026-11-07",
                          "time_of_issue": "11:20:00",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "currency_type_id": "PEN",
                          "exchange_rate_sale": 1.0,
                          "total": 120.0,
                          "user_id": 5,
                          "establishment_id": 1,
                          "income_type_id": 1,
                          "income_type_description": "Otros ingresos",
                          "income_reason_id": 1,
                          "income_reason_description": "Aporte de socio",
                          "customer": "CARLOS RAMIREZ"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de emisión (`YYYY-MM-DD`)."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "05",
            "description": "Filtra por estado."
          },
          {
            "name": "income_reason_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por motivo."
          },
          {
            "name": "income_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por tipo."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por número."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Registrar ingreso",
        "operationId": "RegistrarIngreso",
        "description": "Registra un ingreso con su detalle y sus cobros. El efectivo (`cash`) entra a la caja abierta del usuario; los cobros a una cuenta entran a esa cuenta. Es la **vía recomendada** para integraciones: mismas reglas que *Registrar ingreso (endpoint existente)* (`finances/income`), con respuestas estándar y códigos HTTP reales. El número del ingreso lo asigna el sistema.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con el ingreso completo (ítems y cobros) y `print_url` (PDF A4 público).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `income_type_id` | integer | Sí | Tipo de ingreso (*tipos de ingreso*). |\n| `income_reason_id` | integer | Sí | Motivo de ingreso (*motivos de ingreso*). |\n| `customer` | string | No | Nombre de quien entrega el dinero (texto libre). Por defecto `-`. |\n| `date_of_issue` | date | Sí | Fecha `YYYY-MM-DD`. |\n| `time_of_issue` | string | Sí | Hora `HH:MM:SS`. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric (≥ 0) | No | Tipo de cambio venta. Si no lo envías o envías `0`, se usa el **tipo de cambio del día** de `date_of_issue` registrado en el sistema; en soles (`PEN`) sin tipo registrado ese día se guarda `1`; en otra moneda, si no hay ninguno disponible, responde `422` pidiéndolo. |\n| `establishment_id` | integer | Sí | Establecimiento. |\n| `total` | numeric | Sí | Total, mayor que 0. |\n| `items` | array | Sí | Detalle, al menos uno: `[{description (máx. 500), total (> 0)}]`. |\n| `payments` | array | Sí | Cobros, al menos uno. La suma debe ser **igual** a `total`. |\n\nCada elemento de `payments`: `date_of_payment` (`YYYY-MM-DD`), `payment_method_type_id` (método de pago), `payment_destination_id` (`cash` = la caja abierta del usuario, o el id de una cuenta bancaria o billetera), `payment` (monto > 0) y `reference` (opcional: número de operación, voucher...).\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Reglas:**\n- Un pago con destino `cash` usa la **caja abierta del usuario** del token: sin caja abierta responde `409` y no se guarda nada.\n- Un pago a una cuenta: la cuenta debe existir, ser de la **misma moneda** del registro y estar disponible para el establecimiento; el método de pago debe estar habilitado para esa operación y ese destino (ver *Configuración del flujo de caja*). Si no, `409`.\n- Todo el registro se guarda en una sola operación: si algún pago se rechaza, no queda ni el registro ni ningún pago.\n- Si envías `id`, se ignora: este endpoint **siempre crea** un registro nuevo (para editar usa *Editar gasto* / *Editar ingreso*).\n- Un cobro a una cuenta también exige que el usuario tenga una caja abierta (el cobro se registra dentro de su turno).\n\n**Errores:**\n- `409` cuando una regla de caja lo impide (sin caja abierta, cuenta inexistente o de otra moneda, método no habilitado...).\n- `422` si falta un campo, la suma de cobros no coincide con el total o `exchange_rate_sale` no es válido.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 8,
                        "external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
                        "number": "1",
                        "number_full": "ING-1",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "11:20:00",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 120.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "income_type_id": 1,
                        "income_type_description": "Otros ingresos",
                        "income_reason_id": 1,
                        "income_reason_description": "Aporte de socio",
                        "customer": "CARLOS RAMIREZ",
                        "items": [
                          {
                            "id": 11,
                            "description": "Aporte de capital",
                            "total": 120.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 15,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 120.0
                          }
                        ],
                        "print_url": "https://empresa.dominio/print/income/9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f"
                      },
                      "message": "Ingreso registrado"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin caja abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "La caja se encuentra cerrada. Debes abrirla antes de registrar un ingreso."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Cobros no cuadran",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cobros no cuadran",
                    "value": {
                      "success": false,
                      "message": {
                        "payments": [
                          "Los montos ingresados no coinciden con el monto total."
                        ]
                      }
                    }
                  },
                  "e2": {
                    "summary": "Sin tipo de cambio",
                    "value": {
                      "success": false,
                      "message": {
                        "exchange_rate_sale": [
                          "No hay tipo de cambio registrado para el 2026-11-07. Envía exchange_rate_sale."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar ingreso",
                  "value": {
                    "income_type_id": 1,
                    "income_reason_id": 1,
                    "customer": "CARLOS RAMIREZ",
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "11:20:00",
                    "currency_type_id": "PEN",
                    "establishment_id": 1,
                    "total": 120.0,
                    "items": [
                      {
                        "description": "Aporte de capital",
                        "total": 120.0
                      }
                    ],
                    "payments": [
                      {
                        "date_of_payment": "2026-11-07",
                        "payment_method_type_id": "01",
                        "payment_destination_id": "cash",
                        "payment": 120.0,
                        "reference": null
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/incomes/{income_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver ingreso",
        "operationId": "VerIngreso",
        "description": "Devuelve el ingreso con sus ítems y pagos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `404`; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 8,
                        "external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
                        "number": "1",
                        "number_full": "ING-1",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "11:20:00",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 120.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "income_type_id": 1,
                        "income_type_description": "Otros ingresos",
                        "income_reason_id": 1,
                        "income_reason_description": "Aporte de socio",
                        "customer": "CARLOS RAMIREZ",
                        "items": [
                          {
                            "id": 11,
                            "description": "Aporte de capital",
                            "total": 120.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 15,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 120.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar ingreso (datos no monetarios)",
        "operationId": "EditarIngresoDatosNoMonetarios",
        "description": "Edita datos que no mueven dinero. Acepta `PUT` o `PATCH`; todos los campos son opcionales; cualquier otro campo se ignora.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `number` | string | No | Número (máx. 255, puede ser `null`). |\n| `income_type_id` | integer | No | Tipo de ingreso existente. |\n| `income_reason_id` | integer | No | Motivo de ingreso existente. |\n| `customer` | string | No | Nombre de quien entrega el dinero (texto libre, máx. 255). |\n| `items` | array | No | Solo la descripción de ítems existentes: `[{id, description}]`. |\n\n**Errores:** `409` si el ingreso está anulado; `422`; `404`; `403`.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 8,
                        "external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
                        "number": "2",
                        "number_full": "ING-1",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "11:20:00",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 120.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "income_type_id": 1,
                        "income_type_description": "Otros ingresos",
                        "income_reason_id": 1,
                        "income_reason_description": "Aporte de socio",
                        "customer": "CARLOS RAMIREZ TORRES",
                        "items": [
                          {
                            "id": 11,
                            "description": "Aporte de capital",
                            "total": 120.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 15,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 120.0
                          }
                        ]
                      },
                      "message": "Registro actualizado"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": false,
                      "message": "El registro está anulado y no se puede editar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar ingreso (datos no monetarios)",
                  "value": {
                    "number": "2",
                    "income_type_id": 1,
                    "income_reason_id": 1,
                    "customer": "CARLOS RAMIREZ TORRES",
                    "items": [
                      {
                        "id": 11,
                        "description": "Aporte de capital noviembre"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/finances/income": {
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Registrar ingreso (heredado)",
        "operationId": "RegistrarIngresoHeredado",
        "description": "**Vía recomendada:** `POST /api/incomes` (mismas reglas y campos, respuesta `201` con el ingreso completo y errores con código HTTP real: `409` por reglas de caja, `422` por validación). Este endpoint se mantiene por compatibilidad con la app móvil. `exchange_rate_sale` es opcional: sin él o con `0` se usa el tipo de cambio del día (en soles sin tipo registrado, `1`).\n\nRegistra un ingreso con su detalle y sus cobros.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `income_type_id` | integer | Sí | Tipo de ingreso (sección [Catálogos de gastos e ingresos](/docs/api/tenant/catalogos-gastos-ingresos)). |\n| `income_reason_id` | integer | Sí | Motivo de ingreso (sección [Catálogos de gastos e ingresos](/docs/api/tenant/catalogos-gastos-ingresos)). |\n| `customer` | string | No | Nombre de quien entrega el dinero. Por defecto `-`. |\n| `date_of_issue` | date | Sí | `YYYY-MM-DD`. |\n| `time_of_issue` | string | Sí | `HH:MM:SS`. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric | No | Sin él o con `0`, el tipo de cambio del día (en soles sin tipo registrado, `1`). |\n| `establishment_id` | integer | Sí | Establecimiento. |\n| `total` | numeric | Sí | Total (> 0). |\n| `items` | array | Sí | `[{description, total}]`. |\n| `payments` | array | Sí | `[{date_of_payment, payment_method_type_id, payment_destination_id, payment, reference}]`. La suma debe ser **igual** a `total`. |\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Respuestas:** `200` con `success: true` y `data` (`id`, `external_id`, `number`, `print_url`); `422` por validación; `200` con `success: false` si una regla de caja lo impide.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 8,
                        "external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
                        "number": "1",
                        "print_url": "https://empresa.dominio/print/income/9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Pagos no cuadran",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagos no cuadran",
                    "value": {
                      "success": false,
                      "message": {
                        "payments": [
                          "Los montos ingresados no coinciden con el monto total."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar ingreso (heredado)",
                  "value": {
                    "income_type_id": 1,
                    "income_reason_id": 1,
                    "customer": "CARLOS RAMIREZ",
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "11:20:00",
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 1,
                    "establishment_id": 1,
                    "total": 120.0,
                    "items": [
                      {
                        "description": "Aporte de capital",
                        "total": 120.0
                      }
                    ],
                    "payments": [
                      {
                        "date_of_payment": "2026-11-07",
                        "payment_method_type_id": "01",
                        "payment_destination_id": "cash",
                        "payment": 120.0,
                        "reference": null
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/finances/income/{income_id}/void": {
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Anular ingreso (heredado)",
        "operationId": "AnularIngresoHeredado",
        "description": "**Vía recomendada:** `POST /api/incomes/{id}/void` (`409` si ya está anulado; `403` si es de otro vendedor). Anular un ingreso ya anulado responde aquí `200` con `success: false`.\n\nAnula un ingreso (estado `11`) y revierte sus cobros.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nSin cuerpo. `404` si no existe.",
        "responses": {
          "200": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": true,
                      "message": "Ingreso anulado exitosamente"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/finances/movements-scroll": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Movimientos de dinero",
        "operationId": "MovimientosDinero",
        "description": "Lista unificada de **entradas y salidas de dinero** (cobros de ventas, notas de venta, ingresos, gastos, compras, transferencias...) con paginación por cursor (`limit` máx. 100, por defecto 20).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Movimientos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Movimientos",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 9001,
                          "date_of_payment": "2026-11-07",
                          "time_of_payment": "11:20:00",
                          "type_movement": "input",
                          "instance_type": "income",
                          "instance_type_description": "Ingreso",
                          "document_type_description": "Ingreso",
                          "number_full": "ING-1",
                          "person_name": "CARLOS RAMIREZ",
                          "person_number": null,
                          "payment_method_type_description": "Efectivo",
                          "destination": {
                            "type": "cash",
                            "id": 4,
                            "name": "CAJA - JUAN PEREZ"
                          },
                          "currency_type_id": "PEN",
                          "amount": 120.0,
                          "amount_pen": 120.0,
                          "reference": null,
                          "user_name": "JUAN PEREZ"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de pago (`YYYY-MM-DD`). Por defecto, inicio del mes actual."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha de pago. Por defecto, fin del mes actual."
          },
          {
            "name": "type_movement",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "input",
            "description": "`input` (entradas de dinero) u `output` (salidas)."
          },
          {
            "name": "instance_types[]",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "income",
            "description": "Origen del movimiento; puede repetirse. Valores: `document`, `sale_note`, `quotation`, `contract`, `technical_service`, `income`, `cash_transaction`, `purchase`, `purchase_settlement`, `expense`, `bank_loan_payment`, `transfer_account`."
          },
          {
            "name": "destination",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "cash",
            "description": "`cash` (cajas) o `bank:{id}` (una cuenta concreta, p. ej. `bank:3`)."
          },
          {
            "name": "last_cash_opening",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = solo los movimientos de la caja abierta del usuario."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "20",
            "description": "Registros por página (máx. 100)."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/finances/movements-summary": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Resumen de movimientos",
        "operationId": "ResumenMovimientos",
        "description": "Totales del periodo con los **mismos filtros** que *Movimientos de dinero*: cantidad, total de entradas, total de salidas y saldo. Montos en soles (los movimientos en dólares se convierten con su tipo de cambio). Las transferencias entre cuentas no afectan el saldo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Resumen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Resumen",
                    "value": {
                      "success": true,
                      "data": {
                        "count": 42,
                        "total_input": 3580.5,
                        "total_output": 1240.0,
                        "balance": 2340.5
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de pago (`YYYY-MM-DD`). Por defecto, inicio del mes actual."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha de pago. Por defecto, fin del mes actual."
          },
          {
            "name": "type_movement",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "input",
            "description": "`input` (entradas de dinero) u `output` (salidas)."
          },
          {
            "name": "instance_types[]",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "income",
            "description": "Origen del movimiento; puede repetirse. Valores: `document`, `sale_note`, `quotation`, `contract`, `technical_service`, `income`, `cash_transaction`, `purchase`, `purchase_settlement`, `expense`, `bank_loan_payment`, `transfer_account`."
          },
          {
            "name": "destination",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "cash",
            "description": "`cash` (cajas) o `bank:{id}` (una cuenta concreta, p. ej. `bank:3`)."
          },
          {
            "name": "last_cash_opening",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = solo los movimientos de la caja abierta del usuario."
          }
        ]
      }
    },
    "/api/incomes/{income_id}/void": {
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Anular ingreso",
        "operationId": "AnularIngreso",
        "description": "Anula el ingreso (estado `11`): sus cobros dejan de contar y el dinero sale de la caja o cuenta donde entró. No se puede deshacer.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `200` con el ingreso anulado (ítems y cobros).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `income_id` | integer | Sí | Id del ingreso. |\n\nSin cuerpo.\n\n**Reglas:**\n- Un ingreso ya anulado no se anula otra vez (`409`).\n- Si el cobro en efectivo pertenece a una caja ya cerrada, la anulación **sí** se permite: esa caja no cambia y la salida del dinero se refleja en la siguiente caja que abra el cajero.\n\n**Errores:**\n- `409` si ya está anulado.\n- `403` si el ingreso es de otro vendedor.\n- `404` si no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 8,
                        "external_id": "9b2d4e6f-1a3c-4b5d-8e7f-0a1b2c3d4e5f",
                        "number": "1",
                        "number_full": "ING-1",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "11:20:00",
                        "state_type_id": "11",
                        "state_type_description": "Anulado",
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 120.0,
                        "user_id": 5,
                        "establishment_id": 1,
                        "income_type_id": 1,
                        "income_type_description": "Otros ingresos",
                        "income_reason_id": 1,
                        "income_reason_description": "Aporte de socio",
                        "customer": "CARLOS RAMIREZ",
                        "items": [
                          {
                            "id": 11,
                            "description": "Aporte de capital",
                            "total": 120.0
                          }
                        ],
                        "payments": [
                          {
                            "id": 15,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "destination_description": "CAJA - JUAN PEREZ",
                            "reference": null,
                            "payment": 120.0
                          }
                        ]
                      },
                      "message": "Ingreso anulado exitosamente"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya anulado",
                    "value": {
                      "success": false,
                      "message": "El ingreso ya está anulado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/expense-reasons": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar motivos de gasto",
        "operationId": "ListarMotivosGasto",
        "description": "Lista motivos de gasto ordenados por descripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 2,
                          "description": "Servicios"
                        },
                        {
                          "id": 3,
                          "description": "Movilidad"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar (coincidencia parcial)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Crear motivo de gasto",
        "operationId": "CrearMotivoGasto",
        "description": "Registra un motivo de gasto.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción (máx. 255). |\n\n**Errores:** `422` si falta un campo obligatorio o no cumple el formato.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "Servicios"
                      },
                      "message": "Motivo de gasto registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "description": [
                          "El campo description es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear motivo de gasto",
                  "value": {
                    "description": "Servicios"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/expense-reasons/{expense_reason_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver motivo de gasto",
        "operationId": "VerMotivoGasto",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "Servicios"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_reason_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar motivo de gasto",
        "operationId": "EditarMotivoGasto",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*.\n\n**Errores:** `422`; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "description": "Servicios"
                      },
                      "message": "Motivo de gasto editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_reason_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar motivo de gasto",
                  "value": {
                    "description": "Servicios"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Eliminar motivo de gasto",
        "operationId": "EliminarMotivoGasto",
        "description": "Elimina un registro que no esté en uso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por otros registros; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2
                      },
                      "message": "Motivo de gasto eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El motivo está siendo usado por gastos registrados, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_reason_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/expense-types": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar tipos de gasto",
        "operationId": "ListarTiposGasto",
        "description": "Lista tipos de gasto ordenados por descripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "FACTURA"
                        },
                        {
                          "id": 4,
                          "description": "Otros"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar (coincidencia parcial)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Crear tipo de gasto",
        "operationId": "CrearTipoGasto",
        "description": "Registra un tipo de gasto.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción (máx. 255). |\n\n**Errores:** `422` si falta un campo obligatorio o no cumple el formato.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "FACTURA"
                      },
                      "message": "Tipo de gasto registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "description": [
                          "El campo description es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear tipo de gasto",
                  "value": {
                    "description": "RECIBO POR HONORARIOS"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/expense-types/{expense_type_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver tipo de gasto",
        "operationId": "VerTipoGasto",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "FACTURA"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar tipo de gasto",
        "operationId": "EditarTipoGasto",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*.\n\n**Errores:** `422`; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "FACTURA"
                      },
                      "message": "Tipo de gasto editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar tipo de gasto",
                  "value": {
                    "description": "RECIBO POR HONORARIOS"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Eliminar tipo de gasto",
        "operationId": "EliminarTipoGasto",
        "description": "Elimina un registro que no esté en uso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por otros registros; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1
                      },
                      "message": "Tipo de gasto eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El tipo está siendo usado por gastos registrados, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/expense-method-types": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar métodos de gasto",
        "operationId": "ListarMetodosGasto",
        "description": "Lista métodos de gasto ordenados por descripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "CAJA GENERAL",
                          "has_card": false
                        },
                        {
                          "id": 2,
                          "description": "TARJETA",
                          "has_card": true
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar (coincidencia parcial)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Crear método de gasto",
        "operationId": "CrearMetodoGasto",
        "description": "Registra un método de gasto.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción (máx. 255). |\n| `has_card` | boolean | No | `true` si el método es con tarjeta. |\n\n**Errores:** `422` si falta un campo obligatorio o no cumple el formato.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "CAJA GENERAL",
                        "has_card": false
                      },
                      "message": "Método de gasto registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "description": [
                          "El campo description es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear método de gasto",
                  "value": {
                    "description": "TRANSFERENCIA BANCARIA",
                    "has_card": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/expense-method-types/{expense_method_type_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver método de gasto",
        "operationId": "VerMetodoGasto",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "CAJA GENERAL",
                        "has_card": false
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar método de gasto",
        "operationId": "EditarMetodoGasto",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*.\n\n**Errores:** `422`; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "CAJA GENERAL",
                        "has_card": false
                      },
                      "message": "Método de gasto editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar método de gasto",
                  "value": {
                    "description": "TRANSFERENCIA BANCARIA",
                    "has_card": false
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Eliminar método de gasto",
        "operationId": "EliminarMetodoGasto",
        "description": "Elimina un registro que no esté en uso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por otros registros; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1
                      },
                      "message": "Método de gasto eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El método está siendo usado por pagos de gastos, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "expense_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/income-reasons": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar motivos de ingreso",
        "operationId": "ListarMotivosIngreso",
        "description": "Lista motivos de ingreso ordenados por descripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "Aporte de socio"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar (coincidencia parcial)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Crear motivo de ingreso",
        "operationId": "CrearMotivoIngreso",
        "description": "Registra un motivo de ingreso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción (máx. 255). |\n\n**Errores:** `422` si falta un campo obligatorio o no cumple el formato.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Aporte de socio"
                      },
                      "message": "Motivo de ingreso registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "description": [
                          "El campo description es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear motivo de ingreso",
                  "value": {
                    "description": "Aporte de socio"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/income-reasons/{income_reason_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver motivo de ingreso",
        "operationId": "VerMotivoIngreso",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Aporte de socio"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_reason_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar motivo de ingreso",
        "operationId": "EditarMotivoIngreso",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*.\n\n**Errores:** `422`; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Aporte de socio"
                      },
                      "message": "Motivo de ingreso editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_reason_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar motivo de ingreso",
                  "value": {
                    "description": "Aporte de socio"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Eliminar motivo de ingreso",
        "operationId": "EliminarMotivoIngreso",
        "description": "Elimina un registro que no esté en uso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por otros registros; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1
                      },
                      "message": "Motivo de ingreso eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El motivo está siendo usado por ingresos registrados, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_reason_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/income-types": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Listar tipos de ingreso",
        "operationId": "ListarTiposIngreso",
        "description": "Lista tipos de ingreso ordenados por descripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "Otros ingresos"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar (coincidencia parcial)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Crear tipo de ingreso",
        "operationId": "CrearTipoIngreso",
        "description": "Registra un tipo de ingreso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción (máx. 255). |\n\n**Errores:** `422` si falta un campo obligatorio o no cumple el formato.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Otros ingresos"
                      },
                      "message": "Tipo de ingreso registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "description": [
                          "El campo description es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear tipo de ingreso",
                  "value": {
                    "description": "Préstamo recibido"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/income-types/{income_type_id}": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Ver tipo de ingreso",
        "operationId": "VerTipoIngreso",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Otros ingresos"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Editar tipo de ingreso",
        "operationId": "EditarTipoIngreso",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*.\n\n**Errores:** `422`; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "Otros ingresos"
                      },
                      "message": "Tipo de ingreso editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar tipo de ingreso",
                  "value": {
                    "description": "Préstamo recibido"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Eliminar tipo de ingreso",
        "operationId": "EliminarTipoIngreso",
        "description": "Elimina un registro que no esté en uso.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por otros registros; `404` si no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1
                      },
                      "message": "Tipo de ingreso eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El tipo está siendo usado por ingresos registrados, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "income_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/finances/tables": {
      "get": {
        "tags": [
          "Gastos e ingresos"
        ],
        "summary": "Catálogos de finanzas",
        "operationId": "CatalogosFinanzas",
        "description": "Devuelve en una sola llamada todo lo necesario para registrar gastos, ingresos y pagos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n`data` contiene: `income_types`, `income_reasons`, `expense_types`, `expense_reasons`, `expense_method_types` (con `has_card`), `payment_method_types` (métodos de pago de la empresa), `payment_destinations` (cuentas disponibles para el establecimiento y la caja abierta del usuario, con `id` = `cash` para la caja), `currency_types`, `open_cash` (caja abierta del usuario o `null`), `expense_number_optional_type_id` (tipo de gasto que no exige número) e `instance_types` (orígenes de movimientos).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "success": true,
                      "data": {
                        "income_types": [
                          {
                            "id": 1,
                            "description": "Otros ingresos"
                          }
                        ],
                        "income_reasons": [
                          {
                            "id": 1,
                            "description": "Aporte de socio"
                          }
                        ],
                        "expense_types": [
                          {
                            "id": 1,
                            "description": "FACTURA"
                          },
                          {
                            "id": 4,
                            "description": "Otros"
                          }
                        ],
                        "expense_reasons": [
                          {
                            "id": 2,
                            "description": "Servicios"
                          }
                        ],
                        "expense_method_types": [
                          {
                            "id": 1,
                            "description": "CAJA GENERAL",
                            "has_card": false
                          }
                        ],
                        "payment_method_types": [
                          {
                            "id": "01",
                            "description": "Efectivo"
                          },
                          {
                            "id": "04",
                            "description": "Transferencia"
                          }
                        ],
                        "payment_destinations": [
                          {
                            "id": 3,
                            "description": "BCP SOLES"
                          },
                          {
                            "id": "cash",
                            "description": "CAJA GENERAL - JUAN PEREZ"
                          }
                        ],
                        "currency_types": [
                          {
                            "id": "PEN",
                            "description": "Soles",
                            "symbol": "S/"
                          },
                          {
                            "id": "USD",
                            "description": "Dólares Americanos",
                            "symbol": "$"
                          }
                        ],
                        "open_cash": {
                          "id": 4,
                          "reference_number": "CAJA-0004",
                          "date_opening": "2026-11-07"
                        },
                        "expense_number_optional_type_id": 4,
                        "instance_types": [
                          {
                            "id": "income",
                            "description": "Ingreso",
                            "type_movement": "input"
                          },
                          {
                            "id": "expense",
                            "description": "Gasto",
                            "type_movement": "output"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/purchases/{purchase_id}": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Ver compra",
        "operationId": "VerCompra",
        "description": "Devuelve la compra con sus ítems, pagos, total pagado y saldo pendiente.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `404`; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 77,
                        "external_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                        "document_type_id": "01",
                        "document_type_description": "FACTURA ELECTRÓNICA",
                        "series": "F001",
                        "number": "4587",
                        "number_full": "F001-4587",
                        "date_of_issue": "2026-11-07",
                        "date_of_due": "2026-12-07",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                          "number": "20456789123"
                        },
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 118.0,
                        "total_paid": 50.0,
                        "total_pending": 68.0,
                        "observation": "Entrega en almacén central",
                        "user_id": 5,
                        "establishment_id": 1,
                        "items": [
                          {
                            "id": 301,
                            "item_id": 120,
                            "description": "GASEOSA 500ML",
                            "quantity": 50.0,
                            "unit_price": 2.36,
                            "total": 118.0,
                            "warehouse_id": 1,
                            "lot_code": null
                          }
                        ],
                        "payments": [
                          {
                            "id": 51,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "04",
                            "payment_method_type_description": "Transferencia",
                            "destination_type": "BankAccount",
                            "destination_id": 3,
                            "destination_description": "BCP SOLES",
                            "reference": "OP-99812",
                            "payment": 50.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Compras"
        ],
        "summary": "Editar compra (observación y vencimiento)",
        "operationId": "EditarCompraObservacionVencimiento",
        "description": "Edita solo datos que no mueven stock ni dinero. Acepta `PUT` o `PATCH`; ambos campos son opcionales.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Permisos adicionales del usuario** (se activan en *3. Usuarios*): editar exige `edit_purchase`, anular `annular_purchase` y eliminar `delete_purchase`. Sin el permiso responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `observation` | string | No | Observación (máx. 1000, puede ser `null`). |\n| `date_of_due` | date | No | Fecha de vencimiento `YYYY-MM-DD` (puede ser `null`). |\n\n**Errores:** `403` sin permiso `edit_purchase` o si es de otro vendedor; `409` si la compra está anulada; `422`; `404`.",
        "responses": {
          "200": {
            "description": "Editada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 77,
                        "external_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                        "document_type_id": "01",
                        "document_type_description": "FACTURA ELECTRÓNICA",
                        "series": "F001",
                        "number": "4587",
                        "number_full": "F001-4587",
                        "date_of_issue": "2026-11-07",
                        "date_of_due": "2026-12-15",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                          "number": "20456789123"
                        },
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 118.0,
                        "total_paid": 50.0,
                        "total_pending": 68.0,
                        "observation": "Entrega parcial, saldo la próxima semana",
                        "user_id": 5,
                        "establishment_id": 1,
                        "items": [
                          {
                            "id": 301,
                            "item_id": 120,
                            "description": "GASEOSA 500ML",
                            "quantity": 50.0,
                            "unit_price": 2.36,
                            "total": 118.0,
                            "warehouse_id": 1,
                            "lot_code": null
                          }
                        ],
                        "payments": [
                          {
                            "id": 51,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "04",
                            "payment_method_type_description": "Transferencia",
                            "destination_type": "BankAccount",
                            "destination_id": 3,
                            "destination_description": "BCP SOLES",
                            "reference": "OP-99812",
                            "payment": 50.0
                          }
                        ]
                      },
                      "message": "Compra actualizada"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin permiso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin permiso",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para editar compras."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulada",
                    "value": {
                      "success": false,
                      "message": "La compra está anulada y no se puede editar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar compra (observación y vencimiento)",
                  "value": {
                    "observation": "Entrega parcial, saldo la próxima semana",
                    "date_of_due": "2026-12-15"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Compras"
        ],
        "summary": "Eliminar compra anulada",
        "operationId": "EliminarCompraAnulada",
        "description": "Elimina definitivamente una compra **ya anulada**, con sus pagos y movimientos de kárdex.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Permisos adicionales del usuario** (se activan en *3. Usuarios*): editar exige `edit_purchase`, anular `annular_purchase` y eliminar `delete_purchase`. Sin el permiso responde `403`.\n\n**Errores:** `409` si la compra no está anulada (anúlala primero) o si alguno de sus pagos pertenece a una caja cerrada; `403` sin permiso `delete_purchase`; `404`.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 77
                      },
                      "message": "Compra eliminada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "No anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No anulada",
                    "value": {
                      "success": false,
                      "message": "Solo se puede eliminar una compra anulada. Anúlala primero."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/purchases/{purchase_id}/void": {
      "post": {
        "tags": [
          "Compras"
        ],
        "summary": "Anular compra",
        "operationId": "AnularCompra",
        "description": "Anula la compra (estado `11`): revierte el stock que ingresó, sus lotes y el costo promedio, y saca sus pagos de caja/bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Permisos adicionales del usuario** (se activan en *3. Usuarios*): editar exige `edit_purchase`, anular `annular_purchase` y eliminar `delete_purchase`. Sin el permiso responde `403`.\n\nSin cuerpo.\n\n**Errores (`409`):** la compra ya está anulada; alguno de sus productos ya se vendió (lotes/series vendidos) y no se puede revertir; una regla de caja lo impide. `403` sin permiso `annular_purchase`; `404`.",
        "responses": {
          "200": {
            "description": "Anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 77,
                        "external_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                        "document_type_id": "01",
                        "document_type_description": "FACTURA ELECTRÓNICA",
                        "series": "F001",
                        "number": "4587",
                        "number_full": "F001-4587",
                        "date_of_issue": "2026-11-07",
                        "date_of_due": "2026-12-07",
                        "state_type_id": "11",
                        "state_type_description": "Anulado",
                        "supplier_id": 14,
                        "supplier": {
                          "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                          "number": "20456789123"
                        },
                        "currency_type_id": "PEN",
                        "exchange_rate_sale": 1.0,
                        "total": 118.0,
                        "total_paid": 50.0,
                        "total_pending": 68.0,
                        "observation": "Entrega en almacén central",
                        "user_id": 5,
                        "establishment_id": 1,
                        "items": [
                          {
                            "id": 301,
                            "item_id": 120,
                            "description": "GASEOSA 500ML",
                            "quantity": 50.0,
                            "unit_price": 2.36,
                            "total": 118.0,
                            "warehouse_id": 1,
                            "lot_code": null
                          }
                        ],
                        "payments": [
                          {
                            "id": 51,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "04",
                            "payment_method_type_description": "Transferencia",
                            "destination_type": "BankAccount",
                            "destination_id": 3,
                            "destination_description": "BCP SOLES",
                            "reference": "OP-99812",
                            "payment": 50.0
                          }
                        ]
                      },
                      "message": "Compra anulada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya anulada",
                    "value": {
                      "success": false,
                      "message": "La compra ya se encuentra anulada"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin permiso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin permiso",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para anular compras."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/purchases/{purchase_id}/payments": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Listar pagos de compra",
        "operationId": "ListarPagosCompra",
        "description": "Devuelve los pagos registrados y el resumen de lo pagado y pendiente.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n`summary` trae `total` (total del registro), `total_paid` (suma de pagos) y `total_difference` (saldo pendiente).\n\n**Errores:** `404` si el registro no existe; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Pagos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagos",
                    "value": {
                      "success": true,
                      "data": {
                        "summary": {
                          "total": 50.0,
                          "total_paid": 20.0,
                          "total_difference": 30.0
                        },
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "04",
                            "payment_method_type_description": "Transferencia",
                            "destination_type": "BankAccount",
                            "destination_id": 3,
                            "destination_description": "BCP SOLES",
                            "reference": "OP-458721",
                            "payment": 20.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "post": {
        "tags": [
          "Compras"
        ],
        "summary": "Registrar pago de compra",
        "operationId": "RegistrarPagoCompra",
        "description": "Registra un pago (total o parcial). El dinero entra/sale del destino indicado (caja o cuenta) y queda en el libro de caja y bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_of_payment` | date | Sí | Fecha del pago `YYYY-MM-DD`. |\n| `payment_method_type_id` | string | Sí | Método de pago (`01` efectivo, `04` transferencia...). |\n| `payment_destination_id` | string/integer | Sí | `cash` o id de cuenta bancaria/billetera. |\n| `payment` | numeric | Sí | Monto, mayor que 0. |\n| `reference` | string | No | Referencia: número de operación, voucher, etc. |\n| `has_card` | boolean | No | `true` si fue con tarjeta. |\n| `card_brand_id` | string | No | Marca de tarjeta: `01` Visa, `02` Mastercard... |\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Responde `409` cuando una regla de caja lo impide**, por ejemplo:\n- destino `cash` y el usuario no tiene una caja abierta;\n- el método de pago no está habilitado para ese tipo de operación o destino;\n- el pago pertenece a una caja ya cerrada (al eliminar);\n- el mismo pago (mismo monto y método) se registró hace menos de 20 segundos (protección contra doble envío);\n- el registro está anulado.\n\nEl mensaje (`message`) explica la causa y puede mostrarse al usuario tal cual.\n\n**Otros errores:** `422` si falta un campo o `payment` ≤ 0; `404` si el registro no existe; `403` si es de otro vendedor.\n\nLa respuesta trae el pago creado (`data.payment`) y el resumen actualizado (`data.summary`). `summary` trae `total` (total del registro), `total_paid` (suma de pagos) y `total_difference` (saldo pendiente).",
        "responses": {
          "201": {
            "description": "Pago registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pago registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "payment": {
                          "id": 31,
                          "date_of_payment": "2026-11-07",
                          "payment_method_type_id": "04",
                          "payment_method_type_description": "Transferencia",
                          "destination_type": "BankAccount",
                          "destination_id": 3,
                          "destination_description": "BCP SOLES",
                          "reference": "OP-458721",
                          "payment": 20.0
                        },
                        "summary": {
                          "total": 50.0,
                          "total_paid": 20.0,
                          "total_difference": 30.0
                        }
                      },
                      "message": "Pago registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Monto inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Monto inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "payment": [
                          "El campo payment debe ser mayor que 0."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin caja abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar pago de compra",
                  "value": {
                    "date_of_payment": "2026-11-07",
                    "payment_method_type_id": "04",
                    "payment_destination_id": 3,
                    "payment": 20.0,
                    "reference": "OP-458721",
                    "has_card": false,
                    "card_brand_id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/purchase-payments/{purchase_payment_id}": {
      "delete": {
        "tags": [
          "Compras"
        ],
        "summary": "Eliminar pago de compra",
        "operationId": "EliminarPagoCompra",
        "description": "Elimina un pago y revierte su movimiento en caja o cuenta. El id es el del **pago** (`data.payment.id` al registrarlo o `payments[].id` al listarlos).\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `409` si el pago pertenece a una caja ya cerrada; `404` si el pago no existe; `403` si el registro es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Pago eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pago eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 31,
                        "summary": {
                          "total": 50.0,
                          "total_paid": 0.0,
                          "total_difference": 50.0
                        }
                      },
                      "message": "Pago eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Caja cerrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja cerrada",
                    "value": {
                      "success": false,
                      "message": "No se puede eliminar este pago: pertenece a la caja #4, que ya está cerrada y su arqueo no puede cambiar. Si hubo un error, anula la operación: la devolución se registra en la caja abierta."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/purchases": {
      "post": {
        "tags": [
          "Compras"
        ],
        "summary": "Registrar compra",
        "operationId": "RegistrarCompra",
        "description": "Registra una compra y **suma el stock** de cada ítem en su almacén. Los pagos se registran después con *Registrar pago de compra*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_type_id` | string | Sí | Tipo de comprobante del proveedor: `01` factura, `03` boleta, `GU75` guía, `NE76` nota de entrada (ver `GET /api/purchases/tables`). |\n| `series` | string | Sí | Serie del comprobante del proveedor (p. ej. `F001`). |\n| `number` | numeric | Sí | Número del comprobante (solo dígitos). |\n| `date_of_issue` | date | Sí | Fecha de emisión `YYYY-MM-DD`. |\n| `time_of_issue` | string | Sí | Hora `HH:MM:SS`. |\n| `date_of_due` | date | No | Fecha de vencimiento. |\n| `supplier_id` | integer | Sí | Id del proveedor (persona de tipo proveedor). |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric | Sí | Tipo de cambio (`1` en soles). |\n| `total_* / total` | numeric | Sí | Totales de cabecera: `total_taxed` (gravado), `total_exonerated`, `total_unaffected`, `total_free`, `total_igv`, `total_taxes`, `total_value` (sin IGV), `subtotal` y `total` (con IGV). Deben cuadrar con la suma de las líneas: la plataforma **no recalcula** los totales que envías. |\n| `total_perception` | numeric | No | Percepción. |\n| `observation` | string | No | Observación. |\n| `items` | array | Sí | Líneas de la compra (ver tabla de líneas). `unit_price` es el costo con IGV. Opcionales propios de compras: `warehouse_id` (almacén donde entra el stock), `lot_code` y `date_of_due` (lote y vencimiento), `affectation_igv_type` (objeto de la afectación). |\n| `charges / discounts / attributes / guides / payments` | array | No | Usa `[]`. Los pagos enviados aquí **no** se registran. |\n\n**Línea de la compra (`items[]`):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Id del producto. |\n| `item` | object | Sí | Copia del producto tal como se guardará en el documento (al menos `id`, `description`, `unit_type_id`, `internal_id`, `is_set`, `presentation`). Se obtiene de los endpoints de productos de la API. |\n| `quantity` | numeric | Sí | Cantidad (> 0). |\n| `unit_value` | numeric | Sí | Valor unitario **sin** IGV. |\n| `unit_price` | numeric | Sí | Precio unitario **con** IGV. |\n| `affectation_igv_type_id` | string | Sí | Afectación IGV (catálogo SUNAT 07): `10` gravado, `20` exonerado, `30` inafecto. |\n| `price_type_id` | string | Sí | `01` precio unitario (incluye IGV), `02` valor referencial (gratuito). |\n| `percentage_igv` | numeric | Sí | Porcentaje de IGV (`18`, o `10` si aplica la Ley 31556). |\n| `total_base_igv / total_igv / total_taxes / total_value / total` | numeric | Sí | Totales de la línea: base imponible, IGV, impuestos, valor (sin IGV) y total (con IGV). |\n| `warehouse_id` | integer | No | Almacén del que sale el stock (por defecto el del establecimiento). |\n| `total_discount / total_charge / charges / discounts / attributes` | varios | No | Descuentos, cargos y atributos de la línea (usa `0` y `[]` si no aplica). |\n| `system_isc_type_id / total_base_isc / percentage_isc / total_isc / total_plastic_bag_taxes` | varios | No | ISC e ICBPER (usa `null`/`0` si no aplica). |\n\n**Errores:** `422` si falta `supplier_id`, `series`, `number` (o no es numérico), `date_of_issue` o `items`.\n\n**Respuesta:** `data` con `id`, `number_full`, `external_id`, `state_type_id`, proveedor, `total` y enlaces al PDF (`print_a4`, `print_ticket`).",
        "responses": {
          "200": {
            "description": "Registrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 77,
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "number_full": "F001-4587",
                        "external_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                        "filename": "F001-4587-77-20261107",
                        "supplier": {
                          "id": 14,
                          "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                          "number": "20456789123",
                          "email": null,
                          "phone": null
                        },
                        "total": 118.0,
                        "print_a4": "https://empresa.dominio/purchases/print/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/a4",
                        "print_ticket": "https://empresa.dominio/purchases/print/c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f/ticket"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "number": [
                          "number debe ser numérico."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar compra",
                  "value": {
                    "document_type_id": "01",
                    "series": "F001",
                    "number": "4587",
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "09:30:00",
                    "date_of_due": "2026-12-07",
                    "supplier_id": 14,
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 1,
                    "total_prepayment": 0,
                    "total_charge": 0,
                    "total_discount": 0,
                    "total_exportation": 0,
                    "total_free": 0,
                    "total_taxed": 100.0,
                    "total_unaffected": 0,
                    "total_exonerated": 0,
                    "total_igv": 18.0,
                    "total_base_isc": 0,
                    "total_isc": 0,
                    "total_base_other_taxes": 0,
                    "total_other_taxes": 0,
                    "total_taxes": 18.0,
                    "total_value": 100.0,
                    "total": 118.0,
                    "total_perception": 0,
                    "observation": "Entrega en almacén central",
                    "items": [
                      {
                        "item_id": 120,
                        "item": {
                          "id": 120,
                          "item_id": 120,
                          "internal_id": "P0001",
                          "description": "GASEOSA 500ML",
                          "unit_type_id": "NIU",
                          "currency_type_id": "PEN",
                          "sale_unit_price": 3.5,
                          "purchase_unit_price": 2.2,
                          "sale_affectation_igv_type_id": "10",
                          "purchase_affectation_igv_type_id": "10",
                          "is_set": false,
                          "has_igv": true,
                          "presentation": null
                        },
                        "currency_type_id": "PEN",
                        "quantity": 50,
                        "unit_value": 2.0,
                        "affectation_igv_type_id": "10",
                        "total_base_igv": 100.0,
                        "percentage_igv": 18,
                        "total_igv": 18.0,
                        "system_isc_type_id": null,
                        "total_base_isc": 0,
                        "percentage_isc": 0,
                        "total_isc": 0,
                        "total_base_other_taxes": 0,
                        "percentage_other_taxes": 0,
                        "total_other_taxes": 0,
                        "total_plastic_bag_taxes": 0,
                        "total_taxes": 18.0,
                        "price_type_id": "01",
                        "unit_price": 2.36,
                        "total_value": 100.0,
                        "total_discount": 0,
                        "total_charge": 0,
                        "total": 118.0,
                        "attributes": [],
                        "charges": [],
                        "discounts": [],
                        "warehouse_id": 1,
                        "affectation_igv_type": {
                          "id": "10",
                          "active": 1,
                          "exportation": 0,
                          "free": 0,
                          "description": "Gravado - Operación Onerosa"
                        },
                        "lot_code": null,
                        "date_of_due": null
                      }
                    ],
                    "charges": [],
                    "discounts": [],
                    "attributes": [],
                    "guides": [],
                    "payments": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/purchases/records-scroll": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Listar compras con cursor",
        "operationId": "ListarComprasCursor",
        "description": "Listado de compras paginado por cursor (más recientes primero). Un vendedor solo ve las suyas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 77,
                          "external_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                          "document_type_id": "01",
                          "document_type_description": "FACTURA ELECTRÓNICA",
                          "series": "F001",
                          "number": "4587",
                          "number_full": "F001-4587",
                          "date_of_issue": "2026-11-07",
                          "date_of_due": "2026-12-07",
                          "currency_type_id": "PEN",
                          "total": 118.0,
                          "total_canceled": false,
                          "state_type_id": "01",
                          "state_type_description": "Registrado",
                          "supplier": {
                            "id": 14,
                            "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                            "number": "20456789123"
                          },
                          "user": {
                            "id": 5,
                            "name": "JUAN PEREZ"
                          },
                          "items_count": 1
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Tipo de comprobante."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Estado (`01` registrado, `11` anulado)."
          },
          {
            "name": "series",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "F001",
            "description": "Serie exacta."
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "4587",
            "description": "Número (coincidencia parcial)."
          },
          {
            "name": "supplier_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Proveedor."
          },
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde (requiere también `date_end`)."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta."
          },
          {
            "name": "total_canceled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "0",
            "description": "`1` pagadas, `0` con saldo pendiente."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/purchases/records": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Últimas compras",
        "operationId": "UltimasCompras",
        "description": "Devuelve las últimas compras (cantidad fija por página de la plataforma, normalmente 20), con búsqueda simple por serie o número. Para integraciones se recomienda `records-scroll`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 77,
                          "document_type_description": "FACTURA ELECTRÓNICA",
                          "date_of_issue": "2026-11-07",
                          "number": "F001-4587",
                          "supplier_name": "DISTRIBUIDORA DEL SUR S.A.C.",
                          "supplier_number": "20456789123",
                          "currency_type_id": "PEN",
                          "total": "118.00",
                          "state_type_id": "01",
                          "state_type_description": "Registrado"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "F001",
            "description": "Texto a buscar en serie o número."
          }
        ]
      }
    },
    "/api/purchases/tables": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Catálogos de compras",
        "operationId": "CatalogosCompras",
        "description": "Tipos de documento permitidos al registrar una compra.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "document_types_invoice": [
                        {
                          "id": "01",
                          "description": "FACTURA ELECTRÓNICA"
                        },
                        {
                          "id": "03",
                          "description": "BOLETA DE VENTA ELECTRÓNICA"
                        },
                        {
                          "id": "GU75",
                          "description": "GUÍA"
                        },
                        {
                          "id": "NE76",
                          "description": "NOTA DE ENTRADA"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/purchase/find/{purchase_id}": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Ver compra para impresión",
        "operationId": "VerCompraImpresion",
        "description": "Devuelve la compra en formato de impresión (proveedor, totales, ítems, leyendas). Un vendedor solo accede a las suyas (`404` si no).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Compra",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Compra",
                    "value": {
                      "data": {
                        "series": "F001",
                        "number": "4587",
                        "document_type_id": "01",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "09:30:00",
                        "currency_type_id": "PEN",
                        "supplier_name": "DISTRIBUIDORA DEL SUR S.A.C.",
                        "supplier_number": "20456789123",
                        "total_taxed": 100.0,
                        "total_igv": 18.0,
                        "total": 118.0,
                        "items": [],
                        "legends": []
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No encontrada",
                    "value": {
                      "success": false,
                      "message": "No se encontró la compra solicitada."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/purchase/email": {
      "post": {
        "tags": [
          "Compras"
        ],
        "summary": "Enviar compra por correo",
        "operationId": "EnviarCompraCorreo",
        "description": "Envía la compra en PDF por correo electrónico usando la configuración de correo de la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del registro. |\n| `email` | string | Sí | Correo de destino. Para varios destinatarios sepáralos con coma. |\n\n**Reglas y errores:** no hay validación del cuerpo; la respuesta es `success: true` aunque el correo no llegue (el envío queda en el historial de correos de la empresa). Un `id` inexistente responde `500`.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Email enviado correctamente."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Attempt to read property \"id\" on null"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar compra por correo",
                  "value": {
                    "id": "1",
                    "email": "cobranzas@delsur.pe"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/purchases/suppliers": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Proveedores (primeros 20)",
        "operationId": "ProveedoresPrimeros20",
        "description": "Primeros 20 proveedores ordenados por nombre, para cargar un selector.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado de **cantidad fija** (take/limit): devuelve como máximo N registros, sin metadatos de paginación. Arreglo sin envoltura, máximo 20.",
        "responses": {
          "200": {
            "description": "Proveedores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Proveedores",
                    "value": [
                      {
                        "id": 14,
                        "description": "20456789123 - DISTRIBUIDORA DEL SUR S.A.C.",
                        "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                        "number": "20456789123",
                        "identity_document_type_id": "6",
                        "address": "JR. LOS ANDES 789, CUSCO",
                        "email": "ventas@distsur.pe",
                        "selected": false
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/purchases/search-suppliers": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Buscar proveedores",
        "operationId": "BuscarProveedores",
        "description": "Busca proveedores por número o nombre. Con `document_type_id = 01` (factura) solo devuelve proveedores con RUC.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura ni límite.\n\n**Reglas:**\n- La coincidencia por número se combina con `OR`: puede devolver personas que no son proveedores si su número coincide. Prefiere *Proveedores (scroll)*.",
        "responses": {
          "200": {
            "description": "Proveedores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Proveedores",
                    "value": [
                      {
                        "id": 14,
                        "description": "20456789123 - DISTRIBUIDORA DEL SUR S.A.C.",
                        "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                        "number": "20456789123",
                        "identity_document_type_id": "6",
                        "address": "JR. LOS ANDES 789, CUSCO",
                        "email": "ventas@distsur.pe",
                        "selected": false
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "20456789123",
            "description": "Número o nombre (coincidencia parcial)."
          },
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Tipo de comprobante de la compra: `01` solo RUC; otro valor admite DNI, CE, RUC, pasaporte y sin documento."
          }
        ]
      }
    },
    "/api/purchases/suppliers-scroll": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Proveedores (scroll)",
        "operationId": "ProveedoresScroll",
        "description": "Proveedores con **paginación por cursor**, ordenados por nombre.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Reglas:**\n- `limit` máximo 100 (por defecto 15).",
        "responses": {
          "200": {
            "description": "Página",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Página",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 14,
                          "description": "20456789123 - DISTRIBUIDORA DEL SUR S.A.C.",
                          "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                          "number": "20456789123",
                          "identity_document_type_id": "6",
                          "address": "JR. LOS ANDES 789, CUSCO",
                          "email": "ventas@distsur.pe",
                          "selected": false
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Número o nombre (coincidencia parcial)."
          },
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "`01` solo proveedores con RUC."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/purchases/item-tables": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Catálogos para el detalle de compra",
        "operationId": "CatalogosDetalleCompra",
        "description": "Productos (no packs, activos) y tipos de afectación IGV para el detalle de una compra.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n**Reglas:**\n- `items` trae solo una muestra de 2 productos: para buscar productos usa *Listar productos para venta (scroll)* (sección [Productos](/docs/api/tenant/productos)).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "items": [
                        {
                          "id": 31,
                          "item_code": "50202301",
                          "full_description": "P0001 - GASEOSA COCA COLA 500ML",
                          "description": "GASEOSA COCA COLA 500ML",
                          "currency_type_id": "PEN",
                          "currency_type_symbol": "S/",
                          "sale_unit_price": "2.50",
                          "purchase_unit_price": "1.80",
                          "unit_type_id": "NIU",
                          "sale_affectation_igv_type_id": "10",
                          "purchase_affectation_igv_type_id": "10",
                          "has_perception": false,
                          "lots_enabled": false,
                          "percentage_perception": null
                        }
                      ],
                      "affectation_igv_types": [
                        {
                          "id": "10",
                          "active": 1,
                          "exportation": 0,
                          "free": 0,
                          "description": "Gravado - Operación Onerosa"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/purchases/table/{purchase_table}": {
      "get": {
        "tags": [
          "Compras"
        ],
        "summary": "Catálogo individual de compras",
        "operationId": "CatalogoIndividualCompras",
        "description": "`purchase_table` = `suppliers` (primeros 20 proveedores) o `items` (muestra de productos). Otro valor devuelve `[]`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura.",
        "responses": {
          "200": {
            "description": "suppliers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "suppliers",
                    "value": [
                      {
                        "id": 14,
                        "description": "20456789123 - DISTRIBUIDORA DEL SUR S.A.C.",
                        "name": "DISTRIBUIDORA DEL SUR S.A.C.",
                        "number": "20456789123",
                        "identity_document_type_id": "6",
                        "address": "JR. LOS ANDES 789, CUSCO",
                        "email": "ventas@distsur.pe",
                        "selected": false
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "purchase_table",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "suppliers"
          }
        ]
      }
    },
    "/api/sale-notes/{sale_note_id}/void": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Anular nota de venta",
        "operationId": "AnularNotaVenta",
        "description": "Anula la nota de venta (estado `11`), devuelve el stock y libera lotes y series vendidos. Sus cobros salen de caja/bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\nSin cuerpo.\n\n**Errores (`409`):** la nota ya está anulada; la nota ya se convirtió en un comprobante electrónico vigente (el mensaje indica cuál). `403` si es de otro vendedor; `404`.",
        "responses": {
          "200": {
            "description": "Anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 140,
                        "number_full": "NV01-140",
                        "state_type_id": "11"
                      },
                      "message": "N. Venta anulada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Convertida en comprobante",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Convertida en comprobante",
                    "value": {
                      "success": false,
                      "message": "La nota de venta ya se convirtió en B001-532. Anula ese comprobante en lugar de la nota."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sale_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/sale-notes/{sale_note_id}/payments": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Listar pagos de nota de venta",
        "operationId": "ListarPagosNotaVenta",
        "description": "Devuelve los pagos registrados y el resumen de lo pagado y pendiente.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n`summary` trae `total` (total del registro), `total_paid` (suma de pagos) y `total_difference` (saldo pendiente).\n\n**Errores:** `404` si el registro no existe; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Pagos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagos",
                    "value": {
                      "success": true,
                      "data": {
                        "summary": {
                          "total": 50.0,
                          "total_paid": 20.0,
                          "total_difference": 30.0
                        },
                        "payments": [
                          {
                            "id": 31,
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "04",
                            "payment_method_type_description": "Transferencia",
                            "destination_type": "BankAccount",
                            "destination_id": 3,
                            "destination_description": "BCP SOLES",
                            "reference": "OP-458721",
                            "payment": 20.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sale_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Registrar pago de nota de venta",
        "operationId": "RegistrarPagoNotaVenta",
        "description": "Registra un pago (total o parcial). El dinero entra/sale del destino indicado (caja o cuenta) y queda en el libro de caja y bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_of_payment` | date | Sí | Fecha del pago `YYYY-MM-DD`. |\n| `payment_method_type_id` | string | Sí | Método de pago (`01` efectivo, `04` transferencia...). |\n| `payment_destination_id` | string/integer | Sí | `cash` o id de cuenta bancaria/billetera. |\n| `payment` | numeric | Sí | Monto, mayor que 0. |\n| `reference` | string | No | Referencia: número de operación, voucher, etc. |\n| `has_card` | boolean | No | `true` si fue con tarjeta. |\n| `card_brand_id` | string | No | Marca de tarjeta: `01` Visa, `02` Mastercard... |\n\n**Métodos de pago (`payment_method_type_id`)**: catálogo de la empresa. Los estándar son `01` Efectivo, `02` Tarjeta de crédito, `03` Tarjeta de débito, `04` Transferencia; cada empresa puede tener otros (Yape, Plin, depósito, etc.). Obtén la lista vigente con **GET /api/finances/tables** (`data.payment_method_types`).\n\n**Destino (`payment_destination_id`)**: `cash` = la caja abierta del usuario autenticado, o el **id de una cuenta bancaria / billetera** (ver *5. Cuentas bancarias* o `data.payment_destinations` de **GET /api/finances/tables**).\n\n**Responde `409` cuando una regla de caja lo impide**, por ejemplo:\n- destino `cash` y el usuario no tiene una caja abierta;\n- el método de pago no está habilitado para ese tipo de operación o destino;\n- el pago pertenece a una caja ya cerrada (al eliminar);\n- el mismo pago (mismo monto y método) se registró hace menos de 20 segundos (protección contra doble envío);\n- el registro está anulado.\n\nEl mensaje (`message`) explica la causa y puede mostrarse al usuario tal cual.\n\n**Otros errores:** `422` si falta un campo o `payment` ≤ 0; `404` si el registro no existe; `403` si es de otro vendedor.\n\nLa respuesta trae el pago creado (`data.payment`) y el resumen actualizado (`data.summary`). `summary` trae `total` (total del registro), `total_paid` (suma de pagos) y `total_difference` (saldo pendiente).",
        "responses": {
          "201": {
            "description": "Pago registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pago registrado",
                    "value": {
                      "success": true,
                      "data": {
                        "payment": {
                          "id": 31,
                          "date_of_payment": "2026-11-07",
                          "payment_method_type_id": "04",
                          "payment_method_type_description": "Transferencia",
                          "destination_type": "BankAccount",
                          "destination_id": 3,
                          "destination_description": "BCP SOLES",
                          "reference": "OP-458721",
                          "payment": 20.0
                        },
                        "summary": {
                          "total": 50.0,
                          "total_paid": 20.0,
                          "total_difference": 30.0
                        }
                      },
                      "message": "Pago registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Monto inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Monto inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "payment": [
                          "El campo payment debe ser mayor que 0."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin caja abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sale_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar pago de nota de venta",
                  "value": {
                    "date_of_payment": "2026-11-07",
                    "payment_method_type_id": "04",
                    "payment_destination_id": 3,
                    "payment": 20.0,
                    "reference": "OP-458721",
                    "has_card": false,
                    "card_brand_id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sale-note-payments/{sale_note_payment_id}": {
      "delete": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Eliminar pago de nota de venta",
        "operationId": "EliminarPagoNotaVenta",
        "description": "Elimina un pago y revierte su movimiento en caja o cuenta. El id es el del **pago** (`data.payment.id` al registrarlo o `payments[].id` al listarlos).\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `409` si el pago pertenece a una caja ya cerrada; `404` si el pago no existe; `403` si el registro es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Pago eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pago eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 31,
                        "summary": {
                          "total": 50.0,
                          "total_paid": 0.0,
                          "total_difference": 50.0
                        }
                      },
                      "message": "Pago eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Caja cerrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja cerrada",
                    "value": {
                      "success": false,
                      "message": "No se puede eliminar este pago: pertenece a la caja #4, que ya está cerrada y su arqueo no puede cambiar. Si hubo un error, anula la operación: la devolución se registra en la caja abierta."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sale_note_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/sale-note/lists": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Últimas notas de venta",
        "operationId": "UltimasNotasVenta",
        "description": "Devuelve las últimas notas de venta (cantidad fija, normalmente 20), con búsqueda simple por serie o número.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 140,
                          "date_of_issue": "2026-11-07",
                          "full_number": "NV01-140",
                          "customer_name": "CLIENTES VARIOS",
                          "customer_number": "00000000",
                          "currency_type_id": "PEN",
                          "total": "7.00",
                          "state_type_id": "01",
                          "state_type_description": "Registrado",
                          "total_canceled": true,
                          "total_paid": "7.00",
                          "total_pending_paid": "0.00"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "NV01",
            "description": "Texto a buscar en serie o número."
          }
        ]
      }
    },
    "/api/sale-note/find/{sale_note_id}": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Ver nota de venta",
        "operationId": "VerNotaVenta",
        "description": "Devuelve la nota de venta con cliente, totales, ítems y pagos. Un vendedor solo accede a las suyas (`404` si no).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Nota",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Nota",
                    "value": {
                      "data": {
                        "id": 140,
                        "series": "NV01",
                        "number": 140,
                        "document_type_id": "80",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "12:30:00",
                        "currency_type_id": "PEN",
                        "customer_name": "CLIENTES VARIOS",
                        "customer_number": "00000000",
                        "total_taxed": 5.94,
                        "total_igv": 1.06,
                        "total": 7.0,
                        "items": [
                          {
                            "description": "GASEOSA 500ML",
                            "quantity": 2,
                            "unit_price": 3.5,
                            "total": 7.0
                          }
                        ],
                        "payments": [
                          {
                            "date_of_payment": "2026-11-07",
                            "payment_method_type_id": "01",
                            "payment": 7.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No encontrada",
                    "value": {
                      "success": false,
                      "message": "No se encontró la nota de venta solicitada."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sale_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/sale-note/series": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Series de nota de venta",
        "operationId": "SeriesNotaVenta",
        "description": "Series de tipo `80` del establecimiento del usuario. Usa su `id` como `series_id` al emitir.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Series",
                    "value": [
                      {
                        "id": 5,
                        "document_type_id": "80",
                        "number": "NV01",
                        "is_default": true,
                        "establishment_id": 1
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/sale-note/email": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Enviar nota de venta por correo",
        "operationId": "EnviarNotaVentaCorreo",
        "description": "Envía la nota de venta en PDF por correo electrónico usando la configuración de correo de la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del registro. |\n| `email` | string | Sí | Correo de destino. Para varios destinatarios sepáralos con coma. |\n\n**Reglas y errores:** no hay validación del cuerpo; la respuesta es `success: true` aunque el correo no llegue (el envío queda en el historial de correos de la empresa). Un `id` inexistente responde `500`.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Email enviado correctamente."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Attempt to read property \"id\" on null"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar nota de venta por correo",
                  "value": {
                    "id": "1",
                    "email": "cliente@correo.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quotations/{quotation_id}": {
      "put": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Editar cotización",
        "operationId": "EditarCotizacion",
        "description": "Reemplaza la cabecera y **todos los ítems** de la cotización (envía la cotización completa, no es parcial). Acepta `PUT` o `PATCH`. Los pagos registrados no se modifican. Si envías `number`, `series`, `user_id`, `state_type_id`, `establishment_id` o `external_id` se ignoran.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `customer_id` | integer | Sí | `customer_id` es el id de un cliente ya registrado (persona de tipo cliente). |\n| `customer_address_id` | integer | No | Dirección del cliente a usar (si tiene varias). |\n| `date_of_issue` | date | Sí | `YYYY-MM-DD`. |\n| `time_of_issue` | string | No | `HH:MM:SS`. |\n| `date_of_due` | date | No | Validez de la cotización. |\n| `delivery_date` | date | No | Fecha de entrega. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric | Sí | Tipo de cambio (`1` en soles). |\n| `total_* / subtotal / total` | numeric | Sí | Totales de cabecera: `total_taxed` (gravado), `total_exonerated`, `total_unaffected`, `total_free`, `total_igv`, `total_taxes`, `total_value` (sin IGV), `subtotal` y `total` (con IGV). Deben cuadrar con la suma de las líneas: la plataforma **no recalcula** los totales que envías. |\n| `items` | array | Sí | Líneas (mín. 1). Ver tabla de líneas. |\n| `payment_method_type_id` | string | No | Forma de pago propuesta. |\n| `description` | string | No | Observaciones. |\n| `shipping_address` | string | No | Dirección de envío. |\n| `account_number` | string | No | Cuenta para el depósito. |\n| `contact / phone` | string | No | Contacto y teléfono. |\n| `custom_fields_data` | array | No | Campos personalizados de la empresa. |\n\n**Línea (`items[]`):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Id del producto. |\n| `item` | object | Sí | Copia del producto tal como se guardará en el documento (al menos `id`, `description`, `unit_type_id`, `internal_id`, `is_set`, `presentation`). Se obtiene de los endpoints de productos de la API. |\n| `quantity` | numeric | Sí | Cantidad (> 0). |\n| `unit_value` | numeric | Sí | Valor unitario **sin** IGV. |\n| `unit_price` | numeric | Sí | Precio unitario **con** IGV. |\n| `affectation_igv_type_id` | string | Sí | Afectación IGV (catálogo SUNAT 07): `10` gravado, `20` exonerado, `30` inafecto. |\n| `price_type_id` | string | Sí | `01` precio unitario (incluye IGV), `02` valor referencial (gratuito). |\n| `percentage_igv` | numeric | Sí | Porcentaje de IGV (`18`, o `10` si aplica la Ley 31556). |\n| `total_base_igv / total_igv / total_taxes / total_value / total` | numeric | Sí | Totales de la línea: base imponible, IGV, impuestos, valor (sin IGV) y total (con IGV). |\n| `warehouse_id` | integer | No | Almacén del que sale el stock (por defecto el del establecimiento). |\n| `total_discount / total_charge / charges / discounts / attributes` | varios | No | Descuentos, cargos y atributos de la línea (usa `0` y `[]` si no aplica). |\n| `system_isc_type_id / total_base_isc / percentage_isc / total_isc / total_plastic_bag_taxes` | varios | No | ISC e ICBPER (usa `null`/`0` si no aplica). |\n\n**Errores:** `409` si la cotización está anulada; `422` si falta `customer_id` (o no existe), `currency_type_id`, `exchange_rate_sale`, `date_of_issue`, `total` o `items`; `403`; `404`.",
        "responses": {
          "200": {
            "description": "Editada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 33,
                        "number_full": "COT-33",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "date_of_issue": "2026-11-07",
                        "customer_id": 1,
                        "currency_type_id": "PEN",
                        "total": 23.6,
                        "items_count": 1
                      },
                      "message": "Cotización actualizada"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin ítems",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin ítems",
                    "value": {
                      "success": false,
                      "message": {
                        "items": [
                          "El campo items es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulada",
                    "value": {
                      "success": false,
                      "message": "La cotización está anulada y no se puede editar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "quotation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar cotización",
                  "value": {
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "15:00:00",
                    "date_of_due": "2026-11-14",
                    "delivery_date": "2026-11-20",
                    "customer_id": 1,
                    "customer_address_id": null,
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 1,
                    "total_prepayment": 0,
                    "total_charge": 0,
                    "total_discount": 0,
                    "total_exportation": 0,
                    "total_free": 0,
                    "total_taxed": 20.0,
                    "total_unaffected": 0,
                    "total_exonerated": 0,
                    "total_igv": 3.6,
                    "total_igv_free": 0,
                    "total_base_isc": 0,
                    "total_isc": 0,
                    "total_base_other_taxes": 0,
                    "total_other_taxes": 0,
                    "total_taxes": 3.6,
                    "total_value": 20.0,
                    "subtotal": 23.6,
                    "total": 23.6,
                    "items": [
                      {
                        "item_id": 120,
                        "item": {
                          "id": 120,
                          "item_id": 120,
                          "internal_id": "P0001",
                          "description": "GASEOSA 500ML",
                          "unit_type_id": "NIU",
                          "currency_type_id": "PEN",
                          "sale_unit_price": 3.5,
                          "purchase_unit_price": 2.2,
                          "sale_affectation_igv_type_id": "10",
                          "purchase_affectation_igv_type_id": "10",
                          "is_set": false,
                          "has_igv": true,
                          "presentation": null
                        },
                        "currency_type_id": "PEN",
                        "quantity": 2,
                        "unit_value": 10.0,
                        "affectation_igv_type_id": "10",
                        "total_base_igv": 20.0,
                        "percentage_igv": 18,
                        "total_igv": 3.6,
                        "system_isc_type_id": null,
                        "total_base_isc": 0,
                        "percentage_isc": 0,
                        "total_isc": 0,
                        "total_base_other_taxes": 0,
                        "percentage_other_taxes": 0,
                        "total_other_taxes": 0,
                        "total_plastic_bag_taxes": 0,
                        "total_taxes": 3.6,
                        "price_type_id": "01",
                        "unit_price": 11.8,
                        "total_value": 20.0,
                        "total_discount": 0,
                        "total_charge": 0,
                        "total": 23.6,
                        "attributes": [],
                        "charges": [],
                        "discounts": [],
                        "warehouse_id": 1
                      }
                    ],
                    "payment_method_type_id": "01",
                    "description": "Precios válidos por 7 días",
                    "shipping_address": "AV. LOS PINOS 789, SURCO",
                    "account_number": null,
                    "contact": "María López",
                    "phone": "987123456",
                    "additional_information": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quotations/{quotation_id}/void": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Anular cotización",
        "operationId": "AnularCotizacion",
        "description": "Anula la cotización (estado `11`). Si tenía pagos registrados, salen de caja/bancos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\nSin cuerpo.\n\n**Errores:** `409` si ya está anulada; `403`; `404`.",
        "responses": {
          "200": {
            "description": "Anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 33,
                        "number_full": "COT-33",
                        "state_type_id": "11",
                        "state_type_description": "Anulado",
                        "date_of_issue": "2026-11-07",
                        "customer_id": 1,
                        "currency_type_id": "PEN",
                        "total": 23.6,
                        "items_count": 1
                      },
                      "message": "Cotización anulada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya anulada",
                    "value": {
                      "success": false,
                      "message": "La cotización ya está anulada."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "quotation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/quotations/{quotation_id}/state": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Cambiar estado de cotización",
        "operationId": "CambiarEstadoCotizacion",
        "description": "Cambia el estado de la cotización (p. ej. marcarla como aceptada o rechazada).\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `state_type_id` | string | Sí | `01` registrado, `05` aceptado, `09` rechazado, `11` anulado. |\n\n**Errores:** `422` si el estado no es uno de los permitidos; `409` si la cotización está anulada y se intenta otro estado; `403`; `404`.",
        "responses": {
          "200": {
            "description": "Estado actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estado actualizado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 33,
                        "number_full": "COT-33",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "date_of_issue": "2026-11-07",
                        "customer_id": 1,
                        "currency_type_id": "PEN",
                        "total": 23.6,
                        "items_count": 1
                      },
                      "message": "Estado actualizado correctamente"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Estado inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estado inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "state_type_id": [
                          "state type id es inválido."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Anulada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulada",
                    "value": {
                      "success": false,
                      "message": "La cotización está anulada: no se puede reactivar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "quotation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar estado de cotización",
                  "value": {
                    "state_type_id": "05"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quotations/records-scroll": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Listar cotizaciones con cursor",
        "operationId": "ListarCotizacionesCursor",
        "description": "Listado de cotizaciones paginado por cursor (más recientes primero).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 33,
                          "number_full": "COT-33",
                          "external_id": "e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9",
                          "date_of_issue": "2026-11-07",
                          "total": 23.6,
                          "currency_type_id": "PEN",
                          "state_type_id": "01",
                          "state_type_description": "Registrado",
                          "changed": false,
                          "customer": {
                            "id": 1,
                            "name": "CLIENTES VARIOS",
                            "number": "00000000"
                          },
                          "user": {
                            "id": 5,
                            "name": "JUAN PEREZ"
                          },
                          "seller": {
                            "id": 5,
                            "name": "JUAN PEREZ"
                          },
                          "items_count": 1,
                          "has_documents": false,
                          "can_generate_document": true
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Filtra por estado."
          },
          {
            "name": "changed",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "0",
            "description": "`1` cotizaciones ya convertidas en venta, `0` sin convertir."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/quotations/tables": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Catálogos de cotizaciones",
        "operationId": "CatalogosCotizaciones",
        "description": "Endpoint de compatibilidad: actualmente devuelve `series` vacío.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "series": []
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/quotation/find/{quotation_id}": {
      "get": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Ver cotización",
        "operationId": "VerCotizacion",
        "description": "Devuelve la cotización con cliente, totales, ítems y términos. Un vendedor solo accede a las suyas (`404` si no).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Cotización",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cotización",
                    "value": {
                      "data": {
                        "prefix": "COT",
                        "number": 33,
                        "date_of_issue": "2026-11-07",
                        "date_of_due": "2026-11-14",
                        "currency_type_id": "PEN",
                        "customer_name": "CLIENTES VARIOS",
                        "customer_number": "00000000",
                        "total_taxed": 20.0,
                        "total_igv": 3.6,
                        "total": 23.6,
                        "items": [
                          {
                            "description": "GASEOSA 500ML",
                            "quantity": 2,
                            "unit_price": 11.8,
                            "total": 23.6
                          }
                        ],
                        "description": "Precios válidos por 7 días"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No encontrada",
                    "value": {
                      "success": false,
                      "message": "No se encontró la cotización solicitada."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "quotation_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/quotations/email": {
      "post": {
        "tags": [
          "Notas de venta y cotizaciones"
        ],
        "summary": "Enviar cotización por correo",
        "operationId": "EnviarCotizacionCorreo",
        "description": "Envía la cotización en PDF por correo electrónico usando la configuración de correo de la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del registro. |\n| `email` | string | Sí | Correo de destino. Para varios destinatarios sepáralos con coma. |\n\n**Reglas y errores:** no hay validación del cuerpo; la respuesta es `success: true` aunque el correo no llegue (el envío queda en el historial de correos de la empresa). Un `id` inexistente responde `500`.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Email enviado correctamente."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Attempt to read property \"id\" on null"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar cotización por correo",
                  "value": {
                    "id": "1",
                    "email": "compras@xyz.com.pe"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/order-notes/{order_note_id}": {
      "get": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Ver pedido",
        "operationId": "VerPedido",
        "description": "Devuelve el pedido con sus ítems, usuario y vendedor.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Errores:** `404`; `403` si es de otro vendedor.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "external_id": "f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
                        "number_full": "PD-58",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "16:00:00",
                        "date_of_due": "2026-11-07",
                        "delivery_date": "2026-11-10",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "customer_id": 1,
                        "customer": {
                          "name": "CLIENTES VARIOS",
                          "number": "00000000",
                          "identity_document_type_id": "0"
                        },
                        "currency_type_id": "PEN",
                        "total": 35.4,
                        "user_id": 5,
                        "seller_id": 5,
                        "establishment_id": 1,
                        "observation": "Entregar por la tarde",
                        "user_name": "JUAN PEREZ",
                        "seller_name": "JUAN PEREZ",
                        "items": [
                          {
                            "id": 410,
                            "item_id": 120,
                            "item": {
                              "id": 120,
                              "item_id": 120,
                              "internal_id": "P0001",
                              "description": "GASEOSA 500ML",
                              "unit_type_id": "NIU",
                              "currency_type_id": "PEN",
                              "sale_unit_price": 3.5,
                              "purchase_unit_price": 2.2,
                              "sale_affectation_igv_type_id": "10",
                              "purchase_affectation_igv_type_id": "10",
                              "is_set": false,
                              "has_igv": true,
                              "presentation": null
                            },
                            "warehouse_id": 1,
                            "quantity": 3.0,
                            "unit_price": 11.8,
                            "total": 35.4
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "order_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Editar pedido",
        "operationId": "EditarPedido",
        "description": "Reemplaza la cabecera y los ítems del pedido (envía el pedido completo). Acepta `PUT` o `PATCH`. Para conservar una línea, envía su `id` (el de *Ver pedido* → `items[].id`); si cambia producto, cantidad, almacén o presentación, la línea se reemplaza y el stock se ajusta. Las líneas que no envíes se eliminan y devuelven su stock. No cambian número, usuario ni estado.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `customer_id` | integer | Sí | `customer_id` es el id de un cliente ya registrado (persona de tipo cliente). |\n| `establishment_id` | integer | Sí al crear | Establecimiento del pedido. |\n| `seller_id` | integer | No | Vendedor asignado. Si el usuario autenticado es vendedor, siempre se usa él mismo. |\n| `date_of_issue` | date | Sí | `YYYY-MM-DD`. |\n| `time_of_issue` | string | No | `HH:MM:SS`. |\n| `date_of_due` | date | No | Vencimiento. |\n| `delivery_date` | date | No | Fecha de entrega. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric | Sí | Tipo de cambio, mínimo `0.01` (usa `1` en soles). |\n| `payment_method_type_id` | string | No | Forma de pago prevista. |\n| `total_* / subtotal / total` | numeric | Sí | Totales de cabecera: `total_taxed` (gravado), `total_exonerated`, `total_unaffected`, `total_free`, `total_igv`, `total_taxes`, `total_value` (sin IGV), `subtotal` y `total` (con IGV). Deben cuadrar con la suma de las líneas: la plataforma **no recalcula** los totales que envías. |\n| `items` | array | Sí | Líneas (mín. 1) con `warehouse_id` del que se reserva el stock. Al editar, incluye `id` en las líneas que se conservan. |\n| `shipping_address` | string | No | Dirección de entrega. |\n| `observation` | string | No | Observación. |\n| `additional_data` | array | No | Datos adicionales `[{title, description}]` (ambos obligatorios en cada elemento). |\n| `custom_fields_data` | array | No | Campos personalizados. |\n\n**Línea (`items[]`):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Id del producto. |\n| `item` | object | Sí | Copia del producto tal como se guardará en el documento (al menos `id`, `description`, `unit_type_id`, `internal_id`, `is_set`, `presentation`). Se obtiene de los endpoints de productos de la API. |\n| `quantity` | numeric | Sí | Cantidad (> 0). |\n| `unit_value` | numeric | Sí | Valor unitario **sin** IGV. |\n| `unit_price` | numeric | Sí | Precio unitario **con** IGV. |\n| `affectation_igv_type_id` | string | Sí | Afectación IGV (catálogo SUNAT 07): `10` gravado, `20` exonerado, `30` inafecto. |\n| `price_type_id` | string | Sí | `01` precio unitario (incluye IGV), `02` valor referencial (gratuito). |\n| `percentage_igv` | numeric | Sí | Porcentaje de IGV (`18`, o `10` si aplica la Ley 31556). |\n| `total_base_igv / total_igv / total_taxes / total_value / total` | numeric | Sí | Totales de la línea: base imponible, IGV, impuestos, valor (sin IGV) y total (con IGV). |\n| `warehouse_id` | integer | No | Almacén del que sale el stock (por defecto el del establecimiento). |\n| `total_discount / total_charge / charges / discounts / attributes` | varios | No | Descuentos, cargos y atributos de la línea (usa `0` y `[]` si no aplica). |\n| `system_isc_type_id / total_base_isc / percentage_isc / total_isc / total_plastic_bag_taxes` | varios | No | ISC e ICBPER (usa `null`/`0` si no aplica). |\n\n**Errores:**\n- `409` si el pedido está anulado o ya generó comprobantes / notas de venta vigentes.\n- `422` si falta `customer_id`, `currency_type_id`, `exchange_rate_sale`, `date_of_issue`, `total` o `items` (cada ítem exige `item_id`, `quantity` > 0 e `item`).\n- `403`; `404`.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "external_id": "f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
                        "number_full": "PD-58",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "16:00:00",
                        "date_of_due": "2026-11-07",
                        "delivery_date": "2026-11-10",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "customer_id": 1,
                        "customer": {
                          "name": "CLIENTES VARIOS",
                          "number": "00000000",
                          "identity_document_type_id": "0"
                        },
                        "currency_type_id": "PEN",
                        "total": 35.4,
                        "user_id": 5,
                        "seller_id": 5,
                        "establishment_id": 1,
                        "observation": "Entregar por la tarde",
                        "user_name": "JUAN PEREZ",
                        "seller_name": "JUAN PEREZ",
                        "items": [
                          {
                            "id": 410,
                            "item_id": 120,
                            "item": {
                              "id": 120,
                              "item_id": 120,
                              "internal_id": "P0001",
                              "description": "GASEOSA 500ML",
                              "unit_type_id": "NIU",
                              "currency_type_id": "PEN",
                              "sale_unit_price": 3.5,
                              "purchase_unit_price": 2.2,
                              "sale_affectation_igv_type_id": "10",
                              "purchase_affectation_igv_type_id": "10",
                              "is_set": false,
                              "has_igv": true,
                              "presentation": null
                            },
                            "warehouse_id": 1,
                            "quantity": 3.0,
                            "unit_price": 11.8,
                            "total": 35.4
                          }
                        ]
                      },
                      "message": "Pedido actualizado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin ítems",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin ítems",
                    "value": {
                      "success": false,
                      "message": {
                        "items": [
                          "El campo items es obligatorio."
                        ],
                        "total": [
                          "El campo total es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya facturado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya facturado",
                    "value": {
                      "success": false,
                      "message": "El pedido ya generó comprobantes o notas de venta: no se puede editar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "order_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar pedido",
                  "value": {
                    "customer_id": 1,
                    "establishment_id": 1,
                    "seller_id": 5,
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "16:00:00",
                    "date_of_due": "2026-11-07",
                    "delivery_date": "2026-11-10",
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 1,
                    "payment_method_type_id": "01",
                    "total_prepayment": 0,
                    "total_charge": 0,
                    "total_discount": 0,
                    "total_exportation": 0,
                    "total_free": 0,
                    "total_taxed": 30.0,
                    "total_unaffected": 0,
                    "total_exonerated": 0,
                    "total_igv": 5.4,
                    "total_igv_free": 0,
                    "total_base_isc": 0,
                    "total_isc": 0,
                    "total_base_other_taxes": 0,
                    "total_other_taxes": 0,
                    "total_taxes": 5.4,
                    "total_value": 30.0,
                    "subtotal": 35.4,
                    "total": 35.4,
                    "items": [
                      {
                        "item_id": 120,
                        "item": {
                          "id": 120,
                          "item_id": 120,
                          "internal_id": "P0001",
                          "description": "GASEOSA 500ML",
                          "unit_type_id": "NIU",
                          "currency_type_id": "PEN",
                          "sale_unit_price": 3.5,
                          "purchase_unit_price": 2.2,
                          "sale_affectation_igv_type_id": "10",
                          "purchase_affectation_igv_type_id": "10",
                          "is_set": false,
                          "has_igv": true,
                          "presentation": null
                        },
                        "currency_type_id": "PEN",
                        "quantity": 3,
                        "unit_value": 10.0,
                        "affectation_igv_type_id": "10",
                        "total_base_igv": 30.0,
                        "percentage_igv": 18,
                        "total_igv": 5.4,
                        "system_isc_type_id": null,
                        "total_base_isc": 0,
                        "percentage_isc": 0,
                        "total_isc": 0,
                        "total_base_other_taxes": 0,
                        "percentage_other_taxes": 0,
                        "total_other_taxes": 0,
                        "total_plastic_bag_taxes": 0,
                        "total_taxes": 5.4,
                        "price_type_id": "01",
                        "unit_price": 11.8,
                        "total_value": 30.0,
                        "total_discount": 0,
                        "total_charge": 0,
                        "total": 35.4,
                        "attributes": [],
                        "charges": [],
                        "discounts": [],
                        "warehouse_id": 1,
                        "id": 410
                      }
                    ],
                    "shipping_address": "AV. LOS PINOS 789, SURCO",
                    "observation": "Entregar por la tarde",
                    "additional_data": [
                      {
                        "title": "Referencia",
                        "description": "Frente al parque"
                      }
                    ],
                    "charges": [],
                    "discounts": [],
                    "prepayments": [],
                    "guides": [],
                    "related": [],
                    "legends": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/order-notes/{order_note_id}/void": {
      "post": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Anular pedido",
        "operationId": "AnularPedido",
        "description": "Anula el pedido (estado `11`) y devuelve el stock de sus ítems.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\nSin cuerpo.\n\n**Errores (`409`):** ya está anulado; ya generó comprobantes o notas de venta vigentes. `403`; `404`.",
        "responses": {
          "200": {
            "description": "Anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Anulado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "external_id": "f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
                        "number_full": "PD-58",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "16:00:00",
                        "date_of_due": "2026-11-07",
                        "delivery_date": "2026-11-10",
                        "state_type_id": "11",
                        "state_type_description": "Anulado",
                        "customer_id": 1,
                        "customer": {
                          "name": "CLIENTES VARIOS",
                          "number": "00000000",
                          "identity_document_type_id": "0"
                        },
                        "currency_type_id": "PEN",
                        "total": 35.4,
                        "user_id": 5,
                        "seller_id": 5,
                        "establishment_id": 1,
                        "observation": "Entregar por la tarde"
                      },
                      "message": "Pedido anulado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya anulado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya anulado",
                    "value": {
                      "success": false,
                      "message": "El pedido está anulado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "order_note_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/order-notes": {
      "post": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Crear pedido",
        "operationId": "CrearPedido",
        "description": "Registra un pedido, descuenta el stock de sus ítems y genera su PDF.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `customer_id` | integer | Sí | `customer_id` es el id de un cliente ya registrado (persona de tipo cliente). |\n| `establishment_id` | integer | Sí al crear | Establecimiento del pedido. |\n| `seller_id` | integer | No | Vendedor asignado. Si el usuario autenticado es vendedor, siempre se usa él mismo. |\n| `date_of_issue` | date | Sí | `YYYY-MM-DD`. |\n| `time_of_issue` | string | No | `HH:MM:SS`. |\n| `date_of_due` | date | No | Vencimiento. |\n| `delivery_date` | date | No | Fecha de entrega. |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `exchange_rate_sale` | numeric | Sí | Tipo de cambio, mínimo `0.01` (usa `1` en soles). |\n| `payment_method_type_id` | string | No | Forma de pago prevista. |\n| `total_* / subtotal / total` | numeric | Sí | Totales de cabecera: `total_taxed` (gravado), `total_exonerated`, `total_unaffected`, `total_free`, `total_igv`, `total_taxes`, `total_value` (sin IGV), `subtotal` y `total` (con IGV). Deben cuadrar con la suma de las líneas: la plataforma **no recalcula** los totales que envías. |\n| `items` | array | Sí | Líneas (mín. 1) con `warehouse_id` del que se reserva el stock. Al editar, incluye `id` en las líneas que se conservan. |\n| `shipping_address` | string | No | Dirección de entrega. |\n| `observation` | string | No | Observación. |\n| `additional_data` | array | No | Datos adicionales `[{title, description}]` (ambos obligatorios en cada elemento). |\n| `custom_fields_data` | array | No | Campos personalizados. |\n\nAdemás: `prefix` (usa `PD`).\n\n**Línea (`items[]`):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Id del producto. |\n| `item` | object | Sí | Copia del producto tal como se guardará en el documento (al menos `id`, `description`, `unit_type_id`, `internal_id`, `is_set`, `presentation`). Se obtiene de los endpoints de productos de la API. |\n| `quantity` | numeric | Sí | Cantidad (> 0). |\n| `unit_value` | numeric | Sí | Valor unitario **sin** IGV. |\n| `unit_price` | numeric | Sí | Precio unitario **con** IGV. |\n| `affectation_igv_type_id` | string | Sí | Afectación IGV (catálogo SUNAT 07): `10` gravado, `20` exonerado, `30` inafecto. |\n| `price_type_id` | string | Sí | `01` precio unitario (incluye IGV), `02` valor referencial (gratuito). |\n| `percentage_igv` | numeric | Sí | Porcentaje de IGV (`18`, o `10` si aplica la Ley 31556). |\n| `total_base_igv / total_igv / total_taxes / total_value / total` | numeric | Sí | Totales de la línea: base imponible, IGV, impuestos, valor (sin IGV) y total (con IGV). |\n| `warehouse_id` | integer | No | Almacén del que sale el stock (por defecto el del establecimiento). |\n| `total_discount / total_charge / charges / discounts / attributes` | varios | No | Descuentos, cargos y atributos de la línea (usa `0` y `[]` si no aplica). |\n| `system_isc_type_id / total_base_isc / percentage_isc / total_isc / total_plastic_bag_taxes` | varios | No | ISC e ICBPER (usa `null`/`0` si no aplica). |\n\n**Errores:** `422` si falta `customer_id`, `exchange_rate_sale` (mín. 0.01), `currency_type_id` o `date_of_issue`.\n\n**Respuesta:** `data` con `id`, `external_id`, `number_full`, `filename`, `print_ticket`.",
        "responses": {
          "200": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "external_id": "f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
                        "number_full": "PD-58",
                        "filename": "PD-58-20261107",
                        "print_ticket": "https://empresa.dominio/order-notes/print/f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0/ticket"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "exchange_rate_sale": [
                          "El campo exchange rate sale es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear pedido",
                  "value": {
                    "prefix": "PD",
                    "customer_id": 1,
                    "establishment_id": 1,
                    "seller_id": 5,
                    "date_of_issue": "2026-11-07",
                    "time_of_issue": "16:00:00",
                    "date_of_due": "2026-11-07",
                    "delivery_date": "2026-11-10",
                    "currency_type_id": "PEN",
                    "exchange_rate_sale": 1,
                    "payment_method_type_id": "01",
                    "total_prepayment": 0,
                    "total_charge": 0,
                    "total_discount": 0,
                    "total_exportation": 0,
                    "total_free": 0,
                    "total_taxed": 30.0,
                    "total_unaffected": 0,
                    "total_exonerated": 0,
                    "total_igv": 5.4,
                    "total_igv_free": 0,
                    "total_base_isc": 0,
                    "total_isc": 0,
                    "total_base_other_taxes": 0,
                    "total_other_taxes": 0,
                    "total_taxes": 5.4,
                    "total_value": 30.0,
                    "subtotal": 35.4,
                    "total": 35.4,
                    "items": [
                      {
                        "item_id": 120,
                        "item": {
                          "id": 120,
                          "item_id": 120,
                          "internal_id": "P0001",
                          "description": "GASEOSA 500ML",
                          "unit_type_id": "NIU",
                          "currency_type_id": "PEN",
                          "sale_unit_price": 3.5,
                          "purchase_unit_price": 2.2,
                          "sale_affectation_igv_type_id": "10",
                          "purchase_affectation_igv_type_id": "10",
                          "is_set": false,
                          "has_igv": true,
                          "presentation": null
                        },
                        "currency_type_id": "PEN",
                        "quantity": 3,
                        "unit_value": 10.0,
                        "affectation_igv_type_id": "10",
                        "total_base_igv": 30.0,
                        "percentage_igv": 18,
                        "total_igv": 5.4,
                        "system_isc_type_id": null,
                        "total_base_isc": 0,
                        "percentage_isc": 0,
                        "total_isc": 0,
                        "total_base_other_taxes": 0,
                        "percentage_other_taxes": 0,
                        "total_other_taxes": 0,
                        "total_plastic_bag_taxes": 0,
                        "total_taxes": 5.4,
                        "price_type_id": "01",
                        "unit_price": 11.8,
                        "total_value": 30.0,
                        "total_discount": 0,
                        "total_charge": 0,
                        "total": 35.4,
                        "attributes": [],
                        "charges": [],
                        "discounts": [],
                        "warehouse_id": 1
                      }
                    ],
                    "shipping_address": "AV. LOS PINOS 789, SURCO",
                    "observation": "Entregar por la tarde",
                    "additional_data": [
                      {
                        "title": "Referencia",
                        "description": "Frente al parque"
                      }
                    ],
                    "charges": [],
                    "discounts": [],
                    "prepayments": [],
                    "guides": [],
                    "related": [],
                    "legends": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/order-notes/lists": {
      "get": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Últimos pedidos",
        "operationId": "UltimosPedidos",
        "description": "Devuelve los últimos pedidos (cantidad fija, normalmente 20), con búsqueda simple.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 58,
                          "external_id": "f6a7b8c9-d0e1-4f2a-b3c4-d5e6f7a8b9c0",
                          "date_of_issue": "2026-11-07",
                          "identifier": "PD-58",
                          "customer_name": "CLIENTES VARIOS",
                          "customer_number": "00000000",
                          "currency_type_id": "PEN",
                          "total": "35.40",
                          "state_type_id": "01",
                          "state_type_description": "Registrado",
                          "seller_name": "JUAN PEREZ"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "58",
            "description": "Busca por prefijo o id del pedido."
          }
        ]
      }
    },
    "/api/order-notes/tables": {
      "get": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Catálogos de pedidos",
        "operationId": "CatalogosPedidos",
        "description": "Endpoint de compatibilidad: actualmente devuelve `series` vacío.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "series": []
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/order-note/email": {
      "post": {
        "tags": [
          "Pedidos"
        ],
        "summary": "Enviar pedido por correo",
        "operationId": "EnviarPedidoCorreo",
        "description": "Envía el pedido (nota de pedido) en PDF por correo electrónico usando la configuración de correo de la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del registro. |\n| `email` | string | Sí | Correo de destino. Para varios destinatarios sepáralos con coma. |\n\n**Reglas y errores:** no hay validación del cuerpo; la respuesta es `success: true` aunque el correo no llegue (el envío queda en el historial de correos de la empresa). Un `id` inexistente responde `500`.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Email enviado correctamente."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Attempt to read property \"id\" on null"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar pedido por correo",
                  "value": {
                    "id": "1",
                    "email": "compras@xyz.com.pe"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/categories": {
      "get": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Listar categorías",
        "operationId": "ListarCategorias",
        "description": "Lista categorías ordenadas por nombre.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 7,
                          "name": "BEBIDAS"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Crear categoría",
        "operationId": "CrearCategoria",
        "description": "Registra una categoría.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string | Sí | Nombre. Único. |\n\n**Formato de respuesta propio de este endpoint** (distinto del estándar):\n- Correcto: `200` con `{\"success\": true, \"category\": {...}}` (la categoría viene en `category`, no en `data`).\n- Nombre repetido: **`400`** con `{\"success\": false, \"message\": \"Esa categoría ya esta registrada\"}`.\n- Sin nombre: `422` con `{\"success\": false, \"message\": \"El nombre de Categoría debe ser obligatorio\"}` (`message` es texto, no objeto).",
        "responses": {
          "200": {
            "description": "Creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creada",
                    "value": {
                      "success": true,
                      "category": {
                        "name": "BEBIDAS",
                        "updated_at": "2026-11-07T15:20:11.000000Z",
                        "created_at": "2026-11-07T15:20:11.000000Z",
                        "id": 7
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Repetida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Repetida",
                    "value": {
                      "success": false,
                      "message": "Esa categoría ya esta registrada"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear categoría",
                  "value": {
                    "name": "BEBIDAS"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/categories/{category_id}": {
      "get": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Ver categoría",
        "operationId": "VerCategoria",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 7,
                        "name": "BEBIDAS"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "category_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Editar categoría",
        "operationId": "EditarCategoria",
        "description": "Cambia el nombre. Acepta `PUT` o `PATCH`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string | Sí | Nombre (máx. 255). Único. |\n\n**Errores:** `422` si el nombre ya existe; `404`.",
        "responses": {
          "200": {
            "description": "Editada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 7,
                        "name": "BEBIDAS Y JUGOS"
                      },
                      "message": "Categoría editada con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Nombre repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Nombre repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "name": [
                          "nombre ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "category_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar categoría",
                  "value": {
                    "name": "BEBIDAS Y JUGOS"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Eliminar categoría",
        "operationId": "EliminarCategoria",
        "description": "Elimina una categoría sin productos asociados.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si hay productos que la usan; `404`.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 7
                      },
                      "message": "Categoría eliminada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "La categoría está siendo usada por productos, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "category_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/brands": {
      "get": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Listar marcas",
        "operationId": "ListarMarcas",
        "description": "Lista marcas ordenadas por nombre.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 4,
                          "name": "COCA COLA"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Crear marca",
        "operationId": "CrearMarca",
        "description": "Registra una marca.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string | Sí | Nombre (máx. 255). Único. |\n\n**Errores:** `422` si falta el nombre o ya existe.",
        "responses": {
          "201": {
            "description": "Creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 4,
                        "name": "COCA COLA"
                      },
                      "message": "Marca registrada con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Nombre repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Nombre repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "name": [
                          "nombre ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear marca",
                  "value": {
                    "name": "COCA COLA"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/brands/{brand_id}": {
      "get": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Ver marca",
        "operationId": "VerMarca",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404` si no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 4,
                        "name": "COCA COLA"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "brand_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Editar marca",
        "operationId": "EditarMarca",
        "description": "Cambia el nombre. Acepta `PUT` o `PATCH`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string | Sí | Nombre (máx. 255). Único. |\n\n**Errores:** `422` si el nombre ya existe; `404`.",
        "responses": {
          "200": {
            "description": "Editada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 4,
                        "name": "COCA COLA COMPANY"
                      },
                      "message": "Marca editada con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Nombre repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Nombre repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "name": [
                          "nombre ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "brand_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar marca",
                  "value": {
                    "name": "COCA COLA COMPANY"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Eliminar marca",
        "operationId": "EliminarMarca",
        "description": "Elimina una marca sin productos asociados.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si hay productos que la usan; `404`.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 4
                      },
                      "message": "Marca eliminada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "La marca está siendo usada por productos, no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "brand_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/categories-records": {
      "get": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Todas las categorías",
        "operationId": "TodasCategorias",
        "description": "Lista completa de categorías (sin paginación) con imagen y fechas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Categorías",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Categorías",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 7,
                          "name": "BEBIDAS",
                          "image": "imagen-no-disponible.jpg",
                          "image_url": "https://empresa.dominio/logo/imagen-no-disponible.jpg",
                          "created_at": "07-11-2026 03:20PM",
                          "updated_at": "2026-11-07 15:20:11"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/brands-records": {
      "get": {
        "tags": [
          "Categorías y marcas"
        ],
        "summary": "Todas las marcas",
        "operationId": "TodasMarcas",
        "description": "Lista completa de marcas (sin paginación) con fechas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Marcas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Marcas",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 4,
                          "name": "COCA COLA",
                          "created_at": "07-11-2026 03:25PM",
                          "updated_at": "2026-11-07 15:25:40"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/drivers": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Listar conductores",
        "operationId": "ListarConductores",
        "description": "Lista conductores.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "identity_document_type_id": "1",
                          "number": "45678912",
                          "name": "PEDRO QUISPE MAMANI",
                          "license": "Q45678912",
                          "telephone": "987654321",
                          "is_default": true,
                          "is_active": true
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por nombre, número de documento o licencia."
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` solo activos, `0` solo inactivos."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Crear conductor",
        "operationId": "CrearConductor",
        "description": "Registra un conductor.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `identity_document_type_id` | string | Sí | Tipo de documento (catálogo SUNAT 06): `1` DNI, `4` carné de extranjería, `7` pasaporte. |\n| `number` | string | Sí | Número de documento. Único. |\n| `name` | string | Sí | Nombres y apellidos. |\n| `license` | string | Sí | Número de licencia de conducir. |\n| `telephone` | string | Sí | Teléfono. |\n| `is_default` | boolean | No | Predeterminado al emitir guías. |\n| `is_active` | boolean | No | Activo (por defecto `true`). |\n\nSolo un registro puede tener `is_default: true`: al marcar uno como predeterminado, los demás se desmarcan.\n\n**Errores:** `422` si falta un campo obligatorio, no cumple el formato o el número/placa ya existe.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "name": "PEDRO QUISPE MAMANI",
                        "license": "Q45678912",
                        "telephone": "987654321",
                        "is_default": true,
                        "is_active": true
                      },
                      "message": "Conductor registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "identity_document_type_id": [
                          "El campo identity document type id es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear conductor",
                  "value": {
                    "identity_document_type_id": "1",
                    "number": "45678912",
                    "name": "PEDRO QUISPE MAMANI",
                    "license": "Q45678912",
                    "telephone": "987654321",
                    "is_default": true,
                    "is_active": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/drivers/{driver_id}": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Ver conductor",
        "operationId": "VerConductor",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404`.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "name": "PEDRO QUISPE MAMANI",
                        "license": "Q45678912",
                        "telephone": "987654321",
                        "is_default": true,
                        "is_active": true
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "driver_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Editar conductor",
        "operationId": "EditarConductor",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*. Solo un registro puede tener `is_default: true`: al marcar uno como predeterminado, los demás se desmarcan.\n\n**Errores:** `422` (p. ej. número/placa ya usado por otro registro); `404`.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "identity_document_type_id": "1",
                        "number": "45678912",
                        "name": "PEDRO QUISPE MAMANI",
                        "license": "Q45678912",
                        "telephone": "987654321",
                        "is_default": true,
                        "is_active": true
                      },
                      "message": "Conductor editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "driver_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar conductor",
                  "value": {
                    "telephone": "987654321",
                    "is_default": true,
                    "is_active": true
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Eliminar conductor",
        "operationId": "EliminarConductor",
        "description": "Elimina un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por guías emitidas (desactívalo con `is_active: false`); `404`.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3
                      },
                      "message": "Conductor eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El registro está siendo usado por otros registros y no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "driver_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/transports": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Listar vehículos",
        "operationId": "ListarVehiculos",
        "description": "Lista vehículos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 2,
                          "plate_number": "ABC123",
                          "model": "NPR",
                          "brand": "ISUZU",
                          "tuc": "15M21028954E",
                          "is_default": true,
                          "is_active": true
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por placa, marca o modelo."
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` solo activos, `0` solo inactivos."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Crear vehículo",
        "operationId": "CrearVehiculo",
        "description": "Registra un vehículo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `plate_number` | string | Sí | Placa (sin guion, p. ej. `ABC123`). Única. |\n| `brand` | string | Sí | Marca. |\n| `model` | string | Sí | Modelo. |\n| `tuc` | string | No | Tarjeta única de circulación / certificado de habilitación vehicular. |\n| `is_default` | boolean | No | Predeterminado al emitir guías. |\n| `is_active` | boolean | No | Activo (por defecto `true`). |\n\nSolo un registro puede tener `is_default: true`: al marcar uno como predeterminado, los demás se desmarcan.\n\n**Errores:** `422` si falta un campo obligatorio, no cumple el formato o el número/placa ya existe.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "plate_number": "ABC123",
                        "model": "NPR",
                        "brand": "ISUZU",
                        "tuc": "15M21028954E",
                        "is_default": true,
                        "is_active": true
                      },
                      "message": "Vehículo registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "plate_number": [
                          "El campo plate number es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear vehículo",
                  "value": {
                    "plate_number": "ABC123",
                    "brand": "ISUZU",
                    "model": "NPR",
                    "tuc": "15M21028954E",
                    "is_default": true,
                    "is_active": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/transports/{transport_id}": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Ver vehículo",
        "operationId": "VerVehiculo",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404`.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "plate_number": "ABC123",
                        "model": "NPR",
                        "brand": "ISUZU",
                        "tuc": "15M21028954E",
                        "is_default": true,
                        "is_active": true
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transport_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Editar vehículo",
        "operationId": "EditarVehiculo",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*. Solo un registro puede tener `is_default: true`: al marcar uno como predeterminado, los demás se desmarcan.\n\n**Errores:** `422` (p. ej. número/placa ya usado por otro registro); `404`.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2,
                        "plate_number": "ABC123",
                        "model": "NPR",
                        "brand": "ISUZU",
                        "tuc": "15M21028954E",
                        "is_default": true,
                        "is_active": true
                      },
                      "message": "Vehículo editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transport_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar vehículo",
                  "value": {
                    "tuc": "15M21028954E",
                    "is_default": true,
                    "is_active": true
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Eliminar vehículo",
        "operationId": "EliminarVehiculo",
        "description": "Elimina un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por guías emitidas (desactívalo con `is_active: false`); `404`.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 2
                      },
                      "message": "Vehículo eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El registro está siendo usado por otros registros y no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transport_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/dispatchers": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Listar transportistas",
        "operationId": "ListarTransportistas",
        "description": "Lista transportistas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "identity_document_type_id": "6",
                          "number": "20512345678",
                          "name": "TRANSPORTES RAPIDOS S.A.C.",
                          "address": "AV. ARGENTINA 2450, CALLAO",
                          "number_mtc": "1512345CNG",
                          "is_default": true,
                          "is_active": true
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por razón social o RUC."
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` solo activos, `0` solo inactivos."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Crear transportista",
        "operationId": "CrearTransportista",
        "description": "Registra un transportista.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `identity_document_type_id` | string | Sí | Solo `6` (RUC). |\n| `number` | string | Sí | RUC de 11 dígitos que empiece con 10, 15, 16, 17 o 20. Único. |\n| `name` | string | Sí | Razón social (mín. 2 caracteres, al menos una letra). |\n| `address` | string | Sí | Dirección fiscal (mín. 3 caracteres, al menos una letra). |\n| `number_mtc` | string | No | Registro MTC: solo letras y números, máx. 12. |\n| `is_default` | boolean | No | Predeterminado al emitir guías. |\n| `is_active` | boolean | No | Activo (por defecto `true`). |\n\nSolo un registro puede tener `is_default: true`: al marcar uno como predeterminado, los demás se desmarcan.\n\n**Errores:** `422` si falta un campo obligatorio, no cumple el formato o el número/placa ya existe.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "identity_document_type_id": "6",
                        "number": "20512345678",
                        "name": "TRANSPORTES RAPIDOS S.A.C.",
                        "address": "AV. ARGENTINA 2450, CALLAO",
                        "number_mtc": "1512345CNG",
                        "is_default": true,
                        "is_active": true
                      },
                      "message": "Transportista registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "identity_document_type_id": [
                          "El campo identity document type id es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear transportista",
                  "value": {
                    "identity_document_type_id": "6",
                    "number": "20512345678",
                    "name": "TRANSPORTES RAPIDOS S.A.C.",
                    "address": "AV. ARGENTINA 2450, CALLAO",
                    "number_mtc": "1512345CNG",
                    "is_default": true,
                    "is_active": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatchers/{dispatcher_id}": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Ver transportista",
        "operationId": "VerTransportista",
        "description": "Devuelve un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `404`.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "identity_document_type_id": "6",
                        "number": "20512345678",
                        "name": "TRANSPORTES RAPIDOS S.A.C.",
                        "address": "AV. ARGENTINA 2450, CALLAO",
                        "number_mtc": "1512345CNG",
                        "is_default": true,
                        "is_active": true
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "dispatcher_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "put": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Editar transportista",
        "operationId": "EditarTransportista",
        "description": "Edita un registro. Acepta `PUT` o `PATCH`; la edición es **parcial** (lo que no envíes se conserva).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\nCampos: los mismos de *Crear*. Solo un registro puede tener `is_default: true`: al marcar uno como predeterminado, los demás se desmarcan.\n\n**Errores:** `422` (p. ej. número/placa ya usado por otro registro); `404`.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "identity_document_type_id": "6",
                        "number": "20512345678",
                        "name": "TRANSPORTES RAPIDOS S.A.C.",
                        "address": "AV. ARGENTINA 2450, CALLAO",
                        "number_mtc": "1512345CNG",
                        "is_default": true,
                        "is_active": true
                      },
                      "message": "Transportista editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "dispatcher_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar transportista",
                  "value": {
                    "number_mtc": "1512345CNG",
                    "is_default": true,
                    "is_active": true
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Eliminar transportista",
        "operationId": "EliminarTransportista",
        "description": "Elimina un registro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Errores:** `409` si está siendo usado por guías emitidas (desactívalo con `is_active: false`); `404`.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1
                      },
                      "message": "Transportista eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El registro está siendo usado por otros registros y no se puede eliminar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "dispatcher_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/dispatch-carrier/records": {
      "get": {
        "tags": [
          "Conductores, vehículos y transportistas"
        ],
        "summary": "Guías transportista emitidas",
        "operationId": "GuiasTransportistaEmitidas",
        "description": "Lista paginada (por página, no por cursor) de guías de remisión transportista (tipo `31`), más recientes primero.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).",
        "responses": {
          "200": {
            "description": "Guías",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guías",
                    "value": {
                      "data": [
                        {
                          "id": 90,
                          "external_id": "a7b8c9d0-e1f2-4a3b-c4d5-e6f7a8b9c0d1",
                          "date_of_issue": "2026-11-07",
                          "number": "V001-12",
                          "customer_name": "COMERCIAL NORTE E.I.R.L.",
                          "customer_number": "20601234567",
                          "date_of_shipping": "2026-11-08",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "has_xml": true,
                          "has_pdf": true,
                          "has_cdr": true
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/dispatch-carrier/records?page=1",
                        "last": "https://empresa.dominio/api/dispatch-carrier/records?page=1",
                        "prev": null,
                        "next": null
                      },
                      "meta": {
                        "current_page": 1,
                        "last_page": 1,
                        "per_page": 20,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "V001",
            "description": "Texto a buscar en serie o número."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      }
    },
    "/api/persons/records-scroll/{person_type}": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Listar clientes o proveedores (scroll)",
        "operationId": "ListarClientesProveedoresScroll",
        "description": "Lista para scroll infinito con **paginación por cursor**, ordenada por nombre. `person_type`: `customers` o `suppliers`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`. Sin el campo `success`: devuelve `{data[], pagination: {next_cursor, has_more}}`.\n\n**Reglas:**\n- `limit` máximo 100 (por defecto 20).\n- Hoy la búsqueda por `input` se combina con `OR` de forma que el tipo de la URL solo se aplica a la coincidencia por número: con `input` vacío o que coincida por nombre pueden aparecer también personas del otro tipo. Filtra por tu lado si necesitas exactitud.",
        "responses": {
          "200": {
            "description": "Página",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Página",
                    "value": {
                      "data": [
                        {
                          "id": 25,
                          "description": "20601234567 - COMERCIAL NORTE E.I.R.L.",
                          "name": "COMERCIAL NORTE E.I.R.L.",
                          "number": "20601234567",
                          "addresses": [
                            {
                              "id": 8,
                              "trade_name": null,
                              "country_id": "PE",
                              "location_id": [
                                "04",
                                "0401",
                                "040101"
                              ],
                              "address": "CALLE MERCADERES 456, AREQUIPA",
                              "phone": "054223344",
                              "email": "almacen@comercialnorte.pe",
                              "main": false,
                              "department_id": "04",
                              "province_id": "0401",
                              "district_id": "040101",
                              "establishment_code": "0001",
                              "has_consigned": false,
                              "consigned_id": null,
                              "consigned_name": null
                            }
                          ],
                          "identity_document_type_id": "6",
                          "identity_document_type_code": "6",
                          "address": "AV. PRINCIPAL 123, LIMA",
                          "telephone": "987654321",
                          "country_id": "PE",
                          "district_id": "150101",
                          "email": "compras@comercialnorte.pe",
                          "enabled": true,
                          "selected": false,
                          "identity_document_type_description": "RUC",
                          "location_id": [
                            "15",
                            "1501",
                            "150101"
                          ]
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJuYW1lIjoiQ09NRVJDSUFMIn0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "person_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "customers"
          },
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar en nombre o número de documento."
          },
          {
            "name": "identity_document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "6",
            "description": "Filtra por tipo de documento (`1` DNI, `6` RUC...)."
          },
          {
            "name": "enabled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` solo habilitados, `0` solo inhabilitados."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/persons/record/{customer_id}": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Ver cliente o proveedor",
        "operationId": "VerClienteProveedor",
        "description": "Devuelve una persona (cliente o proveedor) con sus direcciones y ubigeo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve `{data: {...}}`.\n\n**Errores:**\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`",
        "responses": {
          "200": {
            "description": "Persona",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Persona",
                    "value": {
                      "data": {
                        "id": 25,
                        "description": "20601234567 - COMERCIAL NORTE E.I.R.L.",
                        "name": "COMERCIAL NORTE E.I.R.L.",
                        "number": "20601234567",
                        "addresses": [
                          {
                            "id": 8,
                            "trade_name": null,
                            "country_id": "PE",
                            "location_id": [
                              "04",
                              "0401",
                              "040101"
                            ],
                            "address": "CALLE MERCADERES 456, AREQUIPA",
                            "phone": "054223344",
                            "email": "almacen@comercialnorte.pe",
                            "main": false,
                            "department_id": "04",
                            "province_id": "0401",
                            "district_id": "040101",
                            "establishment_code": "0001",
                            "has_consigned": false,
                            "consigned_id": null,
                            "consigned_name": null
                          }
                        ],
                        "identity_document_type_id": "6",
                        "identity_document_type_code": "6",
                        "address": "AV. PRINCIPAL 123, LIMA",
                        "telephone": "987654321",
                        "country_id": "PE",
                        "district_id": "150101",
                        "email": "compras@comercialnorte.pe",
                        "enabled": true,
                        "selected": false,
                        "identity_document_type_description": "RUC",
                        "location_id": [
                          "15",
                          "1501",
                          "150101"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/persons/create/{person_type}": {
      "post": {
        "tags": [
          "Clientes"
        ],
        "summary": "Crear cliente o proveedor",
        "operationId": "CrearClienteProveedor",
        "description": "Registra un cliente (`person_type = customers`) o proveedor (`suppliers`) con direcciones adicionales. **Es el alta recomendada**; *Crear cliente o proveedor (alta simple)* es la alternativa heredada.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `type` | string | Recomendado | Repite el tipo de la URL (`customers`/`suppliers`). La validación de número y nombre únicos lo usa: sin él no se detectan duplicados. |\n| `identity_document_type_id` | string | Sí | Tipo de documento (catálogo SUNAT 06): `0` sin documento, `1` DNI, `4` carné de extranjería, `6` RUC, `7` pasaporte. |\n| `number` | string | Sí | Número de documento. Único entre las personas habilitadas del mismo tipo (cliente/proveedor). |\n| `name` | string | Sí | Nombre o razón social. Único entre las personas habilitadas del mismo tipo. |\n| `trade_name` | string | No | Nombre comercial. |\n| `country_id` | string | Sí | País (código ISO de 2 letras, p. ej. `PE`). |\n| `address` | string | No | Dirección principal. |\n| `telephone` | string | No | Teléfono. |\n| `email` | string | No | Correo. Si se envía debe ser válido y único entre las personas habilitadas. |\n| `location_id` | array | No | Ubigeo principal `[departamento, provincia, distrito]`, p. ej. `[\"15\", \"1501\", \"150101\"]` (ver *Ubigeos*). Si no trae 3 elementos se ignora. |\n| `enabled` | boolean | No | Habilitado (por defecto `true`). |\n| `addresses` | array | No | Direcciones adicionales. Una dirección sin `address` o sin `location_id` de 3 elementos se omite. |\n| `addresses[].address` | string | Sí | Dirección. |\n| `addresses[].location_id` | array | Sí | Ubigeo `[departamento, provincia, distrito]`. |\n| `addresses[].country_id` | string | No | País (`PE`). |\n| `addresses[].phone / email` | string | No | Teléfono y correo de la dirección. |\n| `addresses[].main` | boolean | No | Dirección principal. |\n| `addresses[].establishment_code` | string | No | Código de establecimiento anexo SUNAT (4 dígitos). |\n| `addresses[].has_consigned` | boolean | Sí (la clave) | `true` si la dirección pertenece a un consignado. Envía siempre la clave. |\n| `addresses[].consigned_id` | integer | No | Id del consignado (ver sección [Consignaciones, placas, e-commerce y Vendeya](/docs/api/tenant/consignaciones-ecommerce)) cuando `has_consigned` es `true`; su teléfono se actualiza con `phone`. |\n\n**Reglas:**\n- El tipo se toma de la URL.\n- La respuesta trae la persona creada en `data` (mismo formato que *Ver*).\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`. Ej.: número o nombre ya registrados, falta `country_id`.",
        "responses": {
          "200": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "message": "Cliente creado exitosamente",
                      "data": {
                        "id": 25,
                        "description": "20601234567 - COMERCIAL NORTE E.I.R.L.",
                        "name": "COMERCIAL NORTE E.I.R.L.",
                        "number": "20601234567",
                        "addresses": [
                          {
                            "id": 8,
                            "trade_name": null,
                            "country_id": "PE",
                            "location_id": [
                              "04",
                              "0401",
                              "040101"
                            ],
                            "address": "CALLE MERCADERES 456, AREQUIPA",
                            "phone": "054223344",
                            "email": "almacen@comercialnorte.pe",
                            "main": false,
                            "department_id": "04",
                            "province_id": "0401",
                            "district_id": "040101",
                            "establishment_code": "0001",
                            "has_consigned": false,
                            "consigned_id": null,
                            "consigned_name": null
                          }
                        ],
                        "identity_document_type_id": "6",
                        "identity_document_type_code": "6",
                        "address": "AV. PRINCIPAL 123, LIMA",
                        "telephone": "987654321",
                        "country_id": "PE",
                        "district_id": "150101",
                        "email": "compras@comercialnorte.pe",
                        "enabled": true,
                        "selected": false,
                        "identity_document_type_description": "RUC",
                        "location_id": [
                          "15",
                          "1501",
                          "150101"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Número repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Número repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "number": [
                          "El campo número ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "person_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "customers"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear cliente o proveedor",
                  "value": {
                    "type": "customers",
                    "identity_document_type_id": "6",
                    "number": "20601234567",
                    "name": "COMERCIAL NORTE E.I.R.L.",
                    "trade_name": "COMERCIAL NORTE",
                    "country_id": "PE",
                    "address": "AV. PRINCIPAL 123, LIMA",
                    "telephone": "987654321",
                    "email": "compras@comercialnorte.pe",
                    "location_id": [
                      "15",
                      "1501",
                      "150101"
                    ],
                    "enabled": true,
                    "addresses": [
                      {
                        "id": null,
                        "address": "CALLE MERCADERES 456, AREQUIPA",
                        "location_id": [
                          "04",
                          "0401",
                          "040101"
                        ],
                        "country_id": "PE",
                        "phone": "054223344",
                        "email": "almacen@comercialnorte.pe",
                        "main": false,
                        "establishment_code": "0001",
                        "has_consigned": false,
                        "consigned_id": null
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/persons/update": {
      "post": {
        "tags": [
          "Clientes"
        ],
        "summary": "Editar cliente o proveedor",
        "operationId": "EditarClienteProveedor",
        "description": "Edita una persona. **Las direcciones adicionales se reemplazan** por las enviadas: envía la lista completa (con su `id`) o se pierden.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la persona. |\n| `type` | string | Recomendado | `customers`/`suppliers`; se usa en la validación de duplicados. |\n| `identity_document_type_id` | string | Sí | Tipo de documento (catálogo SUNAT 06): `0` sin documento, `1` DNI, `4` carné de extranjería, `6` RUC, `7` pasaporte. |\n| `number` | string | Sí | Número de documento. Único entre las personas habilitadas del mismo tipo (cliente/proveedor). |\n| `name` | string | Sí | Nombre o razón social. Único entre las personas habilitadas del mismo tipo. |\n| `trade_name` | string | No | Nombre comercial. |\n| `country_id` | string | Sí | País (código ISO de 2 letras, p. ej. `PE`). |\n| `address` | string | No | Dirección principal. |\n| `telephone` | string | No | Teléfono. |\n| `email` | string | No | Correo. Si se envía debe ser válido y único entre las personas habilitadas. |\n| `location_id` | array | No | Ubigeo principal `[departamento, provincia, distrito]`, p. ej. `[\"15\", \"1501\", \"150101\"]` (ver *Ubigeos*). Si no trae 3 elementos se ignora. |\n| `addresses` | array | No | Direcciones adicionales. Una dirección sin `address` o sin `location_id` de 3 elementos se omite. |\n| `addresses[].address` | string | Sí | Dirección. |\n| `addresses[].location_id` | array | Sí | Ubigeo `[departamento, provincia, distrito]`. |\n| `addresses[].country_id` | string | No | País (`PE`). |\n| `addresses[].phone / email` | string | No | Teléfono y correo de la dirección. |\n| `addresses[].main` | boolean | No | Dirección principal. |\n| `addresses[].establishment_code` | string | No | Código de establecimiento anexo SUNAT (4 dígitos). |\n| `addresses[].has_consigned` | boolean | Sí (la clave) | `true` si la dirección pertenece a un consignado. Envía siempre la clave. |\n| `addresses[].consigned_id` | integer | No | Id del consignado (ver sección [Consignaciones, placas, e-commerce y Vendeya](/docs/api/tenant/consignaciones-ecommerce)) cuando `has_consigned` es `true`; su teléfono se actualiza con `phone`. |\n| `addresses[].id` | integer | Sí (la clave) | Id de la dirección o `null` para una nueva. |\n\n**Reglas:**\n- `country_id` es obligatorio en la validación pero no se modifica con este endpoint.\n- El cliente *Clientes varios* no se puede editar: responde HTTP 200 con `success: false`.\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`.\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`\n\n**Clientes - Varios** (DNI `0` / `99999999`, el cliente genérico de las boletas sin datos) es un registro del sistema protegido: intentar editarlo responde HTTP 200 con `{\"success\": false, \"message\": \"Clientes - Varios es un registro del sistema y no se puede editar.\"}` y no se modifica.",
        "responses": {
          "200": {
            "description": "Actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Actualizado",
                    "value": {
                      "success": true,
                      "message": "Cliente actualizado"
                    }
                  },
                  "e2": {
                    "summary": "Clientes varios",
                    "value": {
                      "success": false,
                      "message": "No se puede editar el cliente Clientes varios."
                    }
                  },
                  "e3": {
                    "summary": "Clientes - Varios protegido",
                    "value": {
                      "success": false,
                      "message": "Clientes - Varios es un registro del sistema y no se puede editar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar cliente o proveedor",
                  "value": {
                    "type": "customers",
                    "identity_document_type_id": "6",
                    "number": "20601234567",
                    "name": "COMERCIAL NORTE E.I.R.L.",
                    "trade_name": "COMERCIAL NORTE",
                    "country_id": "PE",
                    "address": "AV. PRINCIPAL 123, LIMA",
                    "telephone": "987654321",
                    "email": "compras@comercialnorte.pe",
                    "location_id": [
                      "15",
                      "1501",
                      "150101"
                    ],
                    "addresses": [
                      {
                        "id": 8,
                        "address": "CALLE MERCADERES 456, AREQUIPA",
                        "location_id": [
                          "04",
                          "0401",
                          "040101"
                        ],
                        "country_id": "PE",
                        "phone": "054223344",
                        "email": "almacen@comercialnorte.pe",
                        "main": false,
                        "establishment_code": "0001",
                        "has_consigned": false,
                        "consigned_id": null
                      }
                    ],
                    "id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/persons/{customer_id}": {
      "delete": {
        "tags": [
          "Clientes"
        ],
        "summary": "Eliminar cliente o proveedor",
        "operationId": "EliminarClienteProveedor",
        "description": "Elimina una persona que no esté siendo usada por comprobantes u otros registros.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Reglas:**\n- El cliente *Clientes varios* no se puede eliminar.\n\n**Errores:**\n- En uso o protegido: HTTP 200 con `success: false`.\n- Id inexistente: **HTTP 500** con `success: false` (no `404`).\n\n**Clientes - Varios** (DNI `0` / `99999999`, el cliente genérico de las boletas sin datos) es un registro del sistema protegido: intentar eliminarlo responde HTTP 200 con `{\"success\": false, \"message\": \"Clientes - Varios es un registro del sistema y no se puede eliminar.\"}` y no se modifica.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "message": "Cliente eliminado con éxito"
                    }
                  },
                  "e2": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El Cliente esta siendo usado por otros registros, no puede eliminar"
                    }
                  },
                  "e3": {
                    "summary": "Clientes - Varios protegido",
                    "value": {
                      "success": false,
                      "message": "Clientes - Varios es un registro del sistema y no se puede eliminar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/persons/default-customer/{document_type_id}": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Cliente por defecto",
        "operationId": "ClienteDefecto",
        "description": "Devuelve el cliente por defecto para vender: el configurado en el establecimiento del usuario o, si no hay y el tipo de comprobante es boleta (`03`) o nota de venta (`80`), el cliente *Clientes varios*. El tipo de comprobante en la URL es opcional (`/api/persons/default-customer`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Reglas:**\n- Si no hay cliente por defecto responde `{success: false, data: null}` (HTTP 200).",
        "responses": {
          "200": {
            "description": "Cliente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cliente",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1,
                        "description": "99999999 - Clientes - Varios",
                        "name": "Clientes - Varios",
                        "number": "99999999",
                        "addresses": [],
                        "identity_document_type_id": "0",
                        "identity_document_type_code": "0",
                        "address": "AV. PRINCIPAL 123, LIMA",
                        "telephone": "987654321",
                        "country_id": "PE",
                        "district_id": "150101",
                        "email": "compras@comercialnorte.pe",
                        "enabled": true,
                        "selected": false,
                        "identity_document_type_description": "DOC.TRIB.NO.DOM.SIN.RUC",
                        "location_id": []
                      }
                    }
                  },
                  "e2": {
                    "summary": "Sin cliente por defecto",
                    "value": {
                      "success": false,
                      "data": null
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "03"
          }
        ]
      }
    },
    "/api/persons/locations": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Ubigeos (departamentos, provincias y distritos)",
        "operationId": "UbigeosDepartamentosProvinciasDistritos",
        "description": "Árbol de ubigeos del Perú para armar `location_id` (`[departamento, provincia, distrito]`). Cambia muy poco: guárdalo en caché.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve `{locations: [...]}`.",
        "responses": {
          "200": {
            "description": "Ubigeos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ubigeos",
                    "value": {
                      "locations": [
                        {
                          "value": "15",
                          "label": "LIMA",
                          "children": [
                            {
                              "value": "1501",
                              "label": "LIMA",
                              "children": [
                                {
                                  "value": "150101",
                                  "label": "LIMA (150101)"
                                },
                                {
                                  "value": "150122",
                                  "label": "MIRAFLORES (150122)"
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/company/customers": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Buscar clientes (formato API de comprobantes)",
        "operationId": "BuscarClientesFormatoApiComprobantes",
        "description": "Busca clientes habilitados por número o nombre y los devuelve con los nombres de campo del API de comprobantes (`codigo_tipo_documento_identidad`, `numero_documento`...), listos para el bloque `datos_del_cliente_o_receptor`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado de **cantidad fija** (take/limit): devuelve como máximo N registros, sin metadatos de paginación. Envuelto en `{success, customers[]}`; máximo `limit` registros (30 por defecto, tope 50).\n\n**Reglas:**\n- Sin `input` devuelve los primeros clientes por nombre.",
        "responses": {
          "200": {
            "description": "Clientes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Clientes",
                    "value": {
                      "success": true,
                      "customers": [
                        {
                          "id": 25,
                          "codigo_tipo_documento_identidad": "6",
                          "numero_documento": "20601234567",
                          "apellidos_y_nombres_o_razon_social": "COMERCIAL NORTE E.I.R.L.",
                          "codigo_pais": "PE",
                          "direccion": "AV. PRINCIPAL 123, LIMA",
                          "correo_electronico": "compras@comercialnorte.pe",
                          "telefono": "987654321"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "20601234567",
            "description": "Número de documento o nombre (coincidencia parcial)."
          },
          {
            "name": "identity_document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "6",
            "description": "Filtra por tipo de documento."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "30",
            "description": "Máximo de registros (1 a 50)."
          }
        ]
      }
    },
    "/api/items/records": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar productos (mantenimiento)",
        "operationId": "ListarProductosMantenimiento",
        "description": "Lista paginada (20 por página) de productos con código interno del almacén del usuario, ordenada por nombre, con stock por almacén y presentaciones.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado **paginado por página** `{data[], links: {first, last, prev, next}, meta: {current_page, last_page, per_page, total, ...}}`. Usa el query param `page` para avanzar.",
        "responses": {
          "200": {
            "description": "Productos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Productos",
                    "value": {
                      "data": [
                        {
                          "id": 31,
                          "full_description": "P0001 - GASEOSA COCA COLA 500ML - BEBIDAS - COCA COLA",
                          "unit_type_id": "NIU",
                          "unit_type_description": "Unidad",
                          "description": "GASEOSA COCA COLA 500ML",
                          "name": "Gaseosa personal",
                          "second_name": null,
                          "barcode": "7751271001234",
                          "internal_id": "P0001",
                          "item_code": "50202301",
                          "currency_type_id": "PEN",
                          "currency_type_symbol": "S/",
                          "sale_affectation_igv_type_id": "10",
                          "has_igv": true,
                          "sale_unit_price": 2.5,
                          "show_sale_unit_price": "S/ 2.50",
                          "image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
                          "purchase_affectation_igv_type_id": "10",
                          "purchase_unit_price": "1.80",
                          "category_id": 7,
                          "active": true,
                          "stock": 120,
                          "stock_min": 10,
                          "favorite": 0,
                          "has_isc": false,
                          "system_isc_type_id": null,
                          "percentage_isc": "0.00",
                          "warehouses": [
                            {
                              "warehouse_description": "Almacén Oficina Principal",
                              "stock": 120,
                              "warehouse_id": 1,
                              "establishment_id": 1
                            }
                          ],
                          "item_unit_types": [
                            {
                              "id": 5,
                              "description": "Paquete x 12",
                              "unit_type_id": "PK",
                              "quantity_unit": "12.0000",
                              "price1": "28.00",
                              "price2": "27.00",
                              "price3": "26.00",
                              "price_default": 1
                            }
                          ]
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/items/records?page=1",
                        "last": "https://empresa.dominio/api/items/records?page=1",
                        "prev": null,
                        "next": null
                      },
                      "meta": {
                        "current_page": 1,
                        "from": 1,
                        "last_page": 1,
                        "path": "https://empresa.dominio/api/items/records",
                        "per_page": 20,
                        "to": 1,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar: todas las palabras en el nombre, o código interno."
          },
          {
            "name": "search_by_barcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` para buscar el código de barras exacto enviado en `input`."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      }
    },
    "/api/items/records-sale": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar productos para venta (paginado)",
        "operationId": "ListarProductosVentaPaginado",
        "description": "Lista paginada (20 por página) de productos para el punto de venta: precios por presentación y etiqueta de precio, stock y almacenes.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado **paginado por página** `{data[], links: {first, last, prev, next}, meta: {current_page, last_page, per_page, total, ...}}`. Usa el query param `page` para avanzar.\n\n**Reglas:**\n- Solo productos activos y con código interno.\n- Los servicios (`ZZ`) se excluyen salvo que la empresa los muestre en el punto de venta.\n- `stock` es del almacén indicado; `warehouses` trae el stock en cada almacén. En un pack (`is_set`) es la cantidad que se puede armar.",
        "responses": {
          "200": {
            "description": "Productos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Productos",
                    "value": {
                      "data": [
                        {
                          "id": 31,
                          "item_id": 31,
                          "name": "GASEOSA COCA COLA 500ML",
                          "full_description": "P0001 - GASEOSA COCA COLA 500ML",
                          "description": "GASEOSA COCA COLA 500ML",
                          "currency_type_id": "PEN",
                          "internal_id": "P0001",
                          "item_code": "50202301",
                          "barcode": "7751271001234",
                          "currency_type_symbol": "S/",
                          "sale_unit_price": "2.50",
                          "purchase_unit_price": "1.80",
                          "unit_type_id": "NIU",
                          "sale_affectation_igv_type_id": "10",
                          "has_igv": true,
                          "purchase_has_igv": true,
                          "purchase_affectation_igv_type_id": "10",
                          "percentage_of_profit": 0,
                          "favorite": 0,
                          "quantity": 0,
                          "item_unit_types": [
                            {
                              "id": 5,
                              "description": "Paquete x 12",
                              "item_id": 31,
                              "unit_type_id": "PK",
                              "unit_type_label": "PK",
                              "quantity_unit": "12.00",
                              "price_default": 1,
                              "barcode": null,
                              "prices": [
                                {
                                  "id": 9,
                                  "price_label_id": 1,
                                  "position": 1,
                                  "quantity_unit": "12.00",
                                  "label": "Precio público",
                                  "price": "28.00",
                                  "is_active": true
                                }
                              ]
                            }
                          ],
                          "stock": 120,
                          "stock_min": 10,
                          "lots_enabled": false,
                          "series_enabled": false,
                          "image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
                          "brand_id": 4,
                          "category_id": 7,
                          "is_set": false,
                          "warehouses": [
                            {
                              "warehouse_id": 1,
                              "establishment_id": 1,
                              "warehouse_description": "Almacén Oficina Principal",
                              "stock": 120
                            }
                          ]
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/items/records-sale?page=1",
                        "last": "https://empresa.dominio/api/items/records-sale?page=1",
                        "prev": null,
                        "next": null
                      },
                      "meta": {
                        "current_page": 1,
                        "from": 1,
                        "last_page": 1,
                        "path": "https://empresa.dominio/api/items/records-sale",
                        "per_page": 20,
                        "to": 1,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar: todas las palabras en el nombre, o coincidencia parcial del código interno."
          },
          {
            "name": "search_by_barcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` para buscar el código de barras exacto enviado en `input` (devuelve como máximo 1)."
          },
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por categoría."
          },
          {
            "name": "favorite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` solo favoritos."
          },
          {
            "name": "warehouse_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Almacén para calcular `stock` (por defecto el del establecimiento del usuario)."
          },
          {
            "name": "stock_filter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "positive",
            "description": "Filtra por stock en el almacén: `all`, `positive`, `negative`, `zero`, `min_alert` (≤ mínimo) o `safe` (> mínimo)."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      }
    },
    "/api/items/records-scroll": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar productos para venta (scroll)",
        "operationId": "ListarProductosVentaScroll",
        "description": "Igual que *Listar productos para venta* pero con **paginación por cursor** (orden por id). Recomendado para catálogos grandes.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`. Sin el campo `success`: devuelve `{data[], pagination: {next_cursor, has_more}}`.\n\n**Reglas:**\n- Solo productos activos y con código interno.\n- Los servicios (`ZZ`) se excluyen salvo que la empresa los muestre en el punto de venta.\n- `stock` es del almacén indicado; `warehouses` trae el stock en cada almacén. En un pack (`is_set`) es la cantidad que se puede armar.\n- `limit` máximo 100 (por defecto 20).",
        "responses": {
          "200": {
            "description": "Página",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Página",
                    "value": {
                      "data": [
                        {
                          "id": 31,
                          "item_id": 31,
                          "name": "GASEOSA COCA COLA 500ML",
                          "full_description": "P0001 - GASEOSA COCA COLA 500ML",
                          "description": "GASEOSA COCA COLA 500ML",
                          "currency_type_id": "PEN",
                          "internal_id": "P0001",
                          "item_code": "50202301",
                          "barcode": "7751271001234",
                          "currency_type_symbol": "S/",
                          "sale_unit_price": "2.50",
                          "purchase_unit_price": "1.80",
                          "unit_type_id": "NIU",
                          "sale_affectation_igv_type_id": "10",
                          "has_igv": true,
                          "purchase_has_igv": true,
                          "purchase_affectation_igv_type_id": "10",
                          "percentage_of_profit": 0,
                          "favorite": 0,
                          "quantity": 0,
                          "item_unit_types": [
                            {
                              "id": 5,
                              "description": "Paquete x 12",
                              "item_id": 31,
                              "unit_type_id": "PK",
                              "unit_type_label": "PK",
                              "quantity_unit": "12.00",
                              "price_default": 1,
                              "barcode": null,
                              "prices": [
                                {
                                  "id": 9,
                                  "price_label_id": 1,
                                  "position": 1,
                                  "quantity_unit": "12.00",
                                  "label": "Precio público",
                                  "price": "28.00",
                                  "is_active": true
                                }
                              ]
                            }
                          ],
                          "stock": 120,
                          "stock_min": 10,
                          "lots_enabled": false,
                          "series_enabled": false,
                          "image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
                          "brand_id": 4,
                          "category_id": 7,
                          "is_set": false,
                          "warehouses": [
                            {
                              "warehouse_id": 1,
                              "establishment_id": 1,
                              "warehouse_description": "Almacén Oficina Principal",
                              "stock": 120
                            }
                          ]
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MzEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Texto a buscar: todas las palabras en el nombre, o coincidencia parcial del código interno."
          },
          {
            "name": "search_by_barcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` para buscar el código de barras exacto enviado en `input` (devuelve como máximo 1)."
          },
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por categoría."
          },
          {
            "name": "favorite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` solo favoritos."
          },
          {
            "name": "warehouse_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Almacén para calcular `stock` (por defecto el del establecimiento del usuario)."
          },
          {
            "name": "stock_filter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "positive",
            "description": "Filtra por stock en el almacén: `all`, `positive`, `negative`, `zero`, `min_alert` (≤ mínimo) o `safe` (> mínimo)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/items/record/{item_id}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Ver producto",
        "operationId": "VerProducto",
        "description": "Devuelve un producto con stock (almacén del usuario), almacenes y presentaciones.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve `{data: {...}}`.\n\n**Errores:**\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`",
        "responses": {
          "200": {
            "description": "Producto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Producto",
                    "value": {
                      "data": {
                        "id": 31,
                        "full_description": "P0001 - GASEOSA COCA COLA 500ML - BEBIDAS - COCA COLA",
                        "unit_type_id": "NIU",
                        "unit_type_description": "Unidad",
                        "description": "GASEOSA COCA COLA 500ML",
                        "name": "Gaseosa personal",
                        "second_name": null,
                        "barcode": "7751271001234",
                        "internal_id": "P0001",
                        "item_code": "50202301",
                        "currency_type_id": "PEN",
                        "currency_type_symbol": "S/",
                        "sale_affectation_igv_type_id": "10",
                        "has_igv": true,
                        "sale_unit_price": 2.5,
                        "show_sale_unit_price": "S/ 2.50",
                        "image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
                        "purchase_affectation_igv_type_id": "10",
                        "purchase_unit_price": "1.80",
                        "category_id": 7,
                        "active": true,
                        "stock": 120,
                        "stock_min": 10,
                        "favorite": 0,
                        "has_isc": false,
                        "system_isc_type_id": null,
                        "percentage_isc": "0.00",
                        "warehouses": [
                          {
                            "warehouse_description": "Almacén Oficina Principal",
                            "stock": 120,
                            "warehouse_id": 1,
                            "establishment_id": 1
                          }
                        ],
                        "item_unit_types": [
                          {
                            "id": 5,
                            "description": "Paquete x 12",
                            "unit_type_id": "PK",
                            "quantity_unit": "12.0000",
                            "price1": "28.00",
                            "price2": "27.00",
                            "price3": "26.00",
                            "price_default": 1
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/items/save": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Crear o editar producto (con imagen)",
        "operationId": "CrearEditarProductoImagen",
        "description": "Crea un producto o, si envías `id`, lo edita. Se envía como **`multipart/form-data`** (no JSON) para poder adjuntar la imagen en `file`. Deja `Content-Type` sin fijar para que se envíe el *boundary*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | No | Id del producto a **editar**. Sin `id` se crea uno nuevo. |\n| `description` | string | Sí | Nombre del producto (máx. 600). |\n| `name / second_name` | string | No | Descripción y nombre secundario (máx. 600). |\n| `internal_id` | string | No | Código interno. Único. Si se omite al crear, se genera automáticamente. |\n| `barcode` | string | No | Código de barras. |\n| `item_code` | string | No | Código de producto SUNAT: 8 dígitos. |\n| `model` | string | No | Modelo (máx. 100). |\n| `unit_type_id` | string | Sí | Unidad de medida (`NIU` unidad, `ZZ` servicio, `KGM`...; ver *Unidades de medida*). |\n| `currency_type_id` | string | Sí | `PEN` o `USD`. |\n| `sale_unit_price` | numeric | Sí | Precio de venta, mayor que 0. |\n| `purchase_unit_price` | numeric | Sí | Precio de compra. |\n| `sale_affectation_igv_type_id / purchase_affectation_igv_type_id` | string | Sí | Afectación IGV (catálogo SUNAT 07): `10` gravado, `20` exonerado, `30` inafecto... |\n| `has_igv / purchase_has_igv` | boolean (0/1) | No | `1` si el precio de venta / compra incluye IGV. |\n| `category_id / brand_id` | integer | No | Categoría y marca (sección [Categorías y marcas](/docs/api/tenant/categorias-marcas)). |\n| `stock` | numeric | No | **Solo al crear:** stock inicial en el almacén de `warehouse_id` (o en el del establecimiento del usuario). No aplica a servicios (`ZZ`). |\n| `warehouse_id` | integer | No | Solo al crear: almacén del stock inicial. |\n| `stock_min` | numeric | No | Stock mínimo para alertas. |\n| `calculate_quantity` | boolean (0/1) | No | Calcular cantidad a partir del monto en la venta. |\n| `has_isc / system_isc_type_id / percentage_isc` | 0/1 / string / numeric | No | ISC en venta: si `has_isc = 1`, el tipo y el porcentaje son obligatorios. |\n| `purchase_has_isc / purchase_system_isc_type_id / purchase_percentage_isc` | 0/1 / string / numeric | No | ISC en compra, misma regla. |\n| `favorite` | boolean (0/1) | No | Favorito en el punto de venta. |\n| `active` | boolean (0/1) | No | Activo. |\n| `file` | archivo | No | Imagen `jpg`, `jpeg`, `png`, `gif`, `svg` o `webp`. Se guardan 3 tamaños; al editar reemplaza la imagen anterior. |\n\n**Reglas:**\n- Al crear: tipo de producto `01`, impuesto a bolsas según la configuración de la empresa e imagen por defecto si no se envía `file`.\n- Al editar solo cambian los campos enviados; `stock` no modifica el inventario (usa ajustes de inventario).\n- Booleanos como `0`/`1` (form-data no tiene tipos).\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`. Ej.: `internal_id` repetido, precio de venta 0, `item_code` sin 8 dígitos.\n- Imagen de tipo no permitido: HTTP 200 con `success: false`.\n- Si el id no existe responde **HTTP 500** con `success: false` y `message` `No query results for model [...]` (no `404`). (al editar)",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "message": "Producto registrado con éxito",
                      "data": {
                        "id": 31,
                        "item_id": 31,
                        "name": "Gaseosa personal",
                        "full_description": "P0001 - GASEOSA COCA COLA 500ML",
                        "description": "GASEOSA COCA COLA 500ML",
                        "currency_type_id": "PEN",
                        "internal_id": "P0001",
                        "item_code": "50202301",
                        "barcode": "7751271001234",
                        "currency_type_symbol": "S/",
                        "sale_unit_price": "2.50",
                        "purchase_unit_price": "1.80",
                        "unit_type_id": "NIU",
                        "sale_affectation_igv_type_id": "10",
                        "purchase_affectation_igv_type_id": "10",
                        "calculate_quantity": false,
                        "has_igv": true,
                        "is_set": false,
                        "category_id": 7,
                        "brand_id": 4,
                        "image": "gaseosa-coca-cola-500ml-31.jpg",
                        "image_medium": "gaseosa-coca-cola-500ml-31-medium.jpg",
                        "image_small": "gaseosa-coca-cola-500ml-31-small.jpg",
                        "image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
                        "favorite": false,
                        "aux_quantity": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "sale_unit_price": [
                          "El precio unitario de venta debe ser mayor que 0."
                        ],
                        "internal_id": [
                          "El campo código interno ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Solo para editar: id del producto. Vacío = crear."
                  },
                  "description": {
                    "type": "string",
                    "example": "GASEOSA COCA COLA 500ML",
                    "description": "Nombre del producto (obligatorio)."
                  },
                  "name": {
                    "type": "string",
                    "example": "Gaseosa personal",
                    "description": "Descripción."
                  },
                  "second_name": {
                    "type": "string",
                    "description": "Nombre secundario."
                  },
                  "internal_id": {
                    "type": "string",
                    "example": "P0001",
                    "description": "Código interno único."
                  },
                  "barcode": {
                    "type": "string",
                    "example": "7751271001234",
                    "description": "Código de barras."
                  },
                  "item_code": {
                    "type": "string",
                    "example": "50202301",
                    "description": "Código SUNAT (8 dígitos)."
                  },
                  "model": {
                    "type": "string",
                    "description": "Modelo."
                  },
                  "unit_type_id": {
                    "type": "string",
                    "example": "NIU",
                    "description": "Unidad de medida (obligatorio)."
                  },
                  "currency_type_id": {
                    "type": "string",
                    "example": "PEN",
                    "description": "Moneda (obligatorio)."
                  },
                  "sale_unit_price": {
                    "type": "string",
                    "example": "2.50",
                    "description": "Precio de venta > 0 (obligatorio)."
                  },
                  "purchase_unit_price": {
                    "type": "string",
                    "example": "1.80",
                    "description": "Precio de compra (obligatorio)."
                  },
                  "sale_affectation_igv_type_id": {
                    "type": "string",
                    "example": "10",
                    "description": "Afectación IGV venta (obligatorio)."
                  },
                  "purchase_affectation_igv_type_id": {
                    "type": "string",
                    "example": "10",
                    "description": "Afectación IGV compra (obligatorio)."
                  },
                  "has_igv": {
                    "type": "string",
                    "example": "1",
                    "description": "Precio de venta incluye IGV."
                  },
                  "purchase_has_igv": {
                    "type": "string",
                    "example": "1",
                    "description": "Precio de compra incluye IGV."
                  },
                  "category_id": {
                    "type": "string",
                    "example": "1",
                    "description": "Categoría."
                  },
                  "brand_id": {
                    "type": "string",
                    "example": "1",
                    "description": "Marca."
                  },
                  "stock": {
                    "type": "string",
                    "example": "120",
                    "description": "Solo al crear: stock inicial."
                  },
                  "warehouse_id": {
                    "type": "string",
                    "example": "1",
                    "description": "Solo al crear: almacén del stock inicial."
                  },
                  "stock_min": {
                    "type": "string",
                    "example": "10",
                    "description": "Stock mínimo."
                  },
                  "calculate_quantity": {
                    "type": "string",
                    "example": "0",
                    "description": "Calcular cantidad por monto."
                  },
                  "has_isc": {
                    "type": "string",
                    "example": "0",
                    "description": "Tiene ISC."
                  },
                  "system_isc_type_id": {
                    "type": "string",
                    "description": "Tipo de ISC (si has_isc = 1)."
                  },
                  "percentage_isc": {
                    "type": "string",
                    "example": "0",
                    "description": "Porcentaje ISC."
                  },
                  "purchase_has_isc": {
                    "type": "string",
                    "example": "0",
                    "description": "ISC en compra."
                  },
                  "purchase_system_isc_type_id": {
                    "type": "string",
                    "description": "Tipo de ISC en compra."
                  },
                  "purchase_percentage_isc": {
                    "type": "string",
                    "example": "0",
                    "description": "Porcentaje ISC en compra."
                  },
                  "favorite": {
                    "type": "string",
                    "example": "0",
                    "description": "Favorito."
                  },
                  "active": {
                    "type": "string",
                    "example": "1",
                    "description": "Activo."
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Imagen del producto (opcional)."
                  }
                },
                "required": [
                  "description",
                  "name",
                  "internal_id",
                  "barcode",
                  "item_code",
                  "unit_type_id",
                  "currency_type_id",
                  "sale_unit_price",
                  "purchase_unit_price",
                  "sale_affectation_igv_type_id",
                  "purchase_affectation_igv_type_id",
                  "has_igv",
                  "purchase_has_igv",
                  "category_id",
                  "brand_id",
                  "stock",
                  "warehouse_id",
                  "stock_min",
                  "calculate_quantity",
                  "has_isc",
                  "percentage_isc",
                  "favorite",
                  "active",
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/api/items/{item_id}": {
      "delete": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Eliminar producto",
        "operationId": "EliminarProducto",
        "description": "Elimina un producto que no esté siendo usado (ventas, compras, movimientos). Borra también sus lotes de cabecera, imágenes adicionales y su inventario inicial.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Errores:**\n- Con variaciones registradas o en uso: HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "message": "Producto eliminado con éxito"
                    }
                  },
                  "e2": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El producto esta siendo usado por otros registros, no puede eliminar"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/items/change-favorite/{item_id}/{favorite_value}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Marcar o quitar favorito",
        "operationId": "MarcarQuitarFavorito",
        "description": "⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\nMarca (`favorite_value = 1`) o quita (`0`) el producto de favoritos del punto de venta.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Errores:**\n- Si el id no existe responde **HTTP 500** con `success: false` y `message` `No query results for model [...]` (no `404`).",
        "responses": {
          "200": {
            "description": "Agregado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Agregado",
                    "value": {
                      "success": true,
                      "message": "Agregado a favoritos"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "No query results for model [App\\Models\\Tenant\\Item]."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "favorite_value",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/items/upload-temp-image": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Subir imagen temporal (vista previa)",
        "operationId": "SubirImagenTemporalVistaPrevia",
        "description": "Recibe una imagen y la devuelve en base64 (`temp_image`) para mostrar una vista previa antes de guardar. **Para guardar la imagen del producto envíala directamente en `file` de *Crear o editar producto*;** el `temp_path` devuelto no se usa en ese endpoint.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `file` | archivo | Sí | `jpg`, `jpeg`, `png`, `svg` o `webp`. |\n| `type` | string | No | Prefijo del archivo temporal (p. ej. `items`). |\n\n**Errores:**\n- Tipo no permitido o archivo no recibido: HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Imagen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Imagen",
                    "value": {
                      "success": true,
                      "data": {
                        "filename": "gaseosa.jpg",
                        "temp_path": "/tmp/itemAbC123",
                        "temp_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
                      }
                    }
                  },
                  "e2": {
                    "summary": "Tipo no permitido",
                    "value": {
                      "success": false,
                      "message": "Tipo de archivo no permitido, solo se aceptan: jpg, jpeg, png, svg, webp"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Imagen."
                  },
                  "type": {
                    "type": "string",
                    "example": "items",
                    "description": "Prefijo del archivo temporal."
                  }
                },
                "required": [
                  "file",
                  "type"
                ]
              }
            }
          }
        }
      }
    },
    "/api/item/upload": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Subir imagen temporal (alternativa)",
        "operationId": "SubirImagenTemporalAlternativa",
        "description": "Igual que *Subir imagen temporal (vista previa)*; acepta además `gif`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `file` | archivo | Sí | `jpg`, `jpeg`, `png`, `gif`, `svg` o `webp`. |\n| `type` | string | No | Prefijo del archivo temporal. |\n\n**Errores:**\n- Tipo no permitido o archivo no recibido: HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Imagen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Imagen",
                    "value": {
                      "success": true,
                      "data": {
                        "filename": "gaseosa.jpg",
                        "temp_path": "/tmp/itemAbC123",
                        "temp_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Imagen."
                  },
                  "type": {
                    "type": "string",
                    "example": "items",
                    "description": "Prefijo del archivo temporal."
                  }
                },
                "required": [
                  "file",
                  "type"
                ]
              }
            }
          }
        }
      }
    },
    "/api/items/tables": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Catálogos para el formulario de producto",
        "operationId": "CatalogosFormularioProducto",
        "description": "Categorías y unidades de medida activas para el formulario de producto.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "categories": [
                        {
                          "id": 7,
                          "name": "BEBIDAS",
                          "selected": false
                        }
                      ],
                      "unit_types": [
                        {
                          "id": "NIU",
                          "description": "Unidad",
                          "symbol": "und"
                        },
                        {
                          "id": "ZZ",
                          "description": "Servicio",
                          "symbol": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/items/table/{item_table}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Catálogo individual de producto",
        "operationId": "CatalogoIndividualProducto",
        "description": "Devuelve un catálogo: `item_table` = `categories`, `unit_types` o `affectation_igv_types` (tipos de afectación IGV activos). Otro valor devuelve `[]`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura.",
        "responses": {
          "200": {
            "description": "unit_types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "unit_types",
                    "value": [
                      {
                        "id": "NIU",
                        "description": "Unidad",
                        "symbol": "und"
                      }
                    ]
                  },
                  "e2": {
                    "summary": "affectation_igv_types",
                    "value": [
                      {
                        "id": "10",
                        "active": 1,
                        "exportation": 0,
                        "free": 0,
                        "description": "Gravado - Operación Onerosa"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_table",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "unit_types"
          }
        ]
      }
    },
    "/api/items/list-price": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Nombres de las listas de precios",
        "operationId": "NombresListasPrecios",
        "description": "Nombres configurados para los precios 1, 2 y 3 de las presentaciones (`price1`, `price2`, `price3` en `item_unit_types`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Etiquetas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Etiquetas",
                    "value": {
                      "price1": "Precio público",
                      "price2": "Precio mayorista",
                      "price3": "Precio distribuidor"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/price-labels/active": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Etiquetas de precio activas",
        "operationId": "EtiquetasPrecioActivas",
        "description": "Etiquetas de precio activas, ordenadas por posición (las que aparecen en `item_unit_types[].prices[]` de los listados de venta). `label_default` es el nombre del precio principal.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Incluye además `label_default`.",
        "responses": {
          "200": {
            "description": "Etiquetas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Etiquetas",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "position": 1,
                          "label": "Precio público",
                          "is_active": true,
                          "is_default": true,
                          "created_at": "2026-01-10 09:00:00",
                          "updated_at": "2026-01-10 09:00:00"
                        },
                        {
                          "id": 2,
                          "position": 2,
                          "label": "Precio mayorista",
                          "is_active": true,
                          "is_default": false,
                          "created_at": "2026-01-10 09:00:00",
                          "updated_at": "2026-01-10 09:00:00"
                        }
                      ],
                      "label_default": "Precio público"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/items/export/stock": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Exportar stock y precio por SKU",
        "operationId": "ExportarStockPrecioSku",
        "description": "Lista **todos** los productos con código interno con su stock total y precio de venta con IGV, pensado para sincronizar tiendas externas. `sku` = código interno.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura ni paginación.\n\n**Reglas:**\n- Puede ser una respuesta grande: no la consultes con alta frecuencia.",
        "responses": {
          "200": {
            "description": "Stock",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Stock",
                    "value": [
                      {
                        "sku": "P0001",
                        "stock": 120,
                        "price": "2.50"
                      },
                      {
                        "sku": "P0002",
                        "stock": 0,
                        "price": "35.00"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents/find/{document_id}": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Ver comprobante",
        "operationId": "VerComprobante",
        "description": "Devuelve un comprobante con sus datos de impresión: cliente, totales, líneas, leyendas, vendedor, hash, QR, condición de pago y pagos.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador ve todos los registros; un vendedor solo los que registró él. Si el comprobante es de otro vendedor responde `404`.\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`.\n\n**Errores:** `404` `{success: false, message}` si no existe o no es accesible.",
        "responses": {
          "200": {
            "description": "Comprobante",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Comprobante",
                    "value": {
                      "data": {
                        "series": "F001",
                        "number": 1520,
                        "document_type_id": "01",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:11:11",
                        "date_of_due": "2026-11-07",
                        "currency_type_id": "PEN",
                        "customer_name": "EMPRESA XYZ S.A.C.",
                        "customer_number": "20501973522",
                        "customer_address": "Av. 2 de Mayo 123, Lima, LIMA - LIMA - LIMA",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150101",
                        "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
                        "total_taxed": 100.0,
                        "total_exonerated": 0,
                        "total_unaffected": 0,
                        "total_exportation": 0,
                        "total_free": 0,
                        "total_igv": 18.0,
                        "subtotal": 118.0,
                        "total_discount_global": 0,
                        "total": 118.0,
                        "items": [
                          {
                            "quantity": 2,
                            "unit_type_id": "NIU",
                            "internal_id": "P0121",
                            "description": "GASEOSA 500ML",
                            "unit_price": 59.0,
                            "total_discount": 0,
                            "total": 118.0
                          }
                        ],
                        "terms_condition": null,
                        "legends": [
                          {
                            "code": "1000",
                            "value": "CIENTO DIECIOCHO CON 00/100 SOLES"
                          }
                        ],
                        "seller": {
                          "id": 5,
                          "name": "JUAN PEREZ"
                        },
                        "hash": "kJ8xQ2m0pZ3l7m9aB1c2d3e4f5g=",
                        "user_name": "JUAN PEREZ",
                        "payment_condition_id": "01",
                        "payment_condition_name": "Contado",
                        "payment_method_type_id": "01",
                        "payment_method_type_description": "Efectivo",
                        "payments": [
                          {
                            "payment_method_type_id": "01",
                            "payment_method_type_description": "Efectivo",
                            "reference": null,
                            "payment": 118.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No encontrado",
                    "value": {
                      "success": false,
                      "message": "No se encontró el comprobante solicitado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/documents/lists": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Últimos comprobantes",
        "operationId": "UltimosComprobantes",
        "description": "Devuelve los **últimos 50 comprobantes** (facturas, boletas y notas) ordenados por fecha de emisión descendente. No acepta filtros: para listados completos usa *Listar comprobantes con cursor*.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador ve todos los registros; un vendedor solo los que registró él.\n\n**Formato de respuesta:** listado de **cantidad fija** (take/limit): devuelve como máximo N registros, sin metadatos de paginación. Respuesta `{data: [...]}` (máximo 50 filas, sin `success`).\n\nCada fila trae además indicadores de interfaz (`btn_*`), estados de envío y relaciones (notas, guías, pedidos); el ejemplo muestra los campos principales. Las fechas `date_of_issue` y `date_of_due` vienen en formato `DD-MM-YYYY`.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 1520,
                          "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "group_id": "01",
                          "soap_type_id": "02",
                          "soap_type_description": "Producción",
                          "date_of_issue": "07-11-2026",
                          "date_of_due": "07-11-2026",
                          "number": "F001-1520",
                          "filename": "20123456789-01-F001-1520",
                          "document_type_id": "01",
                          "document_type_description": "FACTURA ELECTRÓNICA",
                          "customer_name": "EMPRESA XYZ S.A.C.",
                          "customer_number": "20501973522",
                          "customer_identity_document_type_description": "RUC",
                          "customer_telephone": "014271148",
                          "customer_email": "facturacion@xyz.com.pe",
                          "currency_type_id": "PEN",
                          "exchange_rate_sale": "1.000",
                          "total_exportation": "0.00",
                          "total_free": "0.00",
                          "total_unaffected": "0.00",
                          "total_exonerated": "0.00",
                          "total_taxed": "100.00",
                          "total_igv": "18.00",
                          "total_charge": "0.00",
                          "total": "118.00",
                          "balance": "0.00",
                          "date_of_payment": "2026-11-07",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "has_xml": true,
                          "has_pdf": true,
                          "has_cdr": true,
                          "download_xml": "https://empresa.dominio/downloads/document/xml/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "download_pdf": "https://empresa.dominio/downloads/document/pdf/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "download_cdr": "https://empresa.dominio/downloads/document/cdr/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "affected_document": null,
                          "notes": [],
                          "sales_note": [],
                          "order_note": [],
                          "dispatches": [],
                          "guides": null,
                          "purchase_order": "OC-2026-0045",
                          "user_id": 5,
                          "user_name": "JUAN PEREZ",
                          "source_module": "API",
                          "regularize_shipping": false,
                          "message_regularize_shipping": null,
                          "created_at": "2026-11-07 10:11:11",
                          "updated_at": "2026-11-07 10:11:15"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents/records-scroll": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Listar comprobantes con cursor",
        "operationId": "ListarComprobantesCursor",
        "description": "Listado paginado por cursor de comprobantes (más recientes primero). Con `document_type_id=80` lista **notas de venta** con el mismo formato.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador ve todos los registros; un vendedor solo los que registró él.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\nEstados (`state_type_id`): `01` registrado, `03` enviado, `05` aceptado, `07` observado, `09` rechazado, `11` anulado, `13` por anular.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1520,
                          "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "document_type_id": "01",
                          "document_type_description": "FACTURA ELECTRÓNICA",
                          "number_full": "F001-1520",
                          "series": "F001",
                          "number": 1520,
                          "filename": "20123456789-01-F001-1520",
                          "date_of_issue": "2026-11-07",
                          "total": 118.0,
                          "currency_type_id": "PEN",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "customer": {
                            "id": 1,
                            "name": "EMPRESA XYZ S.A.C.",
                            "number": "20501973522",
                            "email": "facturacion@xyz.com.pe",
                            "phone": "014271148"
                          },
                          "user": {
                            "id": 5,
                            "name": "JUAN PEREZ"
                          },
                          "print_a4": "https://empresa.dominio/print/document/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77/a4",
                          "print_ticket": "https://empresa.dominio/print/document/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77/ticket",
                          "has_cdr": true,
                          "download_cdr": "https://empresa.dominio/downloads/document/cdr/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "created_at": "2026-11-07 10:11:11"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJkYXRlX29mX2lzc3VlIjoiMjAyNi0xMS0wNyIsImlkIjoxNTIwfQ",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Tipo: `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito, `80` nota de venta. Sin valor: todos los comprobantes electrónicos."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "05",
            "description": "Estado (solo comprobantes electrónicos)."
          },
          {
            "name": "total_canceled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "0",
            "description": "Solo notas de venta (`80`): `1` pagadas, `0` con saldo."
          },
          {
            "name": "series",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "F001",
            "description": "Serie exacta."
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "152",
            "description": "Número (coincidencia parcial)."
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Id del cliente."
          },
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde `YYYY-MM-DD` (requiere `date_end`)."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta `YYYY-MM-DD`."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/documents/notifications": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Avisos de comprobantes pendientes",
        "operationId": "AvisosComprobantesPendientes",
        "description": "Cantidad de comprobantes **no enviados** a SUNAT y de comprobantes **por regularizar** (rechazados u observados que requieren corrección). Útil para mostrar alertas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).",
        "responses": {
          "200": {
            "description": "Avisos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Avisos",
                    "value": {
                      "success": true,
                      "data": {
                        "documents_not_sent": 2,
                        "documents_regularize_shipping": 0
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents_server": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Registrar comprobante emitido en otro servidor",
        "operationId": "RegistrarComprobanteEmitidoOtroServidor",
        "description": "Registra un comprobante **ya firmado en otro servidor** (sincronización entre instalaciones): guarda el XML firmado y el PDF recibidos en base64, conserva el `external_id`, hash y QR de origen y, si `query` es `true` y es factura o nota de factura, lo envía a SUNAT.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Respuesta `{success: true}`.\n\nAcepta **el mismo cuerpo que *Emitir comprobante electrónico*** (ver sus tablas) más estos campos:\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `external_id` | string (uuid) | Sí | `external_id` del comprobante en el servidor de origen. |\n| `hash` | string | Sí | Hash (DigestValue) del XML firmado. |\n| `qr` | string | Sí | Imagen QR en base64. |\n| `file_xml_signed` | string (base64) | Sí | XML firmado. |\n| `file_pdf` | string (base64) | Sí | PDF. |\n| `query` | boolean | Sí | `true` para enviarlo a SUNAT al registrarlo (solo facturas y sus notas). |\n\nLa serie y el número deben ser los del comprobante original (no uses `#`).\n\n**Errores:**\n- `400` `{success: false, message}`: el cuerpo no superó la validación previa (serie inexistente para el tipo de documento o el establecimiento, código de establecimiento incorrecto, ubigeo inválido, documento de identidad del cliente no permitido para el tipo de comprobante, fecha fuera de plazo, comprobante afectado inexistente, etc.).\n- `500` `{success: false, message}`: error al firmar o al comunicarse con SUNAT/OSE, o un dato que el servidor no pudo procesar.\n- `401` sin token.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Serie incorrecta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Serie incorrecta",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada F001, es incorrecta."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar comprobante emitido en otro servidor",
                  "value": {
                    "serie_documento": "F001",
                    "numero_documento": 1520,
                    "fecha_de_emision": "2026-11-07",
                    "hora_de_emision": "10:11:11",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "01",
                    "codigo_tipo_moneda": "PEN",
                    "factor_tipo_de_cambio": 1,
                    "fecha_de_vencimiento": "2026-11-07",
                    "numero_orden_de_compra": "OC-2026-0045",
                    "numero_de_placa": null,
                    "folio": null,
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "6",
                      "numero_documento": "20501973522",
                      "apellidos_y_nombres_o_razon_social": "EMPRESA XYZ S.A.C.",
                      "nombre_comercial": "XYZ",
                      "codigo_pais": "PE",
                      "ubigeo": "150101",
                      "direccion": "Av. 2 de Mayo 123, Lima",
                      "correo_electronico": "facturacion@xyz.com.pe",
                      "telefono": "014271148",
                      "codigo_tipo_direccion": null
                    },
                    "totales": {
                      "total_anticipos": 0,
                      "total_descuentos": 0,
                      "total_cargos": 0,
                      "total_exportacion": 0,
                      "total_operaciones_gravadas": 100.0,
                      "total_operaciones_inafectas": 0,
                      "total_operaciones_exoneradas": 0,
                      "total_operaciones_gratuitas": 0,
                      "total_igv_operaciones_gratuitas": 0,
                      "total_igv": 18.0,
                      "total_base_isc": 0,
                      "total_isc": 0,
                      "total_base_otros_impuestos": 0,
                      "total_otros_impuestos": 0,
                      "total_impuestos_bolsa_plastica": 0,
                      "total_impuestos": 18.0,
                      "total_valor": 100.0,
                      "subtotal_venta": 118.0,
                      "total_venta": 118.0,
                      "total_pendiente_pago": 0
                    },
                    "items": [
                      {
                        "codigo_interno": "P0121",
                        "descripcion": "GASEOSA 500ML",
                        "nombre": null,
                        "nombre_secundario": null,
                        "codigo_tipo_item": "01",
                        "codigo_producto_sunat": "50202306",
                        "codigo_producto_gsl": null,
                        "unidad_de_medida": "NIU",
                        "cantidad": 2,
                        "valor_unitario": 50,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 59,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 18.0,
                        "codigo_tipo_sistema_isc": null,
                        "total_base_isc": 0,
                        "porcentaje_isc": 0,
                        "total_isc": 0,
                        "total_base_otros_impuestos": 0,
                        "porcentaje_otros_impuestos": 0,
                        "total_otros_impuestos": 0,
                        "total_impuestos_bolsa_plastica": 0,
                        "total_impuestos": 18.0,
                        "total_valor_item": 100.0,
                        "total_cargos": 0,
                        "total_descuentos": 0,
                        "total_item": 118.0,
                        "datos_adicionales": [],
                        "descuentos": [],
                        "cargos": [],
                        "informacion_adicional": null,
                        "lots": [],
                        "actualizar_descripcion": false,
                        "nombre_producto_pdf": null,
                        "nombre_producto_xml": null,
                        "dato_adicional": null
                      }
                    ],
                    "descuentos": [],
                    "cargos": [],
                    "pagos": [
                      {
                        "codigo_metodo_pago": "01",
                        "codigo_destino_pago": "cash",
                        "referencia": "",
                        "monto": 118.0,
                        "pago_recibido": 120.0
                      }
                    ],
                    "cuotas": [],
                    "codigo_condicion_de_pago": "01",
                    "anticipos": [],
                    "guias": [],
                    "relacionados": [],
                    "leyendas": [],
                    "informacion_adicional": "Entrega en almacén del cliente",
                    "dato_adicional": null,
                    "terminos_condiciones": null,
                    "codigo_vendedor": null,
                    "codigo_nota_venta": null,
                    "pago_anticipado": false,
                    "es_itinerante": false,
                    "acciones": {
                      "enviar_email": false,
                      "enviar_xml_firmado": true,
                      "formato_pdf": "a4",
                      "auto_print": false,
                      "name_printer": null,
                      "client_public_ip": null
                    },
                    "external_id": "9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                    "hash": "kJ8xQ2m0pZ3l7m9aB1c2d3e4f5g=",
                    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
                    "file_xml_signed": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
                    "file_pdf": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK...",
                    "query": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/document_check_server/{document_external_id}": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Verificar comprobante sincronizado",
        "operationId": "VerificarComprobanteSincronizado",
        "description": "Devuelve el estado de un comprobante por su `external_id` y, si está **aceptado** y es factura o nota de factura, el CDR en base64. Complementa *Registrar comprobante emitido en otro servidor*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Respuesta `{success, state_type_id, file_cdr}`; `file_cdr` es `null` si no aplica.\n\n**Errores:** `404` `{success: false, message}` si el `external_id` no existe.",
        "responses": {
          "200": {
            "description": "Aceptado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Aceptado",
                    "value": {
                      "success": true,
                      "state_type_id": "05",
                      "file_cdr": "UEsDBBQAAAAIAGhUZ1kAAAAAAAAAAAAAAAAeAAAAUi0yMDEyMzQ1Njc4OS0wMS1GMDAxLTE1MjAueG1s..."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "El documento con código externo 00000000-0000-0000-0000-000000000000, no se encuentra registrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/documents/tables": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Catálogo de estados de comprobante",
        "operationId": "CatalogoEstadosComprobante",
        "description": "Lista de estados de comprobante (para filtros), con la opción adicional `all` (*Todos*).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Objeto `{state_types: [...]}`.\n\nEstados (`state_type_id`): `01` registrado, `03` enviado, `05` aceptado, `07` observado, `09` rechazado, `11` anulado, `13` por anular.",
        "responses": {
          "200": {
            "description": "Estados",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estados",
                    "value": {
                      "state_types": [
                        {
                          "id": "01",
                          "description": "Registrado"
                        },
                        {
                          "id": "03",
                          "description": "Enviado"
                        },
                        {
                          "id": "05",
                          "description": "Aceptado"
                        },
                        {
                          "id": "07",
                          "description": "Observado"
                        },
                        {
                          "id": "09",
                          "description": "Rechazado"
                        },
                        {
                          "id": "11",
                          "description": "Anulado"
                        },
                        {
                          "id": "13",
                          "description": "Por anular"
                        },
                        {
                          "id": "all",
                          "description": "Todos"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents/tables-sale-detail": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Catálogos para las líneas de venta",
        "operationId": "CatalogosLineasVenta",
        "description": "Catálogos para armar las líneas de un comprobante: tipos de afectación IGV activos, tipos de comprobante de venta y tipos de descuento por línea.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "affectation_igv_types": [
                        {
                          "id": "10",
                          "active": 1,
                          "exportation": 0,
                          "free": 0,
                          "description": "Gravado - Operación Onerosa"
                        },
                        {
                          "id": "20",
                          "active": 1,
                          "exportation": 0,
                          "free": 0,
                          "description": "Exonerado - Operación Onerosa"
                        }
                      ],
                      "document_types": [
                        {
                          "id": "01",
                          "description": "FACTURA ELECTRÓNICA"
                        },
                        {
                          "id": "03",
                          "description": "BOLETA DE VENTA ELECTRÓNICA"
                        },
                        {
                          "id": "80",
                          "description": "NOTA DE VENTA"
                        }
                      ],
                      "item_discount_types": [
                        {
                          "id": "00",
                          "active": 1,
                          "base": 1,
                          "level": "item",
                          "type": "discount",
                          "description": "Descuentos que afectan la base imponible del IGV/IVAP"
                        },
                        {
                          "id": "01",
                          "active": 1,
                          "base": 0,
                          "level": "item",
                          "type": "discount",
                          "description": "Descuentos que no afectan la base imponible del IGV/IVAP"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents/tables-sale-payment": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Catálogos para cobrar una venta",
        "operationId": "CatalogosCobrarVenta",
        "description": "Todo lo necesario para la cabecera y el cobro de una venta: series de venta del establecimiento del usuario, condiciones de pago, métodos de pago, destinos del dinero (cuentas bancarias de la sucursal y la caja abierta del usuario como `cash`), los primeros clientes y los términos y condiciones configurados.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\nSi el usuario no tiene caja abierta, `payment_destinations` no incluye `cash` y los cobros en efectivo serán rechazados.",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "series": [
                        {
                          "id": 1,
                          "document_type_id": "01",
                          "number": "F001",
                          "is_default": true,
                          "establishment_id": 1
                        },
                        {
                          "id": 2,
                          "document_type_id": "03",
                          "number": "B001",
                          "is_default": true,
                          "establishment_id": 1
                        }
                      ],
                      "payment_conditions": [
                        {
                          "id": "01",
                          "name": "Contado"
                        },
                        {
                          "id": "02",
                          "name": "Crédito"
                        }
                      ],
                      "payment_method_types": [
                        {
                          "id": "01",
                          "description": "Efectivo",
                          "has_card": false,
                          "charge": null,
                          "number_days": null,
                          "is_credit": false,
                          "is_cash": true
                        },
                        {
                          "id": "05",
                          "description": "Tarjeta de crédito",
                          "has_card": true,
                          "charge": null,
                          "number_days": null,
                          "is_credit": false,
                          "is_cash": false
                        },
                        {
                          "id": "09",
                          "description": "Crédito",
                          "has_card": false,
                          "charge": null,
                          "number_days": null,
                          "is_credit": true,
                          "is_cash": false
                        }
                      ],
                      "payment_destinations": [
                        {
                          "id": 3,
                          "cash_id": null,
                          "type": "bank",
                          "type_label": "Cuenta bancaria",
                          "reconciles_with": null,
                          "logo_url": null,
                          "receives_income": true,
                          "allows_payments": true,
                          "currency_type_id": "PEN",
                          "establishment_id": null,
                          "description": "BCP - PEN - CUENTA CORRIENTE"
                        },
                        {
                          "id": "cash",
                          "cash_id": 41,
                          "description": "CAJA GENERAL - CAJA 01"
                        }
                      ],
                      "customers": [
                        {
                          "id": 1,
                          "description": "20501973522 - EMPRESA XYZ S.A.C.",
                          "name": "EMPRESA XYZ S.A.C.",
                          "number": "20501973522",
                          "identity_document_type_id": "6",
                          "identity_document_type_code": "6",
                          "identity_document_type_description": "RUC",
                          "address": "Av. 2 de Mayo 123, Lima",
                          "telephone": "014271148",
                          "country_id": "PE",
                          "district_id": "150101",
                          "email": "facturacion@xyz.com.pe",
                          "selected": false,
                          "addresses": [
                            {
                              "id": 4,
                              "location_id": [
                                "15",
                                "1501",
                                "150101"
                              ],
                              "address": "Jr. Ica 450, Lima",
                              "code": "0001",
                              "has_consigned": false
                            }
                          ],
                          "enabled": true,
                          "location_id": [
                            "15",
                            "1501",
                            "150101"
                          ]
                        }
                      ],
                      "terms_condition": null
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents/table/{table_name}": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Catálogo individual de comprobantes",
        "operationId": "CatalogoIndividualComprobantes",
        "description": "Devuelve un catálogo por nombre. Único valor soportado: `document_types` (tipos de comprobante de venta). Cualquier otro nombre devuelve `[]`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura.",
        "responses": {
          "200": {
            "description": "Tipos de comprobante",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Tipos de comprobante",
                    "value": [
                      {
                        "id": "01",
                        "description": "FACTURA ELECTRÓNICA"
                      },
                      {
                        "id": "03",
                        "description": "BOLETA DE VENTA ELECTRÓNICA"
                      },
                      {
                        "id": "80",
                        "description": "NOTA DE VENTA"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "table_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "document_types"
          }
        ]
      }
    },
    "/api/documents/detraction-tables": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Catálogos de detracción",
        "operationId": "CatalogosDetraccion",
        "description": "Catálogos para emitir operaciones sujetas a detracción: cuenta de detracciones de la empresa, si las operaciones `1001` y `1004` están habilitadas, tipos de bien/servicio con su porcentaje, métodos de pago de la detracción (catálogo SUNAT 59) y reglas de redondeo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Reglas:** habilita la detracción solo si `detraction_account` no es `null` y `operation_type_active` (o `transport_operation_type_active` para `1004`) es `true`. Toma los porcentajes del catálogo, no los fijes en tu sistema. `minimum_total` es el monto mínimo de la operación (S/ 700) salvo que `allow_amount_minor` sea `true`. Si `amount_rounded_int` es `true`, el monto de la detracción se redondea a entero.",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "success": true,
                      "data": {
                        "detraction_account": "00-000-123456",
                        "operation_type_active": true,
                        "detraction_types": [
                          {
                            "id": "037",
                            "description": "Demás servicios gravados con el IGV",
                            "percentage": 12.0
                          },
                          {
                            "id": "022",
                            "description": "Otros servicios empresariales",
                            "percentage": 12.0
                          }
                        ],
                        "transport_operation_type_active": false,
                        "transport_detraction_types": [
                          {
                            "id": "027",
                            "description": "Servicio de transporte de carga",
                            "percentage": 4.0
                          }
                        ],
                        "payment_methods": [
                          {
                            "id": "001",
                            "description": "Depósito en cuenta"
                          },
                          {
                            "id": "003",
                            "description": "Transferencia de fondos"
                          }
                        ],
                        "amount_rounded_int": false,
                        "allow_amount_minor": false,
                        "minimum_total": 700
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document/tables": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Productos y afectaciones para vender",
        "operationId": "ProductosAfectacionesVender",
        "description": "Devuelve los **primeros 20 productos activos** (con código interno) del almacén del usuario, con precios, presentaciones y stock, además de los tipos de afectación IGV y las categorías. Para buscar productos usa *Buscar productos para vender*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Nota:** en este listado el campo `category` de cada producto contiene el nombre de la **marca**; usa *Buscar productos para vender* si necesitas la categoría real.",
        "responses": {
          "200": {
            "description": "Datos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos",
                    "value": {
                      "success": true,
                      "data": {
                        "items": [
                          {
                            "id": 120,
                            "item_id": 120,
                            "name": null,
                            "full_description": "P0121 - GASEOSA 500ML",
                            "description": "GASEOSA 500ML",
                            "currency_type_id": "PEN",
                            "internal_id": "P0121",
                            "item_code": "50202306",
                            "currency_type_symbol": "S/",
                            "sale_unit_price": "3.50",
                            "purchase_unit_price": "2.200000",
                            "unit_type_id": "NIU",
                            "sale_affectation_igv_type_id": "10",
                            "purchase_affectation_igv_type_id": "10",
                            "calculate_quantity": false,
                            "has_igv": true,
                            "is_set": false,
                            "lots": [],
                            "aux_quantity": 1,
                            "barcode": "7750182002363",
                            "brand_id": 2,
                            "brand": "INCA KOLA",
                            "category_id": 1,
                            "category": "INCA KOLA",
                            "stock": "48.0000",
                            "image": "https://empresa.dominio/logo/imagen-no-disponible.jpg",
                            "warehouses": [
                              {
                                "warehouse_id": 1,
                                "establishment_id": 1,
                                "warehouse_description": "Almacén Oficina Principal",
                                "stock": 48
                              }
                            ],
                            "item_unit_types": [
                              {
                                "id": 7,
                                "description": "Paquete x 12",
                                "unit_type_id": "PK",
                                "quantity_unit": "12.00",
                                "price1": "39.00",
                                "price2": "0.00",
                                "price3": "0.00",
                                "price_default": 1
                              }
                            ],
                            "has_isc": false,
                            "system_isc_type_id": null,
                            "percentage_isc": "0.00",
                            "favorite": false,
                            "price": "3.500000",
                            "IdLoteSelected": null
                          }
                        ],
                        "affectation_types": [
                          {
                            "id": "10",
                            "active": 1,
                            "exportation": 0,
                            "free": 0,
                            "description": "Gravado - Operación Onerosa"
                          }
                        ],
                        "categories": [
                          {
                            "id": 1,
                            "name": "BEBIDAS"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document/customers": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Primeros clientes",
        "operationId": "PrimerosClientes",
        "description": "Devuelve los **primeros 20 clientes** ordenados por nombre, con sus direcciones. Para buscar usa *Buscar clientes para vender*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Los clientes vienen en `data.customers`.",
        "responses": {
          "200": {
            "description": "Clientes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Clientes",
                    "value": {
                      "success": true,
                      "data": {
                        "customers": [
                          {
                            "id": 1,
                            "description": "20501973522 - EMPRESA XYZ S.A.C.",
                            "name": "EMPRESA XYZ S.A.C.",
                            "number": "20501973522",
                            "identity_document_type_id": "6",
                            "identity_document_type_code": "6",
                            "identity_document_type_description": "RUC",
                            "address": "Av. 2 de Mayo 123, Lima",
                            "telephone": "014271148",
                            "country_id": "PE",
                            "district_id": "150101",
                            "email": "facturacion@xyz.com.pe",
                            "selected": false,
                            "addresses": [
                              {
                                "id": 4,
                                "location_id": [
                                  "15",
                                  "1501",
                                  "150101"
                                ],
                                "address": "Jr. Ica 450, Lima",
                                "code": "0001",
                                "has_consigned": false
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document/search-customers": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Buscar clientes para vender",
        "operationId": "BuscarClientesVender",
        "description": "Busca clientes por nombre o número de documento (coincidencia parcial). Con `document_type_id=01` (factura) se limita a clientes con RUC; con otro valor admite DNI, carné de extranjería, RUC, pasaporte y sin documento.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Los clientes vienen en `data.customers` (sin paginación).\n\n**Nota:** la coincidencia por nombre puede traer personas que no son clientes o con otro tipo de documento; verifica `identity_document_type_id` antes de emitir una factura.",
        "responses": {
          "200": {
            "description": "Clientes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Clientes",
                    "value": {
                      "success": true,
                      "data": {
                        "customers": [
                          {
                            "id": 1,
                            "description": "20501973522 - EMPRESA XYZ S.A.C.",
                            "name": "EMPRESA XYZ S.A.C.",
                            "number": "20501973522",
                            "identity_document_type_id": "6",
                            "identity_document_type_code": "6",
                            "identity_document_type_description": "RUC",
                            "address": "Av. 2 de Mayo 123, Lima",
                            "telephone": "014271148",
                            "country_id": "PE",
                            "district_id": "150101",
                            "email": "facturacion@xyz.com.pe",
                            "selected": false,
                            "addresses": [
                              {
                                "id": 4,
                                "location_id": [
                                  "15",
                                  "1501",
                                  "150101"
                                ],
                                "address": "Jr. Ica 450, Lima",
                                "code": "0001",
                                "has_consigned": false
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "XYZ",
            "description": "Texto a buscar (nombre o número)."
          },
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Comprobante que vas a emitir: `01` solo RUC; `03`/`80` cualquier documento."
          }
        ]
      }
    },
    "/api/document/paymentmethod": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Métodos de pago y destinos",
        "operationId": "MetodosPagoDestinos",
        "description": "Métodos de pago (`codigo_metodo_pago` de `pagos[]`) y destinos del dinero (`codigo_destino_pago`): cuentas bancarias visibles en la sucursal del usuario y, si tiene caja abierta, la caja (`id: \"cash\"`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Objeto `{payment_method_type: [...], payment_destinations: [...]}`.",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "payment_method_type": [
                        {
                          "id": "01",
                          "description": "Efectivo",
                          "has_card": false,
                          "charge": null,
                          "number_days": null,
                          "is_credit": false,
                          "is_cash": true
                        },
                        {
                          "id": "05",
                          "description": "Tarjeta de crédito",
                          "has_card": true,
                          "charge": null,
                          "number_days": null,
                          "is_credit": false,
                          "is_cash": false
                        },
                        {
                          "id": "09",
                          "description": "Crédito",
                          "has_card": false,
                          "charge": null,
                          "number_days": null,
                          "is_credit": true,
                          "is_cash": false
                        }
                      ],
                      "payment_destinations": [
                        {
                          "id": 3,
                          "cash_id": null,
                          "type": "bank",
                          "type_label": "Cuenta bancaria",
                          "reconciles_with": null,
                          "logo_url": null,
                          "receives_income": true,
                          "allows_payments": true,
                          "currency_type_id": "PEN",
                          "establishment_id": null,
                          "description": "BCP - PEN - CUENTA CORRIENTE"
                        },
                        {
                          "id": "cash",
                          "cash_id": 41,
                          "description": "CAJA GENERAL - CAJA 01"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document/email": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Enviar comprobante por correo",
        "operationId": "EnviarComprobanteCorreo",
        "description": "Envía el comprobante (PDF y XML) por correo electrónico usando la configuración de correo de la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del comprobante. |\n| `email` | string | Sí | Correo de destino. Para varios destinatarios sepáralos con coma. |\n\n**Reglas y errores:** no hay validación del cuerpo; la respuesta es `success: true` aunque el correo no llegue (el envío se registra en el historial de correos). Un `id` inexistente responde `500`.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Email enviado correctamente."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar comprobante por correo",
                  "value": {
                    "id": "1",
                    "email": "facturacion@xyz.com.pe"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/send-document-to-whatsapp": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Enviar comprobante por WhatsApp",
        "operationId": "EnviarComprobanteWhatsapp",
        "description": "Envía por WhatsApp (API oficial de WhatsApp Business configurada en la empresa) un mensaje de texto con el enlace del comprobante y luego el PDF como documento.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del comprobante o de la nota de venta. |\n| `document_type_id` | string | Sí | `01`, `03`, `07`, `08` para comprobantes; `80` para notas de venta. |\n| `phone_number` | numeric | Sí | Celular de destino, 9 dígitos (sin código de país). |\n| `format` | string | Sí | Formato del PDF: `a4`, `a5`, `ticket`. |\n\n**Errores:** `422` si falta un campo o el celular no tiene 9 dígitos; HTTP 200 con `success: false` si la empresa no configuró WhatsApp Business o el proveedor rechazó el mensaje.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Mensaje enviado correctamente."
                    }
                  },
                  "e2": {
                    "summary": "Sin configuración",
                    "value": {
                      "success": false,
                      "message": "No tiene registrado correctamente el identificador de número de teléfono"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "phone_number": [
                          "El campo phone number debe tener 9 dígitos."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar comprobante por WhatsApp",
                  "value": {
                    "id": "1",
                    "document_type_id": "01",
                    "phone_number": "987654321",
                    "format": "a4"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/record/qrapi": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Configuración de envío por WhatsApp (QR)",
        "operationId": "ConfiguracionEnvioWhatsappQr",
        "description": "Devuelve la configuración del envío de comprobantes por WhatsApp vinculado por QR: si está habilitado, formato del PDF que se comparte, instancia y número conectado, estado de la conexión y consumo de mensajes del plan.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Configuración",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Configuración",
                    "value": {
                      "qr_api_enable_ws": true,
                      "qr_api_use_bot_instance": false,
                      "qr_api_pdf_format": "ticket",
                      "qr_api_instance": "empresa_20123456789",
                      "qr_api_instance_adopted": false,
                      "qr_api_connected_phone": "51987654321",
                      "qr_api_profile_name": "Mi Empresa",
                      "qr_api_connection_state": "open",
                      "qr_api_provider": "evolution",
                      "qr_api_waha_server_key": null,
                      "evolution_instance": null,
                      "evolution_instance_adopted": false,
                      "evolution_use_qr_api_instance": false,
                      "evolution_connected_phone": null,
                      "evolution_provider": "evolution",
                      "evolution_waha_server_key": null,
                      "whatsapp_messages_used": 12,
                      "whatsapp_messages_limit": 500,
                      "whatsapp_messages_unlimited": false
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/documents/{document_id}": {
      "put": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Editar comprobante (antes del envío)",
        "operationId": "EditarComprobanteAntesEnvio",
        "description": "Corrige una factura o boleta que **aún no fue enviada a SUNAT** (estado `01`), con el **mismo cuerpo** que **Emitir comprobante electrónico**. Si el comprobante ya fue aceptado, corrígelo con **Emitir nota de crédito** o **Emitir nota de débito**.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`. Además necesitas ser quien emitió el comprobante o tener el permiso de editar comprobantes (ver reglas).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id interno del comprobante (`{document_id}`). |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `(todo el cuerpo)` | object | Sí | El **mismo cuerpo** de **Emitir comprobante electrónico** (`POST documents`): reutiliza tu payload con los datos corregidos. |\n| `codigo_tipo_documento` | string | Sí | Debe ser el del comprobante (`01` factura o `03` boleta): el tipo no cambia. |\n| `serie_documento / numero_documento` | string | No | Si los envías deben ser los del comprobante (o `#` en el número). La serie y el número **no cambian**. |\n| `codigo_tipo_operacion` | string | Sí | Catálogo 51 (`0101` venta interna...). |\n| `fecha_de_emision` | string `Y-m-d` | Sí | Puede corregirse, dentro del plazo de envío configurado. |\n| `hora_de_emision` | string `H:i:s` | No | Si no la envías se conserva la del comprobante. |\n| `datos_del_cliente_o_receptor` | object | Sí | Cliente (se crea o actualiza por tipo y número de documento). |\n| `totales` | object | Sí | Totales recalculados del comprobante. |\n| `items` | array (mín. 1) | Sí | **Todas** las líneas que debe tener el comprobante (las anteriores se reemplazan). |\n| `pagos` | array | Sí si el comprobante tiene cobros | **Todos** los cobros que debe tener. `[]` lo deja sin cobros. Si el comprobante tenía cobros y no envías `pagos`, responde `422` (para no borrarlos por omisión). |\n| `cuotas` | array | No | Cuotas de una venta al crédito (`codigo_condicion_de_pago: 02`). Se reemplazan. |\n\n**Estado del comprobante (`state_type_id`) y qué se puede hacer:**\n\n| Estado | Significado | Editar | Nota de crédito / débito |\n|---|---|---|---|\n| `01` | Registrado (aún no enviado a SUNAT) | **Sí** | No: corrígelo editándolo o envíalo primero |\n| `03` | Enviado, espera respuesta | No (`409`) | No (`409`): espera la respuesta |\n| `05` | Aceptado | No (`409`): usa una nota | **Sí** |\n| `07` | Observado | No (`409`): usa una nota | No (`409`) |\n| `09` | Rechazado | No (`409`): emite un comprobante nuevo | No (`409`) |\n| `11` | Anulado | No (`409`) | No (`409`) |\n| `13` | Por anular | No (`409`) | No (`409`) |\n\n**Reglas:**\n- **Reemplazo completo**, no edición parcial: cliente, líneas, totales, pagos y cuotas quedan exactamente como los envías. `PUT` y `PATCH` hacen lo mismo.\n- Solo comprobantes en estado **Registrado (`01`)**, es decir, aún no enviados a SUNAT. Ver la tabla de estados.\n- Solo **facturas y boletas**: una nota de crédito o débito no se edita (`409`).\n- **Quién puede editar:** quien emitió el comprobante, o un usuario con el permiso **Editar comprobantes** cuando la empresa tiene habilitada la opción *Permitir editar comprobantes*. Un vendedor solo ve sus comprobantes (los de otro vendedor dan `403`).\n- Se conservan la serie, el número, el `external_id`, el usuario que lo emitió, el establecimiento y el origen (nota de venta, pedido, cotización).\n- El **stock** se ajusta en el almacén del establecimiento del comprobante: las líneas anteriores se devuelven y las nuevas se descuentan.\n- Los **cobros** se reemplazan sin duplicar la caja: los anteriores salen de la caja y los nuevos entran a la caja abierta de quien edita (`codigo_destino_pago: cash`) o a la cuenta indicada. Si algún cobro anterior pertenece a una caja **ya cerrada**, responde `409`.\n- Se regeneran el XML firmado, el hash, el QR y el PDF. La edición **no envía** a SUNAT: el comprobante sigue en `01`; envíalo con **Enviar comprobante a SUNAT** (`documents/send`) o deja que el envío automático lo procese.\n\n**Errores:**\n- `403` si el comprobante es de otro vendedor o no tienes permiso para editarlo.\n- `404` si el comprobante no existe.\n- `409` si el estado no es `01` (el `message` dice qué hacer según el estado), si es una nota, si algún cobro anterior está en una caja cerrada o si falta el certificado digital.\n- `422` `{success: false, message}` si el cuerpo no es válido: falta un campo, cambia el tipo, la serie o el número, faltan `pagos` en un comprobante con cobros, o los pagos superan el total sin efectivo para el vuelto.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1520,
                        "number": "B001-245",
                        "document_type_id": "03",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "external_id": "9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11",
                        "filename": "20123456789-03-B001-245",
                        "hash": "nT2bm1u3kz0b4xQ9gS6v8Lr2pYc=",
                        "date_of_issue": "2026-11-07",
                        "currency_type_id": "PEN",
                        "total": 40.0,
                        "links": {
                          "xml": "https://empresa.dominio/downloads/document/xml/9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11",
                          "pdf": "https://empresa.dominio/downloads/document/pdf/9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11"
                        }
                      },
                      "message": "Comprobante actualizado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin permiso de edición",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin permiso de edición",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para editar este comprobante: solo lo edita quien lo emitió o un usuario con el permiso para editar comprobantes (y la opción habilitada en la configuración de la empresa)."
                    }
                  },
                  "e2": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Aceptado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Aceptado",
                    "value": {
                      "success": false,
                      "message": "El comprobante ya fue aceptado por SUNAT y no se puede editar: para corregirlo usa una nota de crédito o débito."
                    }
                  },
                  "e2": {
                    "summary": "Rechazado",
                    "value": {
                      "success": false,
                      "message": "Un comprobante rechazado por SUNAT no se puede editar: emite uno nuevo."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Cambia el tipo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cambia el tipo",
                    "value": {
                      "success": false,
                      "message": "El tipo de comprobante no se puede cambiar al editar (es 03)."
                    }
                  },
                  "e2": {
                    "summary": "Faltan pagos",
                    "value": {
                      "success": false,
                      "message": "La edición reemplaza el comprobante completo: envía \"pagos\" con los cobros que debe tener (o \"pagos\": [] para dejarlo sin cobros)."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar comprobante (antes del envío)",
                  "value": {
                    "serie_documento": "B001",
                    "numero_documento": "245",
                    "fecha_de_emision": "2026-11-07",
                    "hora_de_emision": "10:15:00",
                    "codigo_tipo_operacion": "0101",
                    "codigo_tipo_documento": "03",
                    "codigo_tipo_moneda": "PEN",
                    "fecha_de_vencimiento": "2026-11-07",
                    "codigo_condicion_de_pago": "01",
                    "datos_del_cliente_o_receptor": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "45678912",
                      "apellidos_y_nombres_o_razon_social": "MARIA LOPEZ RAMOS",
                      "codigo_pais": "PE",
                      "direccion": "-",
                      "correo_electronico": "",
                      "telefono": ""
                    },
                    "totales": {
                      "total_exportacion": 0,
                      "total_operaciones_gravadas": 33.9,
                      "total_operaciones_inafectas": 0,
                      "total_operaciones_exoneradas": 0,
                      "total_operaciones_gratuitas": 0,
                      "total_igv": 6.1,
                      "total_impuestos": 6.1,
                      "total_valor": 33.9,
                      "total_venta": 40
                    },
                    "items": [
                      {
                        "codigo_interno": "P001",
                        "descripcion": "GASEOSA 500 ML",
                        "unidad_de_medida": "NIU",
                        "cantidad": 4,
                        "valor_unitario": 8.474576,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 10,
                        "codigo_tipo_afectacion_igv": "10",
                        "total_base_igv": 33.9,
                        "porcentaje_igv": 18,
                        "total_igv": 6.1,
                        "total_impuestos": 6.1,
                        "total_valor_item": 33.9,
                        "total_item": 40
                      }
                    ],
                    "pagos": [
                      {
                        "codigo_metodo_pago": "01",
                        "codigo_destino_pago": "cash",
                        "referencia": null,
                        "monto": 40
                      }
                    ],
                    "acciones": {
                      "formato_pdf": "a4"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/{document_id}/notes": {
      "get": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Notas de un comprobante (saldo disponible)",
        "operationId": "NotasComprobanteSaldoDisponible",
        "description": "Notas de crédito y débito emitidas sobre una factura o boleta, cuánto queda por acreditar y cuánto queda por devolver de cada línea. Úsalo antes de **Emitir nota de crédito** para armar una nota parcial.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id interno del comprobante (`{document_id}`). |\n\n**Campos de `data`:**\n\n| Campo | Descripción |\n|---|---|\n| `document` | Comprobante: `id`, `number`, `state_type_id`, `currency_type_id`, `total`. |\n| `can_issue_notes` / `reason` | Si hoy admite notas y, si no, por qué (mismo mensaje que el `409`). |\n| `credit_notes_total` | Suma de las notas de crédito vigentes (no rechazadas ni anuladas). |\n| `debit_notes_total` | Suma de las notas de débito vigentes. |\n| `available_for_credit_note` | `total` − `credit_notes_total`: tope de una nueva nota de crédito. |\n| `items[]` | Líneas del comprobante: `line_id`, `item_id`, `description`, `quantity`, `returned_quantity` (devuelto por notas que reingresan stock), `available_quantity`, `unit_price` (con IGV), `total`. |\n| `notes[]` | Notas: `id`, `number`, `document_type_id` (`07` crédito, `08` débito), `note_type`, `note_type_description`, `description`, `date_of_issue`, `total`, `state_type_id`, `counts_for_balance` (`false` si fue rechazada o anulada). |\n\n**Errores:**\n- `403` si el comprobante es de otro vendedor.\n- `404` si el comprobante no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Con una devolución parcial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Con una devolución parcial",
                    "value": {
                      "success": true,
                      "data": {
                        "document": {
                          "id": 1520,
                          "number": "F001-310",
                          "document_type_id": "01",
                          "state_type_id": "05",
                          "currency_type_id": "PEN",
                          "total": 60.0
                        },
                        "can_issue_notes": true,
                        "reason": null,
                        "credit_notes_total": 35.0,
                        "debit_notes_total": 0,
                        "available_for_credit_note": 25.0,
                        "items": [
                          {
                            "line_id": 4101,
                            "item_id": 88,
                            "description": "GASEOSA 500 ML",
                            "quantity": 2,
                            "returned_quantity": 1,
                            "available_quantity": 1,
                            "unit_price": 15.0,
                            "total": 30.0
                          },
                          {
                            "line_id": 4102,
                            "item_id": 91,
                            "description": "GALLETAS X 6",
                            "quantity": 3,
                            "returned_quantity": 2,
                            "available_quantity": 1,
                            "unit_price": 10.0,
                            "total": 30.0
                          }
                        ],
                        "notes": [
                          {
                            "id": 1533,
                            "number": "FC01-12",
                            "document_type_id": "07",
                            "note_type": "07",
                            "note_type_description": "Devolución por ítem",
                            "description": "Devolución parcial",
                            "date_of_issue": "2026-11-07",
                            "total": 35.0,
                            "state_type_id": "05",
                            "state_type_description": "Aceptado",
                            "counts_for_balance": true
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/documents/{document_id}/credit-note": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Emitir nota de crédito",
        "operationId": "EmitirNotaCredito",
        "description": "Emite una nota de crédito (`07`) sobre una factura o boleta **aceptada**: anulación, devolución total o por ítem, descuentos o rebajas posteriores. Sale por el mismo proceso que **Emitir comprobante electrónico** (XML firmado, PDF y envío según la configuración).\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` al registrar la nota.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id interno del comprobante (`{document_id}`). |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `note_type` | string | Sí | Código del catálogo 09 (crédito), activo en la empresa. Ver la tabla de tipos. |\n| `description` | string (máx. 500) | Sí | Motivo o sustento de la nota (sale en el XML y el PDF). |\n| `series` | string (4) | No | Serie de la nota del establecimiento del comprobante (`FC.. / BC..`): las notas de una **factura** usan series que empiezan con **F** y las de una **boleta** con **B**. Si no la envías se usa la primera disponible. |\n| `date_of_issue` | string `Y-m-d` | No | Fecha de la nota. Por defecto hoy. No puede ser anterior a la del comprobante ni futura. |\n| `items` | array | No | Sin `items`: nota **total** con todas las líneas del comprobante. Con `items`: solo esas líneas. |\n| `items[].line_id` | integer | Uno de los dos | Id de la línea del comprobante (`items[].line_id` de **Notas de un comprobante**). |\n| `items[].item_id` | integer | Uno de los dos | Id del producto. Si el producto está en varias líneas, usa `line_id`. |\n| `items[].quantity` | numeric > 0 | Sí | Cantidad (en la misma unidad o presentación de la línea). No puede superar la vendida ni, en devoluciones, lo que falta devolver. |\n| `items[].unit_price` | numeric > 0 | No | Precio unitario **con IGV**. Por defecto el de la línea. No puede superar el de la línea. |\n| `actions.send_xml_signed` | boolean | No | Enviar a SUNAT al emitir si la empresa tiene el envío automático activo. Por defecto `true`. |\n| `actions.send_email` | boolean | No | Enviar la nota por correo al cliente. Por defecto `false`. |\n| `actions.format_pdf` | string | No | `a4` (por defecto), `a5`, `ticket`, `ticket_58` o `ticket_50`. |\n\n**Tipos de nota de crédito (`note_type`, catálogo 09 de SUNAT):**\n\n| Código | Tipo | Cuándo usarlo | Por la API |\n|---|---|---|---|\n| `01` | Anulación de la operación | La venta no se realizó: anula todo el comprobante. | Solo **total** (sin `items`) y sin notas previas. Devuelve el stock. |\n| `02` | Anulación por error en el RUC | El comprobante se emitió a un RUC equivocado (luego emites uno nuevo al correcto). | Solo total. Devuelve el stock. |\n| `03` | Corrección por error en la descripción | Corregir textos sin cambiar importes. | **No** (`422`): emítela desde el sistema web. |\n| `04` | Descuento global | Descuento posterior sobre el total. | Total o parcial. No mueve stock. |\n| `05` | Descuento por ítem | Descuento posterior sobre algunas líneas. | Total o parcial. No mueve stock. |\n| `06` | Devolución total | El cliente devolvió todo. | Solo total y sin notas previas. Devuelve el stock. |\n| `07` | Devolución por ítem | El cliente devolvió parte de los productos. | Total o parcial. Devuelve el stock de lo devuelto. |\n| `08` | Bonificación | Bonificación posterior. | Total o parcial. Devuelve el stock. |\n| `09` | Disminución en el valor | Rebaja de precio posterior a la venta. | Total o parcial. No mueve stock. |\n| `10` | Otros conceptos | Otros casos. | Total o parcial. Devuelve el stock. |\n| `11` | Ajustes de operaciones de exportación | Solo exportaciones. | Total o parcial. |\n| `12` | Ajustes afectos al IVAP | Solo operaciones con IVAP. | Total o parcial. |\n| `13` | Ajustes – montos y/o fechas de pago | Cambiar cuotas de una venta al crédito. | **No** (`422`): emítela desde el sistema web. |\n\nLos tipos activos de tu empresa los da **Catálogos → Tipos de nota de crédito** (`catalogs/credit-note-types`).\n\n**Estado del comprobante (`state_type_id`) y qué se puede hacer:**\n\n| Estado | Significado | Editar | Nota de crédito / débito |\n|---|---|---|---|\n| `01` | Registrado (aún no enviado a SUNAT) | **Sí** | No: corrígelo editándolo o envíalo primero |\n| `03` | Enviado, espera respuesta | No (`409`) | No (`409`): espera la respuesta |\n| `05` | Aceptado | No (`409`): usa una nota | **Sí** |\n| `07` | Observado | No (`409`): usa una nota | No (`409`) |\n| `09` | Rechazado | No (`409`): emite un comprobante nuevo | No (`409`) |\n| `11` | Anulado | No (`409`) | No (`409`) |\n| `13` | Por anular | No (`409`) | No (`409`) |\n\n**Respuesta `201`:** `data.id` (id de la nota), `data.number` (serie-número), `data.state_type_id`, `data.external_id` (para consultar o enviar la nota), `data.total`, `data.affected_document` (comprobante modificado), `data.links` (`xml`, `pdf` y `cdr` si ya fue enviada) y `data.response` (respuesta de SUNAT si se envió).\n\n**Reglas:**\n- Solo sobre **facturas y boletas aceptadas (`05`)**; nunca sobre otra nota. Ver la tabla de estados.\n- No se emite si el comprobante ya tiene una nota de crédito de **anulación (`01`) aceptada**.\n- Si el comprobante tiene **descuentos, cargos o anticipos**, la nota se emite desde el sistema web (que reparte esos importes en las líneas): responde `409`.\n- Las líneas parciales solo admiten operaciones onerosas (gravado `10`, exonerado `20`, inafecto `30`, exportación `40`) sin ISC ni ICBPER; para líneas gratuitas o con esos tributos emite la nota total.\n- Un producto vendido con **series o lotes** solo admite la cantidad completa de su línea.\n- La nota usa el cliente, la moneda y el tipo de cambio del comprobante y queda en estado `01` (o `05` si se envió y SUNAT la aceptó). Si no se envía al emitir, envíala con **Enviar comprobante a SUNAT** (`documents/send`, con su `external_id`).\n- Un vendedor solo emite notas sobre sus comprobantes (`403` en los de otro vendedor).\n- **Saldo:** el total de la nota más las notas de crédito vigentes no puede superar el total del comprobante (ver **Notas de un comprobante**).\n- **Devoluciones:** lo devuelto de cada producto (esta nota más las anteriores que reingresaron stock) no puede superar lo vendido.\n- Los tipos `01`, `02` y `06` son por el **total**: no envíes `items`, y solo si el comprobante no tiene notas de crédito previas.\n- El **stock** reingresa al almacén de la línea original salvo en los tipos que no devuelven mercadería (`03`, `04`, `05`, `09`, `13`).\n\n**Errores:**\n- `403` si el comprobante es de otro vendedor.\n- `404` si el comprobante no existe.\n- `409` si el comprobante no está aceptado (`05`), es una nota, ya fue anulado con una nota `01` aceptada, tiene descuentos/cargos/anticipos o falta el certificado digital.\n- `422` `{success: false, message}` si falta el motivo, el tipo no existe o no se emite por la API, la serie no corresponde, la fecha no es válida, una línea no es del comprobante, la cantidad o el precio superan lo vendido, o el total supera el saldo.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Nota total (anulación)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Nota total (anulación)",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1533,
                        "number": "BC01-12",
                        "document_type_id": "07",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "external_id": "0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                        "filename": "20123456789-07-BC01-12",
                        "hash": "Wc1p8mB2tE7zK0yQ4nR6vS3aD5f=",
                        "date_of_issue": "2026-11-07",
                        "currency_type_id": "PEN",
                        "total": 60.0,
                        "links": {
                          "xml": "https://empresa.dominio/downloads/document/xml/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                          "pdf": "https://empresa.dominio/downloads/document/pdf/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                          "cdr": ""
                        },
                        "affected_document": {
                          "id": 1520,
                          "number": "B001-245",
                          "external_id": "9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11"
                        },
                        "note_type": "01",
                        "response": []
                      },
                      "message": "Nota de crédito BC01-12 registrada."
                    }
                  },
                  "e2": {
                    "summary": "Devolución parcial",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1533,
                        "number": "FC01-13",
                        "document_type_id": "07",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "external_id": "0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                        "filename": "20123456789-07-BC01-12",
                        "hash": "Wc1p8mB2tE7zK0yQ4nR6vS3aD5f=",
                        "date_of_issue": "2026-11-07",
                        "currency_type_id": "PEN",
                        "total": 15.0,
                        "links": {
                          "xml": "https://empresa.dominio/downloads/document/xml/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                          "pdf": "https://empresa.dominio/downloads/document/pdf/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                          "cdr": ""
                        },
                        "affected_document": {
                          "id": 1520,
                          "number": "F001-310",
                          "external_id": "9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11"
                        },
                        "note_type": "07",
                        "response": []
                      },
                      "message": "Nota de crédito FC01-13 registrada."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "No aceptado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No aceptado",
                    "value": {
                      "success": false,
                      "message": "El comprobante aún no fue enviado a SUNAT (estado Registrado): no admite notas. Si tiene errores, edítalo; si está bien, envíalo y espera que sea aceptado."
                    }
                  },
                  "e2": {
                    "summary": "Rechazado",
                    "value": {
                      "success": false,
                      "message": "El comprobante fue rechazado por SUNAT y no admite notas: emite un comprobante nuevo."
                    }
                  },
                  "e3": {
                    "summary": "Ya anulado",
                    "value": {
                      "success": false,
                      "message": "El comprobante ya fue anulado con la nota de crédito BC01-12: no admite más notas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Supera el saldo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Supera el saldo",
                    "value": {
                      "success": false,
                      "message": "El total de la nota (30) supera el saldo disponible del comprobante (25)."
                    }
                  },
                  "e2": {
                    "summary": "Supera lo vendido",
                    "value": {
                      "success": false,
                      "message": "La cantidad a devolver de \"GASEOSA 500 ML\" (2) supera lo que queda por devolver (1)."
                    }
                  },
                  "e3": {
                    "summary": "Serie no corresponde",
                    "value": {
                      "success": false,
                      "message": "La serie FC01 no es una serie de nota de crédito del establecimiento del comprobante que empiece con B (las notas de una boleta usan series B)."
                    }
                  },
                  "e4": {
                    "summary": "Tipo total con items",
                    "value": {
                      "success": false,
                      "message": "La nota de crédito tipo 06 es por el total del comprobante: no envíes items."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Emitir nota de crédito",
                  "value": {
                    "note_type": "07",
                    "description": "Devolución parcial: el cliente devolvió 1 gaseosa",
                    "series": "FC01",
                    "date_of_issue": "2026-11-07",
                    "items": [
                      {
                        "line_id": "1",
                        "quantity": 1
                      }
                    ],
                    "actions": {
                      "send_xml_signed": true,
                      "send_email": false,
                      "format_pdf": "a4"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/{document_id}/debit-note": {
      "post": {
        "tags": [
          "Comprobantes"
        ],
        "summary": "Emitir nota de débito",
        "operationId": "EmitirNotaDebito",
        "description": "Emite una nota de débito (`08`) sobre una factura o boleta **aceptada** para cobrar intereses, un aumento de valor u otros cargos posteriores. Sale por el mismo proceso que **Emitir comprobante electrónico**. No mueve stock.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` al registrar la nota.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id interno del comprobante (`{document_id}`). |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `note_type` | string | Sí | Código del catálogo 10 (débito), activo en la empresa. Ver la tabla de tipos. |\n| `description` | string (máx. 500) | Sí | Motivo o sustento de la nota (sale en el XML y el PDF). |\n| `series` | string (4) | No | Serie de la nota del establecimiento del comprobante (`FD.. / BD..`): las notas de una **factura** usan series que empiezan con **F** y las de una **boleta** con **B**. Si no la envías se usa la primera disponible. |\n| `date_of_issue` | string `Y-m-d` | No | Fecha de la nota. Por defecto hoy. No puede ser anterior a la del comprobante ni futura. |\n| `items` | array | No | Sin `items`: nota **total** con todas las líneas del comprobante. Con `items`: solo esas líneas. |\n| `items[].line_id` | integer | Uno de los dos | Id de la línea del comprobante (`items[].line_id` de **Notas de un comprobante**). |\n| `items[].item_id` | integer | Uno de los dos | Id del producto. Si el producto está en varias líneas, usa `line_id`. |\n| `items[].quantity` | numeric > 0 | Sí | Cantidad (en la misma unidad o presentación de la línea). |\n| `items[].unit_price` | numeric > 0 | No | Precio unitario **con IGV**. Por defecto el de la línea. Para intereses o aumentos es el importe a cobrar por unidad. |\n| `actions.send_xml_signed` | boolean | No | Enviar a SUNAT al emitir si la empresa tiene el envío automático activo. Por defecto `true`. |\n| `actions.send_email` | boolean | No | Enviar la nota por correo al cliente. Por defecto `false`. |\n| `actions.format_pdf` | string | No | `a4` (por defecto), `a5`, `ticket`, `ticket_58` o `ticket_50`. |\n\n**Tipos de nota de débito (`note_type`, catálogo 10 de SUNAT):**\n\n| Código | Tipo | Cuándo usarlo | Por la API |\n|---|---|---|---|\n| `01` | Intereses por mora | El cliente pagó tarde y se le cobran intereses. | Sí |\n| `02` | Aumento en el valor | Se cobra un mayor valor posterior a la venta. | Sí |\n| `03` | Otros conceptos | Otros cargos posteriores. | Sí |\n| `10` | Ajustes de operaciones de exportación | Solo exportaciones. | Sí |\n| `11` | Ajustes afectos al IVAP | Solo operaciones con IVAP. | Sí |\n| `13` | Penalidades | Penalidad al cliente (operación inafecta). | **No** (`422`): emítela desde el sistema web. |\n\nLos tipos activos de tu empresa los da **Catálogos → Tipos de nota de débito** (`catalogs/debit-note-types`). Una nota de débito **no mueve stock**.\n\n**Respuesta `201`:** `data.id` (id de la nota), `data.number` (serie-número), `data.state_type_id`, `data.external_id` (para consultar o enviar la nota), `data.total`, `data.affected_document` (comprobante modificado), `data.links` (`xml`, `pdf` y `cdr` si ya fue enviada) y `data.response` (respuesta de SUNAT si se envió).\n\n**Reglas:**\n- Solo sobre **facturas y boletas aceptadas (`05`)**; nunca sobre otra nota. Ver la tabla de estados.\n- No se emite si el comprobante ya tiene una nota de crédito de **anulación (`01`) aceptada**.\n- Si el comprobante tiene **descuentos, cargos o anticipos**, la nota se emite desde el sistema web (que reparte esos importes en las líneas): responde `409`.\n- Las líneas parciales solo admiten operaciones onerosas (gravado `10`, exonerado `20`, inafecto `30`, exportación `40`) sin ISC ni ICBPER; para líneas gratuitas o con esos tributos emite la nota total.\n- Un producto vendido con **series o lotes** solo admite la cantidad completa de su línea.\n- La nota usa el cliente, la moneda y el tipo de cambio del comprobante y queda en estado `01` (o `05` si se envió y SUNAT la aceptó). Si no se envía al emitir, envíala con **Enviar comprobante a SUNAT** (`documents/send`, con su `external_id`).\n- Un vendedor solo emite notas sobre sus comprobantes (`403` en los de otro vendedor).\n- Sin `items` la nota repite todas las líneas del comprobante con sus importes: para intereses o aumentos envía `items` con el importe a cobrar (`unit_price` con IGV).\n\n**Errores:**\n- `403` si el comprobante es de otro vendedor.\n- `404` si el comprobante no existe.\n- `409` si el comprobante no está aceptado (`05`), es una nota, ya fue anulado con una nota de crédito `01` aceptada, tiene descuentos/cargos/anticipos o falta el certificado digital.\n- `422` `{success: false, message}` si falta el motivo, el tipo no existe o es `13` (penalidades), la serie no corresponde, la fecha no es válida o una línea no es del comprobante.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Intereses",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Intereses",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1534,
                        "number": "FD01-3",
                        "document_type_id": "08",
                        "state_type_id": "01",
                        "state_type_description": "Registrado",
                        "external_id": "0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                        "filename": "20123456789-08-FD01-3",
                        "hash": "Wc1p8mB2tE7zK0yQ4nR6vS3aD5f=",
                        "date_of_issue": "2026-11-07",
                        "currency_type_id": "PEN",
                        "total": 5.9,
                        "links": {
                          "xml": "https://empresa.dominio/downloads/document/xml/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                          "pdf": "https://empresa.dominio/downloads/document/pdf/0f3e2a77-8d1b-4b0e-b1c8-5d2f6a9e3c44",
                          "cdr": ""
                        },
                        "affected_document": {
                          "id": 1520,
                          "number": "F001-310",
                          "external_id": "9b1c6c1e-5e63-4d7c-9a51-7d3c2b1f0a11"
                        },
                        "note_type": "01",
                        "response": []
                      },
                      "message": "Nota de débito FD01-3 registrada."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "No aceptado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No aceptado",
                    "value": {
                      "success": false,
                      "message": "El comprobante fue enviado a SUNAT y espera su respuesta: emite la nota cuando esté aceptado."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Penalidad",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Penalidad",
                    "value": {
                      "success": false,
                      "message": "La nota de débito tipo 13 (penalidades) no se emite por la API: emítela desde el sistema web."
                    }
                  },
                  "e2": {
                    "summary": "Sin motivo",
                    "value": {
                      "success": false,
                      "message": "Indica el motivo o sustento de la nota (description)."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Emitir nota de débito",
                  "value": {
                    "note_type": "01",
                    "description": "Intereses por pago fuera de plazo",
                    "items": [
                      {
                        "line_id": "1",
                        "quantity": 1,
                        "unit_price": 5.9
                      }
                    ],
                    "actions": {
                      "send_xml_signed": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/{summary_id}": {
      "get": {
        "tags": [
          "Resúmenes y anulación de boletas"
        ],
        "summary": "Ver resumen diario",
        "operationId": "VerResumenDiario",
        "description": "Devuelve un resumen diario con su estado, la respuesta de SUNAT y los comprobantes que incluye.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `summary_id` | integer | Sí | Id interno del resumen (`data[].id` del listado). |\n\n**Campos del detalle (además de los del listado):**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `response` | objeto o null | Última respuesta de SUNAT: `code` (`0` = aceptado), `description` y `notes` (observaciones). `null` si aún no hay respuesta. |\n| `documents[]` | array | Comprobantes incluidos: `id`, `external_id`, `document_type_id`, `series`, `number`, `number_full`, `date_of_issue`, `customer_number`, `customer_name`, `currency_type_id`, `total`, `state_type_id` (estado **actual** del comprobante), `state_type_description` y `description` (en una baja, el motivo). |\n\nEstados (`state_type_id`): `01` registrado, `03` enviado (esperando respuesta: falta consultar el ticket), `05` aceptado, `09` rechazado. `pending_ticket: true` indica que el envío está en `03`.\n\n**Errores:**\n- `404` si no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 12,
                        "external_id": "a65c9dcc-477e-4b3f-884a-971c56b3d923",
                        "identifier": "RC-20261107-1",
                        "date_of_issue": "2026-11-07",
                        "date_of_reference": "2026-11-06",
                        "soap_type_id": "02",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "ticket": "1793296089424",
                        "documents_count": 2,
                        "pending_ticket": false,
                        "links": {
                          "xml": "https://empresa.dominio/downloads/summary/xml/a65c9dcc-477e-4b3f-884a-971c56b3d923",
                          "cdr": "https://empresa.dominio/downloads/summary/cdr/a65c9dcc-477e-4b3f-884a-971c56b3d923"
                        },
                        "summary_status_type_id": "1",
                        "summary_status_type_description": "Adicionar",
                        "unknown_error_status_response": false,
                        "manually_regularized": false,
                        "created_at": "2026-11-07 08:30:12",
                        "updated_at": "2026-11-07 08:31:02",
                        "response": {
                          "code": "0",
                          "description": "El Resumen diario RC-20261107-1, ha sido aceptado",
                          "notes": []
                        },
                        "documents": [
                          {
                            "id": 3051,
                            "external_id": "0c4b1e7a-55d2-4c8e-9f1a-2b3c4d5e6f70",
                            "document_type_id": "03",
                            "series": "B001",
                            "number": 1520,
                            "number_full": "B001-1520",
                            "date_of_issue": "2026-11-06",
                            "customer_number": "45879632",
                            "customer_name": "ANA TORRES",
                            "currency_type_id": "PEN",
                            "total": 59.0,
                            "state_type_id": "05",
                            "state_type_description": "Aceptado",
                            "description": null
                          },
                          {
                            "id": 3052,
                            "external_id": "0c4b1e7a-55d2-4c8e-9f1a-2b3c4d5e6f70",
                            "document_type_id": "03",
                            "series": "B001",
                            "number": 1521,
                            "number_full": "B001-1521",
                            "date_of_issue": "2026-11-06",
                            "customer_number": "-",
                            "customer_name": "CLIENTES VARIOS",
                            "currency_type_id": "PEN",
                            "total": 12.5,
                            "state_type_id": "05",
                            "state_type_description": "Aceptado",
                            "description": null
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "summary_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/voided/{voided_id}": {
      "get": {
        "tags": [
          "Anulación de facturas"
        ],
        "summary": "Ver comunicación de baja",
        "operationId": "VerComunicacionBaja",
        "description": "Devuelve una comunicación de baja con su estado, la respuesta de SUNAT y los comprobantes que anula (con su motivo).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `voided_id` | integer | Sí | Id interno de la baja (`data[].id` del listado). |\n\n**Campos del detalle (además de los del listado):**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `response` | objeto o null | Última respuesta de SUNAT: `code` (`0` = aceptado), `description` y `notes` (observaciones). `null` si aún no hay respuesta. |\n| `documents[]` | array | Comprobantes incluidos: `id`, `external_id`, `document_type_id`, `series`, `number`, `number_full`, `date_of_issue`, `customer_number`, `customer_name`, `currency_type_id`, `total`, `state_type_id` (estado **actual** del comprobante), `state_type_description` y `description` (en una baja, el motivo). |\n\nEstados (`state_type_id`): `01` registrado, `03` enviado (esperando respuesta: falta consultar el ticket), `05` aceptado, `09` rechazado. `pending_ticket: true` indica que el envío está en `03`.\n\n**Errores:**\n- `404` si no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 4,
                        "external_id": "7d3e9f10-2a4b-4c6d-8e0f-1a2b3c4d5e6f",
                        "identifier": "RA-20261107-1",
                        "date_of_issue": "2026-11-07",
                        "date_of_reference": "2026-11-06",
                        "soap_type_id": "02",
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "ticket": "1793296089424",
                        "documents_count": 1,
                        "pending_ticket": false,
                        "links": {
                          "xml": "https://empresa.dominio/downloads/voided/xml/7d3e9f10-2a4b-4c6d-8e0f-1a2b3c4d5e6f",
                          "cdr": "https://empresa.dominio/downloads/voided/cdr/7d3e9f10-2a4b-4c6d-8e0f-1a2b3c4d5e6f"
                        },
                        "created_at": "2026-11-07 08:30:12",
                        "updated_at": "2026-11-07 08:31:02",
                        "response": {
                          "code": "0",
                          "description": "La Comunicacion de baja RA-20261107-1, ha sido aceptada",
                          "notes": []
                        },
                        "documents": [
                          {
                            "id": 2988,
                            "external_id": "0c4b1e7a-55d2-4c8e-9f1a-2b3c4d5e6f70",
                            "document_type_id": "01",
                            "series": "F001",
                            "number": 845,
                            "number_full": "F001-845",
                            "date_of_issue": "2026-11-06",
                            "customer_number": "20456789123",
                            "customer_name": "SERVICIOS GENERALES S.A.C.",
                            "currency_type_id": "PEN",
                            "total": 1180.0,
                            "state_type_id": "11",
                            "state_type_description": "Anulado",
                            "description": "ERROR EN EL RUC DEL CLIENTE"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "voided_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/purchase-settlements": {
      "post": {
        "tags": [
          "Liquidaciones de compra"
        ],
        "summary": "Emitir liquidación de compra",
        "operationId": "EmitirLiquidacionCompra",
        "description": "Emite una **liquidación de compra** (`04`): el comprobante que la empresa emite al comprar a personas naturales sin RUC (productores, recolectores, etc.). Lo firma, genera el PDF, lo envía por correo si se pide y a SUNAT.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Se emite en el establecimiento del usuario del token.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Respuesta `{success, data: {number, filename, external_id, number_to_letter, hash}, links: {xml, pdf, cdr}, response}`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `serie_documento` | string | Sí | Serie de liquidación (`L001`). |\n| `numero_documento` | string / integer | Sí | Correlativo. Envía `\"#\"` para que la plataforma asigne el siguiente número de la serie (recomendado). |\n| `fecha_de_emision / hora_de_emision` | date / string | Sí | `YYYY-MM-DD` / `HH:MM:SS`. |\n| `codigo_tipo_operacion` | string | Sí | Catálogo SUNAT 51 (`0501` compra interna). |\n| `codigo_tipo_documento` | string | Sí | `04`. |\n| `codigo_tipo_moneda / factor_tipo_de_cambio` | string / numeric | Sí / No | `PEN`/`USD`; tipo de cambio (por defecto 1). |\n| `datos_del_proveedor_o_receptor` | object | Sí | Vendedor (persona natural, normalmente DNI `1`): mismas claves que el cliente de un comprobante. |\n| `datos_de_la_operacion` | object | Sí | Lugar de la operación: `{codigo_pais, ubigeo, direccion, codigo_tipo_direccion}`. |\n| `totales` | object | Sí | `total_anticipos`, `total_operaciones_gravadas`, `total_operaciones_inafectas`, `total_operaciones_exoneradas`, `total_igv`, `total_impuestos`, `total_valor`, `subtotal_compra`, `total_compra`. |\n| `items` | array | Sí | Líneas: `codigo_interno`, `descripcion`, `unidad_de_medida` (obligatorios), `codigo_tipo_item`, `codigo_producto_sunat`, `codigo_producto_gsl`, `cantidad`, `valor_unitario`, `codigo_tipo_precio`, `precio_unitario`, `codigo_tipo_afectacion_igv`, `total_base_igv`, `porcentaje_igv`, `total_igv`, `total_impuestos`, `total_valor_item`, `total_item` y, si hay retención del impuesto a la renta, `codigo_tipo_afectacion_igv_impuesto_renta`, `porcentaje_retencion_renta`, `monto_retencion_renta`. |\n| `anticipos / relacionados` | array | No | `[{numero, codigo_tipo_documento, monto}]`. |\n| `leyendas` | array | No | `[{codigo, valor}]`. |\n| `observaciones` | string | No | Observaciones. |\n| `acciones` | object | No | `{enviar_email, enviar_xml_firmado, formato_pdf}`. |\n\n**Reglas:** usa productos ya registrados (`codigo_interno` existente); un código nuevo puede ser rechazado. Si no se envió a SUNAT, `links.cdr` llega `\"\"` y `response` como `[]`.\n\n**Errores:** `400` `{success: false, message}` si la serie, el establecimiento o un dato no supera la validación previa (*La serie ingresada R001, es incorrecta.*, *El código ingresado del establecimiento es incorrecto.*); `500` ante errores de SUNAT.\n\n**`codigo_tipo_direccion`** (catálogo de tipos de dirección): `01` punto de venta, `02` producción, `03` extracción, `04` explotación, `05` otros. Un código que no exista responde 400.",
        "responses": {
          "200": {
            "description": "Emitida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Emitida",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "L001-8",
                        "filename": "20123456789-04-L001-8",
                        "external_id": "c4b7e2a1-6d3f-4e8a-9b10-5f4e3d2c1b0a",
                        "number_to_letter": "CIEN CON 00/100",
                        "hash": "Qm9xY2FzaGhhc2gxMjM0NTY3OA="
                      },
                      "links": {
                        "xml": "https://empresa.dominio/downloads/purchaseSettlement/xml/c4b7e2a1-6d3f-4e8a-9b10-5f4e3d2c1b0a",
                        "pdf": "https://empresa.dominio/downloads/purchaseSettlement/pdf/c4b7e2a1-6d3f-4e8a-9b10-5f4e3d2c1b0a",
                        "cdr": "https://empresa.dominio/downloads/purchaseSettlement/cdr/c4b7e2a1-6d3f-4e8a-9b10-5f4e3d2c1b0a"
                      },
                      "response": {
                        "code": "0",
                        "description": "La Liquidacion de compra numero L001-8, ha sido aceptada",
                        "notes": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Serie",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Serie",
                    "value": {
                      "success": false,
                      "message": "La serie ingresada L009, es incorrecta."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Emitir liquidación de compra",
                  "value": {
                    "serie_documento": "L001",
                    "numero_documento": "#",
                    "fecha_de_emision": "2026-11-07",
                    "hora_de_emision": "10:11:11",
                    "codigo_tipo_operacion": "0501",
                    "codigo_tipo_documento": "04",
                    "codigo_tipo_moneda": "PEN",
                    "factor_tipo_de_cambio": 1,
                    "datos_del_proveedor_o_receptor": {
                      "codigo_tipo_documento_identidad": "1",
                      "numero_documento": "45678912",
                      "apellidos_y_nombres_o_razon_social": "JUAN PEREZ QUISPE",
                      "nombre_comercial": null,
                      "codigo_pais": "PE",
                      "ubigeo": "120101",
                      "direccion": "Jr. Los Andes 123, Huancayo",
                      "correo_electronico": null,
                      "telefono": null,
                      "codigo_tipo_direccion": null
                    },
                    "datos_de_la_operacion": {
                      "codigo_pais": "PE",
                      "ubigeo": "120101",
                      "direccion": "Jr. Los Andes 123, Huancayo",
                      "codigo_tipo_direccion": "01"
                    },
                    "totales": {
                      "total_anticipos": 0,
                      "total_operaciones_gravadas": 0,
                      "total_operaciones_inafectas": 0,
                      "total_operaciones_exoneradas": 100.0,
                      "total_igv": 0,
                      "total_impuestos": 0,
                      "total_valor": 100.0,
                      "subtotal_compra": 100.0,
                      "total_compra": 100.0
                    },
                    "items": [
                      {
                        "codigo_interno": "MP001",
                        "descripcion": "PAPA AMARILLA X KG",
                        "codigo_tipo_item": "01",
                        "codigo_producto_sunat": "50404100",
                        "codigo_producto_gsl": null,
                        "unidad_de_medida": "KGM",
                        "cantidad": 50,
                        "valor_unitario": 2,
                        "codigo_tipo_precio": "01",
                        "precio_unitario": 2,
                        "codigo_tipo_afectacion_igv": "20",
                        "total_base_igv": 100.0,
                        "porcentaje_igv": 18,
                        "total_igv": 0,
                        "total_impuestos": 0,
                        "total_valor_item": 100.0,
                        "total_item": 100.0,
                        "codigo_tipo_afectacion_igv_impuesto_renta": null,
                        "porcentaje_retencion_renta": null,
                        "monto_retencion_renta": null
                      }
                    ],
                    "anticipos": [],
                    "relacionados": [],
                    "leyendas": [],
                    "observaciones": "",
                    "acciones": {
                      "enviar_email": false,
                      "enviar_xml_firmado": true,
                      "formato_pdf": "a4"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatches/records": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Listar guías remitente por página",
        "operationId": "ListarGuiasRemitentePagina",
        "description": "Listado paginado por página de guías de remisión **remitente** (`09`), más recientes primero, con búsqueda por serie o número. Para integraciones se recomienda *Listar guías con cursor*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). **Atención:** este listado no filtra por vendedor.\n\n**Formato de respuesta:** listado **paginado por página** `{data[], links: {first, last, prev, next}, meta: {current_page, last_page, per_page, total, ...}}`. Usa el query param `page` para avanzar.\n\nCada fila trae además indicadores de interfaz (`btn_*`); el ejemplo muestra los campos principales.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 15,
                          "external_id": "3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "group_id": "01",
                          "soap_type_id": "02",
                          "date_of_issue": "2026-11-07",
                          "number": "T001-15",
                          "customer_id": 1,
                          "customer_name": "EMPRESA XYZ S.A.C.",
                          "customer_number": "RUC 20501973522",
                          "sender_name": null,
                          "sender_number": null,
                          "receiver_name": null,
                          "receiver_number": null,
                          "user_id": 5,
                          "user_name": "JUAN PEREZ",
                          "date_of_shipping": "2026-11-07",
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "has_xml": true,
                          "has_pdf": true,
                          "has_cdr": true,
                          "download_external_xml": "https://empresa.dominio/downloads/dispatch/xml/3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "download_external_pdf": "https://empresa.dominio/downloads/dispatch/pdf/3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "download_external_cdr": "https://empresa.dominio/downloads/dispatch/cdr/3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "transfer_reason_type": {
                            "id": "01",
                            "active": 1,
                            "description": "Venta"
                          },
                          "transfer_reason_description": "Venta",
                          "documents": [],
                          "sunat_error_response": null,
                          "created_at": "2026-11-07 10:11:11",
                          "updated_at": "2026-11-07 10:12:00"
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/dispatches/records?page=1",
                        "last": "https://empresa.dominio/api/dispatches/records?page=3",
                        "prev": null,
                        "next": "https://empresa.dominio/api/dispatches/records?page=2"
                      },
                      "meta": {
                        "current_page": 1,
                        "from": 1,
                        "last_page": 3,
                        "path": "https://empresa.dominio/api/dispatches/records",
                        "per_page": 20,
                        "to": 1,
                        "total": 55
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "T001",
            "description": "Serie o número (coincidencia parcial)."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      }
    },
    "/api/dispatches/records-scroll": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Listar guías con cursor",
        "operationId": "ListarGuiasCursor",
        "description": "Listado paginado por cursor de guías remitente (`09`) y transportista (`31`), más recientes primero.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador ve todos los registros; un vendedor solo los que registró él.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\nEn guías `31`, `customer_*` son los datos del destinatario y `sender_*` los del remitente.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 15,
                          "external_id": "3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "document_type_id": "09",
                          "series": "T001",
                          "number": 15,
                          "number_full": "T001-15",
                          "filename": "20123456789-09-T001-15",
                          "date_of_issue": "2026-11-07",
                          "date_of_shipping": "2026-11-07",
                          "transport_mode_type_id": "02",
                          "transfer_reason_type_id": "01",
                          "transfer_reason_description": "Venta",
                          "total_weight": 12.5,
                          "unit_type_id": "KGM",
                          "packages_number": 2,
                          "customer_id": 1,
                          "customer_name": "EMPRESA XYZ S.A.C.",
                          "customer_number": "20501973522",
                          "sender_name": null,
                          "sender_number": null,
                          "state_type_id": "05",
                          "state_type_description": "Aceptado",
                          "has_xml": true,
                          "has_pdf": true,
                          "has_cdr": true,
                          "download_external_pdf": "https://empresa.dominio/downloads/dispatch/pdf/3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "download_external_xml": "https://empresa.dominio/downloads/dispatch/xml/3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "download_external_cdr": "https://empresa.dominio/downloads/dispatch/cdr/3f0e5a52-6c1b-4f0e-9d0a-1c2b3d4e5f60",
                          "sunat_error_response": null,
                          "created_at": "2026-11-07 10:11:11"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJkYXRlX29mX2lzc3VlIjoiMjAyNi0xMS0wNyIsImlkIjoxNX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "09",
            "description": "`09` remitente, `31` transportista. Sin valor: ambas."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "05",
            "description": "Estado."
          },
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "T001",
            "description": "Serie o número (coincidencia parcial)."
          },
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde (requiere `date_end`)."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/dispatches/tables": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Catálogos de guías",
        "operationId": "CatalogosGuias",
        "description": "Catálogos activos para emitir guías: motivos de traslado, modos de transporte, unidades de peso (`KGM`, `TNE`), tipos de documento relacionado, direcciones de partida, transportistas, vehículos y conductores.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\nEquivale a *Catálogos de guías (ruta alternativa)*.",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "success": true,
                      "data": {
                        "transfer_reason_types": [
                          {
                            "id": "01",
                            "description": "Venta"
                          },
                          {
                            "id": "04",
                            "description": "Traslado entre establecimientos de la misma empresa"
                          }
                        ],
                        "transport_mode_types": [
                          {
                            "id": "01",
                            "description": "Transporte público"
                          },
                          {
                            "id": "02",
                            "description": "Transporte privado"
                          }
                        ],
                        "unit_types": [
                          {
                            "id": "KGM",
                            "description": "Kilogramos"
                          },
                          {
                            "id": "TNE",
                            "description": "Toneladas"
                          }
                        ],
                        "related_document_types": [
                          {
                            "id": "01",
                            "description": "Factura"
                          },
                          {
                            "id": "03",
                            "description": "Boleta de venta"
                          }
                        ],
                        "origin_addresses": [
                          {
                            "id": 1,
                            "establishment_id": 1,
                            "establishment_code": "0000",
                            "address": "Av. Los Olivos 100, Lima",
                            "location_id": [
                              "15",
                              "1501",
                              "150101"
                            ],
                            "is_default": true
                          }
                        ],
                        "dispatchers": [
                          {
                            "id": 1,
                            "identity_document_type_id": "6",
                            "number": "20601234567",
                            "name": "TRANSPORTES RAPIDOS S.A.C.",
                            "number_mtc": "1534567CNG",
                            "is_default": true
                          }
                        ],
                        "transports": [
                          {
                            "id": 1,
                            "plate_number": "ABC123",
                            "model": "HILUX",
                            "brand": "TOYOTA",
                            "tuc": null,
                            "is_default": true
                          }
                        ],
                        "drivers": [
                          {
                            "id": 1,
                            "identity_document_type_id": "1",
                            "number": "40000000",
                            "name": "CARLOS RAMOS LUNA",
                            "license": "Q40000000",
                            "telephone": "987654321"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/dispatches/table": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Catálogos de guías (ruta alternativa)",
        "operationId": "CatalogosGuiasRutaAlternativa",
        "description": "Misma respuesta que *Catálogos de guías* (`GET /api/dispatches/tables`); se mantiene por compatibilidad.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "success": true,
                      "data": {
                        "transfer_reason_types": [
                          {
                            "id": "01",
                            "description": "Venta"
                          },
                          {
                            "id": "04",
                            "description": "Traslado entre establecimientos de la misma empresa"
                          }
                        ],
                        "transport_mode_types": [
                          {
                            "id": "01",
                            "description": "Transporte público"
                          },
                          {
                            "id": "02",
                            "description": "Transporte privado"
                          }
                        ],
                        "unit_types": [
                          {
                            "id": "KGM",
                            "description": "Kilogramos"
                          },
                          {
                            "id": "TNE",
                            "description": "Toneladas"
                          }
                        ],
                        "related_document_types": [
                          {
                            "id": "01",
                            "description": "Factura"
                          },
                          {
                            "id": "03",
                            "description": "Boleta de venta"
                          }
                        ],
                        "origin_addresses": [
                          {
                            "id": 1,
                            "establishment_id": 1,
                            "establishment_code": "0000",
                            "address": "Av. Los Olivos 100, Lima",
                            "location_id": [
                              "15",
                              "1501",
                              "150101"
                            ],
                            "is_default": true
                          }
                        ],
                        "dispatchers": [
                          {
                            "id": 1,
                            "identity_document_type_id": "6",
                            "number": "20601234567",
                            "name": "TRANSPORTES RAPIDOS S.A.C.",
                            "number_mtc": "1534567CNG",
                            "is_default": true
                          }
                        ],
                        "transports": [
                          {
                            "id": 1,
                            "plate_number": "ABC123",
                            "model": "HILUX",
                            "brand": "TOYOTA",
                            "tuc": null,
                            "is_default": true
                          }
                        ],
                        "drivers": [
                          {
                            "id": 1,
                            "identity_document_type_id": "1",
                            "number": "40000000",
                            "name": "CARLOS RAMOS LUNA",
                            "license": "Q40000000",
                            "telephone": "987654321"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/dispatches/tables-legacy": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Catálogos de guías completos (formato anterior)",
        "operationId": "CatalogosGuiasCompletosFormatoAnterior",
        "description": "Catálogos de guías en el formato anterior: establecimientos, direcciones de partida, modos de transporte, motivos de traslado, unidades, transportistas, vehículos y conductores. Los catálogos de establecimientos, modos, motivos y unidades se devuelven con todas sus columnas. Para integraciones nuevas usa *Catálogos de guías*.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "establishments": [
                        {
                          "id": 1,
                          "description": "Oficina Principal",
                          "country_id": "PE",
                          "department_id": "15",
                          "province_id": "1501",
                          "district_id": "150101",
                          "address": "Av. Los Olivos 100, Lima",
                          "email": "ventas@miempresa.pe",
                          "telephone": "014445566",
                          "code": "0000"
                        }
                      ],
                      "origin_addresses": [
                        {
                          "id": 1,
                          "establishment_id": 1,
                          "establishment_code": "0000",
                          "address": "Av. Los Olivos 100, Lima",
                          "location_id": [
                            "15",
                            "1501",
                            "150101"
                          ],
                          "is_default": 1,
                          "is_active": 1
                        }
                      ],
                      "transportModeTypes": [
                        {
                          "id": "01",
                          "active": 1,
                          "description": "Transporte público"
                        },
                        {
                          "id": "02",
                          "active": 1,
                          "description": "Transporte privado"
                        }
                      ],
                      "transferReasonTypes": [
                        {
                          "id": "01",
                          "active": 1,
                          "description": "Venta"
                        }
                      ],
                      "unitTypes": [
                        {
                          "id": "KGM",
                          "active": 1,
                          "symbol": null,
                          "description": "Kilogramos"
                        }
                      ],
                      "dispatchers": [
                        {
                          "id": 1,
                          "identity_document_type_id": "6",
                          "number": "20601234567",
                          "name": "TRANSPORTES RAPIDOS S.A.C.",
                          "number_mtc": "1534567CNG",
                          "is_default": 1
                        }
                      ],
                      "transports": [
                        {
                          "id": 1,
                          "plate_number": "ABC123",
                          "model": "HILUX",
                          "brand": "TOYOTA",
                          "is_default": 1,
                          "tuc": null
                        }
                      ],
                      "drivers": [
                        {
                          "id": 1,
                          "identity_document_type_id": "1",
                          "number": "40000000",
                          "name": "CARLOS RAMOS LUNA",
                          "license": "Q40000000",
                          "telephone": "987654321"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/dispatches/table-legacy": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Catálogos de guías completos (ruta alternativa)",
        "operationId": "CatalogosGuiasCompletosRutaAlternativa",
        "description": "Misma respuesta que *Catálogos de guías completos (formato anterior)*; se mantiene por compatibilidad.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "establishments": [
                        {
                          "id": 1,
                          "description": "Oficina Principal",
                          "country_id": "PE",
                          "department_id": "15",
                          "province_id": "1501",
                          "district_id": "150101",
                          "address": "Av. Los Olivos 100, Lima",
                          "email": "ventas@miempresa.pe",
                          "telephone": "014445566",
                          "code": "0000"
                        }
                      ],
                      "origin_addresses": [
                        {
                          "id": 1,
                          "establishment_id": 1,
                          "establishment_code": "0000",
                          "address": "Av. Los Olivos 100, Lima",
                          "location_id": [
                            "15",
                            "1501",
                            "150101"
                          ],
                          "is_default": 1,
                          "is_active": 1
                        }
                      ],
                      "transportModeTypes": [
                        {
                          "id": "01",
                          "active": 1,
                          "description": "Transporte público"
                        },
                        {
                          "id": "02",
                          "active": 1,
                          "description": "Transporte privado"
                        }
                      ],
                      "transferReasonTypes": [
                        {
                          "id": "01",
                          "active": 1,
                          "description": "Venta"
                        }
                      ],
                      "unitTypes": [
                        {
                          "id": "KGM",
                          "active": 1,
                          "symbol": null,
                          "description": "Kilogramos"
                        }
                      ],
                      "dispatchers": [
                        {
                          "id": 1,
                          "identity_document_type_id": "6",
                          "number": "20601234567",
                          "name": "TRANSPORTES RAPIDOS S.A.C.",
                          "number_mtc": "1534567CNG",
                          "is_default": 1
                        }
                      ],
                      "transports": [
                        {
                          "id": 1,
                          "plate_number": "ABC123",
                          "model": "HILUX",
                          "brand": "TOYOTA",
                          "is_default": 1,
                          "tuc": null
                        }
                      ],
                      "drivers": [
                        {
                          "id": 1,
                          "identity_document_type_id": "1",
                          "number": "40000000",
                          "name": "CARLOS RAMOS LUNA",
                          "license": "Q40000000",
                          "telephone": "987654321"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/dispatch/find/{dispatch_id}": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Ver guía de remisión",
        "operationId": "VerGuiaRemision",
        "description": "Devuelve una guía con sus datos de impresión: destinatario, motivo, modo, peso, direcciones de partida y llegada, conductor, transportista, líneas, observaciones, QR de SUNAT y hash.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador ve todos los registros; un vendedor solo los que registró él. Si la guía es de otro vendedor responde `404`.\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`.\n\n**Errores:** `404` `{success: false, message}`.",
        "responses": {
          "200": {
            "description": "Guía",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guía",
                    "value": {
                      "data": {
                        "series": "T001",
                        "number": 15,
                        "document_type_id": "09",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:11:11",
                        "date_of_shipping": "2026-11-07",
                        "customer_name": "EMPRESA XYZ S.A.C.",
                        "customer_number": "20501973522",
                        "customer_address": "Av. 2 de Mayo 123, Lima, Lima, Lima",
                        "department_id": "15",
                        "province_id": "1501",
                        "district_id": "150101",
                        "transfer_reason_type_id": "01",
                        "transfer_reason_description": "Venta",
                        "transport_mode_type_id": "02",
                        "unit_type_id": "KGM",
                        "total_weight": 12.5,
                        "packages_number": 2,
                        "container_number": null,
                        "origin": {
                          "country_id": "PE",
                          "location_id": "150101",
                          "address": "Av. Los Olivos 100, Lima",
                          "code": "0000"
                        },
                        "delivery": {
                          "country_id": "PE",
                          "location_id": "150101",
                          "address": "Av. 2 de Mayo 123, Lima",
                          "code": "0000"
                        },
                        "license_plate": "ABC123",
                        "driver": {
                          "identity_document_type_id": "1",
                          "number": "40000000",
                          "name": "CARLOS RAMOS LUNA",
                          "license": "Q40000000",
                          "telephone": "987654321"
                        },
                        "dispatcher": null,
                        "items": [
                          {
                            "quantity": 24.0,
                            "unit_type_id": "NIU",
                            "description": "GASEOSA 500ML"
                          }
                        ],
                        "observations": "Traslado por venta F001-1520",
                        "terms_condition": null,
                        "legends": null,
                        "qr_url": "https://e-factura.sunat.gob.pe/v1/contribuyente/gre/comprobantes/descargaqr?hashqr=...",
                        "hash": "YWJjMTIzaGFzaA="
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No encontrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No encontrada",
                    "value": {
                      "success": false,
                      "message": "No se encontró la guía de remisión solicitada."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "dispatch_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/document/series-dispatch": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Series de guías",
        "operationId": "SeriesGuias",
        "description": "Series de guía de remisión remitente (`09`) y transportista (`31`) disponibles para el usuario.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura.",
        "responses": {
          "200": {
            "description": "Series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Series",
                    "value": [
                      {
                        "id": 5,
                        "document_type_id": "09",
                        "number": "T001",
                        "is_default": true,
                        "establishment_id": 1
                      },
                      {
                        "id": 6,
                        "document_type_id": "31",
                        "number": "V001",
                        "is_default": false,
                        "establishment_id": 1
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document/get-data/{document_id}": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Datos de un comprobante para su guía",
        "operationId": "DatosComprobanteSuGuia",
        "description": "Devuelve los datos de un comprobante para armar su guía de remisión: establecimiento, cliente con sus direcciones, documento relacionado (listo para `documento_relacionado`) y líneas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. `items` son las líneas del comprobante con todas sus columnas.\n\n**Errores:** HTTP 200 con `{success: false, message: \"No éxiste documento\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Datos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos",
                    "value": {
                      "success": true,
                      "data": {
                        "document": {
                          "establishment_id": 1,
                          "customer_id": 1,
                          "document_related": {
                            "documento": {
                              "id": "01",
                              "descripcion": "Factura Electrónica"
                            },
                            "document_type_id": "01",
                            "serie": "F001",
                            "numero": "F001-1520",
                            "empresa": "MI EMPRESA S.A.C.",
                            "ruc": "20123456789"
                          }
                        },
                        "items": [
                          {
                            "id": 3001,
                            "document_id": 1520,
                            "item_id": 120,
                            "item": {
                              "description": "GASEOSA 500ML",
                              "internal_id": "P0121",
                              "unit_type_id": "NIU"
                            },
                            "quantity": "2.0000",
                            "unit_value": "50.000000",
                            "unit_price": "59.000000",
                            "affectation_igv_type_id": "10",
                            "total_igv": "18.00",
                            "total_value": "100.00",
                            "total": "118.00"
                          }
                        ],
                        "customer": {
                          "id": 1,
                          "description": "20501973522 - EMPRESA XYZ S.A.C.",
                          "name": "EMPRESA XYZ S.A.C.",
                          "number": "20501973522",
                          "identity_document_type_id": "6",
                          "identity_document_type_code": "6",
                          "identity_document_type_description": "RUC",
                          "address": "Av. 2 de Mayo 123, Lima",
                          "telephone": "014271148",
                          "country_id": "PE",
                          "district_id": "150101",
                          "email": "facturacion@xyz.com.pe",
                          "selected": false,
                          "addresses": [
                            {
                              "id": 4,
                              "location_id": [
                                "15",
                                "1501",
                                "150101"
                              ],
                              "address": "Jr. Ica 450, Lima",
                              "code": "0001",
                              "has_consigned": false
                            }
                          ]
                        }
                      },
                      "message": "Documento encontrado con éxito"
                    }
                  },
                  "e2": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "No éxiste documento"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/dispatch-addresses/tables": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Ubigeos para direcciones",
        "operationId": "UbigeosDirecciones",
        "description": "Árbol de ubigeos (departamento → provincia → distrito) para elegir `location_id` al guardar direcciones de partida o llegada.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Objeto `{locations: [...]}`.",
        "responses": {
          "200": {
            "description": "Ubigeos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ubigeos",
                    "value": {
                      "locations": [
                        {
                          "value": "15",
                          "label": "LIMA",
                          "children": [
                            {
                              "value": "1501",
                              "label": "LIMA",
                              "children": [
                                {
                                  "value": "150101",
                                  "label": "LIMA (150101)"
                                },
                                {
                                  "value": "150122",
                                  "label": "MIRAFLORES (150122)"
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/dispatch-addresses/save": {
      "post": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Guardar dirección de una persona",
        "operationId": "GuardarDireccionPersona",
        "description": "Registra o actualiza una dirección (de partida o llegada) de una persona (cliente, proveedor, remitente o destinatario). Sin `id` crea una nueva; con `id` la actualiza.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Respuesta `{success, id}`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | No | Id de la dirección a actualizar. `null` para crear. |\n| `person_id` | integer | Sí | Id de la persona. |\n| `location_id` | array | Sí | `[departamento, provincia, distrito]`, p. ej. `[\"15\", \"1501\", \"150101\"]`. |\n| `department_id / province_id` | string | No | Departamento y provincia. Envíalos explícitamente (iguales a `location_id[0]` y `location_id[1]`) para que se guarden. |\n| `address` | string | Sí | Dirección. |\n| `establishment_code` | string | No | Código de establecimiento anexo SUNAT (`0000`...). |\n| `phone / email` | string | No | Teléfono y correo de contacto. |\n| `main` | boolean | No | Dirección principal. |\n| `has_consigned / consigned_id` | boolean / integer | No | Si la dirección tiene consignado y su id. |\n\n**Errores:** `{success: false, id: 0}` (HTTP 200) si `location_id` no es un arreglo de 3 elementos; `500` si falta `location_id`.",
        "responses": {
          "200": {
            "description": "Guardada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardada",
                    "value": {
                      "success": true,
                      "id": 12
                    }
                  },
                  "e2": {
                    "summary": "Ubigeo inválido",
                    "value": {
                      "success": false,
                      "id": 0
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Guardar dirección de una persona",
                  "value": {
                    "id": null,
                    "person_id": "1",
                    "location_id": [
                      "15",
                      "1501",
                      "150122"
                    ],
                    "department_id": "15",
                    "province_id": "1501",
                    "address": "Av. Larco 345, Miraflores",
                    "establishment_code": "0001",
                    "phone": "014445566",
                    "email": "almacen@xyz.com.pe",
                    "main": false,
                    "has_consigned": false,
                    "consigned_id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/dispatch-addresses/get_by_person/{customer_id}": {
      "get": {
        "tags": [
          "Guías de remisión"
        ],
        "summary": "Direcciones de una persona",
        "operationId": "DireccionesPersona",
        "description": "Direcciones guardadas de una persona, para usarlas como partida o llegada (o como `direccion_remitente_id` / `direccion_destinatario_id` en guías de transportista).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura; `[]` si no tiene direcciones.",
        "responses": {
          "200": {
            "description": "Direcciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Direcciones",
                    "value": [
                      {
                        "id": 12,
                        "location_id": [
                          "15",
                          "1501",
                          "150122"
                        ],
                        "address": "Av. Larco 345, Miraflores",
                        "code": "0001",
                        "has_consigned": false
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/cash/open": {
      "post": {
        "tags": [
          "Caja"
        ],
        "summary": "Aperturar caja",
        "operationId": "AperturarCaja",
        "description": "Apertura una caja para el usuario (o edita una caja abierta si envías `id`). Es el endpoint recomendado para iniciar el turno.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Devuelve `data.cash_id`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `beginning_balance` | numeric | Sí | Saldo inicial en soles (efectivo en el cajón al abrir), ≥ 0. |\n| `beginning_balance_usd` | numeric | No | Saldo inicial en dólares, ≥ 0. Si no se envía se conserva el actual (o `0` en una caja nueva). |\n| `user_id` | integer | No | Usuario dueño de la caja. Vacío o `0` = el usuario autenticado. |\n| `reference_number` | string | No | Referencia libre de la caja (p. ej. `CAJA-0004`, número de turno). |\n| `id` | integer | No | Solo para **editar** una caja abierta (saldo inicial, referencia o usuario). Omitido o `null` = apertura. |\n\n**Reglas:**\n- Apertura: si el usuario ya tiene una caja abierta **no se crea otra ni se modifica**: responde `success: true` con el id de la caja abierta y el mensaje *La caja ya se encontraba aperturada.*\n- La fecha y hora de apertura las fija el servidor; el saldo inicial se registra como el primer movimiento de efectivo de la caja.\n- Edición (`id`): solo cajas abiertas; no se puede asignar la caja a un usuario que ya tiene otra abierta.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (p. ej. `beginning_balance` negativo).\n- `200` con `success: false` y `message` si la caja a editar no existe, está cerrada o el usuario destino ya tiene una caja abierta.",
        "responses": {
          "200": {
            "description": "Caja aperturada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja aperturada",
                    "value": {
                      "success": true,
                      "message": "Caja aperturada con éxito",
                      "data": {
                        "cash_id": 4
                      }
                    }
                  },
                  "e2": {
                    "summary": "Ya tenía caja abierta",
                    "value": {
                      "success": true,
                      "message": "La caja ya se encontraba aperturada.",
                      "data": {
                        "cash_id": 4
                      }
                    }
                  },
                  "e3": {
                    "summary": "Caja cerrada (edición)",
                    "value": {
                      "success": false,
                      "message": "La caja está cerrada y su arqueo no puede cambiar. Si hubo un error, corrígelo en la caja abierta."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Saldo inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Saldo inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "beginning_balance": [
                          "El campo beginning balance es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Aperturar caja",
                  "value": {
                    "beginning_balance": 100.0,
                    "beginning_balance_usd": 0,
                    "user_id": null,
                    "reference_number": "CAJA-0004",
                    "id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash": {
      "post": {
        "tags": [
          "Caja"
        ],
        "summary": "Registrar o editar caja",
        "operationId": "RegistrarEditarCaja",
        "description": "Mismo comportamiento que **Aperturar caja**: abre una caja (sin `id`) o edita una caja abierta (con `id`). Si no envías `user_id` se usa el usuario autenticado.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Devuelve `data.cash_id`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `beginning_balance` | numeric | Sí | Saldo inicial en soles (efectivo en el cajón al abrir), ≥ 0. |\n| `beginning_balance_usd` | numeric | No | Saldo inicial en dólares, ≥ 0. Si no se envía se conserva el actual (o `0` en una caja nueva). |\n| `user_id` | integer | No | Usuario dueño de la caja. Vacío o `0` = el usuario autenticado. |\n| `reference_number` | string | No | Referencia libre de la caja (p. ej. `CAJA-0004`, número de turno). |\n| `id` | integer | No | Solo para **editar** una caja abierta (saldo inicial, referencia o usuario). Omitido o `null` = apertura. |\n\n**Reglas:**\n- Apertura: si el usuario ya tiene una caja abierta **no se crea otra ni se modifica**: responde `success: true` con el id de la caja abierta y el mensaje *La caja ya se encontraba aperturada.*\n- La fecha y hora de apertura las fija el servidor; el saldo inicial se registra como el primer movimiento de efectivo de la caja.\n- Edición (`id`): solo cajas abiertas; no se puede asignar la caja a un usuario que ya tiene otra abierta.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (p. ej. `beginning_balance` negativo).\n- `200` con `success: false` y `message` si la caja a editar no existe, está cerrada o el usuario destino ya tiene una caja abierta.",
        "responses": {
          "200": {
            "description": "Caja actualizada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja actualizada",
                    "value": {
                      "success": true,
                      "message": "Caja actualizada con éxito",
                      "data": {
                        "cash_id": 4
                      }
                    }
                  },
                  "e2": {
                    "summary": "Usuario con otra caja",
                    "value": {
                      "success": false,
                      "message": "Ese usuario ya tiene una caja aperturada. Ciérrala antes de asignarle otra."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar o editar caja",
                  "value": {
                    "beginning_balance": 150.0,
                    "beginning_balance_usd": 0,
                    "user_id": null,
                    "reference_number": "CAJA-0004",
                    "id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash/opening_cash": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Consultar caja abierta del usuario",
        "operationId": "ConsultarCajaAbiertaUsuario",
        "description": "Devuelve la caja abierta del usuario autenticado, si existe. Úsalo al iniciar la integración para saber si puedes cobrar en efectivo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. `success` es `true` si hay caja abierta y `false` si no (en ambos casos HTTP 200).\n\n`data.cash_id` es el id de la caja (o `null`), `data.cash` el registro completo y `data.description` un texto para mostrar: referencia, fecha de apertura y usuario.",
        "responses": {
          "200": {
            "description": "Con caja abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Con caja abierta",
                    "value": {
                      "success": true,
                      "message": "Verificar si existe caja abierta",
                      "data": {
                        "cash_id": 4,
                        "cash": {
                          "id": 4,
                          "user_id": 5,
                          "establishment_id": 1,
                          "date_opening": "2026-11-07",
                          "time_opening": "08:00:12",
                          "date_closed": null,
                          "time_closed": null,
                          "beginning_balance": "100.0000",
                          "final_balance": "0.0000",
                          "income": "0.0000",
                          "state": 1,
                          "reference_number": "CAJA-0004",
                          "apply_restaurant": 0,
                          "beginning_balance_usd": 0.0,
                          "counted_amount": null,
                          "difference": null,
                          "closing_notes": null
                        },
                        "description": "CAJA-0004 2026-11-07 (JUAN PEREZ)"
                      }
                    }
                  },
                  "e2": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Verificar si existe caja abierta",
                      "data": {
                        "cash_id": null,
                        "cash": null,
                        "description": ""
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/cash/opening_cash_check/{cash_id}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Verificar si una caja sigue abierta",
        "operationId": "VerificarSiCajaSigueAbierta",
        "description": "Indica si la caja indicada (por **id de caja**) sigue abierta.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. `success: true` si la caja existe y está abierta; `false` en otro caso.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |",
        "responses": {
          "200": {
            "description": "Abierta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Abierta",
                    "value": {
                      "success": true,
                      "message": "Verificar si existe caja abierta",
                      "data": {
                        "cash_id": 4,
                        "description": "CAJA-0004 2026-11-07 (JUAN PEREZ)"
                      }
                    }
                  },
                  "e2": {
                    "summary": "Cerrada o inexistente",
                    "value": {
                      "success": false,
                      "message": "Verificar si existe caja abierta",
                      "data": {
                        "cash_id": null,
                        "description": ""
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/cash/check-open-cash": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Verificar si el usuario puede abrir caja",
        "operationId": "VerificarSiUsuarioPuedeAbrirCaja",
        "description": "Comprueba si el usuario autenticado ya tiene una caja abierta, antes de mostrar el formulario de apertura.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. **Atención:** aquí `success: true` significa que **ya hay una caja abierta** (no puede abrir otra) y `success: false` que puede abrir una nueva.",
        "responses": {
          "200": {
            "description": "Ya tiene caja",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya tiene caja",
                    "value": {
                      "success": true,
                      "message": "No puede crear caja chica, por favor cierre caja chica para el usuario definido"
                    }
                  },
                  "e2": {
                    "summary": "Puede abrir",
                    "value": {
                      "success": false,
                      "message": null
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/cash/available-restaurant": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Listar cajas abiertas (restaurante)",
        "operationId": "ListarCajasAbiertasRestaurante",
        "description": "Lista todas las cajas abiertas de la empresa (de cualquier usuario), para que un mozo o cajero elija a qué caja enviar el cobro.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\nCada elemento trae `id` y `description` (referencia, fecha de apertura y usuario).",
        "responses": {
          "200": {
            "description": "Cajas abiertas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cajas abiertas",
                    "value": {
                      "success": true,
                      "message": "Cajas disponibles",
                      "data": [
                        {
                          "id": 4,
                          "description": "CAJA-0004 2026-11-07 (JUAN PEREZ)"
                        },
                        {
                          "id": 6,
                          "description": "BARRA 2026-11-07 (ANA TORRES)"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/cash/records": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Listar cajas del usuario (paginado)",
        "operationId": "ListarCajasUsuarioPaginado",
        "description": "Lista las cajas **del usuario autenticado**, de la más reciente a la más antigua.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado **paginado por página** `{data[], links: {first, last, prev, next}, meta: {current_page, last_page, per_page, total, ...}}`. Usa el query param `page` para avanzar.\n\nLos montos `current_income` y `current_final_balance` se calculan al momento mientras la caja está abierta; en cajas cerradas son los del cierre.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 4,
                          "user_id": 5,
                          "user_name": "JUAN PEREZ",
                          "date_opening": "2026-11-07",
                          "time_opening": "08:00:12",
                          "opening": "2026-11-07 08:00:12",
                          "date_closed": null,
                          "time_closed": null,
                          "closed": null,
                          "beginning_balance": 100.0,
                          "final_balance": 0.0,
                          "income": 0.0,
                          "current_income": 350.5,
                          "current_final_balance": 450.5,
                          "state": true,
                          "state_description": "Aperturada",
                          "reference_number": "CAJA-0004"
                        },
                        {
                          "id": 3,
                          "user_id": 5,
                          "user_name": "JUAN PEREZ",
                          "date_opening": "2026-11-06",
                          "time_opening": "08:05:00",
                          "opening": "2026-11-06 08:05:00",
                          "date_closed": "2026-11-06",
                          "time_closed": "21:40:10",
                          "closed": "2026-11-06 21:40:10",
                          "beginning_balance": 100.0,
                          "final_balance": 812.4,
                          "income": 712.4,
                          "current_income": 712.4,
                          "current_final_balance": 812.4,
                          "state": false,
                          "state_description": "Cerrada",
                          "reference_number": "CAJA-0003"
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/cash/records?page=1",
                        "last": "https://empresa.dominio/api/cash/records?page=1",
                        "prev": null,
                        "next": null
                      },
                      "meta": {
                        "current_page": 1,
                        "from": 1,
                        "last_page": 1,
                        "path": "https://empresa.dominio/api/cash/records",
                        "per_page": 20,
                        "to": 2,
                        "total": 2
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por referencia (coincidencia parcial) o por monto de ingreso exacto."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      }
    },
    "/api/cash/records-scroll": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Listar cajas del usuario (scroll)",
        "operationId": "ListarCajasUsuarioScroll",
        "description": "Lista las cajas **del usuario autenticado** con paginación por cursor, ideal para scroll infinito.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`. **Esta respuesta no incluye `success`**: trae solo `data` y `pagination`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "data": [
                        {
                          "id": 4,
                          "user_id": 5,
                          "user_name": "JUAN PEREZ",
                          "date_opening": "2026-11-07",
                          "time_opening": "08:00:12",
                          "opening": "2026-11-07 08:00:12",
                          "date_closed": null,
                          "time_closed": null,
                          "closed": null,
                          "beginning_balance": 100.0,
                          "final_balance": 0.0,
                          "income": 0.0,
                          "current_income": 350.5,
                          "current_final_balance": 450.5,
                          "state": true,
                          "state_description": "Aperturada",
                          "reference_number": "CAJA-0004"
                        },
                        {
                          "id": 3,
                          "user_id": 5,
                          "user_name": "JUAN PEREZ",
                          "date_opening": "2026-11-06",
                          "time_opening": "08:05:00",
                          "opening": "2026-11-06 08:05:00",
                          "date_closed": "2026-11-06",
                          "time_closed": "21:40:10",
                          "closed": "2026-11-06 21:40:10",
                          "beginning_balance": 100.0,
                          "final_balance": 812.4,
                          "income": 712.4,
                          "current_income": 712.4,
                          "current_final_balance": 812.4,
                          "state": false,
                          "state_description": "Cerrada",
                          "reference_number": "CAJA-0003"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca por referencia o monto de ingreso exacto."
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "true",
            "description": "`true` solo aperturadas, `false` solo cerradas."
          },
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde esta fecha de apertura (`YYYY-MM-DD`). Se aplica solo si también envías `date_end`."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta esta fecha de apertura."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/cash/record/{cash_id}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Ver caja",
        "operationId": "VerCaja",
        "description": "Devuelve los datos de una caja.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Detalle",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Detalle",
                    "value": {
                      "data": {
                        "id": 4,
                        "user_id": 5,
                        "user": "JUAN PEREZ",
                        "date_opening": "2026-11-07",
                        "time_opening": "08:00:12",
                        "opening": "2026-11-07 08:00:12",
                        "date_closed": null,
                        "time_closed": null,
                        "closed": " ",
                        "beginning_balance": "100.0000",
                        "beginning_balance_usd": 0.0,
                        "final_balance": "0.0000",
                        "income": "0.0000",
                        "expense": null,
                        "filename": null,
                        "state_description": "Aperturada",
                        "state": true,
                        "reference_number": "CAJA-0004"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/cash/close/{cash_id}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Cerrar caja",
        "operationId": "CerrarCaja",
        "description": "⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\nCierra la caja: calcula el saldo esperado a partir de los movimientos registrados y, si envías el **arqueo** (efectivo contado), guarda la diferencia (sobrante/faltante).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito `data` trae el resumen del cierre: saldo inicial, ingresos y egresos en efectivo, `expected_cash` (teórico), `other_means` (cobros por otros medios), arqueo y diferencia.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja a cerrar. |\n\n**Query params (opcionales):** `counted_amount` (efectivo contado en soles, ≥ 0), `counted_amount_usd` (contado en dólares) y `closing_notes` (explicación). Sin `counted_amount` la caja se cierra **sin arqueo**.\n\n**Reglas:**\n- Si lo contado difiere del teórico, `closing_notes` es obligatorio.\n- En una caja de restaurante no se puede cerrar mientras haya mesas, pedidos delivery o para llevar pendientes de cobro.\n- Una caja ya cerrada no se vuelve a cerrar.\n\n**Errores:**\n- `200` con `success: false` y `message`: caja no encontrada, ya cerrada, pedidos pendientes, conteo negativo o diferencia sin explicación.",
        "responses": {
          "200": {
            "description": "Cerrada y cuadrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cerrada y cuadrada",
                    "value": {
                      "success": true,
                      "message": "Caja cerrada y cuadrada.",
                      "data": {
                        "cash_id": 4,
                        "reference_number": "CAJA-0004",
                        "user": "JUAN PEREZ",
                        "opening": "2026-11-07 08:00:12",
                        "beginning_balance": 100.0,
                        "cash_income": 350.5,
                        "cash_egress": 20.0,
                        "expected_cash": 430.5,
                        "has_usd": false,
                        "beginning_balance_usd": 0.0,
                        "cash_income_usd": 0.0,
                        "cash_egress_usd": 0.0,
                        "expected_cash_usd": 0.0,
                        "other_means": 180.0,
                        "movements": 18,
                        "counted_amount": 430.5,
                        "difference": 0.0,
                        "difference_label": "Cuadrada",
                        "counted_amount_usd": null,
                        "difference_usd": null,
                        "difference_usd_label": null
                      }
                    }
                  },
                  "e2": {
                    "summary": "Diferencia sin explicar",
                    "value": {
                      "success": false,
                      "message": "Hay una diferencia entre el efectivo contado y el teórico. Explícala antes de cerrar."
                    }
                  },
                  "e3": {
                    "summary": "Mesas pendientes",
                    "value": {
                      "success": false,
                      "message": "No se puede cerrar la caja: hay mesas con consumo pendiente de cobro."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "counted_amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "430.50",
            "description": "Efectivo contado en soles (arqueo)."
          },
          {
            "name": "counted_amount_usd",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Efectivo contado en dólares (si la empresa cobra en dólares)."
          },
          {
            "name": "closing_notes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Explicación de la diferencia entre lo contado y el teórico."
          }
        ]
      }
    },
    "/api/cash/{cash_id}": {
      "delete": {
        "tags": [
          "Caja"
        ],
        "summary": "Eliminar caja",
        "operationId": "EliminarCaja",
        "description": "Elimina una caja que no tiene movimientos (solo el saldo inicial).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |\n\n**Reglas:**\n- No se elimina una caja con cobros o pagos registrados.\n- No se elimina una caja cerrada con arqueo.\n\n**Errores:**\n- `200` con `success: false` y `message` cuando una regla lo impide.\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "message": "Caja eliminada con éxito"
                    }
                  },
                  "e2": {
                    "summary": "Con movimientos",
                    "value": {
                      "success": false,
                      "message": "No puede eliminar la caja: tiene cobros o pagos registrados."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/cash/store-cash-document": {
      "post": {
        "tags": [
          "Caja"
        ],
        "summary": "Asociar venta a la caja abierta",
        "operationId": "AsociarVentaACajaAbierta",
        "description": "Vincula un comprobante o una nota de venta (y sus pagos) a la **caja abierta del usuario**. Úsalo si la venta se registró sin caja o en otro canal y debe figurar en el cierre. Repetir la llamada no duplica la asociación.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí, si no envías `sale_note_id` | Id del comprobante (factura/boleta). |\n| `sale_note_id` | integer | Sí, si no envías `document_id` | Id de la nota de venta. |\n| `quotation_id` | integer | No | Id de la cotización de origen, si aplica. |\n\n**Reglas:**\n- Si la venta es al crédito queda registrada como crédito pendiente de la caja.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (ninguno de los dos ids).\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el usuario no tiene caja abierta o el id no existe.",
        "responses": {
          "200": {
            "description": "Asociada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Asociada",
                    "value": {
                      "success": true,
                      "message": "Venta con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin ids",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin ids",
                    "value": {
                      "success": false,
                      "message": {
                        "document_id": [
                          "El campo document id es obligatorio cuando sale note id es ."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Asociar venta a la caja abierta",
                  "value": {
                    "document_id": "1",
                    "sale_note_id": null,
                    "quotation_id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash/cash_document": {
      "post": {
        "tags": [
          "Caja"
        ],
        "summary": "Asociar venta a la caja abierta (versión anterior)",
        "operationId": "AsociarVentaACajaAbiertaVersionAnterior",
        "description": "Versión anterior de **Asociar venta a la caja abierta**. Mismo cuerpo y respuesta, pero **no valida los campos** y, si se llama dos veces para la misma venta, puede duplicar el registro de sus pagos en la caja. Para integraciones nuevas usa `POST /api/cash/store-cash-document`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí, si no envías `sale_note_id` | Id del comprobante. |\n| `sale_note_id` | integer | Sí, si no envías `document_id` | Id de la nota de venta. |\n| `quotation_id` | integer | No | Id de la cotización de origen. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el usuario no tiene caja abierta o el id no existe.",
        "responses": {
          "200": {
            "description": "Asociada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Asociada",
                    "value": {
                      "success": true,
                      "message": "Venta con éxito"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Asociar venta a la caja abierta (versión anterior)",
                  "value": {
                    "document_id": null,
                    "sale_note_id": "1",
                    "quotation_id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash/restaurant": {
      "post": {
        "tags": [
          "Caja"
        ],
        "summary": "Registrar caja cerrada de restaurante (versión anterior)",
        "operationId": "RegistrarCajaCerradaRestauranteVersionAnterior",
        "description": "Registra de una vez una caja **ya cerrada** con las ventas de un turno de restaurante, identificadas por su `external_id`. La caja queda a nombre del usuario autenticado, marcada como caja de restaurante; el ingreso se calcula como la suma de los **totales** de las ventas enviadas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `beginningBalance` | numeric | Sí | Saldo inicial. |\n| `dateOpening` | date | Sí | Fecha de apertura `YYYY-MM-DD`. |\n| `timeOpening` | string | Sí | Hora de apertura `HH:MM:SS`. |\n| `referenceNumber` | string | No | Referencia de la caja. |\n| `internalsId` | array | Sí | Ventas del turno: `[{external_id, type}]`. `type` = `NOTA` para nota de venta; cualquier otro valor (`BOLETA`, `FACTURA`, vacío) = comprobante. |\n\n**Reglas:**\n- Los campos van en camelCase.\n- No se validan: un `external_id` inexistente produce error `500` y la caja puede quedar creada parcialmente.\n- El cierre no usa el arqueo ni los pagos reales: para turnos nuevos usa **Aperturar caja** y **Cerrar caja**.",
        "responses": {
          "200": {
            "description": "Registrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrada",
                    "value": {
                      "success": true,
                      "message": "Caja creada con éxito"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar caja cerrada de restaurante (versión anterior)",
                  "value": {
                    "beginningBalance": 100.0,
                    "dateOpening": "2026-11-07",
                    "timeOpening": "08:00:00",
                    "referenceNumber": "TURNO-MAÑANA",
                    "internalsId": [
                      {
                        "external_id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
                        "type": "NOTA"
                      },
                      {
                        "external_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
                        "type": "BOLETA"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash/email": {
      "post": {
        "tags": [
          "Caja"
        ],
        "summary": "Enviar reporte de caja por correo",
        "operationId": "EnviarReporteCajaCorreo",
        "description": "Envía por correo el reporte general de la caja en PDF.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `email` | string | Sí | Correo destino. Puedes enviar varios separados por coma. |\n| `cash_id` | integer | Sí | Id de la caja. |\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (falta `email`).\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si `cash_id` no existe.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin correo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin correo",
                    "value": {
                      "success": false,
                      "message": {
                        "email": [
                          "El campo email es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar reporte de caja por correo",
                  "value": {
                    "email": "administracion@empresa.com",
                    "cash_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash/general-report/{cash_id}/{cash_report_format}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Reporte general de caja (PDF)",
        "operationId": "ReporteGeneralCajaPdf",
        "description": "Genera el reporte general de la caja: resumen de ingresos y egresos, ventas y cobros por método de pago.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Requiere token:** envía `Authorization: Bearer <api_token>` como en el resto de la API.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. PDF en línea (`Content-Type: application/pdf`, `Content-Disposition: inline`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |\n| `format` | string | No | `a4` (por defecto) o `ticket` (80 mm). Si lo omites, la URL termina en el id de la caja. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "PDF"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "cash_report_format",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "a4"
          }
        ]
      }
    },
    "/api/cash/product-report/{cash_id}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Reporte de productos vendidos en la caja (PDF)",
        "operationId": "ReporteProductosVendidosCajaPdf",
        "description": "Genera el PDF con los productos vendidos durante la caja (cantidades y montos).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Requiere token:** envía `Authorization: Bearer <api_token>` como en el resto de la API.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. PDF en línea (`application/pdf`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "PDF"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/cash/income-egress-report/{cash_id}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Reporte de ingresos y egresos en efectivo (PDF)",
        "operationId": "ReporteIngresosEgresosEfectivoPdf",
        "description": "Genera el PDF con los ingresos y egresos **en efectivo** de la caja.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Requiere token:** envía `Authorization: Bearer <api_token>` como en el resto de la API.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. PDF en línea (`application/pdf`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "PDF"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/cash/income-summary-report/{cash_id}": {
      "get": {
        "tags": [
          "Caja"
        ],
        "summary": "Resumen de ingresos de la caja (PDF)",
        "operationId": "ResumenIngresosCajaPdf",
        "description": "Genera el PDF con el resumen de ingresos de la caja.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Requiere token:** envía `Authorization: Bearer <api_token>` como en el resto de la API.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. PDF **como descarga** (`Content-Disposition: attachment`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_id` | integer | Sí | Id de la caja. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "PDF"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/document-payments/tables": {
      "get": {
        "tags": [
          "Pagos"
        ],
        "summary": "Catálogos para registrar pagos de comprobantes",
        "operationId": "CatalogosRegistrarPagosComprobantes",
        "description": "Devuelve los métodos de pago, los destinos posibles (cuentas del establecimiento y la caja abierta del usuario, con `id` = `cash`) y los permisos de pago del usuario.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n`permissions.create_payment` / `permissions.delete_payment` indican si el usuario tiene habilitado registrar / eliminar pagos (para mostrar u ocultar opciones).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "payment_method_types": [
                        {
                          "id": "01",
                          "description": "Efectivo"
                        },
                        {
                          "id": "04",
                          "description": "Transferencia"
                        },
                        {
                          "id": "12",
                          "description": "Yape"
                        }
                      ],
                      "payment_destinations": [
                        {
                          "id": 3,
                          "cash_id": null,
                          "type": "bank",
                          "type_label": "Cuenta bancaria",
                          "reconciles_with": null,
                          "logo_url": null,
                          "receives_income": true,
                          "allows_payments": true,
                          "currency_type_id": "PEN",
                          "establishment_id": null,
                          "description": "BCP - PEN - YAPE EMPRESA"
                        },
                        {
                          "id": "cash",
                          "cash_id": 4,
                          "description": "CAJA GENERAL - CAJA-0004"
                        }
                      ],
                      "permissions": {
                        "create_payment": true,
                        "delete_payment": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/document-payments/document/{document_id}": {
      "get": {
        "tags": [
          "Pagos"
        ],
        "summary": "Ver saldo de un comprobante",
        "operationId": "VerSaldoComprobante",
        "description": "Devuelve el total, lo pagado y el saldo pendiente de un comprobante, para validar el monto antes de registrar un pago.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí | Id del comprobante. |\n\n`total_difference` = saldo pendiente (descuenta notas de crédito y retenciones; incluye propinas cobradas). `is_voided` = `true` si está anulado o rechazado.\n\n**Errores:**\n- `500` si el comprobante no existe.",
        "responses": {
          "200": {
            "description": "Saldo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Saldo",
                    "value": {
                      "number_full": "B001-1520",
                      "document_type_id": "03",
                      "total_paid": 30.0,
                      "total": 80.0,
                      "total_difference": 50.0,
                      "currency_type_id": "PEN",
                      "exchange_rate_sale": 1.0,
                      "credit_notes_total": 0.0,
                      "external_id": "5d6e7f80-91a2-4b3c-8d4e-5f6a7b8c9d0e",
                      "payment_condition_id": "02",
                      "is_voided": false
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/document-payments/records/{document_id}": {
      "get": {
        "tags": [
          "Pagos"
        ],
        "summary": "Listar pagos de un comprobante",
        "operationId": "ListarPagosComprobante",
        "description": "Lista los pagos registrados de un comprobante.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`. Sin paginación. `date_of_payment` viene en formato `DD/MM/YYYY`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí | Id del comprobante. |",
        "responses": {
          "200": {
            "description": "Pagos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagos",
                    "value": {
                      "data": [
                        {
                          "id": 57,
                          "date_of_payment": "07/11/2026",
                          "payment_method_type_description": "Yape",
                          "destination_description": "BCP - PEN - YAPE EMPRESA",
                          "reference": "YAPE 4587",
                          "filename": null,
                          "payment": "30.00",
                          "payment_received": null,
                          "payment_received_description": "-"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/document-payments": {
      "post": {
        "tags": [
          "Pagos"
        ],
        "summary": "Registrar pago de comprobante",
        "operationId": "RegistrarPagoComprobante",
        "description": "Registra un pago de un comprobante (factura, boleta). Si el comprobante es una **nota de crédito**, el pago es una devolución (sale dinero del destino).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Devuelve el `id` del pago en la raíz de la respuesta.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí | Id del comprobante (debe existir). |\n| `date_of_payment` | date | Sí | Fecha del pago `YYYY-MM-DD`. |\n| `payment_method_type_id` | string | Sí | Método de pago (`01` efectivo, `04` transferencia...). |\n| `payment_destination_id` | string/integer | Sí | `cash` o id de cuenta bancaria / billetera. |\n| `payment` | numeric | Sí | Monto, mayor que 0. |\n| `reference` | string | No | Número de operación, voucher, etc. |\n| `has_card` | boolean | No | `true` si fue con tarjeta. |\n| `card_brand_id` | string | No | Marca de tarjeta (`01` Visa, `02` Mastercard...). |\n| `id` | integer | No | Id de un pago existente para editarlo. Omitido = pago nuevo. |\n\n**Destino (`payment_destination_id`)**: `cash` = caja abierta del usuario autenticado, o el id de una cuenta bancaria / billetera. Obtén los valores válidos con **Catálogos para registrar pagos de comprobantes** (`payment_destinations`).\n\n**Reglas de caja:** cuando una regla de caja impide la operación responde `422` con `{success: false, message, cash_rule: true}`; el `message` explica la causa y puede mostrarse al usuario tal cual (caja cerrada, sin caja abierta para un pago en efectivo, pago duplicado en menos de 20 segundos, etc.).\n\n**Reglas:**\n- Cuando el saldo del comprobante llega a 0, el crédito pendiente queda saldado en la caja abierta del usuario.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `422` con `cash_rule: true` cuando una regla de caja lo impide.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "message": "Pago registrado con éxito",
                      "id": 57
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "payment": [
                          "El campo payment debe ser mayor que 0."
                        ],
                        "document_id": [
                          "El campo document id seleccionado es inválido."
                        ]
                      }
                    }
                  },
                  "e2": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Abre una caja antes de registrar este pago en efectivo: sin caja abierta no aparecería en ningún cierre.",
                      "cash_rule": true
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar pago de comprobante",
                  "value": {
                    "document_id": "1",
                    "date_of_payment": "2026-11-07",
                    "payment_method_type_id": "04",
                    "payment_destination_id": 3,
                    "payment": 30.0,
                    "reference": "OP-778812",
                    "has_card": false,
                    "card_brand_id": null,
                    "id": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/document-payments/{document_payment_id}": {
      "delete": {
        "tags": [
          "Pagos"
        ],
        "summary": "Eliminar pago de comprobante",
        "operationId": "EliminarPagoComprobante",
        "description": "Elimina un pago de comprobante y su registro en caja/cuenta.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del pago (no del comprobante). |\n\n**Reglas de caja:** cuando una regla de caja impide la operación responde `422` con `{success: false, message, cash_rule: true}`; el `message` explica la causa y puede mostrarse al usuario tal cual (caja cerrada, sin caja abierta para un pago en efectivo, pago duplicado en menos de 20 segundos, etc.).\n\n**Errores:**\n- `422` con `cash_rule: true` si el pago pertenece a una caja ya cerrada.\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "message": "Pago eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Caja cerrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja cerrada",
                    "value": {
                      "success": false,
                      "message": "No se puede eliminar este pago: pertenece a la caja #3, que ya está cerrada y su arqueo no puede cambiar.",
                      "cash_rule": true
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "document_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/received-payments": {
      "post": {
        "tags": [
          "Pagos"
        ],
        "summary": "Registrar pago recibido (Yape / Plin)",
        "operationId": "RegistrarPagoRecibidoYapePlin",
        "description": "Registra en la bandeja un pago capturado de una notificación de Yape / Plin. Es **idempotente** por `dedup_hash`: si el mismo pago se envía de nuevo responde el registro existente con `duplicated: true`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Además de `data` trae `duplicated` (boolean).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `provider` | string | Sí | Proveedor: `YAPE` o `PLIN`. |\n| `amount` | numeric | Sí | Monto recibido, mayor que 0. |\n| `sender_name` | string | No | Nombre del remitente (máx. 255). |\n| `raw_text` | string | Sí | Texto completo de la notificación. |\n| `package_name` | string | Sí | Aplicación que generó la notificación (máx. 255). |\n| `posted_at` | datetime | Sí | Fecha y hora del pago. ISO 8601; si viene en UTC (`Z`) se convierte a la hora local de la empresa. |\n| `device_id` | string | Sí | Identificador del equipo que capturó el pago (máx. 255). |\n| `dedup_hash` | string | Sí | Huella única del pago, para evitar duplicados (máx. 255). |\n\n**Reglas:**\n- El pago nuevo queda en estado `pending` y se notifica en tiempo real a las pantallas conectadas.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "success": true,
                      "message": "Pago registrado con exito",
                      "data": {
                        "id": 12,
                        "provider": "YAPE",
                        "amount": 25.5,
                        "sender_name": "MARIA LOPEZ",
                        "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                        "package_name": "com.bcp.innovacxion.yapeapp",
                        "posted_at": "2026-11-07 13:42:05",
                        "device_id": "caja-1-android",
                        "dedup_hash": "a3f1c9e2b7d4...",
                        "status": "pending",
                        "matched_document_id": null,
                        "matched_document_payment_id": null,
                        "claimed_by_user_id": null,
                        "created_at": "2026-11-07 13:42:06"
                      },
                      "duplicated": false
                    }
                  },
                  "e2": {
                    "summary": "Duplicado",
                    "value": {
                      "success": true,
                      "message": "El pago ya habia sido registrado",
                      "data": {
                        "id": 12,
                        "provider": "YAPE",
                        "amount": 25.5,
                        "sender_name": "MARIA LOPEZ",
                        "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                        "package_name": "com.bcp.innovacxion.yapeapp",
                        "posted_at": "2026-11-07 13:42:05",
                        "device_id": "caja-1-android",
                        "dedup_hash": "a3f1c9e2b7d4...",
                        "status": "pending",
                        "matched_document_id": null,
                        "matched_document_payment_id": null,
                        "claimed_by_user_id": null,
                        "created_at": "2026-11-07 13:42:06"
                      },
                      "duplicated": true
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "amount": [
                          "El campo amount debe ser mayor que 0."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar pago recibido (Yape / Plin)",
                  "value": {
                    "provider": "YAPE",
                    "amount": 25.5,
                    "sender_name": "MARIA LOPEZ",
                    "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                    "package_name": "com.bcp.innovacxion.yapeapp",
                    "posted_at": "2026-11-07T18:42:05Z",
                    "device_id": "caja-1-android",
                    "dedup_hash": "a3f1c9e2b7d4"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/received-payments/records-scroll": {
      "get": {
        "tags": [
          "Pagos"
        ],
        "summary": "Listar bandeja de pagos recibidos",
        "operationId": "ListarBandejaPagosRecibidos",
        "description": "Lista la bandeja de pagos recibidos, del más reciente al más antiguo. La bandeja es **compartida**: todos los usuarios ven los mismos pagos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\nEstados (`status`): `pending` (por asignar), `matched` (asignado a un comprobante), `discarded` (descartado).",
        "responses": {
          "200": {
            "description": "Bandeja",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Bandeja",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 12,
                          "provider": "YAPE",
                          "amount": 25.5,
                          "sender_name": "MARIA LOPEZ",
                          "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                          "package_name": "com.bcp.innovacxion.yapeapp",
                          "posted_at": "2026-11-07 13:42:05",
                          "device_id": "caja-1-android",
                          "dedup_hash": "a3f1c9e2b7d4...",
                          "status": "pending",
                          "matched_document_id": null,
                          "matched_document_payment_id": null,
                          "claimed_by_user_id": null,
                          "created_at": "2026-11-07 13:42:06"
                        },
                        {
                          "id": 12,
                          "provider": "YAPE",
                          "amount": 25.5,
                          "sender_name": "MARIA LOPEZ",
                          "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                          "package_name": "com.bcp.innovacxion.yapeapp",
                          "posted_at": "2026-11-07 13:42:05",
                          "device_id": "caja-1-android",
                          "dedup_hash": "a3f1c9e2b7d4...",
                          "status": "matched",
                          "matched_document_id": 1520,
                          "matched_document_payment_id": 58,
                          "claimed_by_user_id": 5,
                          "created_at": "2026-11-07 13:42:06"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "pending",
            "description": "`pending`, `matched` o `discarded`."
          },
          {
            "name": "provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "YAPE",
            "description": "`YAPE` o `PLIN`."
          },
          {
            "name": "device_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Equipo que capturó el pago."
          },
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca en el remitente o en el texto de la notificación."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/received-payments/{received_payment_id}/claim": {
      "post": {
        "tags": [
          "Pagos"
        ],
        "summary": "Reclamar pago recibido y asignarlo a un comprobante",
        "operationId": "ReclamarPagoRecibidoAsignarloAComprobante",
        "description": "Asigna un pago pendiente a un comprobante: registra el pago del comprobante con el **monto y la fecha** del pago recibido y el método/destino que envías, y el pago pasa a `matched`. Es atómico: si dos usuarios lo reclaman a la vez, solo uno lo consigue.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del pago recibido. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí | Id del comprobante a pagar (debe existir). |\n| `payment_method_type_id` | string | Sí | Método de pago existente (p. ej. el de Yape o Plin de la empresa). |\n| `payment_destination_id` | string/integer | Sí | `cash` o id de cuenta bancaria / billetera. |\n\n**Reglas de caja:** cuando una regla de caja impide la operación responde `422` con `{success: false, message, cash_rule: true}`; el `message` explica la causa y puede mostrarse al usuario tal cual (caja cerrada, sin caja abierta para un pago en efectivo, pago duplicado en menos de 20 segundos, etc.).\n\n**Errores:**\n- `409` si el pago ya fue reclamado o descartado.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `422` con `cash_rule: true` si una regla de caja lo impide.\n- `500` si el id no existe (el mensaje técnico no es apto para mostrar al usuario: valida el id antes).",
        "responses": {
          "200": {
            "description": "Reclamado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Reclamado",
                    "value": {
                      "success": true,
                      "message": "Pago reclamado y asignado al comprobante con exito",
                      "data": {
                        "id": 12,
                        "provider": "YAPE",
                        "amount": 25.5,
                        "sender_name": "MARIA LOPEZ",
                        "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                        "package_name": "com.bcp.innovacxion.yapeapp",
                        "posted_at": "2026-11-07 13:42:05",
                        "device_id": "caja-1-android",
                        "dedup_hash": "a3f1c9e2b7d4...",
                        "status": "matched",
                        "matched_document_id": 1520,
                        "matched_document_payment_id": 58,
                        "claimed_by_user_id": 5,
                        "created_at": "2026-11-07 13:42:06"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya procesado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya procesado",
                    "value": {
                      "success": false,
                      "message": "El pago ya fue procesado por otro dispositivo."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "received_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Reclamar pago recibido y asignarlo a un comprobante",
                  "value": {
                    "document_id": "1",
                    "payment_method_type_id": "12",
                    "payment_destination_id": 3
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/received-payments/{received_payment_id}": {
      "put": {
        "tags": [
          "Pagos"
        ],
        "summary": "Actualizar pago recibido ya reclamado",
        "operationId": "ActualizarPagoRecibidoYaReclamado",
        "description": "Corrige la asignación de un pago ya reclamado (otro comprobante, método o destino). Elimina el pago del comprobante generado antes y registra uno nuevo con los datos enviados.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del pago recibido. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_id` | integer | Sí | Id del comprobante a pagar (debe existir). |\n| `payment_method_type_id` | string | Sí | Método de pago existente (p. ej. el de Yape o Plin de la empresa). |\n| `payment_destination_id` | string/integer | Sí | `cash` o id de cuenta bancaria / billetera. |\n\n**Reglas de caja:** cuando una regla de caja impide la operación responde `422` con `{success: false, message, cash_rule: true}`; el `message` explica la causa y puede mostrarse al usuario tal cual (caja cerrada, sin caja abierta para un pago en efectivo, pago duplicado en menos de 20 segundos, etc.).\n\n**Errores:**\n- `422` si el pago no está en estado `matched`.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `500` si el id no existe (el mensaje técnico no es apto para mostrar al usuario: valida el id antes).",
        "responses": {
          "200": {
            "description": "Actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Actualizado",
                    "value": {
                      "success": true,
                      "message": "Pago actualizado con exito",
                      "data": {
                        "id": 12,
                        "provider": "YAPE",
                        "amount": 25.5,
                        "sender_name": "MARIA LOPEZ",
                        "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                        "package_name": "com.bcp.innovacxion.yapeapp",
                        "posted_at": "2026-11-07 13:42:05",
                        "device_id": "caja-1-android",
                        "dedup_hash": "a3f1c9e2b7d4...",
                        "status": "matched",
                        "matched_document_id": 1520,
                        "matched_document_payment_id": 58,
                        "claimed_by_user_id": 5,
                        "created_at": "2026-11-07 13:42:06"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "No reclamado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No reclamado",
                    "value": {
                      "success": false,
                      "message": "Solo se puede actualizar un pago que ya fue reclamado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "received_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Actualizar pago recibido ya reclamado",
                  "value": {
                    "document_id": "1",
                    "payment_method_type_id": "12",
                    "payment_destination_id": "cash"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/received-payments/{received_payment_id}/discard": {
      "post": {
        "tags": [
          "Pagos"
        ],
        "summary": "Descartar pago recibido",
        "operationId": "DescartarPagoRecibido",
        "description": "Marca un pago pendiente como `discarded` (no se asigna a ningún comprobante). Sin cuerpo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del pago recibido. |\n\n**Errores:**\n- `409` si el pago ya fue reclamado.\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Descartado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Descartado",
                    "value": {
                      "success": true,
                      "message": "Pago descartado con exito",
                      "data": {
                        "id": 12,
                        "provider": "YAPE",
                        "amount": 25.5,
                        "sender_name": "MARIA LOPEZ",
                        "raw_text": "Yape! MARIA LOPEZ te envió un pago por S/ 25.50",
                        "package_name": "com.bcp.innovacxion.yapeapp",
                        "posted_at": "2026-11-07 13:42:05",
                        "device_id": "caja-1-android",
                        "dedup_hash": "a3f1c9e2b7d4...",
                        "status": "discarded",
                        "matched_document_id": null,
                        "matched_document_payment_id": null,
                        "claimed_by_user_id": null,
                        "created_at": "2026-11-07 13:42:06"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya reclamado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya reclamado",
                    "value": {
                      "success": false,
                      "message": "No se puede descartar un pago ya reclamado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "received_payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/inventory/tables": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Catálogos de inventario",
        "operationId": "CatalogosInventario",
        "description": "Devuelve los almacenes (con `is_current` = almacén del establecimiento del usuario), los motivos de ajuste manual (`adjust_reasons`, con `type` `input` u `output`) y si la empresa controla stock (`stock_control`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "success": true,
                      "data": {
                        "warehouses": [
                          {
                            "id": 1,
                            "description": "Almacén - Oficina Principal",
                            "establishment_id": 1,
                            "establishment_description": "Oficina Principal",
                            "is_current": true
                          },
                          {
                            "id": 2,
                            "description": "Almacén - Sucursal Norte",
                            "establishment_id": 2,
                            "establishment_description": "Sucursal Norte",
                            "is_current": false
                          }
                        ],
                        "adjust_reasons": [
                          {
                            "id": "05",
                            "name": "Donación",
                            "type": "input"
                          },
                          {
                            "id": "13",
                            "name": "Robo",
                            "type": "output"
                          }
                        ],
                        "stock_control": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/inventory/transfer": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Trasladar productos entre almacenes",
        "operationId": "TrasladarProductosEntreAlmacenes",
        "description": "Traslada uno o varios productos de un almacén a otro. Todo el traslado se hace en una sola operación: si un producto falla, no se mueve ninguno.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito `data.items` trae el stock resultante en origen y destino de cada producto.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `warehouse_id` | integer | Sí | Almacén de origen. |\n| `warehouse_destination_id` | integer | Sí | Almacén de destino, distinto del origen. |\n| `description` | string | No | Motivo o detalle del traslado (máx. 500). |\n| `items` | array | Sí | `[{item_id, quantity}]`; `quantity` > 0. Al menos un producto. |\n\n**Reglas:**\n- La cantidad no puede superar el stock del almacén de origen.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `200` con `success: false` y `message`: stock insuficiente o producto con lotes/series.",
        "responses": {
          "200": {
            "description": "Trasladado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Trasladado",
                    "value": {
                      "success": true,
                      "data": {
                        "items": [
                          {
                            "item_id": 15,
                            "quantity": 5.0,
                            "origin_stock": 20.0,
                            "destination_stock": 8.0
                          }
                        ]
                      },
                      "message": "Producto trasladado con éxito"
                    }
                  },
                  "e2": {
                    "summary": "Stock insuficiente",
                    "value": {
                      "success": false,
                      "message": "Stock insuficiente para GASEOSA 500 ML (disponible: 3)."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Mismo almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Mismo almacén",
                    "value": {
                      "success": false,
                      "message": {
                        "warehouse_destination_id": [
                          "El almacén de destino debe ser distinto al de origen."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Trasladar productos entre almacenes",
                  "value": {
                    "warehouse_id": "1",
                    "warehouse_destination_id": 2,
                    "description": "Reposición sucursal norte",
                    "items": [
                      {
                        "item_id": "1",
                        "quantity": 5
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/inventory/adjust": {
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Ajustar a stock real",
        "operationId": "AjustarAStockReal",
        "description": "Fija el stock de uno o varios productos al valor contado (inventario físico). Se registra la diferencia como ingreso (si sube) o salida (si baja) en el kardex.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `warehouse_id` | integer | Sí | Almacén. |\n| `inventory_transaction_id` | string | Sí | Motivo del ajuste (de `adjust_reasons`). Si su sentido no coincide con la diferencia se usa el motivo genérico de ajuste por diferencia. |\n| `comments` | string | No | Comentario (máx. 500). |\n| `items` | array | Sí | `[{item_id, system_stock, real_stock}]`. `system_stock` = stock que leíste antes de contar; `real_stock` ≥ 0 = stock contado. |\n\n**Reglas:**\n- **Control de concurrencia:** si el stock actual de algún producto ya no coincide con `system_stock` no se ajusta nada y responde `success: false`, `code: stock_changed` y `current_stock`; vuelve a leer el stock y confirma.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `200` con `success: false`: `stock_changed` o producto con lotes/series.",
        "responses": {
          "200": {
            "description": "Ajustado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ajustado",
                    "value": {
                      "success": true,
                      "data": {
                        "items": [
                          {
                            "item_id": 15,
                            "previous_stock": 20.0,
                            "new_stock": 18.0,
                            "difference": -2.0
                          }
                        ]
                      },
                      "message": "Stock actualizado con éxito"
                    }
                  },
                  "e2": {
                    "summary": "Stock cambió",
                    "value": {
                      "success": false,
                      "code": "stock_changed",
                      "item_id": 15,
                      "current_stock": 19.0,
                      "message": "El stock cambió desde que abriste el producto. Revisa el valor actual y vuelve a confirmar."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Stock negativo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Stock negativo",
                    "value": {
                      "success": false,
                      "message": {
                        "items.0.real_stock": [
                          "El stock real debe ser mayor o igual a 0."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Ajustar a stock real",
                  "value": {
                    "warehouse_id": "1",
                    "inventory_transaction_id": "13",
                    "comments": "Conteo físico noviembre",
                    "items": [
                      {
                        "item_id": "1",
                        "system_stock": 20,
                        "real_stock": 18
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/inventory/kardex": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Kardex de un producto",
        "operationId": "KardexProducto",
        "description": "Devuelve los movimientos de stock de **un producto** (compras, ventas, notas de venta, pedidos, guías, traslados, devoluciones y ajustes) con el **saldo acumulado** de cada fila. Sin `warehouse_id` un administrador ve todos los almacenes con un saldo conjunto.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador consulta todos los almacenes (o el que indique en `warehouse_id`); un vendedor solo el almacén de **su establecimiento**: si pide otro almacén responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`. Además trae `meta`: `item`, `warehouse` (`null` = todos), `date_start`, `date_end`, `opening_balance` (saldo antes de `date_start`), `page_opening_balance` (saldo antes de la primera fila de la página) y `page_closing_balance` (saldo después de la última).\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Producto. |\n| `warehouse_id` | integer | No | Almacén. Un vendedor solo puede indicar el suyo (por defecto, el suyo). |\n| `date_start` | YYYY-MM-DD | No | Desde (fecha de registro del movimiento). |\n| `date_end` | YYYY-MM-DD | No | Hasta; igual o posterior a `date_start`. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (`limit` de 1 a 100, por defecto 15). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Saldo entre páginas:** el saldo se calcula en el servidor en cada página partiendo del saldo inicial del rango, así que el `balance` de la primera fila de la página 2 continúa exactamente el de la última fila de la página 1 (`page_opening_balance` de una página = `page_closing_balance` de la anterior).\n\n**Campos de cada fila:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del movimiento. Las filas van en el orden en que se registraron. |\n| `date_of_issue` | string | Fecha del documento de origen (`YYYY-MM-DD`). |\n| `registered_at` | string | Fecha y hora en que se registró el movimiento. |\n| `warehouse` | object | Almacén del movimiento `{id, description}`. |\n| `type` | string | Tipo legible: `Compra`, `Venta`, `Nota de venta`, `Anulación Venta`, `Pedido`, `Traslado`, `Devolución`, `Stock Real`, motivo de inventario, etc. |\n| `origin` | object | Documento que generó el movimiento: `type` (`document` comprobante, `sale_note` nota de venta, `purchase` compra, `purchase_settlement` liquidación de compra, `order_note` pedido, `dispatch` guía, `devolution` devolución, `inventory` movimiento de inventario), `id`, `number` (serie-número) y `transfer_id` (si es un traslado, su id en **Traslados**). `id` es `null` si el documento ya no existe. |\n| `related_documents` | array | Documentos relacionados `[{type, number}]` (p. ej. la nota de venta de la que salió la factura). |\n| `quantity` | number | Cantidad registrada (positiva entra, negativa sale). |\n| `input` / `output` | number | Lo que el movimiento **sumó o restó al saldo**. Siempre se cumple `balance = saldo anterior + input - output`. |\n| `balance` | number | Saldo acumulado después de la fila. |\n| `affects_balance` | boolean | `false` cuando el movimiento no cambia el saldo (p. ej. una factura que viene de una nota de venta que ya descontó el stock). |\n| `note` | string o null | Explica por qué la fila no afecta el saldo. |\n\n**Errores:**\n- `403` si un vendedor pide un almacén que no es el de su establecimiento.\n- `422` si falta `item_id`, el producto o el almacén no existen, o las fechas no tienen el formato `YYYY-MM-DD`.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Kardex",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Kardex",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 9101,
                          "date_of_issue": "2026-11-03",
                          "registered_at": "2026-11-03 09:12:40",
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "type": "Compra",
                          "origin": {
                            "type": "purchase",
                            "id": 812,
                            "number": "F001-4520",
                            "transfer_id": null
                          },
                          "related_documents": [],
                          "quantity": 24.0,
                          "input": 24.0,
                          "output": 0,
                          "balance": 30.0,
                          "affects_balance": true,
                          "note": null
                        },
                        {
                          "id": 9115,
                          "date_of_issue": "2026-11-04",
                          "registered_at": "2026-11-04 16:40:02",
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "type": "Nota de venta",
                          "origin": {
                            "type": "sale_note",
                            "id": 3311,
                            "number": "NV01-1532",
                            "transfer_id": null
                          },
                          "related_documents": [],
                          "quantity": -3.0,
                          "input": 0,
                          "output": 3.0,
                          "balance": 27.0,
                          "affects_balance": true,
                          "note": null
                        },
                        {
                          "id": 9120,
                          "date_of_issue": "2026-11-05",
                          "registered_at": "2026-11-05 10:02:11",
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "type": "Venta",
                          "origin": {
                            "type": "document",
                            "id": 20457,
                            "number": "B001-998",
                            "transfer_id": null
                          },
                          "related_documents": [
                            {
                              "type": "sale_note",
                              "number": "NV01-1532"
                            }
                          ],
                          "quantity": -3.0,
                          "input": 0,
                          "output": 0,
                          "balance": 27.0,
                          "affects_balance": false,
                          "note": "Stock descontado en la nota de venta NV01-1532"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      },
                      "meta": {
                        "item": {
                          "id": 15,
                          "internal_id": "P0015",
                          "description": "GASEOSA 500 ML",
                          "unit_type_id": "NIU"
                        },
                        "warehouse": {
                          "id": 3,
                          "description": "Almacén - Tienda Centro"
                        },
                        "date_start": "2026-11-01",
                        "date_end": "2026-11-30",
                        "opening_balance": 6.0,
                        "page_opening_balance": 6.0,
                        "page_closing_balance": 27.0
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Otro almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Otro almacén",
                    "value": {
                      "success": false,
                      "message": "Solo puedes consultar el almacén de tu establecimiento."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Falta el producto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Falta el producto",
                    "value": {
                      "success": false,
                      "message": {
                        "item_id": [
                          "El campo item id es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Producto."
          },
          {
            "name": "warehouse_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Almacén."
          },
          {
            "name": "date_start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde `YYYY-MM-DD`."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta `YYYY-MM-DD`."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "50",
            "description": "Filas por página."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/inventory/stock": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Stock por almacén",
        "operationId": "StockAlmacen",
        "description": "Lista el stock de los productos por almacén: una fila por producto y almacén, con los datos del producto. Es el mismo stock que descuentan las ventas y que suma el kardex.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador consulta todos los almacenes (o el que indique en `warehouse_id`); un vendedor solo el almacén de **su establecimiento**: si pide otro almacén responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `warehouse_id` | integer | No | Almacén. Un vendedor solo puede indicar el suyo (por defecto, el suyo). |\n| `item_id` | integer | No | Un producto. |\n| `search` | string | No | Coincidencia parcial en descripción, código interno o código de barras. |\n| `category_id` | integer | No | Categoría. |\n| `brand_id` | integer | No | Marca. |\n| `stock` | string | No | `positive` (> 0), `zero` (= 0), `negative` (< 0) o `below_min` (por debajo del stock mínimo del producto). |\n| `limit / cursor` | integer / string | No | Paginación por cursor (`limit` de 1 a 100, por defecto 15). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Errores:**\n- `403` si un vendedor pide un almacén que no es el de su establecimiento.\n- `422` si `stock` tiene un valor no permitido o el almacén no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Stock",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Stock",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 640,
                          "item": {
                            "id": 15,
                            "internal_id": "P0015",
                            "description": "GASEOSA 500 ML",
                            "unit_type_id": "NIU",
                            "barcode": "7751234567890",
                            "category": {
                              "id": 2,
                              "name": "BEBIDAS"
                            },
                            "brand": {
                              "id": 4,
                              "name": "COCA COLA"
                            },
                            "stock_min": 5.0,
                            "sale_unit_price": 3.5,
                            "currency_type_id": "PEN",
                            "lots_enabled": false,
                            "series_enabled": false,
                            "active": true
                          },
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "stock": 27.0
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Otro almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Otro almacén",
                    "value": {
                      "success": false,
                      "message": "Solo puedes consultar el almacén de tu establecimiento."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "warehouse_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Almacén."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "gaseosa",
            "description": "Texto a buscar."
          },
          {
            "name": "stock",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "below_min",
            "description": "`positive`, `zero`, `negative` o `below_min`."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/items/{item_id}/stock": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Stock de un producto en todos los almacenes",
        "operationId": "StockProductoTodosAlmacenes",
        "description": "Devuelve el stock de un producto en cada almacén de la empresa (los almacenes donde nunca tuvo movimientos salen con `0` y `has_record: false`) y el total.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Un vendedor solo recibe el almacén de su establecimiento.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` = `{item, total_stock, warehouses[]}`; cada almacén trae `warehouse_id`, `description`, `establishment_id`, `establishment_description`, `is_current` (es el del establecimiento del usuario), `has_record` y `stock`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Producto. |\n\n**Errores:**\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Stock del producto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Stock del producto",
                    "value": {
                      "success": true,
                      "data": {
                        "item": {
                          "id": 15,
                          "internal_id": "P0015",
                          "description": "GASEOSA 500 ML",
                          "unit_type_id": "NIU",
                          "barcode": "7751234567890",
                          "category": {
                            "id": 2,
                            "name": "BEBIDAS"
                          },
                          "brand": {
                            "id": 4,
                            "name": "COCA COLA"
                          },
                          "stock_min": 5.0,
                          "sale_unit_price": 3.5,
                          "currency_type_id": "PEN",
                          "lots_enabled": false,
                          "series_enabled": false,
                          "active": true
                        },
                        "total_stock": 35.0,
                        "warehouses": [
                          {
                            "warehouse_id": 3,
                            "description": "Almacén - Tienda Centro",
                            "establishment_id": 1,
                            "establishment_description": "Tienda Centro",
                            "is_current": true,
                            "has_record": true,
                            "stock": 27.0
                          },
                          {
                            "warehouse_id": 5,
                            "description": "Almacén - Sucursal Norte",
                            "establishment_id": 4,
                            "establishment_description": "Sucursal Norte",
                            "is_current": false,
                            "has_record": true,
                            "stock": 8.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/inventory/transfers": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar traslados",
        "operationId": "ListarTraslados",
        "description": "Lista los traslados entre almacenes, del más reciente al más antiguo. Incluye los registrados con **Trasladar productos entre almacenes** y los de las notas de traslado y guías del sistema.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador ve todos los traslados (o el que indique en `warehouse_id`); un vendedor solo los que salen de o llegan al almacén de **su establecimiento**: si pide otro almacén responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `warehouse_id` | integer | No | Traslados que **salen de o llegan a** ese almacén. |\n| `warehouse_destination_id` | integer | No | Solo los que llegan a ese almacén. |\n| `item_id` | integer | No | Producto. |\n| `document_id` | integer | No | Los productos de una nota de traslado (`document.id`). |\n| `state` | string | No | `active`, `reversed` o `reversal`. |\n| `date_start / date_end` | YYYY-MM-DD | No | Rango por fecha de registro. |\n| `search` | string | No | Descripción o código interno del producto. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (`limit` de 1 a 100, por defecto 15). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada traslado:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del traslado (un producto movido de un almacén a otro). |\n| `date` / `date_of_issue` | string | Fecha y hora de registro / fecha del traslado. |\n| `description` / `observation` | string | Descripción y texto libre ingresado al trasladar. |\n| `state` | string | `active` vigente, `reversed` revertido (eliminado) o `reversal` (es la reversión de otro traslado; `reversal_of` indica cuál). |\n| `item`, `quantity` | object, number | Producto y cantidad. |\n| `warehouse` / `warehouse_destination` | object | Almacén de origen y de destino. |\n| `document` | object o null | Nota de traslado que agrupa varios productos `{id, number, description, dispatch_id}`; `dispatch_id` indica que la generó una guía de remisión. |\n\nEl detalle agrega `reversed_by` (id de la reversión), `series` y `lots` (series y lotes trasladados de ese producto) y `kardex` (los dos movimientos: salida del origen y entrada al destino).\n\n**Errores:**\n- `403` si un vendedor pide un almacén que no es el de su establecimiento.\n- `422` si `state` o las fechas no son válidos.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Traslados",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Traslados",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1207,
                          "date": "2026-11-06 11:20:05",
                          "date_of_issue": "2026-11-06",
                          "description": "Traslado",
                          "observation": "Reposición sucursal norte",
                          "state": "active",
                          "reversal_of": null,
                          "item": {
                            "id": 15,
                            "internal_id": "P0015",
                            "description": "GASEOSA 500 ML",
                            "unit_type_id": "NIU"
                          },
                          "quantity": 5.0,
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "warehouse_destination": {
                            "id": 5,
                            "description": "Almacén - Sucursal Norte"
                          },
                          "document": null
                        },
                        {
                          "id": 1188,
                          "date": "2026-11-06 11:20:05",
                          "date_of_issue": "2026-11-06",
                          "description": "Traslado",
                          "observation": null,
                          "state": "active",
                          "reversal_of": null,
                          "item": {
                            "id": 15,
                            "internal_id": "P0015",
                            "description": "GASEOSA 500 ML",
                            "unit_type_id": "NIU"
                          },
                          "quantity": 5.0,
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "warehouse_destination": {
                            "id": 5,
                            "description": "Almacén - Sucursal Norte"
                          },
                          "document": {
                            "id": 54,
                            "number": "NT01-12",
                            "description": "Envío semanal",
                            "dispatch_id": null
                          }
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "warehouse_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Almacén de origen o destino."
          },
          {
            "name": "item_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Producto."
          },
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "active",
            "description": "`active`, `reversed` o `reversal`."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/inventory/transfers/{transfer_id}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Ver traslado",
        "operationId": "VerTraslado",
        "description": "Devuelve un traslado con sus series o lotes y los movimientos de kardex que generó.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Un vendedor solo ve los traslados que salen de o llegan a su almacén (`403` si no).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `transfer_id` | integer | Sí | Id del traslado. |\n\n**Campos de cada traslado:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del traslado (un producto movido de un almacén a otro). |\n| `date` / `date_of_issue` | string | Fecha y hora de registro / fecha del traslado. |\n| `description` / `observation` | string | Descripción y texto libre ingresado al trasladar. |\n| `state` | string | `active` vigente, `reversed` revertido (eliminado) o `reversal` (es la reversión de otro traslado; `reversal_of` indica cuál). |\n| `item`, `quantity` | object, number | Producto y cantidad. |\n| `warehouse` / `warehouse_destination` | object | Almacén de origen y de destino. |\n| `document` | object o null | Nota de traslado que agrupa varios productos `{id, number, description, dispatch_id}`; `dispatch_id` indica que la generó una guía de remisión. |\n\nEl detalle agrega `reversed_by` (id de la reversión), `series` y `lots` (series y lotes trasladados de ese producto) y `kardex` (los dos movimientos: salida del origen y entrada al destino).\n\n**Errores:**\n- `403` si el traslado no toca el almacén del vendedor.\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Traslado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Traslado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1207,
                        "date": "2026-11-06 11:20:05",
                        "date_of_issue": "2026-11-06",
                        "description": "Traslado",
                        "observation": "Reposición sucursal norte",
                        "state": "active",
                        "reversal_of": null,
                        "item": {
                          "id": 15,
                          "internal_id": "P0015",
                          "description": "GASEOSA 500 ML",
                          "unit_type_id": "NIU"
                        },
                        "quantity": 5.0,
                        "warehouse": {
                          "id": 3,
                          "description": "Almacén - Tienda Centro"
                        },
                        "warehouse_destination": {
                          "id": 5,
                          "description": "Almacén - Sucursal Norte"
                        },
                        "document": null,
                        "reversed_by": null,
                        "series": [],
                        "lots": [],
                        "kardex": [
                          {
                            "id": 9130,
                            "warehouse_id": 3,
                            "quantity": -5.0,
                            "date_of_issue": "2026-11-06"
                          },
                          {
                            "id": 9131,
                            "warehouse_id": 5,
                            "quantity": 5.0,
                            "date_of_issue": "2026-11-06"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro almacén",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transfer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "delete": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Eliminar (revertir) traslado",
        "operationId": "EliminarRevertirTraslado",
        "description": "Revierte un traslado: registra un traslado inverso (del destino al origen) por la misma cantidad, con su propio kardex, y el original queda en estado `reversed`. El stock vuelve a quedar como antes en **ambos** almacenes y el historial se conserva.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Un vendedor solo puede revertir traslados que salen de o llegan a su almacén.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` = `{transfer, reversal}`: el traslado original (ya `reversed`, con `reversed_by`) y la reversión creada.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `transfer_id` | integer | Sí | Id del traslado. |\n\n**Reglas:**\n- Un traslado se revierte una sola vez; la reversión misma no se puede revertir.\n- No se revierten por la API los traslados de productos con **lotes o series**, ni los generados por una **guía de remisión** (se anula la guía).\n- Si la empresa controla stock, el almacén de destino debe tener stock suficiente para devolver la cantidad.\n\n**Errores:**\n- `403` si el traslado no toca el almacén del vendedor.\n- `404` si el registro no existe.\n- `409` si ya fue revertido, es una reversión, tiene lotes/series, viene de una guía o no hay stock en el destino (el `message` lo explica).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Revertido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Revertido",
                    "value": {
                      "success": true,
                      "data": {
                        "transfer": {
                          "id": 1207,
                          "date": "2026-11-06 11:20:05",
                          "date_of_issue": "2026-11-06",
                          "description": "Traslado",
                          "observation": null,
                          "state": "reversed",
                          "reversal_of": null,
                          "item": {
                            "id": 15,
                            "internal_id": "P0015",
                            "description": "GASEOSA 500 ML",
                            "unit_type_id": "NIU"
                          },
                          "quantity": 5.0,
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "warehouse_destination": {
                            "id": 5,
                            "description": "Almacén - Sucursal Norte"
                          },
                          "document": null,
                          "reversed_by": 1215,
                          "series": [],
                          "lots": [],
                          "kardex": [
                            {
                              "id": 9130,
                              "warehouse_id": 3,
                              "quantity": -5.0,
                              "date_of_issue": "2026-11-06"
                            },
                            {
                              "id": 9131,
                              "warehouse_id": 5,
                              "quantity": 5.0,
                              "date_of_issue": "2026-11-06"
                            }
                          ]
                        },
                        "reversal": {
                          "id": 1215,
                          "date": "2026-11-07 09:01:44",
                          "date_of_issue": "2026-11-07",
                          "description": "Reversión de traslado #1207",
                          "observation": null,
                          "state": "reversal",
                          "reversal_of": 1207,
                          "item": {
                            "id": 15,
                            "internal_id": "P0015",
                            "description": "GASEOSA 500 ML",
                            "unit_type_id": "NIU"
                          },
                          "quantity": 5.0,
                          "warehouse": {
                            "id": 5,
                            "description": "Almacén - Sucursal Norte"
                          },
                          "warehouse_destination": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "document": null
                        }
                      },
                      "message": "Traslado revertido con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya revertido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya revertido",
                    "value": {
                      "success": false,
                      "message": "El traslado ya fue revertido."
                    }
                  },
                  "e2": {
                    "summary": "Con series",
                    "value": {
                      "success": false,
                      "message": "El producto maneja lotes o series: el traslado no se puede revertir desde la API."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "transfer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/inventory/devolution-reasons": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Motivos de devolución",
        "operationId": "MotivosDevolucion",
        "description": "Lista los motivos que acepta `devolution_reason_id` al registrar una devolución.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` = `[{id, description}]`, sin paginación.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Motivos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Motivos",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "Productos vencidos"
                        },
                        {
                          "id": 2,
                          "description": "Productos dañados"
                        },
                        {
                          "id": 3,
                          "description": "Productos con errores de Fábrica"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/inventory/devolutions": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar devoluciones",
        "operationId": "ListarDevoluciones",
        "description": "Lista las devoluciones (salidas de mercadería del almacén con un motivo, por ejemplo la devolución a un proveedor), de la más reciente a la más antigua.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `establishment_id` | integer | No | Establecimiento. |\n| `devolution_reason_id` | integer | No | Motivo. |\n| `item_id` | integer | No | Devoluciones que incluyen ese producto. |\n| `date_start / date_end` | YYYY-MM-DD | No | Rango por fecha de la devolución. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (`limit` de 1 a 100, por defecto 15). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Errores:**\n- `422` si las fechas no son válidas.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Devoluciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Devoluciones",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 31,
                          "number": "DV-31",
                          "external_id": "6b0d3c2e-8a4f-4b7a-9f51-2c1e7d9a0b44",
                          "date_of_issue": "2026-11-07",
                          "time_of_issue": "10:15:00",
                          "state_type_id": "01",
                          "establishment": {
                            "id": 1,
                            "description": "Tienda Centro"
                          },
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "devolution_reason": {
                            "id": 2,
                            "description": "Productos dañados"
                          },
                          "observation": "Devolución al proveedor DISTRIBUIDORA LIMA SAC, guía 0001-552",
                          "user": {
                            "id": 7,
                            "name": "JUAN PEREZ"
                          },
                          "total_quantity": 4.0,
                          "created_at": "2026-11-07 10:15:03",
                          "items": [
                            {
                              "id": 52,
                              "item_id": 15,
                              "description": "GASEOSA 500 ML",
                              "internal_id": "P0015",
                              "unit_type_id": "NIU",
                              "quantity": 4.0,
                              "series": [],
                              "lots": []
                            }
                          ]
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Desde."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Hasta."
          },
          {
            "name": "item_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Producto."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Registrar devolución",
        "operationId": "RegistrarDevolucion",
        "description": "Registra una devolución: descuenta el stock de cada producto del almacén del establecimiento y deja el movimiento en el kardex (tipo `Devolución`). En productos con lotes baja la cantidad de cada lote; en productos con series, las series devueltas dejan de estar disponibles.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Un vendedor registra en su establecimiento (`403` si indica otro).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con la devolución creada (mismo formato que **Ver devolución**).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `establishment_id` | integer | No | Establecimiento de cuyo almacén sale la mercadería. Por defecto el del usuario; un vendedor solo puede usar el suyo. |\n| `date_of_issue` | YYYY-MM-DD | Sí | Fecha de la devolución. |\n| `time_of_issue` | HH:MM:SS | No | Hora. Por defecto, la actual. |\n| `devolution_reason_id` | integer | Sí | Motivo (de **Motivos de devolución**). |\n| `observation` | string (máx. 500) | Sí | Detalle: proveedor, documento de referencia, etc. |\n| `items` | array | Sí | Al menos un producto, sin repetir: `[{item_id, quantity, series_ids?, lots?}]`; `quantity` > 0. |\n| `items[].series_ids` | array de integer | Si el producto maneja series | Ids de las series devueltas (de **Listar series**, disponibles y en el almacén); tantas como `quantity`. |\n| `items[].lots` | array | Si el producto maneja lotes | `[{id, quantity}]` con los lotes (de **Listar lotes**); la suma debe ser igual a `quantity`. |\n\n**Reglas:**\n- Solo productos con inventario (no servicios ni packs).\n- Si la empresa controla stock, la cantidad no puede superar el stock del almacén (`409`).\n- Las devoluciones no se editan ni se anulan.\n\n**Errores:**\n- `403` si un vendedor indica otro establecimiento.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. Incluye series o lotes faltantes o que no corresponden al producto.\n- `409` si no hay stock suficiente con control de stock activo.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Registrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 31,
                        "number": "DV-31",
                        "external_id": "6b0d3c2e-8a4f-4b7a-9f51-2c1e7d9a0b44",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:15:00",
                        "state_type_id": "01",
                        "establishment": {
                          "id": 1,
                          "description": "Tienda Centro"
                        },
                        "warehouse": {
                          "id": 3,
                          "description": "Almacén - Tienda Centro"
                        },
                        "devolution_reason": {
                          "id": 2,
                          "description": "Productos dañados"
                        },
                        "observation": "Devolución al proveedor DISTRIBUIDORA LIMA SAC, guía 0001-552",
                        "user": {
                          "id": 7,
                          "name": "JUAN PEREZ"
                        },
                        "total_quantity": 4.0,
                        "created_at": "2026-11-07 10:15:03",
                        "items": [
                          {
                            "id": 52,
                            "item_id": 15,
                            "description": "GASEOSA 500 ML",
                            "internal_id": "P0015",
                            "unit_type_id": "NIU",
                            "quantity": 4.0,
                            "series": [],
                            "lots": []
                          }
                        ],
                        "kardex": [
                          {
                            "id": 9140,
                            "item_id": 15,
                            "warehouse_id": 3,
                            "quantity": -4.0,
                            "date_of_issue": "2026-11-07"
                          }
                        ]
                      },
                      "message": "Devolución registrada correctamente"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Faltan series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Faltan series",
                    "value": {
                      "success": false,
                      "message": {
                        "items.0.series_ids": [
                          "CELULAR X10 maneja series: indica 2 serie(s) en series_ids."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin stock",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin stock",
                    "value": {
                      "success": false,
                      "message": "El producto GASEOSA 500 ML no tiene suficiente stock!"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar devolución",
                  "value": {
                    "date_of_issue": "2026-11-07",
                    "devolution_reason_id": "1",
                    "observation": "Devolución al proveedor DISTRIBUIDORA LIMA SAC, guía 0001-552",
                    "items": [
                      {
                        "item_id": "1",
                        "quantity": 4
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/inventory/devolutions/{devolution_id}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Ver devolución",
        "operationId": "VerDevolucion",
        "description": "Devuelve una devolución con sus productos, series, lotes y el movimiento de kardex que generó.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador accede a todos los registros; un vendedor solo a los que registró él (o en los que figura como vendedor). Si el registro existe pero es de otro vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `devolution_id` | integer | Sí | Id de la devolución. |\n\n**Errores:**\n- `403` si la registró otro vendedor.\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Devolución",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Devolución",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 31,
                        "number": "DV-31",
                        "external_id": "6b0d3c2e-8a4f-4b7a-9f51-2c1e7d9a0b44",
                        "date_of_issue": "2026-11-07",
                        "time_of_issue": "10:15:00",
                        "state_type_id": "01",
                        "establishment": {
                          "id": 1,
                          "description": "Tienda Centro"
                        },
                        "warehouse": {
                          "id": 3,
                          "description": "Almacén - Tienda Centro"
                        },
                        "devolution_reason": {
                          "id": 2,
                          "description": "Productos dañados"
                        },
                        "observation": "Devolución al proveedor DISTRIBUIDORA LIMA SAC, guía 0001-552",
                        "user": {
                          "id": 7,
                          "name": "JUAN PEREZ"
                        },
                        "total_quantity": 4.0,
                        "created_at": "2026-11-07 10:15:03",
                        "items": [
                          {
                            "id": 52,
                            "item_id": 15,
                            "description": "GASEOSA 500 ML",
                            "internal_id": "P0015",
                            "unit_type_id": "NIU",
                            "quantity": 4.0,
                            "series": [],
                            "lots": []
                          }
                        ],
                        "kardex": [
                          {
                            "id": 9140,
                            "item_id": 15,
                            "warehouse_id": 3,
                            "quantity": -4.0,
                            "date_of_issue": "2026-11-07"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "devolution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/item-lots": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar series",
        "operationId": "ListarSeries2",
        "description": "Lista las **series** de productos (una por unidad, con su número de serie, almacén y si sigue disponible).\n\n**Quién puede usarlo:** cualquier usuario autenticado. Un administrador consulta todos los almacenes (o el que indique en `warehouse_id`); un vendedor solo el almacén de **su establecimiento**: si pide otro almacén responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | No | Producto. |\n| `warehouse_id` | integer | No | Almacén. Un vendedor solo el suyo. |\n| `available` | 0 / 1 | No | `1` = solo disponibles; `0` = solo vendidas o devueltas. |\n| `search` | string | No | Coincidencia parcial en el número de serie. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (`limit` de 1 a 100, por defecto 15). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\nCada serie trae `origin` `{type, id}`: el documento con el que ingresó (p. ej. `purchase`).\n\n**Errores:**\n- `403` si un vendedor pide un almacén que no es el de su establecimiento.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Series",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 880,
                          "series": "IMEI356938035643809",
                          "date": "2026-10-20",
                          "state": "Activo",
                          "available": true,
                          "item": {
                            "id": 41,
                            "internal_id": "CEL-X10",
                            "description": "CELULAR X10",
                            "unit_type_id": "NIU"
                          },
                          "warehouse": {
                            "id": 3,
                            "description": "Almacén - Tienda Centro"
                          },
                          "origin": {
                            "type": "purchase",
                            "id": 790
                          },
                          "created_at": "2026-10-20 15:30:12"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Otro almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Otro almacén",
                    "value": {
                      "success": false,
                      "message": "Solo puedes consultar el almacén de tu establecimiento."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Producto."
          },
          {
            "name": "available",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Solo disponibles."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Número de serie."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/item-lots/{item_lot_id}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Ver serie",
        "operationId": "VerSerie2",
        "description": "Devuelve una serie.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Un vendedor solo ve las de su almacén (`403` si no).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_lot_id` | integer | Sí | Id de la serie. |\n\n**Errores:**\n- `403` si la serie está en otro almacén.\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Serie",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Serie",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 880,
                        "series": "IMEI356938035643809",
                        "date": "2026-10-20",
                        "state": "Activo",
                        "available": true,
                        "item": {
                          "id": 41,
                          "internal_id": "CEL-X10",
                          "description": "CELULAR X10",
                          "unit_type_id": "NIU"
                        },
                        "warehouse": {
                          "id": 3,
                          "description": "Almacén - Tienda Centro"
                        },
                        "origin": {
                          "type": "purchase",
                          "id": 790
                        },
                        "created_at": "2026-10-20 15:30:12"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Registro de otro almacén",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registro de otro almacén",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_lot_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/item-lots-groups": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Listar lotes",
        "operationId": "ListarLotes",
        "description": "Lista los **lotes** de productos con su código, cantidad disponible y fecha de vencimiento. Los lotes no se guardan por almacén.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | No | Producto. |\n| `available` | 0 / 1 | No | `1` = con cantidad > 0; `0` = agotados. |\n| `expired` | 0 / 1 | No | `1` = vencidos; `0` = vigentes o sin fecha de vencimiento. |\n| `search` | string | No | Coincidencia parcial en el código del lote. |\n| `limit / cursor` | integer / string | No | Paginación por cursor (`limit` de 1 a 100, por defecto 15). |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Lotes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Lotes",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 66,
                          "code": "L2026-118",
                          "quantity": 40.0,
                          "date_of_due": "2027-03-31",
                          "expired": false,
                          "item": {
                            "id": 52,
                            "internal_id": "MED-AMOX",
                            "description": "AMOXICILINA 500 MG X 100",
                            "unit_type_id": "NIU"
                          },
                          "created_at": "2026-10-02 08:44:00"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Producto."
          },
          {
            "name": "available",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Con cantidad."
          },
          {
            "name": "expired",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "0",
            "description": "Vigentes."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/item-lots-groups/{item_lots_group_id}": {
      "get": {
        "tags": [
          "Productos e inventario"
        ],
        "summary": "Ver lote",
        "operationId": "VerLote",
        "description": "Devuelve un lote.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_lots_group_id` | integer | Sí | Id del lote. |\n\n**Errores:**\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Lote",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Lote",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 66,
                        "code": "L2026-118",
                        "quantity": 40.0,
                        "date_of_due": "2027-03-31",
                        "expired": false,
                        "item": {
                          "id": 52,
                          "internal_id": "MED-AMOX",
                          "description": "AMOXICILINA 500 MG X 100",
                          "unit_type_id": "NIU"
                        },
                        "created_at": "2026-10-02 08:44:00"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "item_lots_group_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/restaurant/list-waiter": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar mozos para el inicio de sesión",
        "operationId": "ListarMozosInicioSesion",
        "description": "Devuelve los usuarios con rol de mozo (nombre y correo) para mostrar la lista de selección en la pantalla de inicio de sesión de la app de mozos, antes de tener token.\n\n**Endpoint público:** no requiere token (auth: *No Auth*). Solo necesita que la URL sea la del dominio de tu empresa. Tiene límite de peticiones por minuto.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\nLuego inicia sesión con **0. Autenticación → Iniciar sesión** usando el correo elegido.",
        "responses": {
          "200": {
            "description": "Mozos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Mozos",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "name": "CARLOS RAMOS",
                          "email": "carlos@empresa.com"
                        },
                        {
                          "name": "LUCIA PAZ",
                          "email": "lucia@empresa.com"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/restaurant/initial-data": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Datos iniciales de la app de restaurante",
        "operationId": "DatosInicialesAppRestaurante",
        "description": "Devuelve los datos del usuario y de la empresa necesarios al iniciar la app: establecimiento y serie por defecto, rol de restaurante, RUC, logo (URL y base64), datos de contacto del establecimiento, configuración de la app y si el usuario puede editar precios.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Los campos van en la raíz de la respuesta (no dentro de `data`). `token` es el mismo token del usuario autenticado.",
        "responses": {
          "200": {
            "description": "Datos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos",
                    "value": {
                      "success": true,
                      "name": "CARLOS RAMOS",
                      "email": "carlos@empresa.com",
                      "establishment_id": 1,
                      "seriedefault": 3,
                      "token": "",
                      "restaurant_role_id": 2,
                      "restaurant_role_code": "MOZO",
                      "ruc": "20601234567",
                      "app_logo": "logo_20601234567.png",
                      "app_logo_base64": "",
                      "company": {
                        "name": "RESTAURANTE EL BUEN SABOR S.A.C.",
                        "address": "LIMA, LIMA, MIRAFLORES, AV. LARCO 123",
                        "phone": "01 4455667",
                        "email": "ventas@empresa.com",
                        "enable_list_product": true,
                        "qr_api_enable_ws": false,
                        "qr_api_url_ws": null,
                        "qr_api_key_ws": null,
                        "url_logo": "https://empresa.dominio/storage/uploads/logos/logo_20601234567.png",
                        "logo_base64": "data:image/png;base64,iVBORw0KGgo...",
                        "is_business_turn_tap": 0
                      },
                      "app_configuration": {
                        "print_format_pdf": "ticket"
                      },
                      "permission_edit_item_prices": false,
                      "sellerId": 5
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/configurations": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Configuración del restaurante",
        "operationId": "ConfiguracionRestaurante",
        "description": "Devuelve la configuración del módulo de restaurante (menús habilitados, ambientes y cantidad de mesas, permisos de cierre de mesa, impresión...) y datos de conexión (`info`: RUC, correo y tipo del usuario, servidor de tiempo real).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Configuración",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Configuración",
                    "value": {
                      "success": true,
                      "data": {
                        "menu_pos": true,
                        "menu_order": true,
                        "menu_tables": true,
                        "menu_bar": false,
                        "menu_kitchen": true,
                        "first_menu": "tables",
                        "tables_quantity": 12,
                        "tables_quantity_environment_2": 6,
                        "tables_quantity_environment_3": 0,
                        "tables_quantity_environment_4": 0,
                        "enabled_environment_1": true,
                        "enabled_environment_2": true,
                        "enabled_environment_3": false,
                        "enabled_environment_4": false
                      },
                      "info": {
                        "ruc": "20601234567",
                        "userEmail": "carlos@empresa.com",
                        "socketServer": "https://socket.dominio",
                        "userType": "seller"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/printers/set": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Guardar configuración de impresión",
        "operationId": "GuardarConfiguracionImpresion",
        "description": "Actualiza la configuración de impresión del restaurante. Todos los campos son opcionales; los que no envías no cambian.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `printer_enabled` | boolean | No | Activa la impresión automática. |\n| `print_local_enabled` | boolean | No | Solo permite imprimir desde la misma red que el servicio de impresión local. |\n| `printer_name_comanda` | string | No | Impresora de comandas (máx. 255). |\n| `printer_name_documents` | string | No | Impresora de comprobantes (máx. 255). |\n| `printer_name_precuenta` | string | No | Impresora de precuentas (máx. 255). |\n| `printer_per_area_enabled` | boolean | No | Imprime cada comanda en la impresora de su área de preparación. |\n| `print_destination` | boolean | No | Incluye el destino (mesa/ambiente) en la impresión. |\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Guardada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardada",
                    "value": {
                      "success": true,
                      "message": "Configuración de impresión guardada."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Guardar configuración de impresión",
                  "value": {
                    "printer_enabled": true,
                    "print_local_enabled": false,
                    "printer_name_comanda": "COCINA-01",
                    "printer_name_documents": "CAJA-01",
                    "printer_name_precuenta": "CAJA-01",
                    "printer_per_area_enabled": true,
                    "print_destination": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/waiters": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar mozos",
        "operationId": "ListarMozos",
        "description": "Lista los usuarios con rol de mozo (id y nombre), por ejemplo para asignar el mozo de una mesa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`.",
        "responses": {
          "200": {
            "description": "Mozos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Mozos",
                    "value": {
                      "data": [
                        {
                          "id": 7,
                          "name": "CARLOS RAMOS"
                        },
                        {
                          "id": 8,
                          "name": "LUCIA PAZ"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/available-sellers": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar usuarios de restaurante activos",
        "operationId": "ListarUsuariosRestauranteActivos",
        "description": "Lista los usuarios activos que tienen algún rol de restaurante (id, nombre y correo), para elegir quién atiende o validar su PIN.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Usuarios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuarios",
                    "value": {
                      "success": true,
                      "message": "Vendedores disponibles",
                      "data": [
                        {
                          "id": 7,
                          "name": "CARLOS RAMOS",
                          "email": "carlos@empresa.com"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/correct_pin_check/{waiter_user_id}/{restaurant_pin}": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Validar PIN de usuario de restaurante",
        "operationId": "ValidarPinUsuarioRestaurante",
        "description": "⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\nVerifica que el PIN de restaurante corresponda al usuario activo indicado (cambio rápido de usuario en un equipo compartido).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. `success: true` y `data` con el usuario si el PIN es correcto; `success: false` y `data: []` si no.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del usuario. |\n| `pin` | string | Sí | PIN de restaurante del usuario. |\n\n**Reglas:**\n- El PIN viaja en la URL: no lo registres en logs de tu integración.",
        "responses": {
          "200": {
            "description": "PIN correcto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "PIN correcto",
                    "value": {
                      "success": true,
                      "message": "Verificar pin",
                      "data": {
                        "id": 7,
                        "name": "CARLOS RAMOS",
                        "email": "carlos@empresa.com"
                      }
                    }
                  },
                  "e2": {
                    "summary": "PIN incorrecto",
                    "value": {
                      "success": false,
                      "message": "Verificar pin",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "waiter_user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2"
          },
          {
            "name": "restaurant_pin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1234"
          }
        ]
      }
    },
    "/api/restaurant/items": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar productos de la carta",
        "operationId": "ListarProductosCarta",
        "description": "Lista los productos marcados para restaurante con código interno, con stock del almacén del establecimiento del usuario, área de preparación (`area_print`), insumos, combos (`items_sets`), modificadores y, si la empresa usa listas de precios, `item_unit_types` con sus precios.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Sin paginación: devuelve toda la carta.",
        "responses": {
          "200": {
            "description": "Carta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Carta",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 15,
                          "unit_type_id": "NIU",
                          "category_id": 3,
                          "description": "LOMO SALTADO",
                          "name": null,
                          "second_name": null,
                          "warehouse_id": null,
                          "internal_id": "P0015",
                          "barcode": null,
                          "item_code": null,
                          "item_code_gs1": null,
                          "stock": 40.0,
                          "stock_min": 1,
                          "currency_type_id": "PEN",
                          "currency_type_symbol": "S/",
                          "sale_affectation_igv_type_id": "10",
                          "price": "32.00",
                          "calculate_quantity": false,
                          "has_igv": true,
                          "active": true,
                          "sale_unit_price": "S/ 32.00",
                          "purchase_unit_price": "S/ 0.00",
                          "created_at": "2026-10-01 10:00:00",
                          "updated_at": "2026-11-05 09:12:00",
                          "apply_store": false,
                          "apply_restaurant": true,
                          "restaurant_favorite": true,
                          "image_url": "https://empresa.dominio/storage/uploads/items/lomo.jpg",
                          "image_url_medium": "https://empresa.dominio/storage/uploads/items/lomo_medium.jpg",
                          "image_url_small": "https://empresa.dominio/storage/uploads/items/lomo_small.jpg",
                          "favorite": false,
                          "area_print": "COCINA-01",
                          "has_supplies": true,
                          "is_dish": true,
                          "has_sets": false,
                          "items_sets": [],
                          "restaurant_stock": {
                            "stock": 40,
                            "available": 36
                          },
                          "modifiers": [],
                          "parent_item_id": null,
                          "variation_label": null,
                          "variation_attributes": [],
                          "variation_value_ids": [],
                          "variations_count": 0,
                          "has_variations": false,
                          "variation_variables": [],
                          "variations": [],
                          "item_unit_types": []
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "group_variations",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = agrupa las variantes (talla, sabor...) dentro de su producto padre en `variations`; sin el parámetro cada variante llega como producto suelto."
          }
        ]
      }
    },
    "/api/restaurant/categories": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar categorías de la carta",
        "operationId": "ListarCategoriasCarta",
        "description": "Lista todas las categorías de productos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Categorías",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Categorías",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "name": "PLATOS DE FONDO",
                          "image": null,
                          "created_at": "2026-10-01 10:00:00",
                          "updated_at": "2026-10-01 10:00:00"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/items/stock": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Stock disponible de la carta",
        "operationId": "StockDisponibleCarta",
        "description": "Devuelve el stock de restaurante de cada producto: `stock`, `quantity_reserved` (comprometido en mesas abiertas) y `available` (= stock − reservado, mínimo 0).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Stock",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Stock",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "item_id": 15,
                          "stock": "40.00",
                          "quantity_reserved": "4.00",
                          "available": "36.00"
                        }
                      ]
                    }
                  },
                  "e2": {
                    "summary": "Error",
                    "value": {
                      "success": false,
                      "message": "Error al obtener el stock: ..."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/items/price": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Cambiar precio de un producto",
        "operationId": "CambiarPrecioProducto",
        "description": "Cambia el precio de venta unitario del producto.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del producto. |\n| `sale_unit_price` | numeric | Sí | Nuevo precio de venta. |\n\n**Reglas:**\n- La app solo debe mostrar esta opción si `permission_edit_item_prices` es `true` en **Datos iniciales**; el servidor no lo valida.\n\n**Errores:**\n- `500` si el producto no existe.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "message": "Precio editado correctamente."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar precio de un producto",
                  "value": {
                    "id": "1",
                    "sale_unit_price": 34.0
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/items/restaurant-favorite": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Marcar o desmarcar producto favorito",
        "operationId": "MarcarDesmarcarProductoFavorito",
        "description": "Alterna el producto entre favorito y no favorito de la carta (cada llamada invierte el estado).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del producto. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Agregado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Agregado",
                    "value": {
                      "success": true,
                      "message": "Producto agregado a favoritos"
                    }
                  },
                  "e2": {
                    "summary": "Quitado",
                    "value": {
                      "success": true,
                      "message": "Producto quitado de favoritos"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Marcar o desmarcar producto favorito",
                  "value": {
                    "id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/notes": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar notas de preparación",
        "operationId": "ListarNotasPreparacion",
        "description": "Lista las notas predefinidas para los pedidos (p. ej. *sin cebolla*, *término medio*).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve `{records: [...]}`.",
        "responses": {
          "200": {
            "description": "Notas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Notas",
                    "value": {
                      "records": [
                        {
                          "id": 1,
                          "description": "Sin cebolla"
                        },
                        {
                          "id": 2,
                          "description": "Término medio"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/tablesAndEnv": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Mesas y ambientes",
        "operationId": "MesasAmbientes",
        "description": "Devuelve todas las mesas con su pedido, total, mozo, grupo, estado de pago y tiempo de apertura, la configuración de los 4 ambientes clásicos y la lista de ambientes activos (`environments`). Es la pantalla principal de la app de mozos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n`quantityOrders` = cantidad de productos pedidos; `timeOpening` = tiempo transcurrido desde que se abrió la mesa; `is_main_table` = mesa principal de su grupo.",
        "responses": {
          "200": {
            "description": "Mesas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Mesas",
                    "value": {
                      "tables": [
                        {
                          "id": 7,
                          "status": "notavailable",
                          "products": [
                            {
                              "id": 15,
                              "name": "LOMO SALTADO",
                              "quantity": 2,
                              "price": 32.0,
                              "note": "sin cebolla"
                            }
                          ],
                          "total": 64.0,
                          "personas": 2,
                          "cliente": null,
                          "label": "M7",
                          "shape": "CUADRADO",
                          "environment": "Salón",
                          "waiter": "CARLOS RAMOS",
                          "comentarios": null,
                          "open": false,
                          "close": false,
                          "group_id": null,
                          "is_main_table": false,
                          "is_active": true,
                          "original_environment": null,
                          "quantityOrders": 2,
                          "timeOpening": "00:35",
                          "order_status": "pending",
                          "is_paid": false,
                          "delivery": null,
                          "opening_token": 1762536000
                        }
                      ],
                      "enabled_environment_1": {
                        "active": true,
                        "tablesQuantity": 12,
                        "name": "Salón"
                      },
                      "enabled_environment_2": {
                        "active": true,
                        "tablesQuantity": 6,
                        "name": "Terraza"
                      },
                      "enabled_environment_3": {
                        "active": false,
                        "tablesQuantity": 0,
                        "name": "Delivery"
                      },
                      "enabled_environment_4": {
                        "active": false,
                        "tablesQuantity": 0,
                        "name": "Para Llevar"
                      },
                      "environments": [
                        {
                          "id": 1,
                          "name": "Salón",
                          "active": true,
                          "is_delivery": false,
                          "is_takeaway": false
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/restaurant/table/{restaurant_table_id}": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Ver mesa",
        "operationId": "VerMesa",
        "description": "Devuelve una mesa con su pedido actual y su `opening_token`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve `{table: {...}}`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la mesa. |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Mesa",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Mesa",
                    "value": {
                      "table": {
                        "id": 7,
                        "status": "notavailable",
                        "products": [
                          {
                            "id": 15,
                            "name": "LOMO SALTADO",
                            "quantity": 2,
                            "price": 32.0,
                            "note": "sin cebolla"
                          }
                        ],
                        "total": 64.0,
                        "personas": 2,
                        "cliente": null,
                        "label": "M7",
                        "shape": "CUADRADO",
                        "environment": "Salón",
                        "waiter": "CARLOS RAMOS",
                        "order_status": "pending",
                        "delivery": null,
                        "opening_token": 1762536000
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "restaurant_table_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      },
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Guardar mesa (pedido, abrir, cerrar)",
        "operationId": "GuardarMesaPedidoAbrirCerrar",
        "description": "Guarda el estado completo de la mesa: pedido (`products`), total, comensales, cliente, mozo y estado. También abre (`open`) o cierra (`close`) la mesa. Si la mesa queda sin productos se liberan las cantidades reservadas y se borran sus comandas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito devuelve el `opening_token` actualizado; ante un conflicto de versión responde `success: false` y `stale: true`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la mesa. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `products` | array | Sí | Pedido completo de la mesa (envía `[]` para vaciarla). |\n| `status` | string | Sí | `available` o `notavailable`. Si `products` tiene elementos se guarda siempre `notavailable`. |\n| `total` | numeric | No | Total del pedido. |\n| `personas` | integer | No | Comensales. |\n| `cliente` | string/object | No | Cliente. |\n| `comentarios` | string | No | Comentarios del pedido. |\n| `waiter` | string | No | Mozo asignado. |\n| `label` | string | No | Nombre de la mesa. |\n| `shape` | string | No | Forma. |\n| `environment` | string | No | Ambiente. |\n| `order_status` | string | Sí en delivery / para llevar | Estado del pedido (`pending`, `served`, `delivered`, `deleted`...). |\n| `is_paid` | boolean | No | `true` si el pedido ya se cobró. |\n| `delivery` | object | No | Datos de entrega. |\n| `open` | boolean | No | `true` para abrir la mesa (inicia el tiempo de atención). |\n| `close` | boolean | No | `true` para cerrar la mesa. |\n| `expected_opening_token` | integer | Recomendado | `opening_token` que leíste. Si la mesa cambió en otro equipo no se guarda (`stale: true`). |\n\n**Reglas:**\n- Una mesa libre y vacía solo se reabre con `open: true`; si llegan productos sin `open` responde `stale: true`.\n- Cerrar la mesa (`close`) requiere ser administrador, tener rol de restaurante administrador o que la configuración permita cerrar mesas al rol del usuario (mozo/cajero).\n- En pedidos **Delivery** / **Para Llevar**, `order_status: deleted` (o un pedido ya entregado) elimina la mesa temporal y sus comandas.\n- Si la mesa pertenece a un grupo, el total y el estado se copian a todas las mesas del grupo.\n\n**Errores:**\n- `200` con `success: false` y `stale: true` cuando tu copia de la mesa está desactualizada: vuelve a leer la mesa.\n- `403` si el usuario no puede cerrar mesas.\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Guardada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardada",
                    "value": {
                      "success": true,
                      "message": "Mesa actualizada.",
                      "opening_token": 1762536000
                    }
                  },
                  "e2": {
                    "summary": "Cambió en otro equipo",
                    "value": {
                      "success": false,
                      "stale": true,
                      "message": "La mesa cambió en otro equipo. Se actualizaron los datos."
                    }
                  },
                  "e3": {
                    "summary": "Pedido entregado",
                    "value": {
                      "success": true,
                      "message": "Pedido finalizado, entrega realizada"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "restaurant_table_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Guardar mesa (pedido, abrir, cerrar)",
                  "value": {
                    "products": [
                      {
                        "id": 15,
                        "name": "LOMO SALTADO",
                        "quantity": 2,
                        "price": 32.0,
                        "note": "sin cebolla"
                      }
                    ],
                    "status": "notavailable",
                    "total": 64.0,
                    "personas": 2,
                    "cliente": null,
                    "comentarios": null,
                    "waiter": "CARLOS RAMOS",
                    "label": "M7",
                    "shape": "CUADRADO",
                    "environment": "Salón",
                    "order_status": "pending",
                    "is_paid": false,
                    "delivery": null,
                    "open": true,
                    "close": false,
                    "expected_opening_token": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/table": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Crear mesa",
        "operationId": "CrearMesa",
        "description": "Crea una mesa (o un pedido delivery / para llevar como mesa temporal).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `label` | string | Sí | Nombre o número visible de la mesa (p. ej. `M7`). |\n| `environment` | string | Sí | Nombre del ambiente (p. ej. `Salón`, `Terraza`, `Delivery`, `Para Llevar`). Debe ser un ambiente de **Mesas y ambientes**. |\n| `shape` | string | No | Forma para el plano: `CUADRADO` (por defecto), `REDONDO`, etc. |\n| `status` | string | No | `available` (libre, por defecto) o `notavailable` (ocupada). |\n| `products` | array | No | Pedido de la mesa (por defecto vacío). |\n| `total` | numeric | No | Total del pedido (por defecto 0). |\n| `personas` | integer | No | Comensales (por defecto 1). |\n| `cliente` | string/object | No | Cliente del pedido. |\n| `waiter` | string | No | Mozo asignado. |\n| `order_status` | string | No | Estado del pedido: `pending`, `served`, `delivered`... |\n| `delivery` | object | No | Datos de entrega (dirección, teléfono...) para pedidos delivery. |\n\n**Reglas:**\n- Los campos no se validan: envía al menos `label` y `environment`.",
        "responses": {
          "200": {
            "description": "Creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 13,
                        "status": "available",
                        "products": [],
                        "total": 0,
                        "personas": 1,
                        "cliente": null,
                        "label": "M13",
                        "shape": "CUADRADO",
                        "environment": "Salón",
                        "waiter": null,
                        "order_status": null,
                        "delivery": null,
                        "opening_token": null
                      },
                      "message": "Mesa creada con éxito."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear mesa",
                  "value": {
                    "label": "M13",
                    "environment": "Salón",
                    "shape": "CUADRADO",
                    "status": "available",
                    "products": [],
                    "total": 0,
                    "personas": 1,
                    "cliente": null,
                    "waiter": null,
                    "order_status": null,
                    "delivery": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/label-table/save": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Renombrar mesa",
        "operationId": "RenombrarMesa",
        "description": "Cambia el nombre visible y la forma de una mesa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la mesa. |\n| `label` | string | Sí | Nuevo nombre. |\n| `shape` | string | Sí | Forma (`CUADRADO`, `REDONDO`...). |\n\n**Errores:**\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Actualizada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Actualizada",
                    "value": {
                      "success": true,
                      "message": "Mesa actualizada con éxito."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Renombrar mesa",
                  "value": {
                    "id": "1",
                    "label": "VIP 1",
                    "shape": "REDONDO"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/order/change-table": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Mover pedido a otra mesa",
        "operationId": "MoverPedidoAOtraMesa",
        "description": "Mueve el pedido completo (productos, total, cliente, mozo, comandas) de una mesa a otra y deja libre la mesa de origen.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `tableid_origin` | integer | Sí | Mesa de origen (distinta del destino). |\n| `tableid_destination` | integer | Sí | Mesa de destino. |\n\n**Reglas:**\n- El pedido de la mesa destino se **reemplaza**: verifica antes que esté libre.\n\n**Errores:**\n- `200` con `success: false` y `message` si alguna mesa no existe o faltan campos.",
        "responses": {
          "200": {
            "description": "Movido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Movido",
                    "value": {
                      "success": true,
                      "message": "Los datos de la mesa se han movido correctamente."
                    }
                  },
                  "e2": {
                    "summary": "Destino inexistente",
                    "value": {
                      "success": false,
                      "message": "La mesa destino no existe."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Mover pedido a otra mesa",
                  "value": {
                    "tableid_origin": "1",
                    "tableid_destination": "2"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/table/toggle-active": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Activar o poner fuera de servicio una mesa",
        "operationId": "ActivarPonerFueraServicioMesa",
        "description": "Alterna la mesa entre activa y fuera de servicio.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito trae `is_active` con el nuevo estado.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `table_id` | integer | Sí | Id de la mesa. |\n\n**Reglas:**\n- No se desactiva una mesa que pertenece a un grupo (sepárala primero).\n\n**Errores:**\n- `400` `{success: false, message}` si una regla lo impide.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Fuera de servicio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Fuera de servicio",
                    "value": {
                      "success": true,
                      "is_active": false,
                      "message": "Mesa M7 fuera de servicio"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "En grupo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En grupo",
                    "value": {
                      "success": false,
                      "message": "Esta mesa ya pertence a un grupo. Separarla primero."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Activar o poner fuera de servicio una mesa",
                  "value": {
                    "table_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/table/cambiar-ambiente": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Cambiar mesa de ambiente",
        "operationId": "CambiarMesaAmbiente",
        "description": "Mueve una mesa libre a otro ambiente activo. Se recuerda el ambiente original para poder restaurarla.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `table_id` | integer | Sí | Id de la mesa. |\n| `nuevo_ambiente` | string | Sí | Nombre del ambiente destino (máx. 100), debe existir y estar activo. |\n\n**Reglas:**\n- La mesa debe estar libre (`available`) y no pertenecer a un grupo.\n\n**Errores:**\n- `400` `{success: false, message}`: mesa ocupada, agrupada, ya está en ese ambiente o ambiente inexistente.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Movida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Movida",
                    "value": {
                      "success": true,
                      "message": "Mesa M7 movida a Terraza",
                      "mesa": {
                        "id": 7,
                        "label": "M7",
                        "environment": "Terraza",
                        "original_environment": "Salón"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Ocupada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ocupada",
                    "value": {
                      "success": false,
                      "message": "No se puede mover una mesa ocupada"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar mesa de ambiente",
                  "value": {
                    "table_id": "1",
                    "nuevo_ambiente": "Terraza"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/table/restaurar-ambiente": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Restaurar mesa a su ambiente original",
        "operationId": "RestaurarMesaASuAmbienteOriginal",
        "description": "Devuelve una mesa movida a su ambiente original.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `table_id` | integer | Sí | Id de la mesa. |\n\n**Reglas:**\n- La mesa debe haber sido movida, estar libre, activa y no pertenecer a un grupo.\n\n**Errores:**\n- `400` `{success: false, message}` si una regla lo impide.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Restaurada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Restaurada",
                    "value": {
                      "success": true,
                      "message": "Mesa M7 restaurada a Salón",
                      "mesa": {
                        "id": 7,
                        "label": "M7",
                        "environment": "Salón",
                        "original_environment": null
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No movida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No movida",
                    "value": {
                      "success": false,
                      "message": "La mesa no ha sido movida de su ambiente original"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Restaurar mesa a su ambiente original",
                  "value": {
                    "table_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/tables/group/create": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Crear grupo de mesas",
        "operationId": "CrearGrupoMesas",
        "description": "Crea un grupo (para juntar mesas en un solo pedido) con la mesa principal indicada.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito trae `group` con el grupo creado.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `main_table_id` | integer | Sí | Mesa principal: activa y sin grupo. |\n\n**Errores:**\n- `400` `{success: false, message}` si la mesa está fuera de servicio o ya está en un grupo.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "group": {
                        "id": 2,
                        "main_table_id": 7,
                        "status": "open",
                        "opening_date": "2026-11-07T19:05:00.000000Z",
                        "total": 0,
                        "updated_at": "2026-11-07T19:05:00.000000Z",
                        "created_at": "2026-11-07T19:05:00.000000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Ya agrupada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya agrupada",
                    "value": {
                      "success": false,
                      "message": "Esta mesa ya pertenece a un grupo"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear grupo de mesas",
                  "value": {
                    "main_table_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/tables/group/add": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Agregar mesa a un grupo",
        "operationId": "AgregarMesaAGrupo",
        "description": "Agrega una mesa secundaria al grupo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `group_id` | integer | Sí | Id del grupo. |\n| `table_id` | integer | Sí | Mesa a agregar: activa, libre, sin otro grupo y distinta de la principal. |\n\n**Errores:**\n- `400` `{success: false, message}` si una regla lo impide.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Agregada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Agregada",
                    "value": {
                      "success": true,
                      "message": "Mesa M8 agregada al grupo exitosamente"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Otro grupo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Otro grupo",
                    "value": {
                      "success": false,
                      "message": "Esta mesa ya pertenece a otro grupo"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Agregar mesa a un grupo",
                  "value": {
                    "group_id": "1",
                    "table_id": "2"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/tables/group/remove": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Separar mesa de un grupo",
        "operationId": "SepararMesaGrupo",
        "description": "Separa una mesa secundaria de su grupo y la deja libre. Si en el grupo solo queda la mesa principal, el grupo se disuelve automáticamente.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `table_id` | integer | Sí | Mesa secundaria a separar. |\n\n**Reglas:**\n- La mesa principal no se separa: disuelve el grupo completo.\n\n**Errores:**\n- `400` `{success: false, message}` si una regla lo impide.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Separada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Separada",
                    "value": {
                      "success": true,
                      "message": "Mesa M8 separada. El grupo fue disuelto automáticamente."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Principal",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Principal",
                    "value": {
                      "success": false,
                      "message": "No puedes separar la mesa principal. Disuelve el grupo completo."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Separar mesa de un grupo",
                  "value": {
                    "table_id": "2"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/tables/group/disband": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Disolver grupo de mesas",
        "operationId": "DisolverGrupoMesas",
        "description": "Disuelve el grupo: la mesa principal conserva el pedido y las secundarias quedan libres y vacías.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `group_id` | integer | Sí | Id del grupo. |\n\n**Errores:**\n- `404` `{success: false, message}` si el grupo no existe.\n- `400` si alguna mesa secundaria tiene productos.",
        "responses": {
          "200": {
            "description": "Disuelto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Disuelto",
                    "value": {
                      "success": true,
                      "message": "Grupo disuelto exitosamente"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Grupo no encontrado"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Disolver grupo de mesas",
                  "value": {
                    "group_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/tables/group/recalculate": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Recalcular total del grupo",
        "operationId": "RecalcularTotalGrupo",
        "description": "Recalcula el total del grupo como la suma de los totales de sus mesas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito trae `total`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `group_id` | integer | Sí | Id del grupo. |\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.",
        "responses": {
          "200": {
            "description": "Total",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Total",
                    "value": {
                      "success": true,
                      "total": "128.00"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Recalcular total del grupo",
                  "value": {
                    "group_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/command-item/save": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Enviar producto a cocina (comanda)",
        "operationId": "EnviarProductoACocinaComanda",
        "description": "Registra un producto de la mesa como comanda para cocina/bar: descuenta los insumos de la receta, reserva el stock (también de los componentes de un combo y de los modificadores que son productos) y notifica a las pantallas de cocina.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito trae `kitchen_complete` y `order_status` (estado del pedido de la mesa).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `table_id` | integer | Sí | Id de la mesa. |\n| `item_id` | integer | Sí | Id del producto. |\n| `quantity` | numeric | Sí | Cantidad. |\n| `item` | object | Sí | Producto tal como lo devuelve **Listar productos de la carta** (se guarda completo). Se usan `name`, `has_supplies`, `has_sets`, `items_sets[].id` / `items_sets[].pivot.quantity` y `modifiersApplied[].items[]` (`type: item`, `item_id`). |\n| `note` | string | No | Nota de preparación. |\n| `status` | integer | Sí | Estado inicial: `1` (Recibido). |\n| `status_description` | string | No | Texto del estado, p. ej. `Recibido`. |\n\n**Reglas:**\n- Si la mesa estaba en `served`, al agregar un producto vuelve a `pending`.\n\n**Errores:**\n- `200` con `success: false` si falla el descuento de insumos o la reserva de stock.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Producto agregado con éxito.",
                      "kitchen_complete": false,
                      "order_status": "pending"
                    }
                  },
                  "e2": {
                    "summary": "Error de stock",
                    "value": {
                      "success": false,
                      "message": "Error al reservar stock."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar producto a cocina (comanda)",
                  "value": {
                    "table_id": "1",
                    "item_id": "1",
                    "quantity": 2,
                    "note": "sin cebolla",
                    "status": 1,
                    "status_description": "Recibido",
                    "item": {
                      "id": 15,
                      "name": "LOMO SALTADO",
                      "has_supplies": true,
                      "has_sets": false,
                      "items_sets": [],
                      "modifiersApplied": [
                        {
                          "group": "Acompañamiento",
                          "items": [
                            {
                              "type": "item",
                              "item_id": 40,
                              "name": "Arroz"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/restaurant/command-status/items/{restaurant_table_id}": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Comandas por estado",
        "operationId": "ComandasEstado",
        "description": "Devuelve las comandas agrupadas por estado: `productsStatusReceived` (1), `productsStatusProcessing` (2), `productsStatusToDeliver` (3) y `productsStatusDelivered` (4, las últimas 20). Es la vista de cocina/bar.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la mesa. Usa `0` para ver las comandas de **todas** las mesas. |",
        "responses": {
          "200": {
            "description": "Comandas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Comandas",
                    "value": {
                      "success": true,
                      "data": {
                        "productsStatusReceived": [
                          {
                            "id": 31,
                            "name": "LOMO SALTADO",
                            "quantity": 2,
                            "note": "sin cebolla",
                            "modifiers_applied": [],
                            "status": 1,
                            "status_description": "Recibido",
                            "mesa_id": 7,
                            "mesa": "M7",
                            "environment_id": null,
                            "environment": "Salón",
                            "preparation_area_id": 1,
                            "preparation_area_name": "Cocina",
                            "created_at": "2026-11-07T18:20:11.000000Z",
                            "updated_at": "2026-11-07T18:20:11.000000Z"
                          }
                        ],
                        "productsStatusProcessing": [],
                        "productsStatusToDeliver": [],
                        "productsStatusDelivered": []
                      },
                      "message": "Listado de productos por estados.",
                      "id": "7"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "restaurant_table_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/restaurant/command-status/set/{command_item_id}": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Avanzar estado de una comanda",
        "operationId": "AvanzarEstadoComanda",
        "description": "⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\nAvanza la comanda al siguiente estado (1 → 2 → 3 → 4; en 4 se queda). Cuando todas las comandas de la mesa están entregadas, el pedido pasa a `served`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. En el éxito trae `kitchen_complete`, `order_status`, `table_id` e `is_paid`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la comanda (`id` en **Comandas por estado**). |\n\n**Errores:**\n- `200` con `success: false` si la comanda no existe.",
        "responses": {
          "200": {
            "description": "Avanzada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Avanzada",
                    "value": {
                      "success": true,
                      "message": "Estado cambiado con éxito",
                      "kitchen_complete": true,
                      "order_status": "served",
                      "table_id": 7,
                      "is_paid": false
                    }
                  },
                  "e2": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Orden no encontrada"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "command_item_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/restaurant/command-status/served/{restaurant_table_id}": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "¿Mesa completamente servida?",
        "operationId": "MesaCompletamenteServida",
        "description": "Indica si todas las comandas de la mesa están entregadas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve solo `true` o `false` (sin objeto). Una mesa sin comandas devuelve `false`.\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `tableId` | integer | Sí | Id de la mesa. |",
        "responses": {
          "200": {
            "description": "Servida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Servida",
                    "value": true
                  },
                  "e2": {
                    "summary": "Pendiente",
                    "value": false
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "restaurant_table_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/print-orders": {
      "post": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Registrar orden de impresión",
        "operationId": "RegistrarOrdenImpresion",
        "description": "Envía un documento (PDF en base64) a la cola del servicio de impresión local del restaurante. Si no indicas impresora se usa la predeterminada.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). En el éxito devuelve `201` con la orden creada (sin `success`).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name_printer` | string | No | Nombre de la impresora (máx. 255). Vacío = impresora predeterminada. |\n| `pdf_b64` | string | Sí en la práctica | Contenido del PDF en base64. |\n| `client_public_ip` | string | Sí si la impresión local está activa | IP pública de la terminal. Con impresión local activa debe coincidir con la del servicio de impresión. |\n\n**Reglas:**\n- Estados de la orden (`status`): `0` pendiente, `1` procesando, `2` impresa, `3` con error.\n\n**Errores:**\n- `403` si la impresión local está activa y la terminal no está en la misma red.\n- `422` si no se indicó impresora y no hay una predeterminada (o falla la validación).",
        "responses": {
          "201": {
            "description": "Encolada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Encolada",
                    "value": {
                      "name_printer": "COCINA-01",
                      "pdf_b64": "JVBERi0xLjcKJcfsj6IK...",
                      "status": 0,
                      "updated_at": "2026-11-07T19:10:00.000000Z",
                      "created_at": "2026-11-07T19:10:00.000000Z",
                      "id": 88
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin impresora",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin impresora",
                    "value": {
                      "success": false,
                      "message": "No hay impresoras configuradas. Configure una impresora predeterminada en el servicio de impresión."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Otra red",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Otra red",
                    "value": {
                      "success": false,
                      "message": "Impresión local activa: esta terminal no está en la red del servicio de impresión."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar orden de impresión",
                  "value": {
                    "name_printer": "COCINA-01",
                    "pdf_b64": "JVBERi0xLjcKJcfsj6IK...",
                    "client_public_ip": "190.12.34.56"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/print-orders/{print_order_id}": {
      "put": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Actualizar estado de orden de impresión",
        "operationId": "ActualizarEstadoOrdenImpresion",
        "description": "El servicio de impresión confirma el resultado de una orden.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve la orden actualizada (sin `success`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id de la orden. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `status` | integer | Sí | `0` pendiente, `1` procesando, `2` impresa, `3` con error. |\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `404` `{success: false, message: \"Registro no encontrado.\"}` si el id no existe.",
        "responses": {
          "200": {
            "description": "Actualizada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Actualizada",
                    "value": {
                      "id": 88,
                      "name_printer": "COCINA-01",
                      "status": 2,
                      "pdf_b64": "JVBERi0xLjcKJcfsj6IK...",
                      "created_at": "2026-11-07T19:10:00.000000Z",
                      "updated_at": "2026-11-07T19:10:04.000000Z"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Estado inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estado inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "status": [
                          "El campo status seleccionado es inválido."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "print_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Actualizar estado de orden de impresión",
                  "value": {
                    "status": 2
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/print-orders/pending": {
      "get": {
        "tags": [
          "Restaurante"
        ],
        "summary": "Listar órdenes de impresión pendientes",
        "operationId": "ListarOrdenesImpresionPendientes",
        "description": "Devuelve las órdenes en estado `0` (pendiente), de la más antigua a la más reciente. Lo usa el servicio de impresión al reconectarse para recuperar los trabajos que no recibió en tiempo real.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve directamente un arreglo.",
        "responses": {
          "200": {
            "description": "Pendientes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pendientes",
                    "value": [
                      {
                        "id": 88,
                        "name_printer": "COCINA-01",
                        "status": 0,
                        "pdf_b64": "JVBERi0xLjcKJcfsj6IK...",
                        "created_at": "2026-11-07T19:10:00.000000Z",
                        "updated_at": "2026-11-07T19:10:00.000000Z"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/reports/filters": {
      "get": {
        "tags": [
          "Reportes"
        ],
        "summary": "Filtros de reportes",
        "operationId": "FiltrosReportes",
        "description": "Devuelve los establecimientos (`id`, `description`) para el filtro de los reportes.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Filtros",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros",
                    "value": {
                      "establishments": [
                        {
                          "id": 1,
                          "description": "Oficina Principal"
                        },
                        {
                          "id": 2,
                          "description": "Sucursal Norte"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/reports/general-sale": {
      "post": {
        "tags": [
          "Reportes"
        ],
        "summary": "Reporte general de ventas",
        "operationId": "ReporteGeneralVentas",
        "description": "Devuelve los totales de ventas del periodo (comprobantes, notas de venta y pedidos) y los datos para un gráfico, más un enlace para descargar el reporte en PDF.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`. Además de `data` trae `download_report` (URL del PDF).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `period` | string | Sí | `month`, `between_months`, `date` o `between_dates`. |\n| `month_start` | string | Con `month` / `between_months` | Mes inicial `YYYY-MM`. |\n| `month_end` | string | Con `between_months` | Mes final `YYYY-MM`. |\n| `date_start` | date | Con `date` / `between_dates` | Fecha inicial `YYYY-MM-DD`. |\n| `date_end` | date | Con `between_dates` | Fecha final `YYYY-MM-DD`. |\n| `establishment_id` | integer | No | Establecimiento. Por defecto el del usuario autenticado. |\n\n`totals.total` incluye comprobantes, notas de venta y pedidos (`total_order_notes`); el gráfico no incluye pedidos.",
        "responses": {
          "200": {
            "description": "Totales",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Totales",
                    "value": {
                      "data": {
                        "totals": {
                          "total_documents": "1520.40",
                          "total_sale_notes": "380.00",
                          "total": "2050.40",
                          "total_order_notes": 150.0
                        },
                        "graph": {
                          "labels": [
                            "01",
                            "02",
                            "03"
                          ],
                          "datasets": [
                            {
                              "label": "Total notas de venta",
                              "data": [
                                120.0,
                                80.0,
                                180.0
                              ],
                              "backgroundColor": "rgba(254, 0, 108, .1)",
                              "borderColor": "rgb(254, 0, 108)",
                              "borderWidth": 2,
                              "fill": true,
                              "lineTension": 0.3,
                              "pointRadius": 1
                            }
                          ]
                        }
                      },
                      "download_report": "https://empresa.dominio/report-app/pdf-general-sale?period=month&month_start=2026-11&establishment_id=1"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Reporte general de ventas",
                  "value": {
                    "period": "month",
                    "month_start": "2026-11",
                    "month_end": null,
                    "date_start": null,
                    "date_end": null,
                    "establishment_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/email": {
      "post": {
        "tags": [
          "Reportes"
        ],
        "summary": "Enviar reporte general de ventas por correo",
        "operationId": "EnviarReporteGeneralVentasCorreo",
        "description": "Envía por correo el reporte general de ventas del periodo indicado.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `email` | string | Sí | Correo destino. |\n| `period` | string | Sí | `month`, `between_months`, `date` o `between_dates`. |\n| `month_start` | string | Con `month` / `between_months` | Mes inicial `YYYY-MM`. |\n| `month_end` | string | Con `between_months` | Mes final `YYYY-MM`. |\n| `date_start` | date | Con `date` / `between_dates` | Fecha inicial `YYYY-MM-DD`. |\n| `date_end` | date | Con `between_dates` | Fecha final `YYYY-MM-DD`. |\n| `establishment_id` | integer | No | Establecimiento. Por defecto el del usuario autenticado. |\n\n**Errores:**\n- `500` si falta `email` o el periodo es inválido.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Email enviado correctamente."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar reporte general de ventas por correo",
                  "value": {
                    "email": "gerencia@empresa.com",
                    "period": "month",
                    "month_start": "2026-11",
                    "month_end": null,
                    "date_start": null,
                    "date_end": null,
                    "establishment_id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/report": {
      "get": {
        "tags": [
          "Reportes"
        ],
        "summary": "Resumen de ventas del mes",
        "operationId": "ResumenVentasMes",
        "description": "Devuelve los totales de ventas del **mes actual** (comprobantes y notas de venta) y los datos de su gráfico.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{data: ...}` sin campo `success`. `data.general` contiene `totals` y `graph`.\n\n**Reglas:**\n- No recibe filtros: siempre es el mes en curso y el establecimiento principal (id 1).",
        "responses": {
          "200": {
            "description": "Resumen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Resumen",
                    "value": {
                      "data": {
                        "general": {
                          "totals": {
                            "total_documents": "1520.40",
                            "total_sale_notes": "380.00",
                            "total": "2050.40"
                          },
                          "graph": {
                            "labels": [
                              "01",
                              "02",
                              "03"
                            ],
                            "datasets": [
                              {
                                "label": "Total notas de venta",
                                "data": [
                                  120.0,
                                  80.0,
                                  180.0
                                ],
                                "backgroundColor": "rgba(254, 0, 108, .1)",
                                "borderColor": "rgb(254, 0, 108)",
                                "borderWidth": 2,
                                "fill": true,
                                "lineTension": 0.3,
                                "pointRadius": 1
                              }
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/stats/{report_date_start}/{report_date_end}": {
      "get": {
        "tags": [
          "Reportes"
        ],
        "summary": "Estadísticas de ventas por tipo de comprobante",
        "operationId": "EstadisticasVentasTipoComprobante",
        "description": "Devuelve cantidades por tipo (facturas, boletas, notas de crédito y débito, notas de venta) y el total vendido del rango. Las notas de crédito restan del total; solo cuentan comprobantes aceptados.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Un vendedor solo ve sus propias ventas.\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n**Parámetros de la URL:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `startDate` | date | Sí | Fecha inicial `YYYY-MM-DD`. |\n| `endDate` | date | Sí | Fecha final `YYYY-MM-DD`. |",
        "responses": {
          "200": {
            "description": "Estadísticas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estadísticas",
                    "value": {
                      "total": 1900.4,
                      "count": 57,
                      "facturas": 12,
                      "boletas": 33,
                      "notasCredito": 1,
                      "notasDebito": 0,
                      "notasVenta": 11
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "report_date_start",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01"
          },
          {
            "name": "report_date_end",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30"
          }
        ]
      }
    },
    "/api/reports/documents": {
      "get": {
        "tags": [
          "Reportes"
        ],
        "summary": "Reporte de comprobantes",
        "operationId": "ReporteComprobantes",
        "description": "Lista los comprobantes electrónicos del rango con cliente, estado, pagos detallados y totales por afectación. Las notas de crédito salen en negativo y los comprobantes anulados o rechazados en 0.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve directamente un arreglo, o `{success: false, message}` si un filtro por nombre no encuentra coincidencias.\n\n**Filtros por nombre:** `item_name`, `user_name`, `person_name` y `establishment_name` buscan por coincidencia parcial (los `_` se tratan como espacios) y usan el **primer** registro que coincide. Si no encuentran nada responden HTTP 200 con `{success: false, message: \"No se encontro ...\"}`. Sin `date_start` / `date_end` se usa el mes actual.",
        "responses": {
          "200": {
            "description": "Comprobantes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Comprobantes",
                    "value": [
                      {
                        "user": "JUAN PEREZ",
                        "document_type_id": "01",
                        "number": "F001-219",
                        "date_of_issue": "2026-11-04",
                        "date_of_due": "2026-11-04",
                        "document_affected": "",
                        "guides": [],
                        "quotations": "",
                        "district": "MIRAFLORES",
                        "province": "LIMA",
                        "department": "LIMA",
                        "address_customer": "AV. AREQUIPA 450",
                        "document_type_customer": null,
                        "name_customer": "DISTRIBUIDORA ANDINA S.A.C.",
                        "number_customer": "20512345678",
                        "status": "Aceptado",
                        "currency_type_id": "PEN",
                        "sale_note": "",
                        "date_of_issue_sale_note": "",
                        "payments": [
                          {
                            "description": "Efectivo",
                            "payment": 118.0
                          }
                        ],
                        "exchange_rate_sale": 1.0,
                        "total_charge": 0.0,
                        "total_exonerated": 0.0,
                        "total_unaffected": 0.0,
                        "total_taxed": 100.0,
                        "total_discount": 0.0,
                        "total_free": 0.0,
                        "total_igv": 18.0,
                        "total_isc": 0.0,
                        "total": 118.0
                      }
                    ]
                  },
                  "e2": {
                    "summary": "Cliente no encontrado",
                    "value": {
                      "success": false,
                      "message": "No se encontro la persona DISTRIBUIDORA XYZ"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Fecha inicial `YYYY-MM-DD`. Por defecto, inicio del mes actual."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Fecha final. Por defecto, fin del mes actual."
          },
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "01",
            "description": "Tipo de comprobante: `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito."
          },
          {
            "name": "person_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del cliente."
          },
          {
            "name": "establishment_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del establecimiento."
          },
          {
            "name": "seller_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Id del vendedor."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Estado: `01`, `05`, `09`, `11`."
          }
        ]
      }
    },
    "/api/reports/general-items": {
      "get": {
        "tags": [
          "Reportes"
        ],
        "summary": "Reporte de productos vendidos o comprados",
        "operationId": "ReporteProductosVendidosComprados",
        "description": "Lista el detalle por producto (línea por línea) de ventas o compras del rango: comprobante, cliente/proveedor, cantidad, precios, impuestos, total y almacén.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve directamente un arreglo (los campos varían según `type`), o `{success: false, message}` si un filtro por nombre no encuentra coincidencias.\n\n**Filtros por nombre:** `item_name`, `user_name`, `person_name` y `establishment_name` buscan por coincidencia parcial (los `_` se tratan como espacios) y usan el **primer** registro que coincide. Si no encuentran nada responden HTTP 200 con `{success: false, message: \"No se encontro ...\"}`. Sin `date_start` / `date_end` se usa el mes actual. Sin `user_name` se filtra por el usuario autenticado según `user_type`.",
        "responses": {
          "200": {
            "description": "Ventas por producto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ventas por producto",
                    "value": [
                      {
                        "date_of_issue": "2026-11-04",
                        "user": "JUAN PEREZ",
                        "district": "MIRAFLORES",
                        "province": "LIMA",
                        "department": "LIMA",
                        "type_document": "FACTURA ELECTRÓNICA",
                        "serie": "F001",
                        "number": 219,
                        "purchase_order": null,
                        "web_platform": "",
                        "annulled": false,
                        "identity_document_customer": "RUC",
                        "number_document_customer": "20512345678",
                        "customer_name": "DISTRIBUIDORA ANDINA S.A.C.",
                        "seller": "JUAN PEREZ",
                        "observation": "",
                        "currency": "PEN",
                        "unit_type": "NIU",
                        "internal_id": "P0015",
                        "description": "GASEOSA 500 ML",
                        "quantity": 10,
                        "payments_method": "",
                        "unit_value": 2.54,
                        "unit_price": 3.0,
                        "discount": 0,
                        "total_value": 25.42,
                        "affectation_igv_type": "10",
                        "igv": 4.58,
                        "system_isc_type_id": null,
                        "total_isc": 0,
                        "total_plastic_bag_taxes": 0,
                        "total": 30.0,
                        "purchase_total": 18.0,
                        "exchange_rate_sale": 1.0,
                        "warehouse_description": "Almacén - Oficina Principal"
                      }
                    ]
                  },
                  "e2": {
                    "summary": "Producto no encontrado",
                    "value": {
                      "success": false,
                      "message": "No se encontro el item GASEOSA 3L"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "sale",
            "description": "`sale` (por defecto) o `purchase`."
          },
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Fecha inicial `YYYY-MM-DD`. Por defecto, inicio del mes actual."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Fecha final. Por defecto, fin del mes actual."
          },
          {
            "name": "document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Tipo de comprobante (`01`, `03`, `80` nota de venta...)."
          },
          {
            "name": "item_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Descripción (parcial) del producto."
          },
          {
            "name": "user_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del usuario."
          },
          {
            "name": "user_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "VENDEDOR",
            "description": "`CREADOR` (quien registró) o `VENDEDOR` (vendedor asignado)."
          },
          {
            "name": "person_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del cliente."
          },
          {
            "name": "establishment_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del establecimiento."
          },
          {
            "name": "brand_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Id de marca."
          },
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Id de categoría."
          }
        ]
      }
    },
    "/api/reports/quotations": {
      "get": {
        "tags": [
          "Reportes"
        ],
        "summary": "Reporte de cotizaciones",
        "operationId": "ReporteCotizaciones",
        "description": "Lista las cotizaciones del rango con cliente, estado, totales y los comprobantes / notas de venta generados a partir de ellas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve directamente un arreglo, o `{success: false, message}` si un filtro por nombre no encuentra coincidencias.\n\n**Filtros por nombre:** `item_name`, `user_name`, `person_name` y `establishment_name` buscan por coincidencia parcial (los `_` se tratan como espacios) y usan el **primer** registro que coincide. Si no encuentran nada responden HTTP 200 con `{success: false, message: \"No se encontro ...\"}`. Sin `date_start` / `date_end` se usa el mes actual.",
        "responses": {
          "200": {
            "description": "Cotizaciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cotizaciones",
                    "value": [
                      {
                        "date_of_issue": "2026-11-03",
                        "user_name": "JUAN PEREZ",
                        "customer_name": "DISTRIBUIDORA ANDINA S.A.C.",
                        "state": "Registrado",
                        "number_full": "COT-45",
                        "documents": [
                          {
                            "document_type_description": "FACTURA ELECTRÓNICA",
                            "number_full": "F001-219"
                          }
                        ],
                        "sale_notes": [],
                        "case": "",
                        "currency": "PEN",
                        "total_exportation": 0.0,
                        "total_unaffected": 0.0,
                        "total_exonerated": 0.0,
                        "total_taxed": 100.0,
                        "total_igv": 18.0,
                        "total": 118.0
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date_start",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-01",
            "description": "Fecha inicial `YYYY-MM-DD`. Por defecto, inicio del mes actual."
          },
          {
            "name": "date_end",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-30",
            "description": "Fecha final. Por defecto, fin del mes actual."
          },
          {
            "name": "person_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del cliente."
          },
          {
            "name": "establishment_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre (parcial) del establecimiento."
          },
          {
            "name": "seller_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Id del vendedor."
          },
          {
            "name": "state_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Estado de la cotización."
          }
        ]
      }
    },
    "/api/service/{service_type}/{service_number}": {
      "get": {
        "tags": [
          "Consultas"
        ],
        "summary": "Consultar RUC o DNI",
        "operationId": "ConsultarRucDni",
        "description": "Consulta los datos de un RUC o DNI en el servicio de consultas de la plataforma (padrón SUNAT / RENIEC). Con el servicio de consultas adicionales activo también admite carné de extranjería, placa y licencia de conducir. Cada consulta exitosa cuenta para el consumo del plan.\n\n⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `service_type (ruta)` | string | Sí | `ruc`, `dni`; con consultas adicionales: `ce`, `placa`, `licencia`. |\n| `service_number (ruta)` | string | Sí | Número a consultar (11 dígitos RUC, 8 DNI). |\n\n**Respuesta:** para `ruc`, `data` = `{name, trade_name, address, location_id: [dep, prov, dist], condition, state, is_agent_retention}`; para `dni`, `data` = `{name, trade_name, location_id, address, department_id, province_id, district_id, condition, state}`. Puede incluir otras claves de primer nivel del proveedor (p. ej. `source`).\n\n**Errores (HTTP 200 con `success: false`):** número no encontrado o inválido; *El servicio de consulta de placa no está disponible. Active el servicio de consultas adicionales.*",
        "responses": {
          "200": {
            "description": "RUC",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "RUC",
                    "value": {
                      "success": true,
                      "data": {
                        "name": "EMPRESA XYZ S.A.C.",
                        "trade_name": "",
                        "address": "AV. 2 DE MAYO NRO. 123 LIMA - LIMA - LIMA",
                        "location_id": [
                          "15",
                          "1501",
                          "150101"
                        ],
                        "condition": "HABIDO",
                        "state": "ACTIVO",
                        "is_agent_retention": false
                      },
                      "source": "apiperu.dev"
                    }
                  },
                  "e2": {
                    "summary": "No disponible",
                    "value": {
                      "success": false,
                      "message": "El servicio de consulta de placa no está disponible. Active el servicio de consultas adicionales."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "service_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "ruc"
          },
          {
            "name": "service_number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "20501973522"
          }
        ]
      }
    },
    "/api/services/ruc/{ruc_number}": {
      "get": {
        "tags": [
          "Consultas"
        ],
        "summary": "Consultar RUC (servicio anterior)",
        "operationId": "ConsultarRucServicioAnterior",
        "description": "Consulta un RUC directamente en la web de SUNAT. Puede fallar si SUNAT cambia su página: **usa preferentemente *Consultar RUC o DNI***.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Errores (HTTP 200 con `success: false`):** RUC inválido o no encontrado.",
        "responses": {
          "200": {
            "description": "RUC",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "RUC",
                    "value": {
                      "success": true,
                      "data": {
                        "name": "EMPRESA XYZ S.A.C.",
                        "trade_name": "XYZ",
                        "address": "AV. 2 DE MAYO NRO. 123",
                        "phone": "014271148",
                        "department": "LIMA",
                        "department_id": "15",
                        "province": "LIMA",
                        "province_id": "1501",
                        "district": "LIMA",
                        "district_id": "150101"
                      }
                    }
                  },
                  "e2": {
                    "summary": "Inválido",
                    "value": {
                      "success": false,
                      "message": "Ruc debe tener 11 dígitos"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ruc_number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "20501973522"
          }
        ]
      }
    },
    "/api/services/dni/{dni_number}": {
      "get": {
        "tags": [
          "Consultas"
        ],
        "summary": "Consultar DNI (servicio anterior)",
        "operationId": "ConsultarDniServicioAnterior",
        "description": "Consulta un DNI en un servicio público externo. Puede dejar de funcionar sin aviso: **usa preferentemente *Consultar RUC o DNI***.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n`data.name` es apellido paterno + materno + nombres. **Errores (HTTP 200 con `success: false`):** *DNI tiene 8 digitos.*, *Datos no encontrados.*",
        "responses": {
          "200": {
            "description": "DNI",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "DNI",
                    "value": {
                      "success": true,
                      "data": {
                        "number": "45678912",
                        "verification_code": "3",
                        "name": "PEREZ QUISPE JUAN CARLOS",
                        "names": "JUAN CARLOS",
                        "first_name": "PEREZ",
                        "last_name": "QUISPE"
                      }
                    }
                  },
                  "e2": {
                    "summary": "No encontrado",
                    "value": {
                      "success": false,
                      "message": "Datos no encontrados."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "dni_number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "45678912"
          }
        ]
      }
    },
    "/api/services/exchange/{exchange_date}": {
      "get": {
        "tags": [
          "Consultas"
        ],
        "summary": "Tipo de cambio del día",
        "operationId": "TipoCambioDia",
        "description": "Tipo de cambio SUNAT (compra y venta) de una fecha `YYYY-MM-DD`. Usa el registrado en la empresa para esa fecha; si no existe lo consulta y lo guarda.\n\n⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Objeto `{date, purchase, sale}`.\n\n**Reglas:** si el proveedor no responde se devuelve el último tipo de cambio registrado; si no hay ninguno, `purchase` y `sale` valen `1`. No hay respuesta de error explícita.",
        "responses": {
          "200": {
            "description": "Tipo de cambio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Tipo de cambio",
                    "value": {
                      "date": "2026-11-07",
                      "purchase": 3.745,
                      "sale": 3.752
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "exchange_date",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-07"
          }
        ]
      }
    },
    "/api/services/consult_cdr_status": {
      "post": {
        "tags": [
          "Consultas"
        ],
        "summary": "Consultar CDR de un comprobante en SUNAT",
        "operationId": "ConsultarCdrComprobanteSunat",
        "description": "Consulta en SUNAT/OSE el CDR de un comprobante emitido en **producción** y actualiza su estado en la plataforma (útil cuando el envío no devolvió respuesta).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Respuesta `{success, message}` con la descripción del CDR.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `codigo_tipo_documento` | string | Sí | `01`, `03`, `07` u `08`. |\n| `serie_documento` | string | Sí | Serie. |\n| `numero_documento` | integer | Sí | Número. |\n\n**Errores:** `422` `{success: false, message: {campo: [...]}}` si falta un campo; HTTP 200 con `success: false`: *Documento no encontrado* o *Code: <código>; Description: <mensaje SUNAT>*.",
        "responses": {
          "200": {
            "description": "Aceptado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Aceptado",
                    "value": {
                      "success": true,
                      "message": "La Factura numero F001-1520, ha sido aceptada"
                    }
                  },
                  "e2": {
                    "summary": "No encontrado",
                    "value": {
                      "success": false,
                      "message": "Documento no encontrado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "serie_documento": [
                          "El campo serie documento es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Consultar CDR de un comprobante en SUNAT",
                  "value": {
                    "codigo_tipo_documento": "01",
                    "serie_documento": "F001",
                    "numero_documento": 1520
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/services/validate_cpe": {
      "post": {
        "tags": [
          "Consultas"
        ],
        "summary": "Validar comprobante en SUNAT (consulta pública)",
        "operationId": "ValidarComprobanteSunatConsultaPublica",
        "description": "Verifica la validez de un comprobante de **cualquier emisor** en la consulta pública de SUNAT (estado del comprobante y estado/condición del RUC emisor). Útil para validar comprobantes de proveedores.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `numero_ruc_emisor` | string | Sí | RUC del emisor. |\n| `codigo_tipo_documento` | string | Sí | `01`, `03`, `07`, `08`... |\n| `serie_documento` | string | Sí | Serie. |\n| `numero_documento` | string | Sí | Número. |\n| `fecha_de_emision` | date | Sí | `YYYY-MM-DD`. |\n| `total` | numeric | Sí | Importe total. |\n\n**Respuesta:** `data.comprobante_estado_codigo`/`_descripcion` (`0` NO EXISTE, `1` ACEPTADO, `2` ANULADO, `3` AUTORIZADO, `4` NO AUTORIZADO), `empresa_estado_codigo`/`empresa_estado_description` y `empresa_condicion_codigo`/`_descripcion`.\n\n**Reglas y errores:** no hay validación previa (envía los 6 campos). La consulta depende de la web de SUNAT y puede fallar; en ese caso responde HTTP 200 con `{success: false, data: {success: false, message}}` (el mensaje va dentro de `data`). Si la empresa tiene credenciales de la API de SUNAT, prefiere *Validar comprobante con la API de SUNAT*.",
        "responses": {
          "200": {
            "description": "Válido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Válido",
                    "value": {
                      "success": true,
                      "data": {
                        "comprobante_estado_codigo": "1",
                        "comprobante_estado_descripcion": "ACEPTADO",
                        "empresa_estado_codigo": "00",
                        "empresa_estado_description": "ACTIVO",
                        "empresa_condicion_codigo": "00",
                        "empresa_condicion_descripcion": "HABIDO"
                      }
                    }
                  },
                  "e2": {
                    "summary": "Error de consulta",
                    "value": {
                      "success": false,
                      "data": {
                        "success": false,
                        "message": "El codigo de captcha es incorrecto"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Validar comprobante en SUNAT (consulta pública)",
                  "value": {
                    "numero_ruc_emisor": "20456789123",
                    "codigo_tipo_documento": "01",
                    "serie_documento": "F001",
                    "numero_documento": "4587",
                    "fecha_de_emision": "2026-11-01",
                    "total": "1180.00"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/validate-document": {
      "post": {
        "tags": [
          "Consultas"
        ],
        "summary": "Validar comprobante con la API de SUNAT",
        "operationId": "ValidarComprobanteApiSunat",
        "description": "Consulta el estado de un comprobante **emitido por la empresa** en la API de validación de SUNAT (requiere que la empresa tenga configuradas sus credenciales de API SUNAT) y lo traduce al estado de la plataforma.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `document_type_id` | string | Sí | `01`, `03`, `07`, `08`. |\n| `series` | string | Sí | Serie. |\n| `number` | numeric | Sí | Número. |\n| `date_of_issue` | date | Sí | `YYYY-MM-DD`. |\n| `total` | numeric | Sí | Importe total. |\n\n**Respuesta:** `data.state_type_id` (`05` aceptado, `11` anulado, `-1` no existe en SUNAT), `state_type_description`, `code_sunat` (código de SUNAT), `message_sunat`, `state_ruc` y `condition_ruc` del emisor.\n\n**Errores:** `422` `{success: false, message: {campo: [...]}}`; HTTP 200 con `success: false` si SUNAT rechaza la consulta; `500` si la empresa no configuró sus credenciales de API SUNAT.",
        "responses": {
          "200": {
            "description": "Consultado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Consultado",
                    "value": {
                      "success": true,
                      "message": "Consulta realizada correctamente.",
                      "data": {
                        "state_type_id": "05",
                        "state_type_description": "Aceptado",
                        "code_sunat": "1",
                        "message_sunat": "Operation Success! ",
                        "state_ruc": "ACTIVO",
                        "condition_ruc": "HABIDO"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "total": [
                          "El campo total es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Validar comprobante con la API de SUNAT",
                  "value": {
                    "document_type_id": "01",
                    "series": "F001",
                    "number": 1520,
                    "date_of_issue": "2026-11-07",
                    "total": 118.0
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/consultas/search": {
      "post": {
        "tags": [
          "Consultas"
        ],
        "summary": "Buscar comprobante (consulta pública)",
        "operationId": "BuscarComprobanteConsultaPublica",
        "description": "Busca un comprobante emitido por una empresa de la plataforma con los datos impresos en él (como la consulta pública de comprobantes para clientes finales) y devuelve los enlaces de descarga del XML y PDF.\n\n**Endpoint público:** no requiere token (auth: *No Auth*). Solo necesita que la URL sea la del dominio de tu empresa. Tiene límite de peticiones por minuto. Límite: 30 peticiones por minuto (`429` al excederlo). La empresa emisora se identifica con `ruc_emisor` o `tenant_slug`.\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Respuesta `{success, message, data}`; `data` es una lista de coincidencias o `null`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `ruc_emisor` | string | Sí* | RUC (11 dígitos) de la empresa emisora. *Obligatorio si no envías `tenant_slug`. |\n| `tenant_slug` | string | No* | Dominio de la empresa emisora (`empresa.dominio`), alternativa a `ruc_emisor`. |\n| `series` | string | Sí | Serie (máx. 10). |\n| `number` | string | Sí | Número (máx. 20). |\n| `customer_number` | string | Sí | Documento del cliente (máx. 15). |\n| `total` | numeric | Sí | Importe total (≥ 0). |\n| `date_of_issue` | date | Sí | Fecha de emisión `YYYY-MM-DD`. |\n\n**Reglas:** las URLs de descarga son relativas al protocolo (empiezan con `//`): antepón `https:`.\n\n**Errores:** HTTP 200 con `{success: false, message, data: null}`: *No se encontró una empresa activa con los datos ingresados.*, *La empresa emisora se encuentra temporalmente inactiva.*, *El número de documento del cliente no fue encontrado.*, *No se encontró un comprobante con los datos ingresados.*; `422` `{success: false, message: {campo: [...]}}` si falta un campo; `429` por exceso de peticiones.",
        "responses": {
          "200": {
            "description": "Encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Encontrado",
                    "value": {
                      "success": true,
                      "message": "Comprobante encontrado",
                      "data": [
                        {
                          "customer": "20501973522",
                          "number": "F001-1520",
                          "total": "118.00",
                          "download_xml": "//empresa.dominio/downloads/document/xml/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77",
                          "download_pdf": "//empresa.dominio/downloads/document/pdf/9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77"
                        }
                      ]
                    }
                  },
                  "e2": {
                    "summary": "Sin resultados",
                    "value": {
                      "success": false,
                      "message": "No se encontró un comprobante con los datos ingresados.",
                      "data": null
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "ruc_emisor": [
                          "El campo ruc emisor es obligatorio cuando tenant slug no está presente."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Buscar comprobante (consulta pública)",
                  "value": {
                    "ruc_emisor": "20123456789",
                    "tenant_slug": null,
                    "series": "F001",
                    "number": "1520",
                    "customer_number": "20501973522",
                    "total": 118.0,
                    "date_of_issue": "2026-11-07"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/company": {
      "get": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Datos de inicio (empresa, series, cobros)",
        "operationId": "DatosInicioEmpresaSeriesCobros",
        "description": "Datos para iniciar una caja o app de ventas: series del usuario, su establecimiento, datos de la empresa, hasta 2000 clientes habilitados (formato API de comprobantes), métodos de pago que se pueden usar para cobrar y destinos del dinero (caja y cuentas que reciben cobros).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n**Reglas:**\n- Para buscar clientes usa *Buscar clientes (formato API de comprobantes)* en lugar de la lista inicial.\n- En cada método de pago, `goes_to_cash_drawer` y `allowed_destination_type` indican a qué destino debe ir el cobro.\n\n**Datos de la empresa:** el objeto `company` trae los datos públicos de la empresa (id, RUC `number`, razón social `name`, `trade_name`, `logo`, tipo de documento, entorno `soap_type_id`...). No incluye credenciales SOL/OSE/PSE, certificado, claves de API ni tokens; la configuración SUNAT (sin secretos) se consulta en *Ver configuración SUNAT* (`GET /api/company/sunat-config`, solo administradores).",
        "responses": {
          "200": {
            "description": "Datos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos",
                    "value": {
                      "series": [
                        {
                          "id": 1,
                          "document_type_id": "01",
                          "number": "F001",
                          "establishment_id": 1
                        }
                      ],
                      "establishments": [
                        {
                          "id": 1,
                          "description": "Oficina Principal",
                          "country_id": "PE",
                          "department_id": "15",
                          "province_id": "1501",
                          "district_id": "150101",
                          "address": "AV. PRINCIPAL 123",
                          "email": "ventas@miempresa.pe",
                          "telephone": "014567890",
                          "code": "0000",
                          "customer_id": null
                        }
                      ],
                      "company": {
                        "id": 1,
                        "identity_document_type_id": "6",
                        "number": "20123456789",
                        "name": "MI EMPRESA S.A.C.",
                        "trade_name": "MI EMPRESA",
                        "logo": "logo_20123456789.png"
                      },
                      "customers": [
                        {
                          "id": 25,
                          "codigo_tipo_documento_identidad": "6",
                          "numero_documento": "20601234567",
                          "apellidos_y_nombres_o_razon_social": "COMERCIAL NORTE E.I.R.L.",
                          "codigo_pais": "PE",
                          "direccion": "AV. PRINCIPAL 123, LIMA",
                          "correo_electronico": "compras@comercialnorte.pe",
                          "telefono": "987654321"
                        }
                      ],
                      "payment_method_types": [
                        {
                          "id": "01",
                          "description": "Efectivo",
                          "goes_to_cash_drawer": true,
                          "allowed_destination_type": "cash"
                        },
                        {
                          "id": "05",
                          "description": "Yape",
                          "goes_to_cash_drawer": false,
                          "allowed_destination_type": "bank_account"
                        }
                      ],
                      "payment_destinations": [
                        {
                          "id": "cash",
                          "description": "CAJA GENERAL"
                        },
                        {
                          "id": 2,
                          "description": "BCP - Cta. corriente 191-1234567-0-12"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/app-configurations/record": {
      "get": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Configuración de la app",
        "operationId": "ConfiguracionApp",
        "description": "Configuración visual y de impresión de la app de ventas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve `{data: {...}}`.",
        "responses": {
          "200": {
            "description": "Configuración",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Configuración",
                    "value": {
                      "data": {
                        "id": 1,
                        "show_image_item": true,
                        "print_format_pdf": "ticket",
                        "theme_color": "blue",
                        "card_color": "unicolor",
                        "header_waves": true,
                        "app_mode": "default",
                        "direct_print": false,
                        "has_igv_31556": false,
                        "igv_31556_percentage": 0.1,
                        "direct_send_documents_whatsapp": false,
                        "primary_color": "#020F3C"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/app-configurations": {
      "post": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Guardar configuración de la app",
        "operationId": "GuardarConfiguracionApp",
        "description": "Actualiza las opciones de la app de ventas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `show_image_item` | boolean | Sí | Mostrar imágenes de productos. |\n| `print_format_pdf` | string | No | Formato de impresión del PDF: `ticket`, `ticket_58`, `a4`, `a5`. |\n| `direct_print` | boolean | No | Imprimir directamente al emitir. |\n\n**Reglas:**\n- Solo cambian esos tres campos; los colores y el modo se configuran desde el panel.\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`.",
        "responses": {
          "200": {
            "description": "Guardado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardado",
                    "value": {
                      "success": true,
                      "message": "Configuración actualizada",
                      "data": {
                        "id": 1,
                        "show_image_item": true,
                        "print_format_pdf": "ticket",
                        "theme_color": "blue",
                        "card_color": "unicolor",
                        "header_waves": true,
                        "app_mode": "default",
                        "direct_print": false,
                        "has_igv_31556": false,
                        "igv_31556_percentage": 0.1,
                        "direct_send_documents_whatsapp": false,
                        "primary_color": "#020F3C"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Guardar configuración de la app",
                  "value": {
                    "show_image_item": true,
                    "print_format_pdf": "ticket",
                    "direct_print": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/app-configurations/initial-settings": {
      "get": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Configuración inicial de la app",
        "operationId": "ConfiguracionInicialApp",
        "description": "Estilos, módulos permitidos al usuario del token, tipos de comprobante del punto de venta, logos y datos del usuario.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Inicial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Inicial",
                    "value": {
                      "style_settings": {
                        "app_mode": "default",
                        "theme_color": "blue",
                        "card_color": "unicolor",
                        "header_waves": true,
                        "style_theme_content": ":root{--primary:#020F3C}",
                        "style_card_content": ".card{}"
                      },
                      "permissions": [
                        {
                          "id": 1,
                          "value": "pos",
                          "description": "Punto de venta"
                        }
                      ],
                      "generals": {
                        "pos_document_types": [
                          {
                            "document_type_id": "01",
                            "module": "invoice"
                          },
                          {
                            "document_type_id": "03",
                            "module": "invoice-ticket"
                          },
                          {
                            "document_type_id": "80",
                            "module": "sale-note"
                          }
                        ],
                        "app_logo": "https://empresa.dominio/storage/uploads/logos/app_logo.png",
                        "app_logo_dark": null,
                        "user_data": {
                          "type": "seller",
                          "establishment_id": 1,
                          "establishment": {
                            "id": 1,
                            "description": "Oficina Principal",
                            "country_id": "PE",
                            "department_id": "15",
                            "province_id": "1501",
                            "district_id": "150101",
                            "address": "AV. PRINCIPAL 123",
                            "email": "ventas@miempresa.pe",
                            "telephone": "014567890",
                            "code": "0000",
                            "customer_id": null
                          }
                        }
                      },
                      "multi_user_enabled": false
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/configuration-web": {
      "get": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Opciones web (consignados)",
        "operationId": "OpcionesWebConsignados",
        "description": "Indica si la empresa trabaja con consignados en las direcciones de sus clientes (sección [Consignaciones, placas, e-commerce y Vendeya](/docs/api/tenant/consignaciones-ecommerce)).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Opciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Opciones",
                    "value": {
                      "success": true,
                      "data": {
                        "enable_consigned": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/user-permissions/{user_id}": {
      "get": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Permisos de un usuario",
        "operationId": "PermisosUsuario",
        "description": "Permisos del usuario: módulos y submódulos del panel, permisos de pagos, de compras y otros (editar comprobantes, recrear, envío por resumen).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n**Errores:**\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`",
        "responses": {
          "200": {
            "description": "Permisos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Permisos",
                    "value": {
                      "other_permissions": {
                        "permission_edit_cpe": false,
                        "recreate_documents": false,
                        "permission_force_send_by_summary": false
                      },
                      "payments": {
                        "create_payment": true,
                        "delete_payment": false
                      },
                      "purchases": {
                        "edit_purchase": false,
                        "annular_purchase": false,
                        "delete_purchase": false
                      },
                      "modules": [
                        {
                          "id": 1,
                          "value": "documents",
                          "description": "Ventas",
                          "levels": [
                            {
                              "id": 1,
                              "value": "new_document",
                              "description": "Nuevo comprobante"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ]
      }
    },
    "/api/store/get_igv": {
      "post": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Tasa de IGV aplicable",
        "operationId": "TasaIgvAplicable",
        "description": "Devuelve la tasa de IGV para un establecimiento y fecha: `0.18`, o la tasa reducida de la Ley 31556 si el establecimiento está acogido y la fecha está en el periodo vigente.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Devuelve solo el número (p. ej. `0.18`).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `establishment_id` | integer | Sí | Id del establecimiento. |\n| `date` | date | Sí | Fecha de emisión `YYYY-MM-DD`. |",
        "responses": {
          "200": {
            "description": "Tasa",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Tasa",
                    "value": 0.18
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Tasa de IGV aplicable",
                  "value": {
                    "establishment_id": "1",
                    "date": "2026-11-07"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/multi-users/records": {
      "get": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Empresas vinculadas (multiusuario)",
        "operationId": "EmpresasVinculadasMultiusuario",
        "description": "Empresas a las que el usuario del token puede cambiar sin volver a iniciar sesión (incluida la actual, con `id: null`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`). Arreglo sin envoltura.",
        "responses": {
          "200": {
            "description": "Empresas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Empresas",
                    "value": [
                      {
                        "id": 4,
                        "is_destination": true,
                        "client_full_name": "20987654321 - SUCURSAL NORTE S.A.C.",
                        "fqdn": "norte.dominio"
                      },
                      {
                        "id": null,
                        "is_destination": true,
                        "client_full_name": "20123456789 - MI EMPRESA S.A.C.",
                        "fqdn": "empresa.dominio"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/multi-users/change-client": {
      "post": {
        "tags": [
          "Configuración y empresa"
        ],
        "summary": "Cambiar a otra empresa (multiusuario)",
        "operationId": "CambiarAOtraEmpresaMultiusuario",
        "description": "Devuelve el token y los datos del usuario vinculado en la empresa elegida. Después usa ese `api_token` y el dominio `fqdn` como `base_url`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `multi_user_id` | integer | Sí | `id` de la fila elegida en *Empresas vinculadas*. |\n| `is_destination` | boolean | Sí | `is_destination` de esa fila. |\n| `fqdn` | string | Sí | `fqdn` de esa fila; debe coincidir con la empresa del vínculo. |\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`.\n- Si el `fqdn` no coincide o el vínculo no existe responde **HTTP 500** con `success: false` y el motivo en `message`.\n- Si el usuario destino no tiene token: HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Datos de la empresa destino",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Datos de la empresa destino",
                    "value": {
                      "success": true,
                      "user_name": "Ventas Norte",
                      "user_email": "ventas@norte.pe",
                      "establishment_id": 1,
                      "api_token": "Xy9kL2mN4pQ7rS1tU3vW5xY8zA0bC6dE",
                      "ruc": "20987654321",
                      "app_logo": "logo_20987654321.png",
                      "company": {
                        "name": "SUCURSAL NORTE S.A.C.",
                        "address": "LIMA, LIMA, LIMA, AV. NORTE 100",
                        "phone": "014445566",
                        "email": "ventas@norte.pe"
                      },
                      "app_configuration": {
                        "id": 1,
                        "show_image_item": true,
                        "print_format_pdf": "ticket",
                        "theme_color": "blue",
                        "card_color": "unicolor",
                        "header_waves": true,
                        "app_mode": "default",
                        "direct_print": false,
                        "has_igv_31556": false,
                        "igv_31556_percentage": 0.1,
                        "direct_send_documents_whatsapp": false,
                        "primary_color": "#020F3C"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "fqdn distinto",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "fqdn distinto",
                    "value": {
                      "success": false,
                      "message": "El fqdn actual es diferente al obtenido para iniciar sesión: otro.dominio - norte.dominio"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar a otra empresa (multiusuario)",
                  "value": {
                    "multi_user_id": "1",
                    "is_destination": true,
                    "fqdn": "norte.dominio"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/document-file/{print_model}/{document_external_id}/{print_format}": {
      "get": {
        "tags": [
          "Descargas"
        ],
        "summary": "Descargar PDF",
        "operationId": "DescargarPdf2",
        "description": "Devuelve el **PDF** de un documento en el formato pedido (lo genera si aún no existe en ese formato). Es el mismo enlace que llega en `data_ws.pdf_a4_filename` al emitir.\n\n⚠️ Este endpoint usa GET por compatibilidad; próximamente tendrá una versión POST.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. `application/pdf` (inline).\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `print_model (ruta)` | string | Sí | `document` comprobante electrónico (factura, boleta, notas), `dispatch` guía de remisión, `saleNote` nota de venta, `quotation` cotización, `income` ingreso, `expense` gasto. Para notas de venta usa `salenote`. |\n| `document_external_id (ruta)` | string (uuid) | Sí | `external_id` del documento. |\n| `print_format (ruta)` | string | Sí | `a4`, `a5`, `ticket` (80 mm), `ticket_58` (58 mm). |\n\n**Errores:** `500` `{success: false, message}` si el `external_id` no existe para ese modelo.",
        "responses": {
          "200": {
            "description": "PDF"
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "El código 9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77 es inválido, no se encontro documento relacionado"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "print_model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "document"
          },
          {
            "name": "document_external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "print_format",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "a4"
          }
        ]
      }
    },
    "/api/document-print-pdf/{print_model}/{document_external_id}/{print_format}/{extend_pdf_height}": {
      "get": {
        "tags": [
          "Descargas"
        ],
        "summary": "Vista de impresión HTML",
        "operationId": "VistaImpresionHtml",
        "description": "Devuelve la **plantilla de impresión en HTML** (no un PDF) de un comprobante o nota de venta, con estilos `@media print` ajustados al ancho del ticket. Pensado para imprimir directamente desde una app o navegador.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. `text/html`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `print_model (ruta)` | string | Sí | `document` (comprobante) o `saleNote` (nota de venta). |\n| `document_external_id (ruta)` | string (uuid) | Sí | `external_id` del documento. |\n| `print_format (ruta)` | string | Sí | `a4`, `a5`, `ticket` (ancho 78 mm), `ticket_58` (56 mm). |\n| `extend_pdf_height (ruta)` | integer | No | Píxeles de alto adicionales al final (margen para el corte del papel). Puedes omitir el segmento; por defecto `0`. |\n\n**Errores:** `500` `{success: false, message}` si el `external_id` no existe.",
        "responses": {
          "200": {
            "description": "HTML"
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "El código 9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77 es inválido, no se encontro documento relacionado"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "print_model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "document"
          },
          {
            "name": "document_external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "print_format",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "a4"
          },
          {
            "name": "extend_pdf_height",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "0"
          }
        ]
      }
    },
    "/api/document-print-pdf-text/{print_model}/{document_external_id}/{print_format}": {
      "get": {
        "tags": [
          "Descargas"
        ],
        "summary": "Vista de impresión en texto",
        "operationId": "VistaImpresionTexto",
        "description": "Devuelve el contenido de impresión del comprobante o nota de venta convertido a **texto plano**, para impresoras térmicas que imprimen texto.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). No se restringe por vendedor: cualquier usuario puede operar sobre cualquier registro de la empresa.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. `text/plain`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `print_model (ruta)` | string | Sí | `document` o `saleNote`. |\n| `document_external_id (ruta)` | string (uuid) | Sí | `external_id` del documento. |\n| `print_format (ruta)` | string | Sí | `ticket`, `ticket_58`, `a4`... |\n\n**Errores:** `500` `{success: false, message}` si el `external_id` no existe.",
        "responses": {
          "200": {
            "description": "Texto"
          },
          "500": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "El código 9b2f6c1e-7a44-4d0b-9a55-0f3c2a1d8e77 es inválido, no se encontro documento relacionado"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "print_model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "document"
          },
          {
            "name": "document_external_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "print_format",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "a4"
          }
        ]
      }
    },
    "/api/qrapi/send-message": {
      "post": {
        "tags": [
          "Mensajería"
        ],
        "summary": "Enviar PDF por WhatsApp (QR)",
        "operationId": "EnviarPdfWhatsappQr",
        "description": "Envía un comprobante PDF por WhatsApp desde el número conectado por QR en la configuración de la empresa; opcionalmente envía además un texto con un enlace.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `number` | string | Sí | Número destino con código de país, sin `+` (p. ej. `51987654321`). |\n| `file` | string | Sí | PDF: URL pública o contenido en base64. |\n| `filename` | string | Sí | Nombre del archivo que verá el destinatario. |\n| `message` | string | Sí | Texto que acompaña al PDF. |\n| `link` | string | No | Enlace para un segundo mensaje: `<message>: puede revisarlo en el siguiente enlace <link>`. |\n\n**Reglas:**\n- Requiere la opción de mensajes por QR habilitada y un número conectado.\n- Hay un límite de mensajes según el plan de la empresa.\n\n**Errores:**\n- `422` si falta un campo, la opción no está habilitada, no hay número conectado o se superó el límite (`success: false`, `message`).\n- `500` si el proveedor de WhatsApp no pudo enviar.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "data": {
                        "key": {
                          "id": "3EB0A1B2C3D4"
                        },
                        "status": "PENDING"
                      },
                      "media_sent": true,
                      "link_sent": true
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "No habilitado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No habilitado",
                    "value": {
                      "success": false,
                      "message": "La opción de enviar mensajes no está habilitada"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Falló el envío",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Falló el envío",
                    "value": {
                      "success": false,
                      "message": "No se pudo enviar el comprobante por WhatsApp."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar PDF por WhatsApp (QR)",
                  "value": {
                    "number": "51987654321",
                    "file": "https://empresa.dominio/print/document/a1b2c3d4-e5f6-4789-abcd-ef0123456789/a4",
                    "filename": "F001-245.pdf",
                    "message": "Hola, te enviamos tu comprobante F001-245",
                    "link": "https://empresa.dominio/print/document/a1b2c3d4-e5f6-4789-abcd-ef0123456789/a4"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/whatsapp-cloud/send-message": {
      "post": {
        "tags": [
          "Mensajería"
        ],
        "summary": "Enviar mensaje por WhatsApp Cloud API",
        "operationId": "EnviarMensajeWhatsappCloudApi",
        "description": "Envía un texto o un documento por la API oficial de WhatsApp (Meta) con el número y token configurados por la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `send_type` | string | Sí | `text` o `document`. |\n| `phone_number` | numeric | Sí | Número destino **sin** código de país. |\n| `prefix_number` | string | No | Código de país (por defecto `51`). |\n| `message` | string | Sí si `send_type = text` | Texto del mensaje. |\n| `document.link` | string | Sí si `send_type = document` | URL pública del documento. |\n| `document.filename` | string | Sí si `send_type = document` | Nombre del archivo. |\n| `document.caption` | string | No | Texto que acompaña al documento. |\n\n**Reglas:**\n- La empresa debe tener configurados el identificador del número y el token de acceso de WhatsApp Cloud.\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`.\n- Falta configuración o Meta rechaza el mensaje: HTTP 200 con `success: false` y el detalle en `message`.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "message": "Mensaje enviado correctamente."
                    }
                  },
                  "e2": {
                    "summary": "Sin configuración",
                    "value": {
                      "success": false,
                      "message": "No tiene registrado correctamente el token de acceso"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Enviar mensaje por WhatsApp Cloud API",
                  "value": {
                    "send_type": "document",
                    "phone_number": "987654321",
                    "prefix_number": "51",
                    "message": "Hola, te enviamos tu comprobante",
                    "document": {
                      "link": "https://empresa.dominio/print/document/a1b2c3d4-e5f6-4789-abcd-ef0123456789/a4",
                      "filename": "F001-245.pdf",
                      "caption": "Comprobante F001-245"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/consigneds/records": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Listar consignados (paginado)",
        "operationId": "ListarConsignadosPaginado",
        "description": "Lista paginada de consignados (personas que reciben la mercadería en nombre del cliente).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado **paginado por página** `{data[], links: {first, last, prev, next}, meta: {current_page, last_page, per_page, total, ...}}`. Usa el query param `page` para avanzar.\n\n**Reglas:**\n- Para la lista completa sin paginar usa *Todos los consignados*.",
        "responses": {
          "200": {
            "description": "Consignados",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Consignados",
                    "value": {
                      "data": [
                        {
                          "id": 3,
                          "identity_document_type_id": "1",
                          "number": "45678912",
                          "name": "ROSA HUAMAN TORRES",
                          "telephone": "987111222",
                          "created_at": "2026-11-07 10:15:00",
                          "updated_at": "2026-11-07 10:15:00"
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/consigneds/records?page=1",
                        "last": "https://empresa.dominio/api/consigneds/records?page=1",
                        "prev": null,
                        "next": null
                      },
                      "meta": {
                        "current_page": 1,
                        "from": 1,
                        "last_page": 1,
                        "path": "https://empresa.dominio/api/consigneds/records",
                        "per_page": 20,
                        "to": 1,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      }
    },
    "/api/consigneds/data": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Todos los consignados",
        "operationId": "TodosConsignados",
        "description": "Lista completa de consignados, sin paginar.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Consignados",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Consignados",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "identity_document_type_id": "1",
                          "number": "45678912",
                          "name": "ROSA HUAMAN TORRES",
                          "telephone": "987111222",
                          "created_at": "2026-11-07 10:15:00",
                          "updated_at": "2026-11-07 10:15:00"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/consigneds/record/{consigned_id}": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Ver consignado",
        "operationId": "VerConsignado",
        "description": "Devuelve un consignado.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).\n\n**Errores:**\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`",
        "responses": {
          "200": {
            "description": "Consignado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Consignado",
                    "value": {
                      "id": 3,
                      "identity_document_type_id": "1",
                      "number": "45678912",
                      "name": "ROSA HUAMAN TORRES",
                      "telephone": "987111222",
                      "created_at": "2026-11-07T15:15:00.000000Z",
                      "updated_at": "2026-11-07T15:15:00.000000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "consigned_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/consigneds": {
      "post": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Crear o editar consignado",
        "operationId": "CrearEditarConsignado",
        "description": "Registra un consignado o, si envías `id`, lo edita.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | No | Id a editar; omítelo para crear. |\n| `identity_document_type_id` | string | Sí | Tipo de documento (`1` DNI, `4` CE, `6` RUC, `7` pasaporte). |\n| `number` | string | Sí | Número de documento. |\n| `name` | string | Sí | Nombre. |\n| `telephone` | string | No | Teléfono. |\n\n**Reglas:**\n- No hay validación de campos: envía todos los obligatorios.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "id": 3,
                      "success": true,
                      "message": "Consignado registrado con éxito"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear o editar consignado",
                  "value": {
                    "identity_document_type_id": "1",
                    "number": "45678912",
                    "name": "ROSA HUAMAN TORRES",
                    "telephone": "987111222"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/consigneds/store-document": {
      "post": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Registrar consignado en dirección de cliente",
        "operationId": "RegistrarConsignadoDireccionCliente",
        "description": "Agrega al cliente una **nueva dirección de entrega con consignado**. Si ya existe un consignado con ese número se reutiliza; si no, se crea.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `person_id` | integer | Sí | Id del cliente. |\n| `identity_document_type_id / number / name` | string | Sí | Documento y nombre del consignado. |\n| `telephone` | string | No | Teléfono (también se guarda en la dirección). |\n| `country_id` | string | Sí | País de la dirección (`PE`). |\n| `location_id` | array | Sí | Ubigeo `[departamento, provincia, distrito]`. |\n| `address` | string | Sí | Dirección de entrega. |\n| `establishment_code` | string | No | Código de establecimiento anexo SUNAT. |\n\n**Errores:**\n- Sin ubigeo de 3 elementos o dirección repetida (mismo cliente, distrito y dirección): HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Registrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Registrado",
                    "value": {
                      "id": 3,
                      "success": true,
                      "message": "Consignado registrado con éxito"
                    }
                  },
                  "e2": {
                    "summary": "Dirección repetida",
                    "value": {
                      "success": false,
                      "message": "Dirección ya existe"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar consignado en dirección de cliente",
                  "value": {
                    "person_id": "1",
                    "identity_document_type_id": "1",
                    "number": "45678912",
                    "name": "ROSA HUAMAN TORRES",
                    "telephone": "987111222",
                    "country_id": "PE",
                    "location_id": [
                      "04",
                      "0401",
                      "040101"
                    ],
                    "address": "AV. EJERCITO 710, AREQUIPA",
                    "establishment_code": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/consigneds/search_by_customer/{customer_id}": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Consignados de un cliente",
        "operationId": "ConsignadosCliente",
        "description": "Consignados asociados a las direcciones de un cliente.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Los registros vienen en `consigneds`, no en `data`.",
        "responses": {
          "200": {
            "description": "Consignados",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Consignados",
                    "value": {
                      "success": true,
                      "consigneds": [
                        {
                          "id": 3,
                          "description": "45678912 - ROSA HUAMAN TORRES",
                          "name": "ROSA HUAMAN TORRES",
                          "number": "45678912",
                          "identity_document_type_id": "1"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/consigneds/addresses": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Direcciones de un consignado",
        "operationId": "DireccionesConsignado",
        "description": "Direcciones del cliente que tienen asignado el consignado.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`. Los registros vienen en `consigned_addresses`.",
        "responses": {
          "200": {
            "description": "Direcciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Direcciones",
                    "value": {
                      "success": true,
                      "consigned_addresses": [
                        {
                          "id": 9,
                          "district_id": "040101",
                          "address": "AV. EJERCITO 710, AREQUIPA"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "consigned_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Id del consignado."
          },
          {
            "name": "person_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Id del cliente."
          }
        ]
      }
    },
    "/api/consigneds/tables": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Catálogos para consignados",
        "operationId": "CatalogosConsignados",
        "description": "Tipos de documento de identidad, países y ubigeos para el formulario de consignado.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado **sin envoltura**: devuelve directamente el objeto o arreglo (sin `success`).",
        "responses": {
          "200": {
            "description": "Catálogos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogos",
                    "value": {
                      "identity_document_types": [
                        {
                          "id": "1",
                          "active": 1,
                          "description": "DNI"
                        },
                        {
                          "id": "6",
                          "active": 1,
                          "description": "RUC"
                        }
                      ],
                      "countries": [
                        {
                          "id": "PE",
                          "active": 1,
                          "description": "PERU"
                        }
                      ],
                      "locations": [
                        {
                          "value": "15",
                          "label": "LIMA",
                          "children": [
                            {
                              "value": "1501",
                              "label": "LIMA",
                              "children": [
                                {
                                  "value": "150101",
                                  "label": "LIMA (150101)"
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/plates/{customer_id}": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Placas de un cliente",
        "operationId": "PlacasCliente",
        "description": "Placas de vehículo registradas para un cliente habilitado (giro grifo / estación de servicio).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Errores:**\n- Cliente inexistente o inhabilitado: HTTP 200 con `success: false` y `data: []`.",
        "responses": {
          "200": {
            "description": "Placas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Placas",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 5,
                          "value": "ABC-123"
                        },
                        {
                          "id": 6,
                          "value": "XYZ-987"
                        }
                      ]
                    }
                  },
                  "e2": {
                    "summary": "Cliente no válido",
                    "value": {
                      "success": false,
                      "message": "El cliente no existe o no está habilitado",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/plates": {
      "post": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Registrar placa",
        "operationId": "RegistrarPlaca",
        "description": "Registra una placa para un cliente. Se guarda en mayúsculas y sin espacios al inicio o final; si ya estaba registrada no se duplica.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `person_id` | integer | Sí | Id del cliente (habilitado). |\n| `value` | string | Sí | Placa (máx. 20). También se acepta en la clave `plates`. |\n\n**Reglas:**\n- Responde la lista completa de placas del cliente en `data` y el id de la placa en `id`.\n\n**Errores:**\n- Validación: `422` con `{success: false, message: {campo: [mensajes]}}`.\n- Cliente inexistente o inhabilitado: HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Guardada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardada",
                    "value": {
                      "success": true,
                      "message": "Placa guardada con éxito",
                      "id": 5,
                      "data": [
                        {
                          "id": 5,
                          "value": "ABC-123"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "value": [
                          "El campo value es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Registrar placa",
                  "value": {
                    "person_id": "1",
                    "value": "ABC-123"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/plates/{plate_id}/destroy": {
      "post": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Eliminar placa",
        "operationId": "EliminarPlaca",
        "description": "Elimina una placa por su id.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Errores:**\n- Id inexistente: HTTP 200 con `success: false`.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "message": "Placa eliminada con éxito"
                    }
                  },
                  "e2": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "La placa no existe"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "plate_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/orders": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Pedidos de la tienda virtual",
        "operationId": "PedidosTiendaVirtual",
        "description": "Pedidos recibidos por la tienda virtual (e-commerce), más recientes primero, 20 por página. **No confundir** con los pedidos internos de la sección [Pedidos](/docs/api/tenant/pedidos).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado **paginado por página** `{data[], links: {first, last, prev, next}, meta: {current_page, last_page, per_page, total, ...}}`. Usa el query param `page` para avanzar.\n\nEstados (`status_order_id`): `1` pago sin verificar, `2` pago verificado, `3` despachado, `4` confirmado por el cliente (la empresa puede tener estados adicionales).",
        "responses": {
          "200": {
            "description": "Pedidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pedidos",
                    "value": {
                      "data": [
                        {
                          "id": 12,
                          "external_id": "f1e2d3c4-b5a6-4789-9abc-def012345678",
                          "number_document": null,
                          "order_id": "PED-000012",
                          "order_code": "A7K2Q9",
                          "customer": "PEDRO QUISPE MAMANI",
                          "customer_email": "pedro.quispe@correo.pe",
                          "customer_telefono": "987654321",
                          "customer_direccion": "JR. HUALLAGA 321, LIMA",
                          "customer_document_number": "45678912",
                          "customer_document_type": "DNI",
                          "is_guest": false,
                          "items": [
                            {
                              "id": 31,
                              "description": "GASEOSA COCA COLA 500ML",
                              "cantidad": 6,
                              "sale_unit_price": 2.5
                            }
                          ],
                          "total": 15.0,
                          "total_discount": 0,
                          "discount_coupont": null,
                          "reference_payment": "YAPE-984512",
                          "document_external_id": null,
                          "created_at": "2026-11-07 11:30:00",
                          "status_order_id": 1,
                          "payment_status_order_id": 1,
                          "shipping_status_order_id": null,
                          "tracking_code": null,
                          "purchase": null,
                          "document_type_id": null,
                          "has_sale_note": false,
                          "sale_note_number_full": null,
                          "sale_note_id": null
                        }
                      ],
                      "links": {
                        "first": "https://empresa.dominio/api/orders?page=1",
                        "last": "https://empresa.dominio/api/orders?page=1",
                        "prev": null,
                        "next": null
                      },
                      "meta": {
                        "current_page": 1,
                        "from": 1,
                        "last_page": 1,
                        "path": "https://empresa.dominio/api/orders",
                        "per_page": 20,
                        "to": 1,
                        "total": 1
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Número de página."
          }
        ]
      },
      "post": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Cambiar estado de pedido de la tienda virtual",
        "operationId": "CambiarEstadoPedidoTiendaVirtual",
        "description": "Cambia el estado de un pedido de la tienda virtual.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del pedido. |\n| `status_order_id` | integer | Sí | Nuevo estado (ver *Pedidos de la tienda virtual*). |\n\n**Reglas:**\n- No hay validación de campos: un `status_order_id` inexistente produce error.\n\n**Errores:**\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`",
        "responses": {
          "200": {
            "description": "Actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Actualizado",
                    "value": {
                      "success": true,
                      "message": "Orden actualizada con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar estado de pedido de la tienda virtual",
                  "value": {
                    "id": "1",
                    "status_order_id": 2
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sellnow/items": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Vendeya: productos",
        "operationId": "VendeyaProductos",
        "description": "Catálogo completo (sin paginar) para Vendeya: productos activos con código interno y stock en el almacén del establecimiento del usuario, favoritos primero. Incluye insumos, combos, modificadores y, si la empresa usa lista de precios, las presentaciones con sus precios.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n**Reglas:**\n- Con `group_variations=1` las variaciones viajan dentro de su producto padre (`variations`) en lugar de como productos sueltos.",
        "responses": {
          "200": {
            "description": "Productos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Productos",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 31,
                          "unit_type_id": "NIU",
                          "category_id": 7,
                          "description": "GASEOSA COCA COLA 500ML",
                          "name": "Gaseosa personal",
                          "second_name": null,
                          "warehouse_id": null,
                          "internal_id": "P0001",
                          "barcode": "7751271001234",
                          "item_code": "50202301",
                          "item_code_gs1": null,
                          "stock": 120,
                          "stock_min": 10,
                          "currency_type_id": "PEN",
                          "currency_type_symbol": "S/",
                          "sale_affectation_igv_type_id": "10",
                          "price": "2.50",
                          "calculate_quantity": false,
                          "has_igv": true,
                          "active": true,
                          "sale_unit_price": "S/ 2.50",
                          "purchase_unit_price": "S/ 1.80",
                          "created_at": "2026-10-01 09:00:00",
                          "updated_at": "2026-11-07 10:00:00",
                          "apply_store": false,
                          "apply_restaurant": false,
                          "restaurant_favorite": false,
                          "image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
                          "image_url_medium": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31-medium.jpg",
                          "image_url_small": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31-small.jpg",
                          "favorite": true,
                          "area_print": null,
                          "has_supplies": false,
                          "is_dish": false,
                          "has_sets": false,
                          "items_sets": [],
                          "modifiers": [],
                          "parent_item_id": null,
                          "variation_label": null,
                          "variation_attributes": [],
                          "variations_count": 0,
                          "has_variations": false,
                          "variation_variables": [],
                          "variations": [],
                          "item_unit_types": []
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "group_variations",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` agrupa las variaciones (talla, color...) dentro del producto padre."
          }
        ]
      }
    },
    "/api/sellnow/categories": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Vendeya: categorías",
        "operationId": "VendeyaCategorias",
        "description": "Todas las categorías de productos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.",
        "responses": {
          "200": {
            "description": "Categorías",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Categorías",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 7,
                          "name": "BEBIDAS",
                          "image": "imagen-no-disponible.jpg",
                          "created_at": "2026-10-01T14:00:00.000000Z",
                          "updated_at": "2026-10-01T14:00:00.000000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/sellnow/favoriteitem": {
      "post": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Vendeya: alternar favorito",
        "operationId": "VendeyaAlternarFavorito",
        "description": "Alterna el producto entre favorito y no favorito.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** heredado `{success, message?, data?}` sin paginación. Ante reglas de negocio puede responder **HTTP 200 con `success: false`**: revisa siempre `success`.\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer | Sí | Id del producto. |\n\n**Errores:**\n- Si el id no existe responde **HTTP 404** con `success: false` y `message` `Registro no encontrado.`",
        "responses": {
          "200": {
            "description": "Agregado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Agregado",
                    "value": {
                      "success": true,
                      "message": "Producto agregado a favoritos"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Id inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Id inexistente",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Vendeya: alternar favorito",
                  "value": {
                    "id": "1"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sellnow/customers": {
      "get": {
        "tags": [
          "Consignaciones y e-commerce"
        ],
        "summary": "Vendeya: buscar clientes",
        "operationId": "VendeyaBuscarClientes",
        "description": "Mismo comportamiento que *Buscar clientes (formato API de comprobantes)* (sección [Clientes y proveedores](/docs/api/tenant/clientes)).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** listado de **cantidad fija** (take/limit): devuelve como máximo N registros, sin metadatos de paginación. Envuelto en `{success, customers[]}`; máximo `limit` registros (30 por defecto, tope 50).",
        "responses": {
          "200": {
            "description": "Clientes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Clientes",
                    "value": {
                      "success": true,
                      "customers": [
                        {
                          "id": 26,
                          "codigo_tipo_documento_identidad": "1",
                          "numero_documento": "45678912",
                          "apellidos_y_nombres_o_razon_social": "PEDRO QUISPE MAMANI",
                          "codigo_pais": "PE",
                          "direccion": "AV. PRINCIPAL 123, LIMA",
                          "correo_electronico": "compras@comercialnorte.pe",
                          "telefono": "987654321"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "PEDRO",
            "description": "Número de documento o nombre."
          },
          {
            "name": "identity_document_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Filtra por tipo de documento."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "30",
            "description": "Máximo de registros (1 a 50)."
          }
        ]
      }
    },
    "/api/catalogs/document-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de comprobante",
        "operationId": "TiposComprobante",
        "description": "Catálogo SUNAT 01: tipos de comprobante (factura, boleta, notas, guías, nota de venta).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `use` | string | No | `sale` = solo los de venta (`01` factura, `03` boleta, `80` nota de venta); `purchase` = los que se registran en compras (`01`, `02`, `03`, `14`, `GU75`, `NE76`). |\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `short` | string | No | Abreviatura (`FT`, `BV`, `NC`...). |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "FACTURA ELECTRÓNICA",
                          "short": "FT",
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "BOLETA DE VENTA ELECTRÓNICA",
                          "short": "BV",
                          "active": true
                        },
                        {
                          "id": "07",
                          "description": "NOTA DE CRÉDITO",
                          "short": "NC",
                          "active": true
                        },
                        {
                          "id": "08",
                          "description": "NOTA DE DÉBITO",
                          "short": "ND",
                          "active": true
                        },
                        {
                          "id": "09",
                          "description": "GUIA DE REMISIÓN REMITENTE",
                          "short": "GR",
                          "active": true
                        },
                        {
                          "id": "31",
                          "description": "GUÍA DE REMISIÓN TRANSPORTISTA",
                          "short": "GT",
                          "active": true
                        },
                        {
                          "id": "80",
                          "description": "NOTA DE VENTA",
                          "short": "NV",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "use",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "sale",
            "description": "`sale` (venta) o `purchase` (compras). Opcional."
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/identity-document-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de documento de identidad",
        "operationId": "TiposDocumentoIdentidad",
        "description": "Catálogo SUNAT 06: tipos de documento de identidad del cliente, proveedor o conductor. Vienen en el orden en que conviene mostrarlos (DNI, RUC, pasaporte...).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\nPara boletas a consumidor final sin documento se usa el código `-` (VARIOS) con número `99999999`, si está activo.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "1",
                          "description": "DNI",
                          "active": true
                        },
                        {
                          "id": "6",
                          "description": "RUC",
                          "active": true
                        },
                        {
                          "id": "7",
                          "description": "PASAPORTE",
                          "active": true
                        },
                        {
                          "id": "4",
                          "description": "CARNET DE EXTRANJERÍA",
                          "active": true
                        },
                        {
                          "id": "0",
                          "description": "Doc.trib.no.dom.sin.ruc",
                          "active": true
                        },
                        {
                          "id": "-",
                          "description": "VARIOS - VENTAS MENORES A S/.700.00 Y OTROS",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/affectation-igv-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de afectación del IGV",
        "operationId": "TiposAfectacionIgv",
        "description": "Catálogo SUNAT 07: afectación del IGV de cada ítem (gravado, exonerado, inafecto, exportación, gratuitas).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `exportation` | boolean | Sí | `true` si es de exportación. |\n| `free` | boolean | Sí | `true` si es una operación gratuita (no onerosa): el ítem se emite con tipo de precio `02`. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "10",
                          "description": "Gravado - Operación Onerosa",
                          "exportation": false,
                          "free": false,
                          "active": true
                        },
                        {
                          "id": "11",
                          "description": "Gravado – Retiro por premio",
                          "exportation": false,
                          "free": true,
                          "active": true
                        },
                        {
                          "id": "20",
                          "description": "Exonerado - Operación Onerosa",
                          "exportation": false,
                          "free": false,
                          "active": true
                        },
                        {
                          "id": "30",
                          "description": "Inafecto - Operación Onerosa",
                          "exportation": false,
                          "free": false,
                          "active": true
                        },
                        {
                          "id": "40",
                          "description": "Exportación",
                          "exportation": true,
                          "free": false,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/operation-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de operación",
        "operationId": "TiposOperacion",
        "description": "Catálogo SUNAT 51: tipo de operación del comprobante (venta interna, exportación, operación sujeta a detracción...).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `exportation` | boolean | Sí | `true` si es una operación de exportación. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\nSi `1001` o `1004` no vienen activos, la empresa no emite comprobantes con detracción.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "0101",
                          "description": "Venta interna",
                          "exportation": false,
                          "active": true
                        },
                        {
                          "id": "0200",
                          "description": "Exportación de Bienes",
                          "exportation": true,
                          "active": true
                        },
                        {
                          "id": "1001",
                          "description": "Operación Sujeta a Detracción",
                          "exportation": false,
                          "active": true
                        },
                        {
                          "id": "1004",
                          "description": "Operación Sujeta a Detracción- Servicios de Transporte Carga",
                          "exportation": false,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/credit-note-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de nota de crédito",
        "operationId": "TiposNotaCredito",
        "description": "Catálogo SUNAT 09: motivo de la nota de crédito (comprobante `07`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Anulación de la operación",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Anulación por error en el RUC",
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "Corrección por error en la descripción",
                          "active": true
                        },
                        {
                          "id": "06",
                          "description": "Devolución total",
                          "active": true
                        },
                        {
                          "id": "07",
                          "description": "Devolución por ítem",
                          "active": true
                        },
                        {
                          "id": "13",
                          "description": "Ajustes – montos y/o fechas de pago",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/debit-note-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de nota de débito",
        "operationId": "TiposNotaDebito",
        "description": "Catálogo SUNAT 10: motivo de la nota de débito (comprobante `08`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Intereses por mora",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Aumento en el valor",
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "Penalidades/ otros conceptos",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/price-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de precio",
        "operationId": "TiposPrecio",
        "description": "Catálogo SUNAT 16: tipo de precio del ítem.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n`02` se usa en ítems gratuitos (afectaciones con `free = true`).\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Precio unitario (incluye el IGV)",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Valor referencial unitario en operaciones no onerosas",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/system-isc-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Sistemas de cálculo del ISC",
        "operationId": "SistemasCalculoIsc",
        "description": "Catálogo SUNAT 08: sistema de cálculo del Impuesto Selectivo al Consumo, para ítems afectos al ISC.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Sistema al valor",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Aplicación del Monto Fijo",
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "Sistema de Precios de Venta al Público",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/charge-discount-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de cargos y descuentos",
        "operationId": "TiposCargosDescuentos",
        "description": "Catálogo SUNAT 53: códigos de cargos y descuentos, por ítem o globales, y si afectan la base imponible.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `type` | string | No | `discount` o `charge`. |\n| `level` | string | No | `item` o `global`. |\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `type` | string | Sí | `discount` (descuento) o `charge` (cargo). |\n| `level` | string | Sí | `item` (por ítem) o `global` (a todo el comprobante). |\n| `base` | boolean | Sí | `true` si afecta la base imponible del IGV. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "00",
                          "description": "Descuentos que afectan la base imponible del IGV/IVAP",
                          "type": "discount",
                          "level": "item",
                          "base": true,
                          "active": true
                        },
                        {
                          "id": "01",
                          "description": "Descuentos que no afectan la base imponible del IGV/IVAP",
                          "type": "discount",
                          "level": "item",
                          "base": false,
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Descuentos globales que afectan la base imponible del IGV/IVAP",
                          "type": "discount",
                          "level": "global",
                          "base": true,
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "Descuentos globales que no afectan la base imponible del IGV/IVAP",
                          "type": "discount",
                          "level": "global",
                          "base": false,
                          "active": true
                        },
                        {
                          "id": "47",
                          "description": "Cargos que afectan la base imponible del IGV/IVAP",
                          "type": "charge",
                          "level": "item",
                          "base": true,
                          "active": true
                        },
                        {
                          "id": "50",
                          "description": "Otros cargos globales que no afectan la base imponible",
                          "type": "charge",
                          "level": "global",
                          "base": false,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "discount",
            "description": "`discount` o `charge`. Opcional."
          },
          {
            "name": "level",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "item",
            "description": "`item` o `global`. Opcional."
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/currency-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Monedas",
        "operationId": "Monedas",
        "description": "Catálogo SUNAT 02: monedas habilitadas en la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `symbol` | string | No | Símbolo para mostrar. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "PEN",
                          "description": "Soles",
                          "symbol": "S/",
                          "active": true
                        },
                        {
                          "id": "USD",
                          "description": "Dólares Americanos",
                          "symbol": "$",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/unit-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Unidades de medida",
        "operationId": "UnidadesMedida",
        "description": "Catálogo SUNAT 03: unidades de medida habilitadas en la empresa, ordenadas por descripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `symbol` | string | No | Abreviatura para mostrar. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\nUsa `NIU` para bienes y `ZZ` para servicios (los servicios no controlan stock).\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "BX",
                          "description": "CAJA",
                          "symbol": "caja",
                          "active": true
                        },
                        {
                          "id": "KGM",
                          "description": "KILOGRAMO",
                          "symbol": "kg",
                          "active": true
                        },
                        {
                          "id": "LTR",
                          "description": "LITRO",
                          "symbol": "l",
                          "active": true
                        },
                        {
                          "id": "NIU",
                          "description": "UNIDAD (BIENES)",
                          "symbol": "und",
                          "active": true
                        },
                        {
                          "id": "ZZ",
                          "description": "UNIDAD (SERVICIOS)",
                          "symbol": "und",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/attribute-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de atributo del ítem",
        "operationId": "TiposAtributoItem",
        "description": "Catálogo SUNAT 55: códigos de atributos adicionales de un ítem (datos que exigen algunas operaciones, p. ej. detracción de recursos hidrobiológicos).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "3001",
                          "description": "Detracciones: Recursos Hidrobiológicos-Matrícula de la embarcación",
                          "active": true
                        },
                        {
                          "id": "3002",
                          "description": "Detracciones: Recursos Hidrobiológicos-Nombre de la embarcación",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/state-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Estados de comprobante",
        "operationId": "EstadosComprobante",
        "description": "Estados de un comprobante frente a SUNAT. Útil para filtrar listados y para interpretar `state_type_id` en las respuestas.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** este catálogo no se activa ni desactiva por empresa: siempre devuelve todos los registros (`all` no tiene efecto).\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n\n`05` (aceptado) y `07` (observado) son comprobantes válidos; `09` y `11` ya no tienen efecto tributario.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Registrado"
                        },
                        {
                          "id": "03",
                          "description": "Enviado"
                        },
                        {
                          "id": "05",
                          "description": "Aceptado"
                        },
                        {
                          "id": "07",
                          "description": "Observado"
                        },
                        {
                          "id": "09",
                          "description": "Rechazado"
                        },
                        {
                          "id": "11",
                          "description": "Anulado"
                        },
                        {
                          "id": "13",
                          "description": "Por anular"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/catalogs/detraction-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de detracción",
        "operationId": "TiposDetraccion",
        "description": "Catálogo SUNAT 54: bienes y servicios sujetos a detracción, con su porcentaje.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `operation_type_id` | string | No | `1001` o `1004`: solo los tipos de esa operación. |\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `percentage` | number | Sí | Porcentaje de detracción sobre el total. |\n| `operation_type_id` | string | Sí | Tipo de operación del comprobante con el que se usa: `1001` (general) o `1004` (transporte de carga). |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\nLa detracción aplica a comprobantes de más de S/ 700.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "022",
                          "description": "Otros servicios empresariales",
                          "percentage": 12.0,
                          "operation_type_id": "1001",
                          "active": true
                        },
                        {
                          "id": "027",
                          "description": "Servicio de transporte de carga",
                          "percentage": 4.0,
                          "operation_type_id": "1004",
                          "active": true
                        },
                        {
                          "id": "037",
                          "description": "Demás servicios gravados con el IGV",
                          "percentage": 12.0,
                          "operation_type_id": "1001",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "operation_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1001",
            "description": "`1001` (general) o `1004` (transporte de carga). Opcional."
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/detraction-payment-methods": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Medios de pago de la detracción",
        "operationId": "MediosPagoDetraccion",
        "description": "Catálogo SUNAT 59: medio con el que el cliente deposita la detracción. **No** es el método de pago del cobro (ese es `catalogs/payment-method-types`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "001",
                          "description": "Depósito en cuenta",
                          "active": true
                        },
                        {
                          "id": "003",
                          "description": "Transferencia de fondos",
                          "active": true
                        },
                        {
                          "id": "004",
                          "description": "Orden de pago",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/retention-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de retención",
        "operationId": "TiposRetencion",
        "description": "Catálogo SUNAT 23: régimen de retención del IGV, con su tasa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** este catálogo no se activa ni desactiva por empresa: siempre devuelve todos los registros (`all` no tiene efecto).\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `percentage` | number | Sí | Tasa de retención. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Tasa 3%",
                          "percentage": 3.0,
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Tasa 6%",
                          "percentage": 6.0,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/catalogs/perception-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de percepción",
        "operationId": "TiposPercepcion",
        "description": "Catálogo SUNAT 22: régimen de percepción del IGV, con su tasa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** este catálogo no se activa ni desactiva por empresa: siempre devuelve todos los registros (`all` no tiene efecto).\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `percentage` | number | Sí | Tasa de percepción. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Percepción Venta Interna",
                          "percentage": 2.0,
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Percepción a la adquisición de combustible",
                          "percentage": 1.0,
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "Percepción realizada al agente de percepción con tasa especial",
                          "percentage": 0.5,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/catalogs/payment-method-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Métodos de pago",
        "operationId": "MetodosPago",
        "description": "Métodos de pago de la empresa (efectivo, tarjeta, transferencia, Yape...), los mismos que ofrece el sistema al cobrar o pagar. Es el valor de `payment_method_type_id` en los pagos.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** solo devuelve los métodos activos (`all` no aplica: un método inactivo no se acepta en un pago).\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `for` | string | No | `income` = los que sirven para **cobrar**; `expense` = los que sirven para **pagar** (gastos, compras). |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `is_cash` | boolean | Sí | `true` = efectivo. |\n| `is_credit` | boolean | Sí | `true` = es una condición de crédito (p. ej. *Factura a 30 días*), no un medio de pago. |\n| `has_card` | boolean | Sí | `true` = con tarjeta: envía también `card_brand_id` (ver Marcas de tarjeta). |\n| `number_days` | integer | Sí | Días de crédito cuando `is_credit` es `true`. |\n| `charge` | number | Sí | Recargo porcentual configurado para el método (0 si no tiene). |\n| `is_payment_medium` | boolean | Sí | `true` = medio de pago real (no una condición de crédito). |\n| `use_for_income` | boolean | Sí | Se puede usar para cobrar. |\n| `use_for_expense` | boolean | Sí | Se puede usar para pagar. |\n| `goes_to_cash_drawer` | boolean | Sí | `true` = el dinero entra a la caja: usa `payment_destination_id = cash`. |\n| `allowed_destination_type` | string/null | Sí | Si no es nulo, el destino debe ser una cuenta de ese tipo: `bank`, `wallet`, `gateway` o `card`. |\n| `default_destination_id` | integer/null | Sí | Cuenta sugerida por defecto para este método. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Efectivo",
                          "is_cash": true,
                          "is_credit": false,
                          "has_card": false,
                          "number_days": 0,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "use_for_income": true,
                          "use_for_expense": true,
                          "goes_to_cash_drawer": true,
                          "allowed_destination_type": null,
                          "default_destination_id": null
                        },
                        {
                          "id": "02",
                          "description": "Tarjeta de crédito",
                          "is_cash": false,
                          "is_credit": false,
                          "has_card": true,
                          "number_days": 0,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "use_for_income": true,
                          "use_for_expense": false,
                          "goes_to_cash_drawer": false,
                          "allowed_destination_type": "gateway",
                          "default_destination_id": null
                        },
                        {
                          "id": "04",
                          "description": "Transferencia",
                          "is_cash": false,
                          "is_credit": false,
                          "has_card": false,
                          "number_days": 0,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "use_for_income": true,
                          "use_for_expense": true,
                          "goes_to_cash_drawer": false,
                          "allowed_destination_type": "bank",
                          "default_destination_id": null
                        },
                        {
                          "id": "12",
                          "description": "Yape",
                          "is_cash": false,
                          "is_credit": false,
                          "has_card": false,
                          "number_days": 0,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "use_for_income": true,
                          "use_for_expense": true,
                          "goes_to_cash_drawer": false,
                          "allowed_destination_type": "wallet",
                          "default_destination_id": 3
                        },
                        {
                          "id": "09",
                          "description": "Crédito",
                          "is_cash": false,
                          "is_credit": true,
                          "has_card": false,
                          "number_days": 30,
                          "charge": 0.0,
                          "is_payment_medium": false,
                          "use_for_income": true,
                          "use_for_expense": false,
                          "goes_to_cash_drawer": false,
                          "allowed_destination_type": null,
                          "default_destination_id": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "for",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "income",
            "description": "`income` (cobrar) o `expense` (pagar). Opcional."
          }
        ]
      }
    },
    "/api/catalogs/payment-destinations": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Destinos de pago (caja y cuentas)",
        "operationId": "DestinosPagoCajaCuentas",
        "description": "Valores válidos de `payment_destination_id` (y `pagos[].codigo_destino_pago`): a dónde entra o de dónde sale el dinero de un pago. Incluye las cuentas bancarias, billeteras y pasarelas del establecimiento del usuario (y las generales) y, **solo si el usuario tiene una caja abierta**, la caja con `id = \"cash\"`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** devuelve los destinos que el usuario puede usar ahora mismo (`all` no aplica).\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `for` | string | No | `income` = solo cuentas que reciben cobros; `expense` = solo cuentas que permiten pagar. La caja siempre se incluye. |\n| `currency_type_id` | string | No | `PEN` o `USD`: solo cuentas en esa moneda (la caja acepta ambas). |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | integer / string | Sí | Id de la cuenta, o `cash` para la caja abierta del usuario. |\n| `cash_id` | integer/null | Sí | Id de la caja abierta (solo en la fila `cash`). |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `type` | string | Sí | `cash` (caja), `bank` (cuenta bancaria), `wallet` (billetera digital), `gateway` (pasarela de pago) o `card` (tarjeta de la empresa). |\n| `type_label` | string | Sí | Nombre del tipo para mostrar. |\n| `currency_type_id` | string | No | Moneda de la cuenta: la cuenta solo recibe pagos en su moneda. (No viene en la fila `cash`.) |\n| `receives_income` | boolean | No | La cuenta puede recibir cobros. (No viene en la fila `cash`.) |\n| `allows_payments` | boolean | No | La cuenta puede usarse para pagar. (No viene en la fila `cash`.) |\n| `establishment_id` | integer/null | No | Establecimiento de la cuenta; `null` = general. |\n| `reconciles_with` | string | No | Contra qué se cuadra la cuenta (texto informativo). |\n| `logo_url` | string/null | No | Logo de la cuenta o billetera, si tiene. |\n\n**Reglas:**\n- Para cobrar o pagar en efectivo con `cash` el usuario del token debe tener una **caja abierta**; si no aparece `cash` en esta lista, abre una caja antes.\n- Respeta `allowed_destination_type` y `goes_to_cash_drawer` del método de pago (ver Métodos de pago).\n- Una pasarela (`gateway`) solo cobra; la tarjeta de la empresa (`card`) solo paga.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "cash_id": null,
                          "type": "wallet",
                          "type_label": "Billetera digital",
                          "reconciles_with": "Con la aplicación de la billetera",
                          "logo_url": null,
                          "receives_income": true,
                          "allows_payments": true,
                          "currency_type_id": "PEN",
                          "establishment_id": null,
                          "description": "PEN - YAPE EMPRESA"
                        },
                        {
                          "id": 5,
                          "cash_id": null,
                          "type": "bank",
                          "type_label": "Cuenta bancaria",
                          "reconciles_with": "Con el estado de cuenta del banco",
                          "logo_url": null,
                          "receives_income": true,
                          "allows_payments": true,
                          "currency_type_id": "PEN",
                          "establishment_id": 1,
                          "description": "BANCO DE CREDITO DEL PERU - PEN - CTA CTE 191-2345678-0-11"
                        },
                        {
                          "id": "cash",
                          "cash_id": 4,
                          "description": "CAJA GENERAL - CAJA-0004",
                          "type": "cash",
                          "type_label": "Caja"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "for",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "income",
            "description": "`income` o `expense`. Opcional."
          },
          {
            "name": "currency_type_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "PEN",
            "description": "`PEN` o `USD`. Opcional."
          }
        ]
      }
    },
    "/api/catalogs/payment-conditions": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Condiciones de pago",
        "operationId": "CondicionesPago",
        "description": "Condición de pago del comprobante (`payment_condition_id` / `codigo_condicion_de_pago`): `01` contado o `02` crédito (con cuotas en `cuotas`/`fee`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `days` | integer | Sí | Días de plazo por defecto. |\n| `is_locked` | boolean | Sí | `true` = condición del sistema (no editable por la empresa). |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Contado",
                          "days": 0,
                          "is_locked": true,
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Crédito",
                          "days": 0,
                          "is_locked": true,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/banks": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Bancos",
        "operationId": "Bancos",
        "description": "Bancos registrados en la empresa (para `bank_id` al crear una cuenta bancaria). Ordenados por nombre.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `id` | integer | Sí | Id para `bank_id`. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "BANCO DE CREDITO DEL PERU",
                          "active": true
                        },
                        {
                          "id": 2,
                          "description": "BBVA",
                          "active": true
                        },
                        {
                          "id": 3,
                          "description": "INTERBANK",
                          "active": true
                        },
                        {
                          "id": 4,
                          "description": "SCOTIABANK",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/card-brands": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Marcas de tarjeta",
        "operationId": "MarcasTarjeta",
        "description": "Marcas de tarjeta para `card_brand_id` cuando el método de pago es con tarjeta (`has_card = true`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Visa",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Mastercard",
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "American Express",
                          "active": true
                        },
                        {
                          "id": "04",
                          "description": "Diners Club",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/transfer-reason-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Motivos de traslado",
        "operationId": "MotivosTraslado",
        "description": "Catálogo SUNAT 20: motivo de traslado de la guía de remisión.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Venta",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Compra",
                          "active": true
                        },
                        {
                          "id": "04",
                          "description": "Traslado entre establecimientos de la misma empresa",
                          "active": true
                        },
                        {
                          "id": "08",
                          "description": "Importación",
                          "active": true
                        },
                        {
                          "id": "09",
                          "description": "Exportación",
                          "active": true
                        },
                        {
                          "id": "13",
                          "description": "Otros",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/transport-mode-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Modalidades de transporte",
        "operationId": "ModalidadesTransporte",
        "description": "Catálogo SUNAT 18: modalidad de transporte de la guía de remisión.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n`01` (público) exige los datos del transportista; `02` (privado) exige vehículo y conductor.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Transporte público",
                          "active": true
                        },
                        {
                          "id": "02",
                          "description": "Transporte privado",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/related-document-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de documento relacionado (guía)",
        "operationId": "TiposDocumentoRelacionadoGuia",
        "description": "Catálogo SUNAT 61: tipos de documento que se pueden relacionar en una guía de remisión.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** este catálogo no se activa ni desactiva por empresa: siempre devuelve todos los registros (`all` no tiene efecto).\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Factura",
                          "active": true
                        },
                        {
                          "id": "03",
                          "description": "Boleta de Venta",
                          "active": true
                        },
                        {
                          "id": "09",
                          "description": "Guía de Remisión Remitente",
                          "active": true
                        },
                        {
                          "id": "50",
                          "description": "Declaración Aduanera de Mercancías",
                          "active": true
                        },
                        {
                          "id": "52",
                          "description": "Declaración Simplificada (DS)",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/catalogs/countries": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Países",
        "operationId": "Paises",
        "description": "Países (código ISO de 2 letras) para la dirección de clientes y proveedores. Ordenados por nombre.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "AR",
                          "description": "ARGENTINA",
                          "active": true
                        },
                        {
                          "id": "CL",
                          "description": "CHILE",
                          "active": true
                        },
                        {
                          "id": "CO",
                          "description": "COLOMBIA",
                          "active": true
                        },
                        {
                          "id": "PE",
                          "description": "PERÚ",
                          "active": true
                        },
                        {
                          "id": "US",
                          "description": "ESTADOS UNIDOS",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/departments": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Departamentos",
        "operationId": "Departamentos",
        "description": "Departamentos del Perú (primer nivel del ubigeo INEI). Ordenados por nombre.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "04",
                          "description": "AREQUIPA",
                          "active": true
                        },
                        {
                          "id": "13",
                          "description": "LA LIBERTAD",
                          "active": true
                        },
                        {
                          "id": "15",
                          "description": "LIMA",
                          "active": true
                        },
                        {
                          "id": "08",
                          "description": "CUSCO",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/provinces": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Provincias",
        "operationId": "Provincias",
        "description": "Provincias del Perú (segundo nivel del ubigeo). Filtra por departamento con `department_id`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `department_id` | string | No | Id del departamento (`15` = Lima). Sin él devuelve todas las provincias. |\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `department_id` | string | Sí | Departamento al que pertenece. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "1508",
                          "description": "HUAURA",
                          "department_id": "15",
                          "active": true
                        },
                        {
                          "id": "1501",
                          "description": "LIMA",
                          "department_id": "15",
                          "active": true
                        },
                        {
                          "id": "1502",
                          "description": "BARRANCA",
                          "department_id": "15",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "department_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Id del departamento."
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/districts": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Distritos (ubigeo)",
        "operationId": "DistritosUbigeo",
        "description": "Distritos de una provincia. El `id` del distrito es el **ubigeo** de 6 dígitos que se envía en `district_id` / `ubigeo`.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `province_id` | string (4) | Sí | Id de la provincia (`1501` = Lima). Obligatorio. |\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `province_id` | string | Sí | Provincia a la que pertenece. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `422` `{success: false, message: {province_id: [...]}}` si falta `province_id` o no tiene 4 caracteres.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "150101",
                          "description": "LIMA",
                          "province_id": "1501",
                          "active": true
                        },
                        {
                          "id": "150122",
                          "description": "MIRAFLORES",
                          "province_id": "1501",
                          "active": true
                        },
                        {
                          "id": "150131",
                          "description": "SAN ISIDRO",
                          "province_id": "1501",
                          "active": true
                        },
                        {
                          "id": "150140",
                          "description": "SANTIAGO DE SURCO",
                          "province_id": "1501",
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Falta province_id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Falta province_id",
                    "value": {
                      "success": false,
                      "message": {
                        "province_id": [
                          "El campo province id es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "province_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1501",
            "description": "Id de la provincia (obligatorio)."
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/person-types": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Tipos de cliente",
        "operationId": "TiposCliente",
        "description": "Tipos de cliente de la empresa (p. ej. mayorista, minorista). Un tipo puede tener una lista de precios asociada (`price_label_id`).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** este catálogo no se activa ni desactiva por empresa: siempre devuelve todos los registros (`all` no tiene efecto).\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `id` | integer | Sí | Id para `person_type_id` del cliente. |\n| `price_label_id` | integer/null | Sí | Etiqueta de precio que se aplica a este tipo de cliente (ver Etiquetas de precio). |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "MAYORISTA",
                          "price_label_id": 2
                        },
                        {
                          "id": 2,
                          "description": "MINORISTA",
                          "price_label_id": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/catalogs/price-labels": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Etiquetas de precio",
        "operationId": "EtiquetasPrecio",
        "description": "Listas de precio de la empresa (precio público, mayorista...), en su orden. Cada producto puede tener un precio por etiqueta.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos e inactivos:** por defecto solo devuelve los registros **activos** de la empresa (los que se ofrecen en los formularios del sistema). Envía `all=1` para incluir también los inactivos; cada fila trae `active` para distinguirlos. Un código inactivo puede ser rechazado al registrar comprobantes: usa siempre los activos.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | `1` = incluir inactivos. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `id` | integer | Sí | Id para `price_label_id`. |\n| `position` | integer | Sí | Orden de la etiqueta (1 = principal). |\n| `is_default` | boolean | Sí | `true` = precio que se usa por defecto al vender. |\n| `active` | boolean | Sí | `true` si la empresa lo tiene activo. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "description": "Precio público",
                          "position": 1,
                          "is_default": true,
                          "active": true
                        },
                        {
                          "id": 2,
                          "description": "Precio mayorista",
                          "position": 2,
                          "is_default": false,
                          "active": true
                        },
                        {
                          "id": 3,
                          "description": "Precio distribuidor",
                          "position": 3,
                          "is_default": false,
                          "active": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir también los registros inactivos (cada fila trae `active`). Por defecto solo activos."
          }
        ]
      }
    },
    "/api/catalogs/inventory-transactions": {
      "get": {
        "tags": [
          "Catálogos"
        ],
        "summary": "Motivos de ajuste de inventario",
        "operationId": "MotivosAjusteInventario",
        "description": "Motivos que se pueden elegir al registrar un ingreso o salida manual de inventario (`inventory_transaction_id`). No incluye los movimientos automáticos del sistema (venta, compra, inventario inicial, traslado entre almacenes...).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Aquí `data` es la **lista completa** (sin paginación ni `pagination`): son catálogos cortos.\n\n**Activos:** este catálogo no se activa ni desactiva por empresa: siempre devuelve todos los registros (`all` no tiene efecto).\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `type` | string | No | `input` o `output`: solo los motivos de ese tipo. |\n\n**Campos de cada fila de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `id` | string | Sí | Código a enviar en el campo correspondiente del comprobante / registro. |\n| `description` | string | Sí | Descripción para mostrar al usuario. |\n| `type` | string | Sí | `input` (ingreso) u `output` (salida). |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "19",
                          "description": "Ingreso de producción",
                          "type": "input"
                        },
                        {
                          "id": "05",
                          "description": "Devolución recibida",
                          "type": "input"
                        },
                        {
                          "id": "13",
                          "description": "Mermas",
                          "type": "output"
                        },
                        {
                          "id": "28",
                          "description": "Ajuste por diferencia de inventario",
                          "type": "output"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "output",
            "description": "`input` o `output`. Opcional."
          }
        ]
      }
    },
    "/api/payment-method-types": {
      "get": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Listar métodos de pago",
        "operationId": "ListarMetodosPago",
        "description": "Lista los métodos de pago de la empresa (efectivo, billeteras, transferencias, tarjetas y condiciones de crédito) en el orden configurado, con su regla de destino. Es la vista de **administración**: incluye los inactivos. Para llenar un formulario de cobro usa **Catálogos → Métodos de pago** (`catalogs/payment-method-types`), que solo trae los activos.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `is_active` | 0 / 1 | No | `1` = solo activos; `0` = solo inactivos. Sin el parámetro, todos. |\n| `for` | string | No | `income` = los que sirven para cobrar; `expense` = los que sirven para pagar. |\n| `search` | string | No | Coincidencia parcial en la descripción. |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada método:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | string | Código interno de 2 caracteres. Es el `payment_method_type_id` que se envía al registrar cobros y pagos. |\n| `description` | string | Nombre. |\n| `sort_order` | integer | Posición en las listas (menor = primero). |\n| `is_active` | boolean | Se ofrece en los formularios. |\n| `is_credit / number_days` | boolean / integer | Condición de crédito y su plazo. |\n| `is_payment_medium` | boolean | `false` en las condiciones de crédito. |\n| `goes_to_cash_drawer` | boolean | Entra al cajón (efectivo). |\n| `use_for_income / use_for_expense` | boolean | Para cobrar / para pagar. |\n| `destination_rule` | string | Regla de destino (`any`, `type:<tipo>`, `account:<id>`). |\n| `default_destination_id` | integer o null | Cuenta fija (regla `account:<id>`). |\n| `allowed_destination_type` | string o null | Tipo de cuenta permitido (regla `type:<tipo>`). |\n| `destination_label` | string | Texto del destino para mostrar (`Caja`, `Cualquier banco`, nombre de la cuenta, `Se elige al registrar`). |\n| `uses_label` | string | `Cobros y pagos`, `Solo cobros`, `Solo pagos`, `Sin uso` o `Condición de pago`. |\n| `has_no_use` | boolean | Medio de pago sin ningún uso (queda inactivo). |\n| `can_delete` | boolean | `false` en los códigos del sistema `01` a `10`. |\n| `logo_url / initials / monogram_color` | string | Logotipo subido (o `null`) y monograma para mostrar cuando no hay logo. |\n\nLas condiciones reservadas del sistema (*Crédito*, *Contado*) no se listan.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` si `for` o `is_active` tienen un valor no permitido.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Efectivo",
                          "sort_order": 10,
                          "is_active": true,
                          "is_credit": false,
                          "number_days": 0,
                          "has_card": false,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "goes_to_cash_drawer": true,
                          "use_for_income": true,
                          "use_for_expense": true,
                          "destination_rule": "any",
                          "default_destination_id": null,
                          "allowed_destination_type": null,
                          "destination_label": "Caja",
                          "uses_label": "Cobros y pagos",
                          "has_no_use": false,
                          "can_delete": false,
                          "logo_url": null,
                          "initials": "EF",
                          "monogram_color": "#0f766e"
                        },
                        {
                          "id": "04",
                          "description": "Transferencia",
                          "sort_order": 20,
                          "is_active": true,
                          "is_credit": false,
                          "number_days": 0,
                          "has_card": false,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "goes_to_cash_drawer": false,
                          "use_for_income": true,
                          "use_for_expense": true,
                          "destination_rule": "type:bank",
                          "default_destination_id": null,
                          "allowed_destination_type": "bank",
                          "destination_label": "Cualquier banco",
                          "uses_label": "Cobros y pagos",
                          "has_no_use": false,
                          "can_delete": false,
                          "logo_url": null,
                          "initials": "TR",
                          "monogram_color": "#1a4f7a"
                        },
                        {
                          "id": "13",
                          "description": "Yape",
                          "sort_order": 30,
                          "is_active": true,
                          "is_credit": false,
                          "number_days": 0,
                          "has_card": false,
                          "charge": 0.0,
                          "is_payment_medium": true,
                          "goes_to_cash_drawer": false,
                          "use_for_income": true,
                          "use_for_expense": true,
                          "destination_rule": "account:4",
                          "default_destination_id": 4,
                          "allowed_destination_type": null,
                          "destination_label": "YAPE TIENDA CENTRO",
                          "uses_label": "Cobros y pagos",
                          "has_no_use": false,
                          "can_delete": true,
                          "logo_url": "https://empresa.dominio/logo/payment-methods/yape-13.png",
                          "initials": "YA",
                          "monogram_color": "#6b3fa0"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` activos, `0` inactivos."
          },
          {
            "name": "for",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "income",
            "description": "`income` o `expense`."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca en la descripción."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Crear método de pago",
        "operationId": "CrearMetodoPago",
        "description": "Registra un método de pago. El servidor asigna el código.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con el método creado (incluye su `id`).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string (máx. 255) | Sí al crear | Nombre que ve el cajero (p. ej. `Yape`, `Transferencia BBVA`). |\n| `is_credit` | boolean | No | `true` = **condición de crédito** (plazo de cobro, p. ej. *A 45 días*), no una forma de cobro. Por defecto `false`. |\n| `number_days` | integer (0 a 3650) | No | Días de plazo de una condición de crédito. Por defecto `0`. |\n| `goes_to_cash_drawer` | boolean | No | `true` = el dinero entra y sale del **cajón** (efectivo) y se cuadra en el arqueo de la caja. Por defecto `false`. |\n| `use_for_income` | boolean | No | Se ofrece para **cobrar** (ventas, cobranzas, ingresos). Por defecto `true`. |\n| `use_for_expense` | boolean | No | Se ofrece para **pagar** (compras, gastos). Por defecto `false`. |\n| `destination_rule` | string | No | `any` · `type:bank` · `type:wallet` · `type:gateway` · `type:card` · `account:<id>`. Por defecto `any`. Ver la tabla de reglas. |\n| `is_active` | boolean | No | Activo (se ofrece en los formularios). Por defecto `true`. |\n| `has_card` | boolean | No | Pide marca de tarjeta al registrar el pago. |\n| `charge` | numeric (0 a 100) | No | Recargo porcentual informativo del método. |\n\n**Regla de destino (`destination_rule`)** — un solo valor decide a dónde va (o de dónde sale) el dinero:\n\n| Valor | Significado | Cómo queda el método |\n|---|---|---|\n| `any` | Se elige la cuenta al registrar cada cobro o pago. | `default_destination_id = null`, `allowed_destination_type = null` |\n| `type:bank` | Solo cuentas bancarias. | `allowed_destination_type = \"bank\"` |\n| `type:wallet` | Solo billeteras digitales (Yape, Plin...). | `allowed_destination_type = \"wallet\"` |\n| `type:gateway` | Solo pasarelas de pago (Niubiz, Izipay...). Una pasarela **recibe cobros pero no paga**. | `allowed_destination_type = \"gateway\"` |\n| `type:card` | Solo tarjetas de la empresa. Una tarjeta de la empresa **paga pero no recibe cobros**. | `allowed_destination_type = \"card\"` |\n| `account:<id>` | Siempre esa cuenta (id de **Cuentas bancarias**, `bank-accounts`). Al registrar un pago con este método hay que enviar esa misma cuenta como `payment_destination_id`; otra se rechaza. | `default_destination_id = <id>` |\n\nUn método que **va al cajón** (`goes_to_cash_drawer: true`, el efectivo) no tiene cuenta: su regla siempre queda en `any` y sus cobros van a la caja abierta (`payment_destination_id = \"cash\"`).\n\n**Reglas:**\n- El **código** (`id`) lo asigna el servidor al crear: el primer libre desde `11` (los códigos `01` a `10` están reservados). No se envía ni cambia al editar; si se envía, se ignora.\n- Un método nuevo se coloca **al final** del orden (`sort_order`).\n- `is_credit: true` → no es medio de pago (`is_payment_medium: false`): se fuerza `goes_to_cash_drawer`, `use_for_income` y `use_for_expense` a `false` y no aparece al registrar pagos.\n- Un medio de pago **sin uso** (ni cobrar ni pagar) queda **inactivo** aunque envíes `is_active: true` (`has_no_use: true`). Márcale un uso para activarlo.\n- `goes_to_cash_drawer: true` → la regla de destino queda en `any` (el efectivo no tiene cuenta).\n- La cuenta (o el tipo) tiene que servir para **todo lo marcado**: si `use_for_income` y la cuenta no recibe cobros, o `use_for_expense` y la cuenta no permite pagos, responde `409` y no guarda nada.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (falta `description`, `destination_rule` con formato inválido o `account:<id>` de una cuenta que no existe).\n- `409` si la cuenta o el tipo elegido no sirve para lo marcado, o si ya no quedan códigos libres.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "21",
                        "description": "Plin",
                        "sort_order": 140,
                        "is_active": true,
                        "is_credit": false,
                        "number_days": 0,
                        "has_card": false,
                        "charge": 0.0,
                        "is_payment_medium": true,
                        "goes_to_cash_drawer": false,
                        "use_for_income": true,
                        "use_for_expense": true,
                        "destination_rule": "account:5",
                        "default_destination_id": 5,
                        "allowed_destination_type": null,
                        "destination_label": "PLIN TIENDA CENTRO",
                        "uses_label": "Cobros y pagos",
                        "has_no_use": false,
                        "can_delete": true,
                        "logo_url": null,
                        "initials": "PL",
                        "monogram_color": "#155e75"
                      },
                      "message": "Método de pago registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "La cuenta no sirve para lo marcado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "La cuenta no sirve para lo marcado",
                    "value": {
                      "success": false,
                      "message": "\"NIUBIZ TIENDA\" no permite pagos. Desmarca \"Para pagar\" o elige otra cuenta."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Regla de destino inválida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Regla de destino inválida",
                    "value": {
                      "success": false,
                      "message": {
                        "destination_rule": [
                          "destination_rule debe ser \"any\", \"type:bank\", \"type:wallet\", \"type:gateway\", \"type:card\" o \"account:<id de la cuenta>\"."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear método de pago",
                  "value": {
                    "description": "Plin",
                    "goes_to_cash_drawer": false,
                    "use_for_income": true,
                    "use_for_expense": true,
                    "destination_rule": "account:5"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/payment-method-types/{payment_method_type_id}": {
      "get": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Ver método de pago",
        "operationId": "VerMetodoPago",
        "description": "Devuelve un método de pago con su regla de destino.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `payment_method_type_id` | string | Sí | Código del método (`01`, `13`...). Respeta el cero a la izquierda. |\n\n**Campos de cada método:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | string | Código interno de 2 caracteres. Es el `payment_method_type_id` que se envía al registrar cobros y pagos. |\n| `description` | string | Nombre. |\n| `sort_order` | integer | Posición en las listas (menor = primero). |\n| `is_active` | boolean | Se ofrece en los formularios. |\n| `is_credit / number_days` | boolean / integer | Condición de crédito y su plazo. |\n| `is_payment_medium` | boolean | `false` en las condiciones de crédito. |\n| `goes_to_cash_drawer` | boolean | Entra al cajón (efectivo). |\n| `use_for_income / use_for_expense` | boolean | Para cobrar / para pagar. |\n| `destination_rule` | string | Regla de destino (`any`, `type:<tipo>`, `account:<id>`). |\n| `default_destination_id` | integer o null | Cuenta fija (regla `account:<id>`). |\n| `allowed_destination_type` | string o null | Tipo de cuenta permitido (regla `type:<tipo>`). |\n| `destination_label` | string | Texto del destino para mostrar (`Caja`, `Cualquier banco`, nombre de la cuenta, `Se elige al registrar`). |\n| `uses_label` | string | `Cobros y pagos`, `Solo cobros`, `Solo pagos`, `Sin uso` o `Condición de pago`. |\n| `has_no_use` | boolean | Medio de pago sin ningún uso (queda inactivo). |\n| `can_delete` | boolean | `false` en los códigos del sistema `01` a `10`. |\n| `logo_url / initials / monogram_color` | string | Logotipo subido (o `null`) y monograma para mostrar cuando no hay logo. |\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el código no existe (o es una condición reservada del sistema, que no se administra por la API).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Método",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Método",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "13",
                        "description": "Yape",
                        "sort_order": 30,
                        "is_active": true,
                        "is_credit": false,
                        "number_days": 0,
                        "has_card": false,
                        "charge": 0.0,
                        "is_payment_medium": true,
                        "goes_to_cash_drawer": false,
                        "use_for_income": true,
                        "use_for_expense": true,
                        "destination_rule": "account:4",
                        "default_destination_id": 4,
                        "allowed_destination_type": null,
                        "destination_label": "YAPE TIENDA CENTRO",
                        "uses_label": "Cobros y pagos",
                        "has_no_use": false,
                        "can_delete": true,
                        "logo_url": "https://empresa.dominio/logo/payment-methods/yape-13.png",
                        "initials": "YA",
                        "monogram_color": "#6b3fa0"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "payment_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "13"
          }
        ]
      },
      "put": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Editar método de pago",
        "operationId": "EditarMetodoPago",
        "description": "Edita un método de pago. **Edición parcial**: los campos que no envías conservan su valor (también acepta `PATCH`).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `payment_method_type_id` | string | Sí | Código del método. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `description` | string (máx. 255) | No | Nombre que ve el cajero (p. ej. `Yape`, `Transferencia BBVA`). |\n| `is_credit` | boolean | No | `true` = **condición de crédito** (plazo de cobro, p. ej. *A 45 días*), no una forma de cobro. Por defecto `false`. |\n| `number_days` | integer (0 a 3650) | No | Días de plazo de una condición de crédito. Por defecto `0`. |\n| `goes_to_cash_drawer` | boolean | No | `true` = el dinero entra y sale del **cajón** (efectivo) y se cuadra en el arqueo de la caja. Por defecto `false`. |\n| `use_for_income` | boolean | No | Se ofrece para **cobrar** (ventas, cobranzas, ingresos). Por defecto `true`. |\n| `use_for_expense` | boolean | No | Se ofrece para **pagar** (compras, gastos). Por defecto `false`. |\n| `destination_rule` | string | No | `any` · `type:bank` · `type:wallet` · `type:gateway` · `type:card` · `account:<id>`. Por defecto `any`. Ver la tabla de reglas. |\n| `is_active` | boolean | No | Activo (se ofrece en los formularios). Por defecto `true`. |\n| `has_card` | boolean | No | Pide marca de tarjeta al registrar el pago. |\n| `charge` | numeric (0 a 100) | No | Recargo porcentual informativo del método. |\n\n**Regla de destino (`destination_rule`)** — un solo valor decide a dónde va (o de dónde sale) el dinero:\n\n| Valor | Significado | Cómo queda el método |\n|---|---|---|\n| `any` | Se elige la cuenta al registrar cada cobro o pago. | `default_destination_id = null`, `allowed_destination_type = null` |\n| `type:bank` | Solo cuentas bancarias. | `allowed_destination_type = \"bank\"` |\n| `type:wallet` | Solo billeteras digitales (Yape, Plin...). | `allowed_destination_type = \"wallet\"` |\n| `type:gateway` | Solo pasarelas de pago (Niubiz, Izipay...). Una pasarela **recibe cobros pero no paga**. | `allowed_destination_type = \"gateway\"` |\n| `type:card` | Solo tarjetas de la empresa. Una tarjeta de la empresa **paga pero no recibe cobros**. | `allowed_destination_type = \"card\"` |\n| `account:<id>` | Siempre esa cuenta (id de **Cuentas bancarias**, `bank-accounts`). Al registrar un pago con este método hay que enviar esa misma cuenta como `payment_destination_id`; otra se rechaza. | `default_destination_id = <id>` |\n\nUn método que **va al cajón** (`goes_to_cash_drawer: true`, el efectivo) no tiene cuenta: su regla siempre queda en `any` y sus cobros van a la caja abierta (`payment_destination_id = \"cash\"`).\n\n**Reglas:**\n- `is_credit: true` → no es medio de pago (`is_payment_medium: false`): se fuerza `goes_to_cash_drawer`, `use_for_income` y `use_for_expense` a `false` y no aparece al registrar pagos.\n- Un medio de pago **sin uso** (ni cobrar ni pagar) queda **inactivo** aunque envíes `is_active: true` (`has_no_use: true`). Márcale un uso para activarlo.\n- `goes_to_cash_drawer: true` → la regla de destino queda en `any` (el efectivo no tiene cuenta).\n- La cuenta (o el tipo) tiene que servir para **todo lo marcado**: si `use_for_income` y la cuenta no recibe cobros, o `use_for_expense` y la cuenta no permite pagos, responde `409` y no guarda nada.\n- Cambiar la regla reemplaza la anterior: pasar a `account:<id>` borra el tipo, pasar a `type:<tipo>` borra la cuenta fija.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el código no existe (o es una condición reservada del sistema, que no se administra por la API).\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `409` si la cuenta o el tipo no sirve para lo marcado (no se guarda nada).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "21",
                        "description": "Plin",
                        "sort_order": 140,
                        "is_active": true,
                        "is_credit": false,
                        "number_days": 0,
                        "has_card": false,
                        "charge": 0.0,
                        "is_payment_medium": true,
                        "goes_to_cash_drawer": false,
                        "use_for_income": true,
                        "use_for_expense": false,
                        "destination_rule": "type:wallet",
                        "default_destination_id": null,
                        "allowed_destination_type": "wallet",
                        "destination_label": "Cualquier billetera",
                        "uses_label": "Solo cobros",
                        "has_no_use": false,
                        "can_delete": true,
                        "logo_url": null,
                        "initials": "PL",
                        "monogram_color": "#155e75"
                      },
                      "message": "Método de pago editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "La cuenta no sirve para lo marcado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "La cuenta no sirve para lo marcado",
                    "value": {
                      "success": false,
                      "message": "\"NIUBIZ TIENDA\" no permite pagos. Desmarca \"Para pagar\" o elige otra cuenta."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "payment_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "13"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar método de pago",
                  "value": {
                    "destination_rule": "type:wallet",
                    "use_for_expense": false
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Eliminar método de pago",
        "operationId": "EliminarMetodoPago",
        "description": "Elimina un método de pago que **nunca se usó**.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). En el éxito `data` es `{id}`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `payment_method_type_id` | string | Sí | Código del método. |\n\n**Reglas:**\n- Los códigos del sistema `01` a `10` no se eliminan (`can_delete: false`).\n- Si tiene cobros, pagos o movimientos de caja registrados no se elimina: desactívalo con **Editar método de pago** (`is_active: false`).\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el código no existe (o es una condición reservada del sistema, que no se administra por la API).\n- `409` si es del sistema o está en uso.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "21"
                      },
                      "message": "Método de pago eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En uso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En uso",
                    "value": {
                      "success": false,
                      "message": "El método de pago tiene pagos registrados y no se puede eliminar. Desactívalo en su lugar."
                    }
                  },
                  "e2": {
                    "summary": "Del sistema",
                    "value": {
                      "success": false,
                      "message": "Los métodos de pago del 01 al 10 son del sistema y no se pueden eliminar. Desactívalo en su lugar."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "payment_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "13"
          }
        ]
      }
    },
    "/api/payment-method-types/sort-order": {
      "post": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Ordenar métodos de pago",
        "operationId": "OrdenarMetodosPago",
        "description": "Guarda el orden en que se muestran los métodos de pago (en los formularios de cobro y en los reportes).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae los métodos enviados con su nueva posición.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `ids` | array de string | Sí | Códigos en el orden deseado. Cada uno debe existir y no repetirse. |\n\n**Reglas:**\n- Se guardan como posiciones 10, 20, 30... en el orden recibido.\n- Los métodos que no envías conservan su posición actual: para un orden completo envía todos.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (lista vacía, código inexistente o repetido).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Ordenado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ordenado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": "01",
                          "description": "Efectivo",
                          "sort_order": 10
                        },
                        {
                          "id": "13",
                          "description": "Yape",
                          "sort_order": 20
                        },
                        {
                          "id": "21",
                          "description": "Plin",
                          "sort_order": 30
                        },
                        {
                          "id": "04",
                          "description": "Transferencia",
                          "sort_order": 40
                        }
                      ],
                      "message": "Orden actualizado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Código inexistente",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Código inexistente",
                    "value": {
                      "success": false,
                      "message": {
                        "ids.0": [
                          "El campo ids.0 seleccionado no existe."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Ordenar métodos de pago",
                  "value": {
                    "ids": [
                      "01",
                      "13",
                      "21",
                      "04"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/payment-method-types/{payment_method_type_id}/logo": {
      "post": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Subir logotipo del método de pago",
        "operationId": "SubirLogotipoMetodoPago",
        "description": "Sube el logotipo oficial de la marca del método (se muestra al cobrar). Reemplaza el anterior. Si un método no tiene logo, el sistema muestra sus iniciales (`initials`) sobre `monogram_color`.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es el método actualizado, con `logo_url`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `payment_method_type_id` | string | Sí | Código del método. |\n\n**Cuerpo (`multipart/form-data`):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `file` | archivo | Sí | Imagen `jpeg`, `jpg`, `png`, `svg` o `webp`, máximo 1 MB. |\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el código no existe (o es una condición reservada del sistema, que no se administra por la API).\n- `422` si falta el archivo, no es una imagen permitida o pesa más de 1 MB.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Logotipo actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Logotipo actualizado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": "21",
                        "description": "Plin",
                        "sort_order": 140,
                        "is_active": true,
                        "is_credit": false,
                        "number_days": 0,
                        "has_card": false,
                        "charge": 0.0,
                        "is_payment_medium": true,
                        "goes_to_cash_drawer": false,
                        "use_for_income": true,
                        "use_for_expense": true,
                        "destination_rule": "account:5",
                        "default_destination_id": 5,
                        "allowed_destination_type": null,
                        "destination_label": "PLIN TIENDA CENTRO",
                        "uses_label": "Cobros y pagos",
                        "has_no_use": false,
                        "can_delete": true,
                        "logo_url": "https://empresa.dominio/logo/payment-methods/plin-21.png",
                        "initials": "PL",
                        "monogram_color": "#155e75"
                      },
                      "message": "Logotipo actualizado"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin archivo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin archivo",
                    "value": {
                      "success": false,
                      "message": {
                        "file": [
                          "El campo file es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "payment_method_type_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "13"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Logotipo (jpeg, png, svg o webp, máx. 1 MB)."
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        }
      }
    },
    "/api/cash-settings": {
      "get": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Ver opciones de caja",
        "operationId": "VerOpcionesCaja",
        "description": "Devuelve las opciones de configuración que afectan el flujo de caja y los reportes de caja.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Campos de `data`:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `destination_sale` | boolean | — | **Caja general por defecto:** en los formularios de venta del sistema el primer pago aparece con destino *Caja* (`cash`) ya elegido. No cambia lo que envía una integración: en la API siempre indicas `payment_destination_id`. |\n| `separate_cash_transactions` | boolean | — | Valor inicial de la opción *Separar ingresos y egresos* del **Libro de caja** (`separate_directions`). |\n| `order_cash_income` | boolean | — | Valor inicial de *Agrupar por* del **Libro de caja**: `true` = por tipo de comprobante (`group_by=document_type`); `false` = sin agrupar. |\n| `available_cash_report_seller` | boolean | — | `true` = los **vendedores** pueden generar reportes de caja (solo de sus propias cajas). `false` = solo administradores. |\n| `disabled_cash_reports` | array de string o null | — | Tipos de reporte **ocultos** en el catálogo: `cash_movements`, `cash_operations`, `cash_credit`, `cash_products`. `[]` o `null` = todos visibles. El **Cierre de caja** (`cash_close`) no se puede ocultar. |\n\n`cash_report_types` lista los tipos de reporte con su nombre, si se pueden ocultar (`toggleable`) y si hoy se muestran (`enabled`): son los valores permitidos de `disabled_cash_reports`.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Opciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Opciones",
                    "value": {
                      "success": true,
                      "data": {
                        "destination_sale": true,
                        "separate_cash_transactions": false,
                        "order_cash_income": true,
                        "available_cash_report_seller": true,
                        "disabled_cash_reports": [
                          "cash_products"
                        ],
                        "cash_report_types": [
                          {
                            "type": "cash_close",
                            "label": "Cierre de caja",
                            "toggleable": false,
                            "enabled": true
                          },
                          {
                            "type": "cash_movements",
                            "label": "Libro de caja",
                            "toggleable": true,
                            "enabled": true
                          },
                          {
                            "type": "cash_operations",
                            "label": "Resumen de operaciones",
                            "toggleable": true,
                            "enabled": true
                          },
                          {
                            "type": "cash_credit",
                            "label": "Créditos y cobranzas",
                            "toggleable": true,
                            "enabled": true
                          },
                          {
                            "type": "cash_products",
                            "label": "Productos vendidos",
                            "toggleable": true,
                            "enabled": false
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Editar opciones de caja",
        "operationId": "EditarOpcionesCaja",
        "description": "Cambia las opciones de caja. **Edición parcial**: envía solo lo que cambias (también acepta `PATCH`).\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae todas las opciones ya guardadas (mismo formato que **Ver opciones de caja**).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `destination_sale` | boolean | No | **Caja general por defecto:** en los formularios de venta del sistema el primer pago aparece con destino *Caja* (`cash`) ya elegido. No cambia lo que envía una integración: en la API siempre indicas `payment_destination_id`. |\n| `separate_cash_transactions` | boolean | No | Valor inicial de la opción *Separar ingresos y egresos* del **Libro de caja** (`separate_directions`). |\n| `order_cash_income` | boolean | No | Valor inicial de *Agrupar por* del **Libro de caja**: `true` = por tipo de comprobante (`group_by=document_type`); `false` = sin agrupar. |\n| `available_cash_report_seller` | boolean | No | `true` = los **vendedores** pueden generar reportes de caja (solo de sus propias cajas). `false` = solo administradores. |\n| `disabled_cash_reports` | array de string o null | No | Tipos de reporte **ocultos** en el catálogo: `cash_movements`, `cash_operations`, `cash_credit`, `cash_products`. `[]` o `null` = todos visibles. El **Cierre de caja** (`cash_close`) no se puede ocultar. |\n\n**Reglas:**\n- Se aplica de inmediato a todos los usuarios de la empresa.\n- `disabled_cash_reports` reemplaza la lista completa (no agrega): para volver a mostrar todos envía `[]`. Los repetidos se guardan una vez.\n- Ocultar un reporte solo lo quita del catálogo (**Catálogo de reportes de caja**); generarlo por su tipo sigue funcionando.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (valor no booleano, tipo de reporte no permitido o `cash_close` en `disabled_cash_reports`).\n- `422` si el cuerpo no trae ninguno de los campos.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Guardado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardado",
                    "value": {
                      "success": true,
                      "data": {
                        "destination_sale": true,
                        "separate_cash_transactions": false,
                        "order_cash_income": true,
                        "available_cash_report_seller": true,
                        "disabled_cash_reports": [
                          "cash_products"
                        ],
                        "cash_report_types": [
                          {
                            "type": "cash_close",
                            "label": "Cierre de caja",
                            "toggleable": false,
                            "enabled": true
                          },
                          {
                            "type": "cash_movements",
                            "label": "Libro de caja",
                            "toggleable": true,
                            "enabled": true
                          },
                          {
                            "type": "cash_operations",
                            "label": "Resumen de operaciones",
                            "toggleable": true,
                            "enabled": true
                          },
                          {
                            "type": "cash_credit",
                            "label": "Créditos y cobranzas",
                            "toggleable": true,
                            "enabled": true
                          },
                          {
                            "type": "cash_products",
                            "label": "Productos vendidos",
                            "toggleable": true,
                            "enabled": false
                          }
                        ]
                      },
                      "message": "Configuración actualizada"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Tipo no permitido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Tipo no permitido",
                    "value": {
                      "success": false,
                      "message": {
                        "disabled_cash_reports.0": [
                          "Tipo de reporte no válido. Valores permitidos: cash_movements, cash_operations, cash_credit, cash_products (el Cierre de caja no se puede ocultar)."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar opciones de caja",
                  "value": {
                    "available_cash_report_seller": true,
                    "disabled_cash_reports": [
                      "cash_products"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/cash-reports/catalog": {
      "get": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Catálogo de reportes de caja",
        "operationId": "CatalogoReportesCaja",
        "description": "Devuelve los reportes de caja disponibles con sus formatos, papeles, secciones y opciones (con su valor inicial según la configuración). Úsalo para construir el selector de reportes y para saber qué parámetros acepta **Generar reporte de caja**.\n\n**Quién puede usarlo:** un administrador, siempre y de cualquier caja. Un vendedor solo si la opción `available_cash_report_seller` está activa (**Editar opciones de caja**) y solo de **sus propias cajas**; en otro caso responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es una lista de categorías; cada una trae `reports[]`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `all` | 0 / 1 | No | Solo administradores: `1` incluye también los reportes ocultos (`enabled: false`). |\n\nReportes: `cash_close` (Cierre de caja), `cash_movements` (Libro de caja), `cash_operations` (Resumen de operaciones), `cash_credit` (Créditos y cobranzas), `cash_products` (Productos vendidos). Por defecto no vienen los que el administrador ocultó (`disabled_cash_reports`).\n\n**Errores:**\n- `403` si el usuario no puede generar reportes de caja.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Catálogo",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "key": "cash",
                          "label": "Caja",
                          "description": "Reportes del libro de caja. Todos comparten las mismas cifras.",
                          "reports": [
                            {
                              "type": "cash_close",
                              "enabled": true,
                              "toggleable": false,
                              "label": "Cierre de caja",
                              "question": "Arqueo del turno: efectivo teórico frente al contado y fondos por destino.",
                              "description": "Arqueo de efectivo, fondos por destino, cobros por medio de pago y ventas al crédito del turno.",
                              "audience": [
                                "Caja",
                                "Administración"
                              ],
                              "legacy_consumers": null,
                              "formats": [
                                "pdf",
                                "excel"
                              ],
                              "papers": [
                                "a4",
                                "ticket80",
                                "ticket58"
                              ],
                              "sections": [
                                {
                                  "key": "arqueo",
                                  "label": "Arqueo de efectivo",
                                  "description": "Saldo inicial, ingresos y egresos en efectivo, efectivo teórico y contado.",
                                  "locked": true,
                                  "default": true,
                                  "papers": null,
                                  "formats": null
                                },
                                {
                                  "key": "methods",
                                  "label": "Cobros por medio de pago",
                                  "description": "Ingresos y egresos por cada medio de pago.",
                                  "locked": false,
                                  "default": true,
                                  "papers": null,
                                  "formats": null
                                },
                                {
                                  "key": "credit",
                                  "label": "Ventas al crédito",
                                  "description": "Comprobantes emitidos al crédito en el turno y su saldo pendiente.",
                                  "locked": false,
                                  "default": true,
                                  "papers": null,
                                  "formats": null
                                }
                              ],
                              "options": [
                                {
                                  "key": "summary",
                                  "label": "Versión resumida",
                                  "type": "checkbox",
                                  "values": null,
                                  "papers": [
                                    "ticket80",
                                    "ticket58"
                                  ],
                                  "formats": null,
                                  "default": false
                                },
                                {
                                  "key": "all_methods",
                                  "label": "Incluir medios de pago sin movimiento",
                                  "type": "checkbox",
                                  "values": null,
                                  "papers": null,
                                  "formats": null,
                                  "default": false
                                }
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin permiso de reportes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin permiso de reportes",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para generar reportes de caja."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` = incluir ocultos (solo administradores)."
          }
        ]
      }
    },
    "/api/cash-reports/daily": {
      "get": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Consolidado de cajas del día",
        "operationId": "ConsolidadoCajasDia",
        "description": "Genera el consolidado de **todas las cajas abiertas en una fecha** (una fila por caja con saldo inicial, ingresos, egresos, teórico, arqueo y diferencia, más los totales por medio de pago). Cada fila coincide con el Cierre de caja de esa caja.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`. Un vendedor recibe `403` aunque tenga permiso de reportes (el consolidado incluye las cajas de todos).\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. PDF A4 (`application/pdf`) o Excel (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`).\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date` | YYYY-MM-DD | No | Fecha de apertura de las cajas. Por defecto, hoy. |\n| `establishment_id` | integer | No | Solo las cajas de ese establecimiento. |\n| `format` | string | No | `pdf` (por defecto) o `excel`. |\n| `action` | string | No | Solo PDF: `preview` (por defecto) o `download`. |\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` si la fecha no tiene el formato `YYYY-MM-DD`, el establecimiento no existe o el formato no es válido.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "PDF"
          },
          "403": {
            "description": "No administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede generar el consolidado de cajas del día."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-07",
            "description": "Fecha `YYYY-MM-DD`."
          },
          {
            "name": "establishment_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Establecimiento."
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "pdf",
            "description": "`pdf` o `excel`."
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "download",
            "description": "`preview` o `download`."
          }
        ]
      }
    },
    "/api/cash-reports/{cash_report_type}/{cash_id}": {
      "get": {
        "tags": [
          "Flujo de caja"
        ],
        "summary": "Generar reporte de caja",
        "operationId": "GenerarReporteCaja",
        "description": "Genera un reporte de una caja (turno): cierre con arqueo, libro de caja, resumen de operaciones, créditos y cobranzas o productos vendidos. Todos salen del mismo libro de caja, así que sus cifras coinciden entre sí.\n\n**Quién puede usarlo:** un administrador, siempre y de cualquier caja. Un vendedor solo si la opción `available_cash_report_seller` está activa (**Editar opciones de caja**) y solo de **sus propias cajas**; en otro caso responde `403`.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. PDF (`application/pdf`) o Excel (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`). Nombre: `Caja_<tipo>_<usuario>_<AAAAMMDD>_<HHmm>`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `cash_report_type` | string | Sí | `cash_close`, `cash_movements`, `cash_operations`, `cash_credit` o `cash_products`. También acepta los nombres anteriores (`cash_summary`, `cash_simple`, `summary_daily_operations`, `general_with_payments`, `income_egress`, `payments_associated`, `income_summary`, `products`, `products_garage`, `cash`). |\n| `cash_id` | integer | Sí | Id de la caja (lo guardan **Aperturar caja** y **Consultar caja abierta del usuario**). |\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | No | `pdf` (por defecto) o `excel`. Debe estar en `formats` del reporte. |\n| `paper` | string | No | Solo PDF: `a4` (por defecto), `ticket80` o `ticket58`. Debe estar en `papers` del reporte. |\n| `action` | string | No | `preview` (por defecto, `Content-Disposition: inline`) o `download` (`attachment`). |\n| `sections` | string | No | Secciones a imprimir separadas por coma (p. ej. `methods,movements`), de las que ofrece el reporte en el catálogo. Las bloqueadas (`locked`) van siempre. Sin el parámetro: las que vienen por defecto. |\n| `direction` | string | No | `income` = solo ingresos; `egress` = solo egresos. |\n| `group_by` | string | No | `none`, `method` (medio de pago) o `document_type` (tipo de comprobante). Por defecto según `order_cash_income`. |\n| `summary, garage, only_cash, separate_directions, by_currency, sort_desc, credit_list, only_pending, all_methods, include_voided_products` | 0 / 1 | No | Opciones de cada reporte (ver `options` en el catálogo): versión resumida (ticket), galones, solo efectivo, separar ingresos y egresos, una tabla por moneda, orden descendente, detalle de créditos, solo saldos pendientes, incluir medios sin movimiento, incluir comprobantes anulados. |\n\n**Reglas:**\n- Un reporte oculto por el administrador (`disabled_cash_reports`) igual se puede generar por su tipo.\n- Se puede generar con la caja abierta (cifras al momento) o cerrada.\n\n**Errores:**\n- `403` si no puedes generar reportes de caja o la caja es de otro vendedor.\n- `404` si la caja o el tipo de reporte no existen.\n- `422` si el formato o el papel no están disponibles para ese reporte (p. ej. `cash_operations` solo se imprime en A4).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "PDF"
          },
          "403": {
            "description": "Caja de otro vendedor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Caja de otro vendedor",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Reporte no disponible",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Reporte no disponible",
                    "value": {
                      "success": false,
                      "message": "Reporte no disponible"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Papel no disponible",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Papel no disponible",
                    "value": {
                      "success": false,
                      "message": "Papel no disponible para este reporte"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cash_report_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cash_close"
          },
          {
            "name": "cash_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "pdf",
            "description": "`pdf` o `excel`."
          },
          {
            "name": "paper",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "ticket80",
            "description": "`a4`, `ticket80` o `ticket58`."
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "preview",
            "description": "`preview` o `download`."
          },
          {
            "name": "sections",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "methods,movements",
            "description": "Secciones separadas por coma."
          },
          {
            "name": "only_cash",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Solo movimientos en efectivo."
          }
        ]
      }
    },
    "/api/subscriptions/periods": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Listar periodos",
        "operationId": "ListarPeriodos",
        "description": "Periodicidades de cobro disponibles para los planes. El `id` es el `cat_period_id` del plan.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es la lista completa, sin paginación.\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Periodos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Periodos",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1,
                          "code": "M",
                          "name": "Mensual"
                        },
                        {
                          "id": 2,
                          "code": "Y",
                          "name": "Anual"
                        },
                        {
                          "id": 3,
                          "code": "D",
                          "name": "Diario"
                        },
                        {
                          "id": 4,
                          "code": "W",
                          "name": "Semanal"
                        },
                        {
                          "id": 5,
                          "code": "Q",
                          "name": "Quincenal"
                        },
                        {
                          "id": 6,
                          "code": "B",
                          "name": "Bimestral"
                        },
                        {
                          "id": 7,
                          "code": "T",
                          "name": "Trimestral"
                        },
                        {
                          "id": 8,
                          "code": "S",
                          "name": "Semestral"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/subscriptions/plans": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Listar planes",
        "operationId": "ListarPlanes",
        "description": "Lista los planes de suscripción, del más reciente al más antiguo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). El vendedor los necesita para suscribir clientes.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `status` | 0 / 1 | No | `1` activos, `0` inactivos. Sin el parámetro, todos. |\n| `cat_period_id` | integer | No | Solo los de esa periodicidad. |\n| `search` | string | No | Coincidencia parcial en el nombre o la descripción. |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada plan:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del plan. |\n| `name / description` | string | Nombre y descripción. |\n| `status` | boolean | `true` activo: se puede suscribir clientes. `false` inactivo. |\n| `cat_period_id / period` | integer / objeto | Periodicidad del cobro `{id, code, name}`. |\n| `unlimited` | boolean | `true` = sin fecha de fin: se cobra cada periodo hasta cancelar. |\n| `quantity_period` | integer o null | Cantidad de cobros (periodos) del plan; `null` si es ilimitado. |\n| `trial_days` | integer o null | Días de prueba gratis antes del primer cobro. |\n| `total_taxed / total_exonerated / total_unaffected / total_igv / total_value / total` | number | Totales por periodo calculados por el servidor. |\n| `items` | array | Productos del plan con sus importes calculados (`unit_value` sin IGV, `total` con IGV) y `apply_in_period`. |\n| `subscriptions_count / can_delete` | integer / boolean | Suscripciones que usan el plan; con alguna, `can_delete` es `false`. |\n| `checkout_url` | string | Página pública del plan para que el cliente se suscriba y pague en línea. |\n\n**Errores:**\n- `422` si `status` no es 0/1.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 3,
                          "name": "Plan Mensual Gold",
                          "description": "Acceso ilimitado al gimnasio y clases grupales",
                          "status": true,
                          "cat_period_id": 1,
                          "period": {
                            "id": 1,
                            "code": "M",
                            "name": "Mensual"
                          },
                          "unlimited": false,
                          "quantity_period": 12,
                          "trial_days": 7,
                          "currency_type_id": "PEN",
                          "total_taxed": 100.0,
                          "total_exonerated": 0.0,
                          "total_unaffected": 0.0,
                          "total_igv": 18.0,
                          "total_value": 100.0,
                          "total": 118.0,
                          "items": [
                            {
                              "id": 77,
                              "item_id": 845,
                              "description": "MEMBRESÍA GIMNASIO",
                              "internal_id": "MEM-001",
                              "quantity": 1.0,
                              "unit_price": 118.0,
                              "unit_value": 100.0,
                              "affectation_igv_type_id": "10",
                              "total_value": 100.0,
                              "total_igv": 18.0,
                              "total": 118.0,
                              "apply_in_period": "all"
                            }
                          ],
                          "subscriptions_count": 24,
                          "can_delete": false,
                          "checkout_url": "https://empresa.dominio/full_suscription/plans/3"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "`1` activos, `0` inactivos."
          },
          {
            "name": "cat_period_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Periodicidad."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Busca en nombre y descripción."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Crear plan",
        "operationId": "CrearPlan",
        "description": "Registra un plan de suscripción.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con el plan creado (incluye su `id`).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string (máx. 255) | Sí | Nombre del plan. |\n| `description` | string (máx. 255) | Sí | Descripción. |\n| `cat_period_id` | integer | Sí | Periodicidad: id de **Listar periodos** (1 mensual, 2 anual, 3 diario, 4 semanal, 5 quincenal, 6 bimestral, 7 trimestral, 8 semestral). |\n| `unlimited` | boolean | No | `true` = plan ilimitado (sin cantidad de periodos). Por defecto `false`. |\n| `quantity_period` | integer (1 a 1000) | Sí si no es ilimitado | Cantidad de cobros. Se ignora en un plan ilimitado. |\n| `trial_days` | integer (0 a 365) | No | Días de prueba gratis. `0` o `null` = sin prueba. |\n| `status` | boolean | No | Activo. Por defecto `true`. |\n| `currency_type_id` | string | No | Moneda (`PEN`, `USD`). Por defecto `PEN`. |\n| `items` | array (1 a 50) | Sí | Productos que se cobran cada periodo. |\n| `items[].item_id` | integer | Sí | Id del producto o servicio. |\n| `items[].quantity` | number (> 0) | Sí | Cantidad. |\n| `items[].unit_price` | number (≥ 0) | Sí | Precio de venta unitario. Si es gravado, **incluye IGV**. |\n| `items[].affectation_igv_type_id` | string | No | `10` gravado (por defecto, o la afectación de venta del producto), `20` exonerado, `30` inafecto. |\n| `items[].apply_in_period` | string | No | `all` = se cobra en todos los periodos (por defecto). `first` = solo en el primer cobro (solo planes ilimitados). |\n\n**Reglas:**\n- Los importes de cada producto y los totales del plan los **calcula el servidor** desde `quantity`, `unit_price` y la afectación (IGV 18%).\n- Al menos un producto debe tener `apply_in_period: all`. `first` solo se admite en planes ilimitados.\n- Los cambios del plan no modifican las suscripciones existentes: cada suscripción guarda el monto y los productos del plan al momento de suscribirse.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (falta `name`, `description`, `cat_period_id`, `quantity_period` en un plan no ilimitado o `items`; producto inexistente; cantidad 0; ningún producto con `apply_in_period: all`; `first` en un plan con cantidad de periodos).\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "name": "Plan Mensual Gold",
                        "description": "Acceso ilimitado al gimnasio y clases grupales",
                        "status": true,
                        "cat_period_id": 1,
                        "period": {
                          "id": 1,
                          "code": "M",
                          "name": "Mensual"
                        },
                        "unlimited": false,
                        "quantity_period": 12,
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total_taxed": 100.0,
                        "total_exonerated": 0.0,
                        "total_unaffected": 0.0,
                        "total_igv": 18.0,
                        "total_value": 100.0,
                        "total": 118.0,
                        "items": [
                          {
                            "id": 77,
                            "item_id": 845,
                            "description": "MEMBRESÍA GIMNASIO",
                            "internal_id": "MEM-001",
                            "quantity": 1.0,
                            "unit_price": 118.0,
                            "unit_value": 100.0,
                            "affectation_igv_type_id": "10",
                            "total_value": 100.0,
                            "total_igv": 18.0,
                            "total": 118.0,
                            "apply_in_period": "all"
                          }
                        ],
                        "subscriptions_count": 0,
                        "can_delete": true,
                        "checkout_url": "https://empresa.dominio/full_suscription/plans/3"
                      },
                      "message": "Plan registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "quantity_period": [
                          "La cantidad de periodos es obligatoria si el plan no es ilimitado."
                        ],
                        "items": [
                          "Se requiere al menos un producto."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear plan",
                  "value": {
                    "name": "Plan Mensual Gold",
                    "description": "Acceso ilimitado al gimnasio y clases grupales",
                    "cat_period_id": 1,
                    "quantity_period": 12,
                    "trial_days": 7,
                    "items": [
                      {
                        "item_id": 845,
                        "quantity": 1,
                        "unit_price": 118,
                        "affectation_igv_type_id": "10"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/plans/{subscription_plan_id}": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Ver plan",
        "operationId": "VerPlan",
        "description": "Devuelve un plan con sus productos y totales.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor).\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_plan_id` | integer | Sí | Id del plan. |\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del plan. |\n| `name / description` | string | Nombre y descripción. |\n| `status` | boolean | `true` activo: se puede suscribir clientes. `false` inactivo. |\n| `cat_period_id / period` | integer / objeto | Periodicidad del cobro `{id, code, name}`. |\n| `unlimited` | boolean | `true` = sin fecha de fin: se cobra cada periodo hasta cancelar. |\n| `quantity_period` | integer o null | Cantidad de cobros (periodos) del plan; `null` si es ilimitado. |\n| `trial_days` | integer o null | Días de prueba gratis antes del primer cobro. |\n| `total_taxed / total_exonerated / total_unaffected / total_igv / total_value / total` | number | Totales por periodo calculados por el servidor. |\n| `items` | array | Productos del plan con sus importes calculados (`unit_value` sin IGV, `total` con IGV) y `apply_in_period`. |\n| `subscriptions_count / can_delete` | integer / boolean | Suscripciones que usan el plan; con alguna, `can_delete` es `false`. |\n| `checkout_url` | string | Página pública del plan para que el cliente se suscriba y pague en línea. |\n\n**Errores:**\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Plan",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "name": "Plan Mensual Gold",
                        "description": "Acceso ilimitado al gimnasio y clases grupales",
                        "status": true,
                        "cat_period_id": 1,
                        "period": {
                          "id": 1,
                          "code": "M",
                          "name": "Mensual"
                        },
                        "unlimited": false,
                        "quantity_period": 12,
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total_taxed": 100.0,
                        "total_exonerated": 0.0,
                        "total_unaffected": 0.0,
                        "total_igv": 18.0,
                        "total_value": 100.0,
                        "total": 118.0,
                        "items": [
                          {
                            "id": 77,
                            "item_id": 845,
                            "description": "MEMBRESÍA GIMNASIO",
                            "internal_id": "MEM-001",
                            "quantity": 1.0,
                            "unit_price": 118.0,
                            "unit_value": 100.0,
                            "affectation_igv_type_id": "10",
                            "total_value": 100.0,
                            "total_igv": 18.0,
                            "total": 118.0,
                            "apply_in_period": "all"
                          }
                        ],
                        "subscriptions_count": 24,
                        "can_delete": false,
                        "checkout_url": "https://empresa.dominio/full_suscription/plans/3"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_plan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3"
          }
        ]
      },
      "put": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Editar plan",
        "operationId": "EditarPlan",
        "description": "Edita un plan. **Edición parcial**: los campos que no envías conservan su valor (también acepta `PATCH`). Si envías `items`, reemplazan a todos los productos del plan.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_plan_id` | integer | Sí | Id del plan. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `name` | string (máx. 255) | No | Nombre del plan. |\n| `description` | string (máx. 255) | No | Descripción. |\n| `cat_period_id` | integer | No | Periodicidad: id de **Listar periodos** (1 mensual, 2 anual, 3 diario, 4 semanal, 5 quincenal, 6 bimestral, 7 trimestral, 8 semestral). |\n| `unlimited` | boolean | No | `true` = plan ilimitado (sin cantidad de periodos). Por defecto `false`. |\n| `quantity_period` | integer (1 a 1000) | No | Cantidad de cobros. Se ignora en un plan ilimitado. |\n| `trial_days` | integer (0 a 365) | No | Días de prueba gratis. `0` o `null` = sin prueba. |\n| `status` | boolean | No | Activo. Por defecto `true`. |\n| `currency_type_id` | string | No | Moneda (`PEN`, `USD`). Por defecto `PEN`. |\n| `items` | array (1 a 50) | No | Productos que se cobran cada periodo. |\n| `items[].item_id` | integer | No | Id del producto o servicio. |\n| `items[].quantity` | number (> 0) | No | Cantidad. |\n| `items[].unit_price` | number (≥ 0) | No | Precio de venta unitario. Si es gravado, **incluye IGV**. |\n| `items[].affectation_igv_type_id` | string | No | `10` gravado (por defecto, o la afectación de venta del producto), `20` exonerado, `30` inafecto. |\n| `items[].apply_in_period` | string | No | `all` = se cobra en todos los periodos (por defecto). `first` = solo en el primer cobro (solo planes ilimitados). |\n\n**Reglas:**\n- Los importes de cada producto y los totales del plan los **calcula el servidor** desde `quantity`, `unit_price` y la afectación (IGV 18%).\n- Al menos un producto debe tener `apply_in_period: all`. `first` solo se admite en planes ilimitados.\n- Los cambios del plan no modifican las suscripciones existentes: cada suscripción guarda el monto y los productos del plan al momento de suscribirse.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el registro no existe.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "name": "Plan Mensual Gold Plus",
                        "description": "Acceso ilimitado al gimnasio y clases grupales",
                        "status": true,
                        "cat_period_id": 1,
                        "period": {
                          "id": 1,
                          "code": "M",
                          "name": "Mensual"
                        },
                        "unlimited": false,
                        "quantity_period": 12,
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total_taxed": 109.32,
                        "total_exonerated": 30.0,
                        "total_unaffected": 0.0,
                        "total_igv": 19.68,
                        "total_value": 139.32,
                        "total": 159.0,
                        "items": [
                          {
                            "id": 77,
                            "item_id": 845,
                            "description": "MEMBRESÍA GIMNASIO",
                            "internal_id": "MEM-001",
                            "quantity": 1.0,
                            "unit_price": 118.0,
                            "unit_value": 100.0,
                            "affectation_igv_type_id": "10",
                            "total_value": 100.0,
                            "total_igv": 18.0,
                            "total": 118.0,
                            "apply_in_period": "all"
                          }
                        ],
                        "subscriptions_count": 24,
                        "can_delete": false,
                        "checkout_url": "https://empresa.dominio/full_suscription/plans/3"
                      },
                      "message": "Plan editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_plan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar plan",
                  "value": {
                    "name": "Plan Mensual Gold Plus",
                    "items": [
                      {
                        "item_id": 845,
                        "quantity": 1,
                        "unit_price": 129
                      },
                      {
                        "item_id": 912,
                        "quantity": 1,
                        "unit_price": 30,
                        "affectation_igv_type_id": "20",
                        "apply_in_period": "all"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Eliminar plan",
        "operationId": "EliminarPlan",
        "description": "Elimina un plan **sin suscripciones** junto con sus productos.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). En el éxito `data` es `{id}`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_plan_id` | integer | Sí | Id del plan. |\n\n**Reglas:**\n- Si alguna suscripción (en cualquier estado) usa el plan, no se elimina: desactívalo con **Desactivar plan**.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el registro no existe.\n- `409` si el plan tiene suscripciones.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3
                      },
                      "message": "Plan eliminado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Con suscripciones",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Con suscripciones",
                    "value": {
                      "success": false,
                      "message": "El plan tiene 24 suscripciones y no se puede eliminar. Desactívalo en su lugar."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_plan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3"
          }
        ]
      }
    },
    "/api/subscriptions/plans/{subscription_plan_id}/activate": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Activar plan",
        "operationId": "ActivarPlan",
        "description": "Activa el plan: vuelve a aceptar suscripciones y su página pública de pago queda disponible.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_plan_id` | integer | Sí | Id del plan. |\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Activado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Activado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "name": "Plan Mensual Gold",
                        "description": "Acceso ilimitado al gimnasio y clases grupales",
                        "status": true,
                        "cat_period_id": 1,
                        "period": {
                          "id": 1,
                          "code": "M",
                          "name": "Mensual"
                        },
                        "unlimited": false,
                        "quantity_period": 12,
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total_taxed": 100.0,
                        "total_exonerated": 0.0,
                        "total_unaffected": 0.0,
                        "total_igv": 18.0,
                        "total_value": 100.0,
                        "total": 118.0,
                        "items": [
                          {
                            "id": 77,
                            "item_id": 845,
                            "description": "MEMBRESÍA GIMNASIO",
                            "internal_id": "MEM-001",
                            "quantity": 1.0,
                            "unit_price": 118.0,
                            "unit_value": 100.0,
                            "affectation_igv_type_id": "10",
                            "total_value": 100.0,
                            "total_igv": 18.0,
                            "total": 118.0,
                            "apply_in_period": "all"
                          }
                        ],
                        "subscriptions_count": 24,
                        "can_delete": false,
                        "checkout_url": "https://empresa.dominio/full_suscription/plans/3"
                      },
                      "message": "Plan activado"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_plan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3"
          }
        ]
      }
    },
    "/api/subscriptions/plans/{subscription_plan_id}/deactivate": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Desactivar plan",
        "operationId": "DesactivarPlan",
        "description": "Desactiva el plan: no admite nuevas suscripciones. Las suscripciones existentes siguen cobrándose.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_plan_id` | integer | Sí | Id del plan. |\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Desactivado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Desactivado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 3,
                        "name": "Plan Mensual Gold",
                        "description": "Acceso ilimitado al gimnasio y clases grupales",
                        "status": false,
                        "cat_period_id": 1,
                        "period": {
                          "id": 1,
                          "code": "M",
                          "name": "Mensual"
                        },
                        "unlimited": false,
                        "quantity_period": 12,
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total_taxed": 100.0,
                        "total_exonerated": 0.0,
                        "total_unaffected": 0.0,
                        "total_igv": 18.0,
                        "total_value": 100.0,
                        "total": 118.0,
                        "items": [
                          {
                            "id": 77,
                            "item_id": 845,
                            "description": "MEMBRESÍA GIMNASIO",
                            "internal_id": "MEM-001",
                            "quantity": 1.0,
                            "unit_price": 118.0,
                            "unit_value": 100.0,
                            "affectation_igv_type_id": "10",
                            "total_value": 100.0,
                            "total_igv": 18.0,
                            "total": 118.0,
                            "apply_in_period": "all"
                          }
                        ],
                        "subscriptions_count": 24,
                        "can_delete": false,
                        "checkout_url": "https://empresa.dominio/full_suscription/plans/3"
                      },
                      "message": "Plan desactivado"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_plan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "3"
          }
        ]
      }
    },
    "/api/subscriptions/subscribers": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Listar suscriptores",
        "operationId": "ListarSuscriptores",
        "description": "Lista los clientes habilitados de la empresa con sus datos de suscriptor, del más reciente al más antiguo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `search` | string | No | Coincidencia parcial en nombre o número de documento. |\n| `parent_id` | integer | No | Solo los hijos de ese suscriptor. |\n| `only_parents` | 0 / 1 | No | `1` = solo los que no tienen padre. |\n| `with_subscriptions` | 0 / 1 | No | `1` = solo clientes que tienen alguna suscripción. |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada suscriptor:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del suscriptor (es el id del cliente: el mismo `customer_id` de los comprobantes). |\n| `identity_document_type_id / number / name / trade_name` | string | Identificación. |\n| `email / telephone / address / country_id / location_id` | string / array | Contacto y dirección. |\n| `parent_id` | integer o null | Suscriptor padre. |\n| `discord_user / slack_channel / discord_channel / gitlab_user` | string o null | Datos extra. |\n| `subscriptions_count` | integer | Suscripciones del cliente. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 1520,
                          "identity_document_type_id": "1",
                          "number": "45879632",
                          "name": "MARÍA FERNANDA QUISPE ROJAS",
                          "trade_name": null,
                          "email": "maria.quispe@correo.pe",
                          "telephone": "987654321",
                          "address": "Av. Arequipa 1450, Lince",
                          "country_id": "PE",
                          "location_id": [
                            "15",
                            "1501",
                            "150116"
                          ],
                          "parent_id": null,
                          "discord_user": "mquispe",
                          "slack_channel": null,
                          "discord_channel": "#socios-gold",
                          "gitlab_user": null,
                          "subscriptions_count": 1
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre o número de documento."
          },
          {
            "name": "parent_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1520",
            "description": "Hijos de este suscriptor."
          },
          {
            "name": "only_parents",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Solo suscriptores sin padre."
          },
          {
            "name": "with_subscriptions",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Solo con suscripciones."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Crear suscriptor",
        "operationId": "CrearSuscriptor",
        "description": "Registra un cliente como suscriptor, con las mismas validaciones que el registro de clientes del sistema.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con el suscriptor creado (incluye su `id` y `servers`).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `identity_document_type_id` | string | Sí al crear | Tipo de documento: `1` DNI, `6` RUC, `4` carnet de extranjería, `7` pasaporte, `0` sin documento. |\n| `number` | string | Sí al crear | Número de documento. Único entre los clientes. |\n| `name` | string | Sí al crear | Nombre o razón social. Único entre los clientes. |\n| `trade_name` | string | No | Nombre comercial. |\n| `email` | string (email) | No | Correo: a él llegan los avisos de cobro con el enlace de pago. |\n| `telephone` | string | No | Teléfono. |\n| `address` | string | Con RUC 20 | Dirección. Obligatoria salvo con DNI, carnet de extranjería o RUC 10. |\n| `country_id` | string | No | País. Por defecto `PE`. |\n| `location_id` | array [departamento, provincia, distrito] | Con RUC 20 en PE | Ubigeo, p. ej. `[\"15\", \"1501\", \"150116\"]`. |\n| `parent_id` | integer | No | Id del suscriptor padre (para registrar un hijo). `0` o sin enviar = sin padre. |\n| `discord_user / slack_channel / discord_channel / gitlab_user` | string | No | Datos extra del suscriptor. |\n| `servers` | array | No | Servidores del suscriptor: `{id?, host, ip, user, password}`. Con `id` edita uno existente del mismo suscriptor; sin `id` agrega uno. |\n\n**Reglas:**\n- Se registra como cliente (`customers`): queda disponible también para emitir comprobantes.\n- Para registrar un hijo envía `parent_id` con el id de otro suscriptor.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (falta documento o nombre, número o nombre repetido, correo inválido o repetido, padre inexistente; con RUC 20: falta la dirección o el ubigeo, con `message` de texto).\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Creado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1520,
                        "identity_document_type_id": "1",
                        "number": "45879632",
                        "name": "MARÍA FERNANDA QUISPE ROJAS",
                        "trade_name": null,
                        "email": "maria.quispe@correo.pe",
                        "telephone": "987654321",
                        "address": "Av. Arequipa 1450, Lince",
                        "country_id": "PE",
                        "location_id": [
                          "15",
                          "1501",
                          "150116"
                        ],
                        "parent_id": null,
                        "discord_user": "mquispe",
                        "slack_channel": null,
                        "discord_channel": "#socios-gold",
                        "gitlab_user": null,
                        "subscriptions_count": 0,
                        "servers": []
                      },
                      "message": "Suscriptor registrado con éxito"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Número repetido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Número repetido",
                    "value": {
                      "success": false,
                      "message": {
                        "number": [
                          "El campo número ya ha sido registrado."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear suscriptor",
                  "value": {
                    "identity_document_type_id": "1",
                    "number": "45879632",
                    "name": "MARÍA FERNANDA QUISPE ROJAS",
                    "email": "maria.quispe@correo.pe",
                    "telephone": "987654321",
                    "address": "Av. Arequipa 1450, Lince",
                    "discord_user": "mquispe",
                    "discord_channel": "#socios-gold"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/subscribers/{subscriber_id}": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Ver suscriptor",
        "operationId": "VerSuscriptor",
        "description": "Devuelve el suscriptor con sus hijos, servidores y suscripciones.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscriber_id` | integer | Sí | Id del suscriptor (cliente). |\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del suscriptor (es el id del cliente: el mismo `customer_id` de los comprobantes). |\n| `identity_document_type_id / number / name / trade_name` | string | Identificación. |\n| `email / telephone / address / country_id / location_id` | string / array | Contacto y dirección. |\n| `parent_id` | integer o null | Suscriptor padre. |\n| `discord_user / slack_channel / discord_channel / gitlab_user` | string o null | Datos extra. |\n| `subscriptions_count` | integer | Suscripciones del cliente. |\n\nAdemás: `children[]` `{id, name, number, identity_document_type_id}`, `servers[]` `{id, host, ip, user, has_password}` (la contraseña nunca se devuelve) y `subscriptions[]` `{id, plan_id, plan_name, status, start_date, total}`.\n\n**Errores:**\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Suscriptor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Suscriptor",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1520,
                        "identity_document_type_id": "1",
                        "number": "45879632",
                        "name": "MARÍA FERNANDA QUISPE ROJAS",
                        "trade_name": null,
                        "email": "maria.quispe@correo.pe",
                        "telephone": "987654321",
                        "address": "Av. Arequipa 1450, Lince",
                        "country_id": "PE",
                        "location_id": [
                          "15",
                          "1501",
                          "150116"
                        ],
                        "parent_id": null,
                        "discord_user": "mquispe",
                        "slack_channel": null,
                        "discord_channel": "#socios-gold",
                        "gitlab_user": null,
                        "subscriptions_count": 1,
                        "children": [
                          {
                            "id": 1533,
                            "name": "DIEGO QUISPE ROJAS",
                            "number": "78451236",
                            "identity_document_type_id": "1"
                          }
                        ],
                        "servers": [
                          {
                            "id": 12,
                            "host": "vps1.midominio.pe",
                            "ip": "190.12.45.8",
                            "user": "deploy",
                            "has_password": true
                          }
                        ],
                        "subscriptions": [
                          {
                            "id": 48,
                            "plan_id": 3,
                            "plan_name": "Plan Mensual Gold",
                            "status": "authorized",
                            "start_date": "2026-11-14",
                            "total": 118.0
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscriber_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1520"
          }
        ]
      },
      "put": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Editar suscriptor",
        "operationId": "EditarSuscriptor",
        "description": "Edita el suscriptor. **Edición parcial** (también acepta `PATCH`): lo que no envías se conserva, incluidas sus direcciones adicionales y los datos extra no enviados.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscriber_id` | integer | Sí | Id del suscriptor (cliente). |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `identity_document_type_id` | string | No | Tipo de documento: `1` DNI, `6` RUC, `4` carnet de extranjería, `7` pasaporte, `0` sin documento. |\n| `number` | string | No | Número de documento. Único entre los clientes. |\n| `name` | string | No | Nombre o razón social. Único entre los clientes. |\n| `trade_name` | string | No | Nombre comercial. |\n| `email` | string (email) | No | Correo: a él llegan los avisos de cobro con el enlace de pago. |\n| `telephone` | string | No | Teléfono. |\n| `address` | string | No | Dirección. Obligatoria salvo con DNI, carnet de extranjería o RUC 10. |\n| `country_id` | string | No | País. Por defecto `PE`. |\n| `location_id` | array [departamento, provincia, distrito] | No | Ubigeo, p. ej. `[\"15\", \"1501\", \"150116\"]`. |\n| `parent_id` | integer | No | Id del suscriptor padre (para registrar un hijo). `0` o sin enviar = sin padre. |\n| `discord_user / slack_channel / discord_channel / gitlab_user` | string | No | Datos extra del suscriptor. |\n| `servers` | array | No | Servidores del suscriptor: `{id?, host, ip, user, password}`. Con `id` edita uno existente del mismo suscriptor; sin `id` agrega uno. |\n\n**Reglas:**\n- En `servers`, un servidor con `id` debe ser de este suscriptor. Si no envías `password`, se conserva la guardada.\n\n**Errores:**\n- `404` si el registro no existe.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Editado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Editado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 1520,
                        "identity_document_type_id": "1",
                        "number": "45879632",
                        "name": "MARÍA FERNANDA QUISPE ROJAS",
                        "trade_name": null,
                        "email": "maria.quispe@correo.pe",
                        "telephone": "912345678",
                        "address": "Av. Arequipa 1450, Lince",
                        "country_id": "PE",
                        "location_id": [
                          "15",
                          "1501",
                          "150116"
                        ],
                        "parent_id": null,
                        "discord_user": "mquispe",
                        "slack_channel": "#soporte",
                        "discord_channel": "#socios-gold",
                        "gitlab_user": null,
                        "subscriptions_count": 1,
                        "servers": [
                          {
                            "id": 12,
                            "host": "vps2.midominio.pe",
                            "ip": "190.12.45.8",
                            "user": "deploy",
                            "has_password": true
                          }
                        ]
                      },
                      "message": "Suscriptor editado con éxito"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscriber_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1520"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Editar suscriptor",
                  "value": {
                    "telephone": "912345678",
                    "slack_channel": "#soporte",
                    "servers": [
                      {
                        "id": 12,
                        "host": "vps2.midominio.pe"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/subscriptions": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Listar suscripciones",
        "operationId": "ListarSuscripciones",
        "description": "Lista las suscripciones, de la más reciente a la más antigua.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `customer_id` | integer | No | Solo las de ese suscriptor. |\n| `plan_id` | integer | No | Solo las de ese plan. |\n| `status` | string | No | `authorized`, `paused`, `cancelled` o `finished`. |\n| `search` | string | No | Nombre o número de documento del suscriptor. |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada suscripción:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id de la suscripción. |\n| `status / status_description` | string | `authorized` Activa, `paused` Pausada, `cancelled` Cancelada, `finished` Finalizada. |\n| `plan_id / plan_name` | integer / string | Plan. |\n| `customer_id / customer` | integer / objeto | Suscriptor `{id, name, number, identity_document_type_id, email}`. |\n| `cat_period_id / period_name / unlimited / quantity_period` |  | Periodicidad y cantidad de cobros copiadas del plan. |\n| `orders_created` | integer | Órdenes de cobro creadas hasta ahora. |\n| `start_date / end_date` | fecha | Primer cobro y último cobro (`end_date` `null` si es ilimitado). |\n| `trial_start_date / trial_days` | fecha / integer | Prueba gratis. |\n| `total / currency_type_id` | number / string | Monto de cada periodo (copiado del plan al suscribirse). |\n\n**Errores:**\n- `422` si `status` no es un estado válido.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 48,
                          "status": "authorized",
                          "status_description": "Activa",
                          "plan_id": 3,
                          "plan_name": "Plan Mensual Gold",
                          "customer_id": 1520,
                          "customer": {
                            "id": 1520,
                            "name": "MARÍA FERNANDA QUISPE ROJAS",
                            "number": "45879632",
                            "identity_document_type_id": "1",
                            "email": "maria.quispe@correo.pe"
                          },
                          "cat_period_id": 1,
                          "period_name": "Mensual",
                          "unlimited": false,
                          "quantity_period": 12,
                          "orders_created": 1,
                          "start_date": "2026-11-14",
                          "end_date": "2027-10-14",
                          "trial_start_date": "2026-11-07",
                          "trial_days": 7,
                          "currency_type_id": "PEN",
                          "total": 118.0,
                          "created_at": "2026-11-07 10:15:32"
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1520",
            "description": "Suscriptor."
          },
          {
            "name": "plan_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "3",
            "description": "Plan."
          },
          {
            "name": "status",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "authorized",
            "description": "Estado."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Nombre o documento del suscriptor."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      },
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Crear suscripción",
        "operationId": "CrearSuscripcion",
        "description": "Suscribe un cliente a un plan y crea su primera orden de cobro pendiente.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde `201` con la suscripción creada.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `customer_id` | integer | Sí | Id del suscriptor (cliente habilitado). |\n| `plan_id` | integer | Sí | Id del plan (debe estar activo). |\n| `start_date` | fecha `Y-m-d` | No | Fecha del primer cobro. Por defecto hoy. Se ignora si el plan tiene prueba gratis. |\n| `trial_start_date` | fecha `Y-m-d` | No | Inicio de la prueba gratis (por defecto hoy). Solo si hay días de prueba. |\n| `trial_days` | integer (0 a 365) | No | Días de prueba. Por defecto los del plan; `0` = sin prueba. |\n\n**Reglas:**\n- Se copian el monto, los productos, la periodicidad y la cantidad de cobros del plan: cambios posteriores del plan no la afectan.\n- Con prueba gratis el primer cobro (`start_date`) es `trial_start_date` + `trial_days`.\n- Se crea la primera orden de cobro (`pending`) por el monto del plan, con vencimiento en `start_date`. Las órdenes de los periodos siguientes las crea el sistema automáticamente.\n- La suscripción queda `authorized` (activa).\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (cliente o plan inexistente, fecha con otro formato).\n- `409` si el plan está inactivo o no tiene productos.\n- `401` sin token o con un token inválido.",
        "responses": {
          "201": {
            "description": "Creada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Creada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 48,
                        "status": "authorized",
                        "status_description": "Activa",
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer": {
                          "id": 1520,
                          "name": "MARÍA FERNANDA QUISPE ROJAS",
                          "number": "45879632",
                          "identity_document_type_id": "1",
                          "email": "maria.quispe@correo.pe"
                        },
                        "cat_period_id": 1,
                        "period_name": "Mensual",
                        "unlimited": false,
                        "quantity_period": 12,
                        "orders_created": 1,
                        "start_date": "2026-11-14",
                        "end_date": "2027-10-14",
                        "trial_start_date": "2026-11-07",
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total": 118.0,
                        "created_at": "2026-11-07 10:15:32"
                      },
                      "message": "Suscripción registrada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Plan inactivo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Plan inactivo",
                    "value": {
                      "success": false,
                      "message": "El plan está inactivo: actívalo antes de suscribir clientes."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Validación",
                    "value": {
                      "success": false,
                      "message": {
                        "plan_id": [
                          "El campo plan id seleccionado no existe."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Crear suscripción",
                  "value": {
                    "customer_id": 1520,
                    "plan_id": 3,
                    "trial_start_date": "2026-11-07"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/{subscription_id}": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Ver suscripción",
        "operationId": "VerSuscripcion",
        "description": "Devuelve la suscripción con el resumen de sus órdenes y la fecha en que se creará la próxima.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_id` | integer | Sí | Id de la suscripción. |\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id de la suscripción. |\n| `status / status_description` | string | `authorized` Activa, `paused` Pausada, `cancelled` Cancelada, `finished` Finalizada. |\n| `plan_id / plan_name` | integer / string | Plan. |\n| `customer_id / customer` | integer / objeto | Suscriptor `{id, name, number, identity_document_type_id, email}`. |\n| `cat_period_id / period_name / unlimited / quantity_period` |  | Periodicidad y cantidad de cobros copiadas del plan. |\n| `orders_created` | integer | Órdenes de cobro creadas hasta ahora. |\n| `start_date / end_date` | fecha | Primer cobro y último cobro (`end_date` `null` si es ilimitado). |\n| `trial_start_date / trial_days` | fecha / integer | Prueba gratis. |\n| `total / currency_type_id` | number / string | Monto de cada periodo (copiado del plan al suscribirse). |\n\nAdemás: `orders_summary` `{total, pending, paid}` (pending incluye rechazadas y vencidas) y `next_order_date` (fecha en que el sistema creará la siguiente orden, o `null` si ya no generará más).\n\n**Errores:**\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Suscripción",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Suscripción",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 48,
                        "status": "authorized",
                        "status_description": "Activa",
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer": {
                          "id": 1520,
                          "name": "MARÍA FERNANDA QUISPE ROJAS",
                          "number": "45879632",
                          "identity_document_type_id": "1",
                          "email": "maria.quispe@correo.pe"
                        },
                        "cat_period_id": 1,
                        "period_name": "Mensual",
                        "unlimited": false,
                        "quantity_period": 12,
                        "orders_created": 1,
                        "start_date": "2026-11-14",
                        "end_date": "2027-10-14",
                        "trial_start_date": "2026-11-07",
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total": 118.0,
                        "created_at": "2026-11-07 10:15:32",
                        "orders_summary": {
                          "total": 1,
                          "pending": 1,
                          "paid": 0
                        },
                        "next_order_date": "2026-12-11"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "48"
          }
        ]
      },
      "delete": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Eliminar suscripción",
        "operationId": "EliminarSuscripcion",
        "description": "Elimina una suscripción registrada por error, con sus órdenes sin pagar.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). En el éxito `data` es `{id}`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_id` | integer | Sí | Id de la suscripción. |\n\n**Reglas:**\n- Si tiene alguna orden pagada (cobros con comprobante) no se elimina: cancélala con **Cambiar estado de la suscripción**.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `404` si el registro no existe.\n- `409` si tiene órdenes pagadas.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Eliminada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 48
                      },
                      "message": "Suscripción eliminada con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Con pagos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Con pagos",
                    "value": {
                      "success": false,
                      "message": "La suscripción tiene órdenes pagadas y no se puede eliminar. Cancélala en su lugar."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "48"
          }
        ]
      }
    },
    "/api/subscriptions/{subscription_id}/status": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Cambiar estado de la suscripción",
        "operationId": "CambiarEstadoSuscripcion",
        "description": "Activa, pausa o cancela la suscripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_id` | integer | Sí | Id de la suscripción. |\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `status` | string | Sí | `authorized` (activar/reanudar), `paused` (pausar) o `cancelled` (cancelar). |\n\n**Reglas:**\n- `paused`: la suscripción **sigue generando órdenes** de cobro. Para dejar de cobrar, cancélala.\n- `cancelled`: deja de generar órdenes. Es **definitivo**: una suscripción cancelada o finalizada ya no cambia de estado.\n- Las órdenes ya creadas no cambian: si no se van a cobrar, recházalas.\n- Enviar el estado actual no hace cambios y responde `200`.\n\n**Errores:**\n- `404` si el registro no existe.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (estado no permitido; `finished` lo asigna solo el sistema).\n- `409` si la suscripción está cancelada o finalizada.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Actualizado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Actualizado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 48,
                        "status": "paused",
                        "status_description": "Pausada",
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer": {
                          "id": 1520,
                          "name": "MARÍA FERNANDA QUISPE ROJAS",
                          "number": "45879632",
                          "identity_document_type_id": "1",
                          "email": "maria.quispe@correo.pe"
                        },
                        "cat_period_id": 1,
                        "period_name": "Mensual",
                        "unlimited": false,
                        "quantity_period": 12,
                        "orders_created": 1,
                        "start_date": "2026-11-14",
                        "end_date": "2027-10-14",
                        "trial_start_date": "2026-11-07",
                        "trial_days": 7,
                        "currency_type_id": "PEN",
                        "total": 118.0,
                        "created_at": "2026-11-07 10:15:32"
                      },
                      "message": "Estado de suscripción actualizado con éxito"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Cancelada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Cancelada",
                    "value": {
                      "success": false,
                      "message": "La suscripción está cancelada y ya no cambia de estado."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "48"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Cambiar estado de la suscripción",
                  "value": {
                    "status": "paused"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/orders": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Listar órdenes de cobro",
        "operationId": "ListarOrdenesCobro",
        "description": "Lista las órdenes de cobro de las suscripciones (una por periodo), de la más reciente a la más antigua.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `status` | string | No | Uno o varios separados por coma: `pending`, `paid`, `rejected`, `expired`, `canceled`. P. ej. `pending,rejected,expired` = por cobrar. |\n| `customer_id` | integer | No | Suscriptor. |\n| `plan_id` | integer | No | Plan. |\n| `subscription_id` | integer | No | Suscripción. |\n| `date_field` | string | No | Fecha a la que aplican `date_from`/`date_to`: `issue` creación (por defecto), `due` vencimiento, `payment` pago. |\n| `date_from / date_to` | fecha `Y-m-d` | No | Rango de fechas (inclusive). |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada orden:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id / number` | integer / string | Id y número correlativo de la orden (`SO-0311`). |\n| `status / status_description` | string | `pending`, `paid`, `rejected`, `expired`, `canceled`. |\n| `amount / currency_type_id` | number / string | Monto a cobrar. |\n| `date_of_issue / date_of_due / date_of_payment` | fecha | Creación, vencimiento y pago (con hora). |\n| `subscription_id / plan_id / plan_name` |  | Suscripción y plan. |\n| `customer_id / customer_name / customer_number` |  | Suscriptor. |\n| `count_notification / date_notification` | integer / fecha | Avisos de cobro enviados y el último. |\n| `count_rejected_payments` | integer | Veces que se rechazó el pago. |\n| `payment_url` | string | Enlace de pago en línea para el cliente. |\n| `document` | objeto o null | Comprobante emitido `{id, document_type_id, number_full, date_of_issue, total, state_type_id, download_pdf}`. |\n\n**Errores:**\n- `422` si `status` tiene un valor no válido, o las fechas otro formato o `date_to` es anterior a `date_from`.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 311,
                          "number": "SO-0311",
                          "status": "pending",
                          "status_description": "Pendiente",
                          "amount": 118.0,
                          "currency_type_id": "PEN",
                          "date_of_issue": "2026-12-14",
                          "date_of_due": "2026-12-14",
                          "date_of_payment": null,
                          "subscription_id": 48,
                          "plan_id": 3,
                          "plan_name": "Plan Mensual Gold",
                          "customer_id": 1520,
                          "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                          "customer_number": "45879632",
                          "count_notification": 1,
                          "date_notification": "2026-12-14 09:00:04",
                          "count_rejected_payments": 0,
                          "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                          "document": null
                        },
                        {
                          "id": 311,
                          "number": "SO-0311",
                          "status": "rejected",
                          "status_description": "Rechazado",
                          "amount": 118.0,
                          "currency_type_id": "PEN",
                          "date_of_issue": "2026-12-14",
                          "date_of_due": "2026-12-14",
                          "date_of_payment": null,
                          "subscription_id": 48,
                          "plan_id": 3,
                          "plan_name": "Plan Mensual Gold",
                          "customer_id": 1520,
                          "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                          "customer_number": "45879632",
                          "count_notification": 1,
                          "date_notification": "2026-12-14 09:00:04",
                          "count_rejected_payments": 1,
                          "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                          "document": null
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Estado inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estado inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "status": [
                          "Estado no válido: pagado. Usa pending, paid, rejected, expired, canceled."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "pending,rejected,expired",
            "description": "Estados separados por coma."
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1520",
            "description": "Suscriptor."
          },
          {
            "name": "plan_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "3",
            "description": "Plan."
          },
          {
            "name": "subscription_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "48",
            "description": "Suscripción."
          },
          {
            "name": "date_field",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "due",
            "description": "`issue`, `due` o `payment`."
          },
          {
            "name": "date_from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-12-01",
            "description": "Desde."
          },
          {
            "name": "date_to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-12-31",
            "description": "Hasta."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/subscriptions/orders/{subscription_order_id}": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Ver orden de cobro",
        "operationId": "VerOrdenCobro",
        "description": "Devuelve una orden de cobro con su comprobante, si lo tiene.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_order_id` | integer | Sí | Id de la orden de cobro. |\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id / number` | integer / string | Id y número correlativo de la orden (`SO-0311`). |\n| `status / status_description` | string | `pending`, `paid`, `rejected`, `expired`, `canceled`. |\n| `amount / currency_type_id` | number / string | Monto a cobrar. |\n| `date_of_issue / date_of_due / date_of_payment` | fecha | Creación, vencimiento y pago (con hora). |\n| `subscription_id / plan_id / plan_name` |  | Suscripción y plan. |\n| `customer_id / customer_name / customer_number` |  | Suscriptor. |\n| `count_notification / date_notification` | integer / fecha | Avisos de cobro enviados y el último. |\n| `count_rejected_payments` | integer | Veces que se rechazó el pago. |\n| `payment_url` | string | Enlace de pago en línea para el cliente. |\n| `document` | objeto o null | Comprobante emitido `{id, document_type_id, number_full, date_of_issue, total, state_type_id, download_pdf}`. |\n\n**Errores:**\n- `404` si el registro no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Orden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Orden",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 311,
                        "number": "SO-0311",
                        "status": "pending",
                        "status_description": "Pendiente",
                        "amount": 118.0,
                        "currency_type_id": "PEN",
                        "date_of_issue": "2026-12-14",
                        "date_of_due": "2026-12-14",
                        "date_of_payment": null,
                        "subscription_id": 48,
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                        "customer_number": "45879632",
                        "count_notification": 1,
                        "date_notification": "2026-12-14 09:00:04",
                        "count_rejected_payments": 0,
                        "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                        "document": null
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "311"
          }
        ]
      }
    },
    "/api/subscriptions/orders/{subscription_order_id}/pay": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Marcar orden como pagada",
        "operationId": "MarcarOrdenComoPagada",
        "description": "Registra el cobro de la orden y **emite su comprobante electrónico** por el monto de la suscripción.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es la orden ya pagada con su `document`; `message` incluye la respuesta del envío a SUNAT.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_order_id` | integer | Sí | Id de la orden de cobro. |\n\n**Reglas:**\n- Comprobante: **boleta** si el cliente tiene DNI (u otro documento), **factura** si tiene RUC; con la serie del establecimiento del usuario y los productos del plan.\n- El cobro se registra en **efectivo** (método `01`) en la **caja abierta del usuario** que marca el pago: abre la caja antes (sección [Caja](/docs/api/tenant/caja)).\n- Todo o nada: si el comprobante no se puede emitir (sin caja abierta, sin serie, límite del plan de la empresa...), la orden queda como estaba y responde `409` con el motivo.\n- Se pueden cobrar órdenes `pending`, `rejected` y `expired`.\n\n**Errores:**\n- `404` si el registro no existe.\n- `409` si la orden ya está pagada o cancelada, o si no se pudo emitir el comprobante (el `message` dice por qué).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Pagada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 311,
                        "number": "SO-0311",
                        "status": "paid",
                        "status_description": "Pagado",
                        "amount": 118.0,
                        "currency_type_id": "PEN",
                        "date_of_issue": "2026-12-14",
                        "date_of_due": "2026-12-14",
                        "date_of_payment": "2026-12-14 16:42:10",
                        "subscription_id": 48,
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                        "customer_number": "45879632",
                        "count_notification": 1,
                        "date_notification": "2026-12-14 09:00:04",
                        "count_rejected_payments": 0,
                        "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                        "document": {
                          "id": 90211,
                          "document_type_id": "03",
                          "number_full": "B001-4581",
                          "date_of_issue": "2026-12-14",
                          "total": 118.0,
                          "state_type_id": "05",
                          "download_pdf": "https://empresa.dominio/downloads/document/pdf/9b1c3f2e-0f7a-4c11-9a9d-7e2b61c2d0aa"
                        }
                      },
                      "message": "Orden pagada. Comprobante: La Boleta numero B001-4581, ha sido aceptada"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya pagada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya pagada",
                    "value": {
                      "success": false,
                      "message": "La orden ya está pagada."
                    }
                  },
                  "e2": {
                    "summary": "Sin caja abierta",
                    "value": {
                      "success": false,
                      "message": "Ocurrió un error: Caja seleccionada en métodos de pago se encuentra cerrada"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "311"
          }
        ]
      }
    },
    "/api/subscriptions/orders/{subscription_order_id}/reject": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Rechazar orden",
        "operationId": "RechazarOrden",
        "description": "Marca la orden como rechazada (pago fallido) y suma un rechazo. La orden se puede volver a cobrar después.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_order_id` | integer | Sí | Id de la orden de cobro. |\n\n**Errores:**\n- `404` si el registro no existe.\n- `409` si la orden está pagada o cancelada.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Rechazada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Rechazada",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 311,
                        "number": "SO-0311",
                        "status": "rejected",
                        "status_description": "Rechazado",
                        "amount": 118.0,
                        "currency_type_id": "PEN",
                        "date_of_issue": "2026-12-14",
                        "date_of_due": "2026-12-14",
                        "date_of_payment": null,
                        "subscription_id": 48,
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                        "customer_number": "45879632",
                        "count_notification": 1,
                        "date_notification": "2026-12-14 09:00:04",
                        "count_rejected_payments": 1,
                        "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                        "document": null
                      },
                      "message": "Orden rechazada"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Pagada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Pagada",
                    "value": {
                      "success": false,
                      "message": "La orden ya está pagada y no se puede rechazar."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "311"
          }
        ]
      }
    },
    "/api/subscriptions/orders/{subscription_order_id}/notify": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Avisar orden por correo",
        "operationId": "AvisarOrdenCorreo",
        "description": "Envía al cliente por correo el aviso de cobro (mensaje configurado por la empresa) con el enlace de pago en línea.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_order_id` | integer | Sí | Id de la orden de cobro. |\n\n**Reglas:**\n- Suma uno a `count_notification` y guarda `date_notification`.\n\n**Errores:**\n- `404` si el registro no existe.\n- `409` si la orden está pagada o cancelada, o el cliente no tiene correo.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Enviado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviado",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 311,
                        "number": "SO-0311",
                        "status": "pending",
                        "status_description": "Pendiente",
                        "amount": 118.0,
                        "currency_type_id": "PEN",
                        "date_of_issue": "2026-12-14",
                        "date_of_due": "2026-12-14",
                        "date_of_payment": null,
                        "subscription_id": 48,
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                        "customer_number": "45879632",
                        "count_notification": 2,
                        "date_notification": "2026-12-14 09:00:04",
                        "count_rejected_payments": 0,
                        "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                        "document": null
                      },
                      "message": "Notificación enviada"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Sin correo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin correo",
                    "value": {
                      "success": false,
                      "message": "El cliente no tiene correo registrado."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "311"
          }
        ]
      }
    },
    "/api/subscriptions/orders/notify": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Avisar varias órdenes por correo",
        "operationId": "AvisarVariasOrdenesCorreo",
        "description": "Envía el aviso de cobro a varias órdenes a la vez. Envía las que se pueden y devuelve las omitidas con el motivo.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es `{sent: [ids], skipped: [{id, reason}]}`.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `ids` | array de integer (1 a 100) | Sí | Ids de las órdenes, sin repetir. |\n\n**Reglas:**\n- Se omiten las órdenes inexistentes, pagadas o canceladas y las de clientes sin correo.\n\n**Errores:**\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (lista vacía, más de 100 o ids repetidos).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Enviadas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Enviadas",
                    "value": {
                      "success": true,
                      "data": {
                        "sent": [
                          311,
                          318
                        ],
                        "skipped": [
                          {
                            "id": 312,
                            "reason": "El cliente no tiene correo registrado."
                          }
                        ]
                      },
                      "message": "2 notificación(es) enviada(s), 1 omitida(s)"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Sin ids",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin ids",
                    "value": {
                      "success": false,
                      "message": {
                        "ids": [
                          "El campo ids es obligatorio."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Avisar varias órdenes por correo",
                  "value": {
                    "ids": [
                      311,
                      312,
                      318
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/subscriptions/receipts": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Listar recibos",
        "operationId": "ListarRecibos",
        "description": "Lista las órdenes **pagadas** con su comprobante, de la más reciente a la más antigua.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `has_document` | 0 / 1 | No | `1` con comprobante; `0` pagadas sin comprobante (para emitirlo con **Emitir comprobante**). |\n| `customer_id / plan_id / subscription_id` | integer | No | Suscriptor, plan o suscripción. |\n| `date_field` | string | No | `payment` pago (por defecto), `issue` creación o `due` vencimiento. |\n| `date_from / date_to` | fecha `Y-m-d` | No | Rango de fechas (inclusive). |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\nCada recibo tiene los mismos campos que una orden de cobro (ver **Ver orden de cobro**).\n\n**Errores:**\n- `422` si las fechas tienen otro formato o `date_to` es anterior a `date_from`.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 311,
                          "number": "SO-0311",
                          "status": "paid",
                          "status_description": "Pagado",
                          "amount": 118.0,
                          "currency_type_id": "PEN",
                          "date_of_issue": "2026-12-14",
                          "date_of_due": "2026-12-14",
                          "date_of_payment": "2026-12-14 16:42:10",
                          "subscription_id": 48,
                          "plan_id": 3,
                          "plan_name": "Plan Mensual Gold",
                          "customer_id": 1520,
                          "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                          "customer_number": "45879632",
                          "count_notification": 1,
                          "date_notification": "2026-12-14 09:00:04",
                          "count_rejected_payments": 0,
                          "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                          "document": {
                            "id": 90211,
                            "document_type_id": "03",
                            "number_full": "B001-4581",
                            "date_of_issue": "2026-12-14",
                            "total": 118.0,
                            "state_type_id": "05",
                            "download_pdf": "https://empresa.dominio/downloads/document/pdf/9b1c3f2e-0f7a-4c11-9a9d-7e2b61c2d0aa"
                          }
                        }
                      ],
                      "pagination": {
                        "next_cursor": null,
                        "has_more": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "has_document",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1",
            "description": "Con comprobante."
          },
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "1520",
            "description": "Suscriptor."
          },
          {
            "name": "date_from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-12-01",
            "description": "Pagadas desde."
          },
          {
            "name": "date_to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2026-12-31",
            "description": "Pagadas hasta."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/subscriptions/receipts/statistics": {
      "get": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Estadísticas de cobro",
        "operationId": "EstadisticasCobro",
        "description": "Totales de todas las órdenes de cobro de la empresa.\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `total_collected` | number | Monto cobrado (órdenes pagadas). |\n| `total_paid` | integer | Órdenes pagadas. |\n| `total_rejected` | integer | Órdenes rechazadas o canceladas. |\n| `total_pending` | integer | Órdenes pendientes. |\n| `total_expired` | integer | Órdenes vencidas sin pagar. |\n\n**Errores:**\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Estadísticas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Estadísticas",
                    "value": {
                      "success": true,
                      "data": {
                        "total_collected": 28320.0,
                        "total_paid": 240,
                        "total_rejected": 6,
                        "total_pending": 18,
                        "total_expired": 4
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/subscriptions/receipts/{subscription_order_id}/generate-document": {
      "post": {
        "tags": [
          "Suscripciones"
        ],
        "summary": "Emitir comprobante de una orden pagada",
        "operationId": "EmitirComprobanteOrdenPagada",
        "description": "Emite el comprobante de una orden **pagada que quedó sin comprobante** (p. ej. pagada en línea desde el enlace de pago).\n\n**Quién puede usarlo:** cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es la orden con su `document`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `subscription_order_id` | integer | Sí | Id de la orden de cobro. |\n\n**Reglas:**\n- Mismo comprobante y mismo cobro que **Marcar orden como pagada**: boleta o factura según el cliente, cobro en efectivo en la caja abierta del usuario.\n- Si no se puede emitir, responde `409` con el motivo y la orden no cambia.\n\n**Errores:**\n- `404` si el registro no existe.\n- `409` si la orden no está pagada, ya tiene comprobante o no se pudo emitir.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Emitido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Emitido",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 311,
                        "number": "SO-0311",
                        "status": "paid",
                        "status_description": "Pagado",
                        "amount": 118.0,
                        "currency_type_id": "PEN",
                        "date_of_issue": "2026-12-14",
                        "date_of_due": "2026-12-14",
                        "date_of_payment": "2026-12-14 16:42:10",
                        "subscription_id": 48,
                        "plan_id": 3,
                        "plan_name": "Plan Mensual Gold",
                        "customer_id": 1520,
                        "customer_name": "MARÍA FERNANDA QUISPE ROJAS",
                        "customer_number": "45879632",
                        "count_notification": 1,
                        "date_notification": "2026-12-14 09:00:04",
                        "count_rejected_payments": 0,
                        "payment_url": "https://empresa.dominio/full-suscription/pending-payments/order/482913",
                        "document": {
                          "id": 90211,
                          "document_type_id": "03",
                          "number_full": "B001-4581",
                          "date_of_issue": "2026-12-14",
                          "total": 118.0,
                          "state_type_id": "05",
                          "download_pdf": "https://empresa.dominio/downloads/document/pdf/9b1c3f2e-0f7a-4c11-9a9d-7e2b61c2d0aa"
                        }
                      },
                      "message": "Comprobante emitido. Comprobante: La Boleta numero B001-4581, ha sido aceptada"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya tiene",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ya tiene",
                    "value": {
                      "success": false,
                      "message": "La orden ya tiene comprobante."
                    }
                  },
                  "e2": {
                    "summary": "No pagada",
                    "value": {
                      "success": false,
                      "message": "Solo se emite el comprobante de una orden pagada: márcala como pagada."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "311"
          }
        ]
      }
    },
    "/api/reports/documents/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte de ventas (comprobantes)",
        "operationId": "SolicitarReporteVentasComprobantes",
        "description": "Reporte de **comprobantes electrónicos** (facturas, boletas, notas de crédito y débito) de un rango de fechas, en PDF o Excel.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | Sí | `pdf` o `xlsx`. |\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `document_type_id` | string | No | `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito. Sin él, todos. |\n| `guides` | string | No | Número de guía de remisión asociada. |\n| `establishment_id` | integer | No | Solo ese establecimiento. También define la cabecera del reporte (por defecto, el del usuario). |\n| `person_id` | integer | No | Id del cliente. |\n| `seller_id` | integer | No | Id del usuario que registró el comprobante. |\n| `state_type_id` | string | No | Estado del comprobante (`05` aceptado, `11` anulado...). Ver **Catálogos → Estados**. |\n| `purchase_order` | string | No | Número de orden de compra. |\n| `web_platform_id` | integer | No | Solo comprobantes con productos de esa plataforma web. |\n| `include_categories` | boolean | No | Solo Excel: agrega el resumen por categorías. |\n| `apply_conversion_to_pen` | boolean | No | Convierte a soles los importes en dólares. |\n| `columns` | array de string | No | Columnas opcionales del Excel/PDF (envía las que quieras ver; sin `columns` salen las del panel web): `user_seller`, `doc_affect`, `quote`, `case`, `items`, `currency_type_id`, `purchase_order`, `total_exonerated`, `total_unaffected`, `total_free`, `total_taxed`, `total_igv`, `total_isc`, `total`, `guides`, `options`, `web_platforms`, `total_charge`, `district`, `department`, `province`, `client_direction`, `ruc`, `note_sale`, `date_note`, `payment_form`, `payment_method`, `plate`, `agent`, `reference_data`. |\n\n**Errores:**\n- `422` si `columns` trae una columna que no existe.\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "documents",
                        "module": "REPORT",
                        "type": "Reporte Documentos - Ventas",
                        "format": "xlsx",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte de ventas (comprobantes)",
                  "value": {
                    "format": "xlsx",
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "document_type_id": "01",
                    "establishment_id": 1,
                    "include_categories": false,
                    "columns": [
                      "user_seller",
                      "items",
                      "currency_type_id",
                      "total_taxed",
                      "total_igv",
                      "total"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/sale-notes/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte de notas de venta",
        "operationId": "SolicitarReporteNotasVenta",
        "description": "Reporte de **notas de venta** de un rango de fechas, en PDF o Excel (mismo formato que el de ventas).\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | Sí | `pdf` o `xlsx`. |\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `establishment_id` | integer | No | Solo ese establecimiento. También define la cabecera del reporte (por defecto, el del usuario). |\n| `person_id` | integer | No | Id del cliente. |\n| `seller_id` | integer | No | Id del usuario que registró el comprobante. |\n| `state_type_id` | string | No | Estado del comprobante (`05` aceptado, `11` anulado...). Ver **Catálogos → Estados**. |\n| `purchase_order` | string | No | Número de orden de compra. |\n| `web_platform_id` | integer | No | Solo comprobantes con productos de esa plataforma web. |\n| `include_categories` | boolean | No | Solo Excel: agrega el resumen por categorías. |\n| `apply_conversion_to_pen` | boolean | No | Convierte a soles los importes en dólares. |\n| `columns` | array de string | No | Columnas opcionales del Excel/PDF (envía las que quieras ver; sin `columns` salen las del panel web): `user_seller`, `doc_affect`, `quote`, `case`, `items`, `currency_type_id`, `purchase_order`, `total_exonerated`, `total_unaffected`, `total_free`, `total_taxed`, `total_igv`, `total_isc`, `total`, `guides`, `options`, `web_platforms`, `total_charge`, `district`, `department`, `province`, `client_direction`, `ruc`, `note_sale`, `date_note`, `payment_form`, `payment_method`, `plate`, `agent`, `reference_data`. |\n\n**Errores:**\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "sale-notes",
                        "module": "REPORT",
                        "type": "Reporte Notas de Venta",
                        "format": "pdf",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte de notas de venta",
                  "value": {
                    "format": "pdf",
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "establishment_id": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/purchases/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte de compras",
        "operationId": "SolicitarReporteCompras",
        "description": "Reporte de **compras** de un rango de fechas con sus pagos, en PDF o Excel.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | Sí | `pdf` o `xlsx`. |\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `establishment_id` | integer | No | Solo ese establecimiento (y cabecera del reporte). |\n| `document_type_id` | string | No | `01` factura, `03` boleta, `GU75` guía, `NE76` nota de entrada. |\n| `person_id` | integer | No | Id del proveedor. |\n| `seller_id` | integer | No | Id del usuario que registró la compra. |\n| `state_type_id` | string | No | Estado de la compra. |\n| `apply_conversion_to_pen` | boolean | No | Convierte a soles los importes en dólares. |\n\n**Errores:**\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "purchases",
                        "module": "REPORT",
                        "type": "Reporte Compras",
                        "format": "pdf",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte de compras",
                  "value": {
                    "format": "pdf",
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "document_type_id": "01"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/general-items/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte general de productos",
        "operationId": "SolicitarReporteGeneralProductos",
        "description": "Reporte **línea por línea** de los productos vendidos o comprados (cantidades, precios, cliente/proveedor), en PDF o Excel.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | Sí | `pdf` o `xlsx`. |\n| `type` | string | Sí | `sale` (ventas) o `purchase` (compras). |\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `document_type_id` | array de string | No | `01`, `03`, `07`, `80` (nota de venta), `GU75`, `NE76`. La nota de venta (`80`) solo se reporta sola. Sin él: todos menos la nota de venta. |\n| `person_id` | integer | No | Cliente (ventas) o proveedor (compras). |\n| `item_id` | integer | No | Solo ese producto. |\n| `brand_id / category_id` | integer | No | Solo productos de esa marca / categoría. |\n| `web_platform_id` | integer | No | Solo productos de esa plataforma web. |\n| `user_type` | string | Con `user_id` | `CREADOR` (quien registró) o `VENDEDOR` (vendedor asignado). |\n| `user_id` | integer | No | Usuario por el que filtrar (según `user_type`). |\n| `apply_conversion_to_pen` | boolean | No | Convierte a soles los importes en dólares. |\n| `record_chunk` | integer (100 a 5000) | No | Divide un reporte grande en archivos de N líneas y los entrega juntos en un **ZIP** (`format` de la bandeja pasa a `zip`). Recomendado desde unas 5 000 líneas. |\n\n**Errores:**\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "general-items",
                        "module": "REPORT",
                        "type": "Reporte general de venta/productos",
                        "format": "xlsx",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte general de productos",
                  "value": {
                    "format": "xlsx",
                    "type": "sale",
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "document_type_id": [
                      "01",
                      "03"
                    ],
                    "user_type": "VENDEDOR",
                    "user_id": 3
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/sales-consolidated/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar consolidado de productos vendidos",
        "operationId": "SolicitarConsolidadoProductosVendidos",
        "description": "Consolidado de **productos vendidos** (comprobantes y notas de venta): detalle por comprobante o totales por producto, en PDF o Excel. Por API siempre se genera en la bandeja (el panel web solo la usa desde 500 registros).\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | Sí | `pdf` o `xlsx`. |\n| `export_mode` | string | No | `detail` (por defecto), `totals` (totales por producto), `ticket` / `ticket80` (totales en ticket de 58 / 80 mm, solo PDF). |\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `establishment_id` | integer | No | Solo ese establecimiento. |\n| `person_id` | integer | No | Id del cliente. |\n| `document_type_id` | array de string | No | `01`, `03`, `80`. Sin él, todos. |\n| `series` | string | No | Solo esa serie. |\n| `user_id` | array de integer | No | Usuarios por los que filtrar. |\n| `user_type` | string | No | `CREADOR` (por defecto) o `VENDEDOR`. |\n\n**Errores:**\n- `422` si `export_mode` es `ticket`/`ticket80` y el formato no es `pdf`.\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "sales-consolidated",
                        "module": "REPORT",
                        "type": "Consolidado de items de ventas",
                        "format": "pdf",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar consolidado de productos vendidos",
                  "value": {
                    "format": "pdf",
                    "export_mode": "totals",
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "document_type_id": [
                      "01",
                      "03",
                      "80"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/massive-documents/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar descarga masiva de comprobantes",
        "operationId": "SolicitarDescargaMasivaComprobantes",
        "description": "Genera un **PDF con la representación impresa** de todos los comprobantes del rango (facturas, boletas, notas de venta y guías). Más de 100 comprobantes se dividen en lotes de hasta 100 y se entregan en un **ZIP**.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte — esta descarga no exige módulo —. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `document_types` | array de string | No | `01` factura, `03` boleta, `80` nota de venta, `09` guía. Sin él, todos. |\n| `person_id` | integer | No | Id del cliente. |\n| `series` | string | No | Solo esa serie. |\n| `sellers` | array de integer | No | Solo comprobantes de esos vendedores. |\n| `number_from / number_to` | integer | No | Rango de correlativos (ambos). |\n| `paper` | string | No | `a4` (por defecto), `a5`, `ticket` (80 mm) o `ticket_58`. Las guías solo salen en A4. |\n| `record_chunk` | integer (1 a 100) | No | Tamaño del lote. Sin él, se usa 100 cuando hay más de 100 comprobantes. |\n\n**Errores:**\n- `422` si `number_to` es menor que `number_from`.\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "massive-documents",
                        "module": "REPORT",
                        "type": "Descarga masiva de documentos",
                        "format": "pdf",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar descarga masiva de comprobantes",
                  "value": {
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-07",
                    "document_types": [
                      "01",
                      "03"
                    ],
                    "paper": "a4"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/kardex/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar kardex de un producto",
        "operationId": "SolicitarKardexProducto",
        "description": "**Kardex** (movimientos de entrada y salida con saldo) de un producto en un almacén, en PDF. El saldo inicial es el acumulado antes de `date_start`. Más de 500 movimientos se dividen en varios PDF entregados en un **ZIP**.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `item_id` | integer | Sí | Id del producto. |\n| `warehouse_id` | integer | No | Almacén. Por defecto, el del establecimiento del usuario. Un vendedor solo puede pedir almacenes de su establecimiento. |\n| `date_start` | YYYY-MM-DD | No | Desde. Sin fechas: todo el historial. |\n| `date_end` | YYYY-MM-DD | No | Hasta. |\n| `format` | string | No | Solo `pdf` (por defecto). |\n\n**Errores:**\n- `403` si un vendedor pide un almacén de otro establecimiento.\n- `422` si falta `item_id` o no existe.\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "kardex",
                        "module": "INVENTORY",
                        "type": "Reporte Kardex",
                        "format": "pdf",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Almacén de otro establecimiento",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Almacén de otro establecimiento",
                    "value": {
                      "success": false,
                      "message": "Solo puedes consultar el kardex de los almacenes de tu establecimiento."
                    }
                  },
                  "e2": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar kardex de un producto",
                  "value": {
                    "item_id": "1",
                    "warehouse_id": 1,
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/inventory/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte de inventario",
        "operationId": "SolicitarReporteInventario",
        "description": "**Stock actual** por almacén con costos y precios, en PDF o Excel. No lleva fechas: es la foto del momento en que se genera.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `format` | string | Sí | `pdf` o `xlsx`. |\n| `warehouse_id` | integer | No | Almacén. Sin él, todos. |\n| `filter` | string | No | `01` todos (por defecto), `02` stock ≤ 0, `03` stock = 0, `04` stock por debajo del mínimo, `05` stock sobre el mínimo, `06` stock > 0. |\n| `category_id / brand_id` | integer | No | Solo productos de esa categoría / marca. |\n\n**Errores:**\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "inventory",
                        "module": "INVENTORY",
                        "type": "Reporte Inventario",
                        "format": "xlsx",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte de inventario",
                  "value": {
                    "format": "xlsx",
                    "warehouse_id": 1,
                    "filter": "01"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/finance-movements/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte de movimientos (ingresos y egresos)",
        "operationId": "SolicitarReporteMovimientosIngresosEgresos",
        "description": "Movimientos de dinero (cobros, pagos, gastos, ingresos, transferencias) con saldo acumulado, en Excel.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `format` | string | No | Solo `xlsx` (por defecto). |\n| `last_cash_opening` | boolean | No | `true` = solo los movimientos de la caja abierta del usuario. |\n| `include_voided` | boolean | No | Incluye los cobros de comprobantes anulados. |\n\n**Errores:**\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "finance-movements",
                        "module": "FINANCE",
                        "type": "Reporte Movimientos ingresos-egresos",
                        "format": "xlsx",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte de movimientos (ingresos y egresos)",
                  "value": {
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "last_cash_opening": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reports/global-payments/export": {
      "post": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Solicitar reporte de pagos",
        "operationId": "SolicitarReportePagos",
        "description": "Pagos y cobros con su destino (caja o cuenta), en Excel.\n\n**Quién puede usarlo:** administradores y vendedores. Si al usuario se le asignaron módulos, necesita el módulo del reporte (*Reportes*, *Inventario* o *Finanzas*, según el caso), igual que en el panel web; si no, responde `403`. **Un vendedor solo obtiene sus propios comprobantes y movimientos** (los que registró o en los que figura como vendedor): el reporte se genera con su usuario aunque envíe filtros de otros.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). Responde **`202 Accepted`** con la fila de la bandeja (`data.id`, `data.status = IN_PROCESS`). El archivo se genera en segundo plano: consulta **Estado de un reporte** y descárgalo con **Descargar reporte**.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `date_start` | YYYY-MM-DD | Sí | Fecha inicial (inclusive). |\n| `date_end` | YYYY-MM-DD | Sí | Fecha final (inclusive). Igual o posterior a `date_start`. |\n| `format` | string | No | Solo `xlsx` (por defecto). |\n| `payment_type` | string | No | `document` (comprobantes), `sale_note`, `purchase`, `expense`, `quotation`, `contract`, `income`, `technical_service`, `purchase_settlement`. |\n| `destination_type` | string | No | `cash` (caja) o `bank_account` (cualquier cuenta, billetera o pasarela). |\n| `bank_account_id` | integer | No | Solo esa cuenta (tiene prioridad sobre `destination_type`). |\n\n**Errores:**\n- `422` si `format` es `pdf` (este reporte solo existe en Excel).\n- `403` si el usuario no tiene el módulo del reporte.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de filtros (fechas, formato, ids inexistentes...). No se crea ningún reporte.\n- `401` sin token o con un token inválido.",
        "responses": {
          "202": {
            "description": "En cola",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En cola",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "global-payments",
                        "module": "FINANCE",
                        "type": "Reporte Pagos",
                        "format": "xlsx",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      },
                      "message": "El reporte se está procesando. Consulte su estado en la bandeja de descargas."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Filtros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Filtros inválidos",
                    "value": {
                      "success": false,
                      "message": {
                        "date_end": [
                          "fecha final debe ser una fecha posterior o igual a fecha inicial."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Sin el módulo del reporte",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin el módulo del reporte",
                    "value": {
                      "success": false,
                      "message": "No tienes acceso al módulo de este reporte."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Solicitar reporte de pagos",
                  "value": {
                    "date_start": "2026-11-01",
                    "date_end": "2026-11-30",
                    "payment_type": "document",
                    "destination_type": "bank_account"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/download-tray": {
      "get": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Listar bandeja de descargas",
        "operationId": "ListarBandejaDescargas",
        "description": "Lista los reportes solicitados (por la API o desde el panel web), del más reciente al más antiguo.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Cada usuario ve **solo sus reportes**; un administrador ve los de todos (y puede filtrar por `user_id`). Pedir el reporte de otro usuario sin ser administrador responde `403`.\n\n**Formato de respuesta:** listado con **paginación por cursor** `{success, data[], pagination: {next_cursor, has_more}}`.\n\n**Parámetros de la URL (query):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `status` | string | No | `IN_PROCESS`, `FINISHED`, `ERROR` o `FAILED`. |\n| `module` | string | No | `REPORT`, `INVENTORY` o `FINANCE`. |\n| `date` | YYYY-MM-DD | No | Solo los solicitados ese día. |\n| `user_id` | integer | No | Solo administradores: reportes de ese usuario. Para un vendedor se ignora. |\n| `limit / cursor` | integer / string | No | Paginación por cursor. |\n\n**Paginación por cursor:** envía `limit` (1 a 100, por defecto 15). La respuesta trae `pagination.next_cursor`; para la página siguiente repite la misma consulta agregando `cursor=<next_cursor>`. Cuando `pagination.has_more` es `false` no hay más páginas.\n\n**Campos de cada reporte:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del reporte en la bandeja. |\n| `status` | string | `IN_PROCESS` (generándose), `FINISHED` (listo), `ERROR` o `FAILED` (no se pudo generar: solicítalo de nuevo). |\n| `ready` | boolean | `true` cuando se puede descargar. |\n| `report` | string o null | Tipo solicitado por la API (`documents`, `kardex`...). `null` en los reportes pedidos desde el panel web. |\n| `module` | string | `REPORT`, `INVENTORY` o `FINANCE` (los pedidos desde el panel web pueden traer otros valores, p. ej. `Reporte`). |\n| `type` | string | Nombre del reporte. |\n| `format` | string | `pdf`, `xlsx` o `zip` (reporte dividido en lotes). |\n| `file_name` | string o null | Nombre del archivo cuando está listo. |\n| `user_id` | integer | Usuario que lo pidió. |\n| `date_init` / `date_end` | string | Inicio y fin del proceso (`YYYY-MM-DD HH:mm:ss`). |\n| `download_url` | string o null | URL de **Descargar reporte** cuando está listo. |\n\n**Errores:**\n- `422` si `status` o `date` tienen un valor no permitido.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Listado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Listado",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 59,
                          "status": "IN_PROCESS",
                          "ready": false,
                          "report": "kardex",
                          "module": "INVENTORY",
                          "type": "Reporte Kardex",
                          "format": "pdf",
                          "file_name": null,
                          "user_id": 3,
                          "date_init": "2026-11-07 10:15:02",
                          "date_end": null,
                          "download_url": null
                        },
                        {
                          "id": 58,
                          "status": "FINISHED",
                          "ready": true,
                          "report": "documents",
                          "module": "REPORT",
                          "type": "Reporte Documentos - Ventas",
                          "format": "xlsx",
                          "file_name": "REPORT_Reporte_Documentos_Ventas_20261107101509.xlsx",
                          "user_id": 3,
                          "date_init": "2026-11-07 10:15:02",
                          "date_end": "2026-11-07 10:15:09",
                          "download_url": "https://empresa.dominio/api/download-tray/58/download"
                        }
                      ],
                      "pagination": {
                        "next_cursor": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
                        "has_more": true
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "FINISHED",
            "description": "Estado."
          },
          {
            "name": "module",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "REPORT",
            "description": "Módulo."
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "2026-11-07",
            "description": "Día de la solicitud."
          },
          {
            "name": "user_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "3",
            "description": "Solo administradores."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "15",
            "description": "Registros por página, de 1 a 100. Por defecto 15."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Valor de `pagination.next_cursor` de la respuesta anterior para obtener la página siguiente."
          }
        ]
      }
    },
    "/api/download-tray/{download_tray_id}": {
      "get": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Estado de un reporte",
        "operationId": "EstadoReporte",
        "description": "Devuelve el estado de un reporte. Úsalo para esperar a que termine (**polling**): cuando `ready` es `true`, descárgalo con `download_url`.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Cada usuario ve **solo sus reportes**; un administrador ve los de todos (y puede filtrar por `user_id`). Pedir el reporte de otro usuario sin ser administrador responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `download_tray_id` | integer | Sí | Id que devolvió la solicitud (202). |\n\n**Campos de cada reporte:**\n\n| Campo | Tipo | Descripción |\n|---|---|---|\n| `id` | integer | Id del reporte en la bandeja. |\n| `status` | string | `IN_PROCESS` (generándose), `FINISHED` (listo), `ERROR` o `FAILED` (no se pudo generar: solicítalo de nuevo). |\n| `ready` | boolean | `true` cuando se puede descargar. |\n| `report` | string o null | Tipo solicitado por la API (`documents`, `kardex`...). `null` en los reportes pedidos desde el panel web. |\n| `module` | string | `REPORT`, `INVENTORY` o `FINANCE` (los pedidos desde el panel web pueden traer otros valores, p. ej. `Reporte`). |\n| `type` | string | Nombre del reporte. |\n| `format` | string | `pdf`, `xlsx` o `zip` (reporte dividido en lotes). |\n| `file_name` | string o null | Nombre del archivo cuando está listo. |\n| `user_id` | integer | Usuario que lo pidió. |\n| `date_init` / `date_end` | string | Inicio y fin del proceso (`YYYY-MM-DD HH:mm:ss`). |\n| `download_url` | string o null | URL de **Descargar reporte** cuando está listo. |\n\n**Errores:**\n- `403` si el reporte es de otro usuario y no eres administrador.\n- `404` si no existe.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "En proceso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En proceso",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 59,
                        "status": "IN_PROCESS",
                        "ready": false,
                        "report": "kardex",
                        "module": "INVENTORY",
                        "type": "Reporte Kardex",
                        "format": "pdf",
                        "file_name": null,
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": null,
                        "download_url": null
                      }
                    }
                  },
                  "e2": {
                    "summary": "Listo",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 58,
                        "status": "FINISHED",
                        "ready": true,
                        "report": "documents",
                        "module": "REPORT",
                        "type": "Reporte Documentos - Ventas",
                        "format": "xlsx",
                        "file_name": "REPORT_Reporte_Documentos_Ventas_20261107101509.xlsx",
                        "user_id": 3,
                        "date_init": "2026-11-07 10:15:02",
                        "date_end": "2026-11-07 10:15:09",
                        "download_url": "https://empresa.dominio/api/download-tray/58/download"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "De otro usuario",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "De otro usuario",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "No existe",
                    "value": {
                      "success": false,
                      "message": "Registro no encontrado."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "download_tray_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/download-tray/{download_tray_id}/download": {
      "get": {
        "tags": [
          "Reportes en cola"
        ],
        "summary": "Descargar reporte",
        "operationId": "DescargarReporte",
        "description": "Descarga el archivo de un reporte terminado.\n\n**Quién puede usarlo:** cualquier usuario autenticado. Cada usuario ve **solo sus reportes**; un administrador ve los de todos (y puede filtrar por `user_id`). Pedir el reporte de otro usuario sin ser administrador responde `403`.\n\n**Formato de respuesta:** **archivo** (PDF, XML, ZIP, Excel o texto), no JSON. `application/pdf`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` o `application/zip` (reporte dividido en lotes). Si hay error, responde JSON `{success: false, message}`.\n\n**Parámetros de la ruta:**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `download_tray_id` | integer | Sí | Id del reporte. |\n\n**Errores:**\n- `403` si el reporte es de otro usuario y no eres administrador.\n- `404` si el reporte no existe o su archivo ya no está disponible.\n- `409` si aún se está generando (`status: IN_PROCESS`) o falló (`status: ERROR` / `FAILED`); la respuesta trae `status`.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Excel"
          },
          "409": {
            "description": "Aún en proceso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Aún en proceso",
                    "value": {
                      "success": false,
                      "message": "El reporte aún se está generando. Vuelva a consultar en unos segundos.",
                      "status": "IN_PROCESS"
                    }
                  },
                  "e2": {
                    "summary": "Falló",
                    "value": {
                      "success": false,
                      "message": "El reporte no se pudo generar. Solicítelo nuevamente.",
                      "status": "ERROR"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "De otro usuario",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "De otro usuario",
                    "value": {
                      "success": false,
                      "message": "No tienes permiso para acceder a este registro."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Archivo no disponible",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Archivo no disponible",
                    "value": {
                      "success": false,
                      "message": "El archivo del reporte ya no está disponible."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "download_tray_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ]
      }
    },
    "/api/company/sunat-config": {
      "get": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Ver configuración SUNAT",
        "operationId": "VerConfiguracionSunat",
        "description": "Estado de la configuración de facturación electrónica de la empresa: entorno, modo de envío, credenciales (sin secretos), certificado digital, PSE y **qué falta para pasar a producción** (`ready_for_production`). Úsalo antes y después de cada paso.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único).\n\n**Entorno (`soap_type_id`):**\n\n| Valor | Alias `environment` | Significado |\n|---|---|---|\n| `01` | `demo` | Demo / beta: los comprobantes se envían al ambiente de pruebas de SUNAT (u OSE/PSE), **sin validez legal**. |\n| `02` | `production` | Producción: los comprobantes se envían a SUNAT con **validez legal**. |\n\n**Modo de envío (`soap_send_id`):**\n\n| Valor | Descripción | Credenciales que necesita |\n|---|---|---|\n| `01` | Sunat (envío directo) | Usuario secundario SOL (`sunat_sol_username` = RUC + usuario) y su clave (`sunat_sol_password`). |\n| `02` | Ose | Usuario y clave del OSE (`ose_username`, `ose_password`) y la URL del servicio (`soap_url`). |\n| `04` | OseSendfact | Usuario y clave del OSE (`ose_username`, `ose_password`). |\n\nEl envío por **PSE** (el proveedor firma y envía) no es un valor de `soap_send_id`: se activa con **Configurar PSE** (`send_document_to_pse: true`) y tiene prioridad sobre el modo de envío.\n\n**Campos de la respuesta (`data`):**\n\n| Campo | Descripción |\n|---|---|\n| `editable` | `false` si el proveedor del sistema bloqueó la configuración del entorno (los cambios de entorno, modo, credenciales SOL/OSE y certificado responden `403`). |\n| `environment` | `soap_type_id` (`01`/`02`), `code` (`demo`/`production`) y `description`. |\n| `send_mode` | `soap_send_id`, `description`, `channel` efectivo (`sunat`, `ose` o `pse`) y `uses_pse`. |\n| `sol_user` / `has_sol_password` | Usuario secundario SOL vigente y si tiene clave guardada. La clave **nunca** se devuelve. |\n| `soap_url` | URL del servicio del OSE (solo modo `02`). |\n| `ose` | `username` y `has_password` del OSE (solo en modo OSE). |\n| `sunat_api` | `client_id` y `has_client_secret` de la aplicación API de SUNAT (guías de remisión y SIRE). |\n| `has_certificate` / `certificate` | Datos públicos del certificado: titular (`subject`), emisor, RUC detectado, si coincide con la empresa, vigencia (`valid_from`, `valid_to`), `days_to_expire` y `expired`. `null` si no hay certificado. Nunca incluye el certificado ni su clave. |\n| `pse` | Configuración PSE sin la contraseña: `enabled`, `provider`, `user_pse`, `has_password`, `has_credentials` y las URL opcionales. |\n| `ready_for_production` | `ok` y `missing[]` (`{code, message}`): lo que falta para pasar a producción. |\n| `warnings[]` | Avisos que no bloquean (`{code, message}`): certificado por vencer (`certificate_expiring`, 30 días o menos), RUC del certificado no determinado (`certificate_ruc_unknown`), documentos creados en demo (`demo_documents`). |\n\n**Códigos de `missing`:** `certificate` (no hay certificado), `certificate_file` (falta el archivo en el servidor), `certificate_invalid` (no se puede leer), `certificate_expired`, `certificate_ruc_mismatch`, `send_mode`, `sol_credentials`, `sol_username` (no empieza con el RUC), `ose_credentials`, `ose_url`, `pse_provider`, `pse_user`, `pse_password`. Con PSE no se pide certificado (firma el proveedor).\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Lista para producción",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Lista para producción",
                    "value": {
                      "success": true,
                      "data": {
                        "editable": true,
                        "environment": {
                          "soap_type_id": "01",
                          "code": "demo",
                          "description": "Demo"
                        },
                        "send_mode": {
                          "soap_send_id": "01",
                          "description": "Sunat",
                          "channel": "sunat",
                          "uses_pse": false
                        },
                        "sol_user": "20123456789VENTAS01",
                        "has_sol_password": true,
                        "soap_url": null,
                        "ose": {
                          "username": null,
                          "has_password": false
                        },
                        "sunat_api": {
                          "client_id": "8c1f2a9e-0b6d-4c1e-9f3a-2d7e5b4a1c90",
                          "has_client_secret": true
                        },
                        "has_certificate": true,
                        "certificate": {
                          "file_exists": true,
                          "readable": true,
                          "subject": "EMPRESA DEMO S.A.C.",
                          "organization": "EMPRESA DEMO S.A.C.",
                          "issuer": "ENTIDAD DE CERTIFICACION ACREDITADA",
                          "serial_number": "5A3F09C1D2",
                          "ruc": "20123456789",
                          "ruc_matches": true,
                          "valid_from": "2026-11-01 10:15:00",
                          "valid_to": "2027-11-01 10:15:00",
                          "days_to_expire": 358,
                          "expired": false,
                          "not_yet_valid": false
                        },
                        "pse": {
                          "enabled": false,
                          "provider": null,
                          "pse_provider_id": null,
                          "user_pse": null,
                          "has_password": false,
                          "has_credentials": false,
                          "url_signature_pse": null,
                          "url_send_cdr_pse": null,
                          "url_login_pse": null,
                          "client_id_pse": null
                        },
                        "ready_for_production": {
                          "ok": true,
                          "missing": []
                        },
                        "warnings": [
                          {
                            "code": "demo_documents",
                            "message": "Hay documentos creados en demo: bórrelos para evitar conflictos en producción.",
                            "types": [
                              {
                                "description": "Factura/Boleta o Nota de Crédito o Nota de Débito",
                                "count": 12
                              }
                            ]
                          }
                        ]
                      }
                    }
                  },
                  "e2": {
                    "summary": "Faltan requisitos",
                    "value": {
                      "success": true,
                      "data": {
                        "editable": true,
                        "environment": {
                          "soap_type_id": "01",
                          "code": "demo",
                          "description": "Demo"
                        },
                        "send_mode": {
                          "soap_send_id": "01",
                          "description": "Sunat",
                          "channel": "sunat",
                          "uses_pse": false
                        },
                        "sol_user": "20123456789VENTAS01",
                        "has_sol_password": false,
                        "soap_url": null,
                        "ose": {
                          "username": null,
                          "has_password": false
                        },
                        "sunat_api": {
                          "client_id": "8c1f2a9e-0b6d-4c1e-9f3a-2d7e5b4a1c90",
                          "has_client_secret": true
                        },
                        "has_certificate": false,
                        "certificate": null,
                        "pse": {
                          "enabled": false,
                          "provider": null,
                          "pse_provider_id": null,
                          "user_pse": null,
                          "has_password": false,
                          "has_credentials": false,
                          "url_signature_pse": null,
                          "url_send_cdr_pse": null,
                          "url_login_pse": null,
                          "client_id_pse": null
                        },
                        "ready_for_production": {
                          "ok": false,
                          "missing": [
                            {
                              "code": "certificate",
                              "message": "Suba el certificado digital (.pfx) de la empresa."
                            },
                            {
                              "code": "sol_credentials",
                              "message": "Faltan el usuario secundario SOL y su clave."
                            }
                          ]
                        },
                        "warnings": [
                          {
                            "code": "demo_documents",
                            "message": "Hay documentos creados en demo: bórrelos para evitar conflictos en producción.",
                            "types": [
                              {
                                "description": "Factura/Boleta o Nota de Crédito o Nota de Débito",
                                "count": 12
                              }
                            ]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Configurar envío directo a SUNAT",
        "operationId": "ConfigurarEnvioDirectoASunat",
        "description": "Configura el modo de envío y las credenciales. Este ejemplo deja el envío **directo a SUNAT** con el usuario secundario SOL. Es edición parcial: envía solo lo que cambias.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae la configuración completa (igual que **Ver configuración SUNAT**).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `soap_send_id` | string | No | `01` Sunat, `02` Ose, `04` OseSendfact. Ver la tabla de modos de envío. |\n| `sunat_sol_username` | string (máx. 255) | No | Usuario secundario SOL: **RUC de la empresa + usuario** (p. ej. `20123456789VENTAS01`). |\n| `sunat_sol_password` | string (máx. 255) | No | Clave SOL. **Solo escritura.** Si no se envía se conserva la guardada; si cambias el usuario debes enviar su clave. |\n| `ose_username` | string (máx. 255) | No | Usuario del OSE (modos `02` y `04`). |\n| `ose_password` | string (máx. 255) | No | Clave del OSE. **Solo escritura.** Si no se envía se conserva la guardada. |\n| `soap_url` | string (URL, máx. 255) | No | URL del servicio del OSE (obligatoria en modo `02` para producción). |\n| `soap_username / soap_password` | string | No | Alias: se guardan como usuario/clave **SOL** en modo `01` o del **OSE** en modos `02`/`04`. Con PSE responden `422`. |\n| `sunat_client_id` | string (máx. 255) | No | Client ID de la aplicación API de SUNAT (guías de remisión, SIRE). |\n| `sunat_client_secret` | string (máx. 255) | No | Client Secret. **Solo escritura.** Va en pareja con `sunat_client_id`. |\n| `soap_type_id` | string | No | `01` (demo) o `02` (producción). Solo para cambiar de entorno: ver **Pasar a producción** y **Volver a demo**. |\n| `environment` | string | No | Alias de `soap_type_id`: `demo` o `production`. |\n| `confirm_production` | boolean | Para pasar a producción | `true` para confirmar el paso a producción. |\n| `confirm_demo` | boolean | Para volver a demo | `true` para confirmar el regreso a demo. |\n\n**Modo de envío (`soap_send_id`):**\n\n| Valor | Descripción | Credenciales que necesita |\n|---|---|---|\n| `01` | Sunat (envío directo) | Usuario secundario SOL (`sunat_sol_username` = RUC + usuario) y su clave (`sunat_sol_password`). |\n| `02` | Ose | Usuario y clave del OSE (`ose_username`, `ose_password`) y la URL del servicio (`soap_url`). |\n| `04` | OseSendfact | Usuario y clave del OSE (`ose_username`, `ose_password`). |\n\nEl envío por **PSE** (el proveedor firma y envía) no es un valor de `soap_send_id`: se activa con **Configurar PSE** (`send_document_to_pse: true`) y tiene prioridad sobre el modo de envío.\n\n**Reglas:**\n- **Edición parcial:** solo cambia lo que envías; lo demás se conserva. Un campo de clave vacío o ausente conserva la clave guardada.\n- Las claves (`sunat_sol_password`, `ose_password`, `sunat_client_secret`) son de **solo escritura**: la respuesta solo dice si existen (`has_*`).\n- En modo `01` (Sunat) el envío de comprobantes usa el usuario y la clave SOL.\n- Si la empresa ya está en **producción**, un cambio que la deje sin poder emitir (p. ej. pasar a OSE sin URL) responde `409` con los faltantes que agrega.\n- Al cambiar credenciales se invalidan los tokens de SUNAT guardados; el siguiente envío pide uno nuevo.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `403` si el proveedor del sistema bloqueó la configuración del entorno de la empresa (`editable: false`): no se pueden cambiar entorno, modo de envío, credenciales SOL/OSE ni el certificado.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (usuario SOL sin el RUC de la empresa, usuario nuevo sin su clave, OSE sin usuario/clave, Client ID sin Client Secret, cuerpo vacío).\n- `409` con `missing` si la empresa está en producción y el cambio la dejaría sin poder emitir.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Guardado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardado",
                    "value": {
                      "success": true,
                      "data": {
                        "editable": true,
                        "environment": {
                          "soap_type_id": "01",
                          "code": "demo",
                          "description": "Demo"
                        },
                        "send_mode": {
                          "soap_send_id": "01",
                          "description": "Sunat",
                          "channel": "sunat",
                          "uses_pse": false
                        },
                        "sol_user": "20123456789VENTAS01",
                        "has_sol_password": true,
                        "soap_url": null,
                        "ose": {
                          "username": null,
                          "has_password": false
                        },
                        "sunat_api": {
                          "client_id": "8c1f2a9e-0b6d-4c1e-9f3a-2d7e5b4a1c90",
                          "has_client_secret": true
                        },
                        "has_certificate": true,
                        "certificate": {
                          "file_exists": true,
                          "readable": true,
                          "subject": "EMPRESA DEMO S.A.C.",
                          "organization": "EMPRESA DEMO S.A.C.",
                          "issuer": "ENTIDAD DE CERTIFICACION ACREDITADA",
                          "serial_number": "5A3F09C1D2",
                          "ruc": "20123456789",
                          "ruc_matches": true,
                          "valid_from": "2026-11-01 10:15:00",
                          "valid_to": "2027-11-01 10:15:00",
                          "days_to_expire": 358,
                          "expired": false,
                          "not_yet_valid": false
                        },
                        "pse": {
                          "enabled": false,
                          "provider": null,
                          "pse_provider_id": null,
                          "user_pse": null,
                          "has_password": false,
                          "has_credentials": false,
                          "url_signature_pse": null,
                          "url_send_cdr_pse": null,
                          "url_login_pse": null,
                          "client_id_pse": null
                        },
                        "ready_for_production": {
                          "ok": true,
                          "missing": []
                        },
                        "warnings": [
                          {
                            "code": "demo_documents",
                            "message": "Hay documentos creados en demo: bórrelos para evitar conflictos en producción.",
                            "types": [
                              {
                                "description": "Factura/Boleta o Nota de Crédito o Nota de Débito",
                                "count": 12
                              }
                            ]
                          }
                        ]
                      },
                      "message": "Configuración SUNAT actualizada."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Usuario SOL inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario SOL inválido",
                    "value": {
                      "success": false,
                      "message": {
                        "sunat_sol_username": [
                          "Debe ser el RUC de la empresa seguido del usuario SOL. Ejemplo: 20123456789USUARIO"
                        ]
                      }
                    }
                  },
                  "e2": {
                    "summary": "Usuario nuevo sin clave",
                    "value": {
                      "success": false,
                      "message": {
                        "sunat_sol_password": [
                          "Ingrese la clave SOL del nuevo usuario."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  },
                  "e2": {
                    "summary": "Configuración bloqueada",
                    "value": {
                      "success": false,
                      "message": "El proveedor del sistema bloqueó el cambio de entorno, modo de envío y credenciales SOL/OSE de esta empresa. Campos no permitidos: soap_send_id."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Configurar envío directo a SUNAT",
                  "value": {
                    "soap_send_id": "01",
                    "sunat_sol_username": "20123456789VENTAS01",
                    "sunat_sol_password": "********"
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Configurar envío por OSE",
        "operationId": "ConfigurarEnvioOse",
        "description": "Mismo endpoint que **Configurar envío directo a SUNAT**: este ejemplo cambia el envío a un **OSE** con su usuario, clave y URL.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae la configuración completa.\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `soap_send_id` | string | No | `01` Sunat, `02` Ose, `04` OseSendfact. Ver la tabla de modos de envío. |\n| `sunat_sol_username` | string (máx. 255) | No | Usuario secundario SOL: **RUC de la empresa + usuario** (p. ej. `20123456789VENTAS01`). |\n| `sunat_sol_password` | string (máx. 255) | No | Clave SOL. **Solo escritura.** Si no se envía se conserva la guardada; si cambias el usuario debes enviar su clave. |\n| `ose_username` | string (máx. 255) | No | Usuario del OSE (modos `02` y `04`). |\n| `ose_password` | string (máx. 255) | No | Clave del OSE. **Solo escritura.** Si no se envía se conserva la guardada. |\n| `soap_url` | string (URL, máx. 255) | No | URL del servicio del OSE (obligatoria en modo `02` para producción). |\n| `soap_username / soap_password` | string | No | Alias: se guardan como usuario/clave **SOL** en modo `01` o del **OSE** en modos `02`/`04`. Con PSE responden `422`. |\n| `sunat_client_id` | string (máx. 255) | No | Client ID de la aplicación API de SUNAT (guías de remisión, SIRE). |\n| `sunat_client_secret` | string (máx. 255) | No | Client Secret. **Solo escritura.** Va en pareja con `sunat_client_id`. |\n| `soap_type_id` | string | No | `01` (demo) o `02` (producción). Solo para cambiar de entorno: ver **Pasar a producción** y **Volver a demo**. |\n| `environment` | string | No | Alias de `soap_type_id`: `demo` o `production`. |\n| `confirm_production` | boolean | Para pasar a producción | `true` para confirmar el paso a producción. |\n| `confirm_demo` | boolean | Para volver a demo | `true` para confirmar el regreso a demo. |\n\n**Reglas:**\n- **Edición parcial:** solo cambia lo que envías; lo demás se conserva. Un campo de clave vacío o ausente conserva la clave guardada.\n- Las claves (`sunat_sol_password`, `ose_password`, `sunat_client_secret`) son de **solo escritura**: la respuesta solo dice si existen (`has_*`).\n- En modo `01` (Sunat) el envío de comprobantes usa el usuario y la clave SOL.\n- Si la empresa ya está en **producción**, un cambio que la deje sin poder emitir (p. ej. pasar a OSE sin URL) responde `409` con los faltantes que agrega.\n- Al cambiar credenciales se invalidan los tokens de SUNAT guardados; el siguiente envío pide uno nuevo.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `403` si el proveedor del sistema bloqueó la configuración del entorno de la empresa (`editable: false`): no se pueden cambiar entorno, modo de envío, credenciales SOL/OSE ni el certificado.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (falta `ose_username` u `ose_password`).\n- `409` con `missing` si la empresa está en producción y el cambio la dejaría sin poder emitir (p. ej. sin `soap_url`).\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Guardado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardado",
                    "value": {
                      "success": true,
                      "data": {
                        "editable": true,
                        "environment": {
                          "soap_type_id": "01",
                          "code": "demo",
                          "description": "Demo"
                        },
                        "send_mode": {
                          "soap_send_id": "02",
                          "description": "Ose",
                          "channel": "ose",
                          "uses_pse": false
                        },
                        "sol_user": "20123456789VENTAS01",
                        "has_sol_password": true,
                        "soap_url": "https://ose.proveedor.pe/ol-ti-itcpe/billService",
                        "ose": {
                          "username": "usuario-ose",
                          "has_password": true
                        },
                        "sunat_api": {
                          "client_id": "8c1f2a9e-0b6d-4c1e-9f3a-2d7e5b4a1c90",
                          "has_client_secret": true
                        },
                        "has_certificate": true,
                        "certificate": {
                          "file_exists": true,
                          "readable": true,
                          "subject": "EMPRESA DEMO S.A.C.",
                          "organization": "EMPRESA DEMO S.A.C.",
                          "issuer": "ENTIDAD DE CERTIFICACION ACREDITADA",
                          "serial_number": "5A3F09C1D2",
                          "ruc": "20123456789",
                          "ruc_matches": true,
                          "valid_from": "2026-11-01 10:15:00",
                          "valid_to": "2027-11-01 10:15:00",
                          "days_to_expire": 358,
                          "expired": false,
                          "not_yet_valid": false
                        },
                        "pse": {
                          "enabled": false,
                          "provider": null,
                          "pse_provider_id": null,
                          "user_pse": null,
                          "has_password": false,
                          "has_credentials": false,
                          "url_signature_pse": null,
                          "url_send_cdr_pse": null,
                          "url_login_pse": null,
                          "client_id_pse": null
                        },
                        "ready_for_production": {
                          "ok": true,
                          "missing": []
                        },
                        "warnings": [
                          {
                            "code": "demo_documents",
                            "message": "Hay documentos creados en demo: bórrelos para evitar conflictos en producción.",
                            "types": [
                              {
                                "description": "Factura/Boleta o Nota de Crédito o Nota de Débito",
                                "count": 12
                              }
                            ]
                          }
                        ]
                      },
                      "message": "Configuración SUNAT actualizada."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Faltan credenciales del OSE",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Faltan credenciales del OSE",
                    "value": {
                      "success": false,
                      "message": {
                        "ose_username": [
                          "El usuario del OSE es obligatorio."
                        ],
                        "ose_password": [
                          "La clave del OSE es obligatoria."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Dejaría producción sin emitir",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Dejaría producción sin emitir",
                    "value": {
                      "success": false,
                      "message": "La empresa está en producción y el cambio la dejaría sin poder emitir.",
                      "missing": [
                        {
                          "code": "ose_url",
                          "message": "Falta la URL del servicio del OSE (soap_url)."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Configurar envío por OSE",
                  "value": {
                    "soap_send_id": "02",
                    "ose_username": "usuario-ose",
                    "ose_password": "********",
                    "soap_url": "https://ose.proveedor.pe/ol-ti-itcpe/billService"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/company/certificate": {
      "post": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Subir certificado digital",
        "operationId": "SubirCertificadoDigital",
        "description": "Sube el certificado digital de la empresa (archivo `.pfx` o `.p12` emitido por una entidad acreditada) con su contraseña. Antes de guardarlo se verifica que la contraseña lo abra, que contenga la clave privada, que esté vigente y que su RUC sea el de la empresa. Reemplaza al certificado anterior.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae `certificate` (datos públicos), `ready_for_production` y `warnings`. Nunca devuelve el certificado ni la contraseña.\n\n**Cuerpo (`multipart/form-data`):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `file` | archivo | Sí | Certificado `.pfx` o `.p12` (máx. 100 KB). |\n| `password` | string | Sí | Contraseña del certificado. No se guarda. |\n\n**Reglas:**\n- El RUC se busca en el titular del certificado (serialNumber, organizationIdentifier, OU o CN). Si el certificado no trae RUC (p. ej. de persona natural con DNI) se acepta y se avisa en `warnings` (`certificate_ruc_unknown`): verifica que sea de la empresa.\n- Renueva el certificado antes de `valid_to`: un certificado vencido no permite emitir. Desde 30 días antes se avisa en `warnings`.\n- Si el servidor responde que el cifrado es antiguo, exporta el certificado de nuevo con cifrado AES.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `403` si el proveedor del sistema bloqueó la configuración del entorno de la empresa (`editable: false`): no se pueden cambiar entorno, modo de envío, credenciales SOL/OSE ni el certificado.\n- `422` en `message.password` si la contraseña es incorrecta (o el archivo no es un .pfx).\n- `422` en `message.file` si no es .pfx/.p12, no tiene clave privada, está vencido o aún no es válido, o es de otro RUC.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Certificado guardado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Certificado guardado",
                    "value": {
                      "success": true,
                      "data": {
                        "certificate": {
                          "file_exists": true,
                          "readable": true,
                          "subject": "EMPRESA DEMO S.A.C.",
                          "organization": "EMPRESA DEMO S.A.C.",
                          "issuer": "ENTIDAD DE CERTIFICACION ACREDITADA",
                          "serial_number": "5A3F09C1D2",
                          "ruc": "20123456789",
                          "ruc_matches": true,
                          "valid_from": "2026-11-01 10:15:00",
                          "valid_to": "2027-11-01 10:15:00",
                          "days_to_expire": 358,
                          "expired": false,
                          "not_yet_valid": false
                        },
                        "ready_for_production": {
                          "ok": true,
                          "missing": []
                        },
                        "warnings": [
                          {
                            "code": "demo_documents",
                            "message": "Hay documentos creados en demo: bórrelos para evitar conflictos en producción.",
                            "types": [
                              {
                                "description": "Factura/Boleta o Nota de Crédito o Nota de Débito",
                                "count": 12
                              }
                            ]
                          }
                        ]
                      },
                      "message": "Certificado guardado."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Contraseña incorrecta",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Contraseña incorrecta",
                    "value": {
                      "success": false,
                      "message": {
                        "password": [
                          "No se pudo abrir el certificado: la contraseña es incorrecta o el archivo no es un .pfx/.p12 válido."
                        ]
                      }
                    }
                  },
                  "e2": {
                    "summary": "Otro RUC",
                    "value": {
                      "success": false,
                      "message": {
                        "file": [
                          "El certificado pertenece al RUC 20999999999 y la empresa es 20123456789."
                        ]
                      }
                    }
                  },
                  "e3": {
                    "summary": "Vencido",
                    "value": {
                      "success": false,
                      "message": {
                        "file": [
                          "El certificado venció el 2026-10-31 23:59:59."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  },
                  "e2": {
                    "summary": "Configuración bloqueada",
                    "value": {
                      "success": false,
                      "message": "El proveedor del sistema bloqueó el cambio de entorno, modo de envío y credenciales SOL/OSE de esta empresa. Campos no permitidos: soap_send_id."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Certificado .pfx o .p12."
                  },
                  "password": {
                    "type": "string",
                    "description": "Contraseña del certificado."
                  }
                },
                "required": [
                  "file",
                  "password"
                ]
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Eliminar certificado",
        "operationId": "EliminarCertificado",
        "description": "Quita el certificado digital de la empresa.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae la configuración completa.\n\n**Reglas:**\n- En producción (sin PSE) no se puede: sube el nuevo certificado (reemplaza al actual) o vuelve primero a demo.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `403` si el proveedor del sistema bloqueó la configuración del entorno de la empresa (`editable: false`): no se pueden cambiar entorno, modo de envío, credenciales SOL/OSE ni el certificado.\n- `404` si la empresa no tiene certificado.\n- `409` si la empresa está en producción sin PSE.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Eliminado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Eliminado",
                    "value": {
                      "success": true,
                      "data": {
                        "editable": true,
                        "environment": {
                          "soap_type_id": "01",
                          "code": "demo",
                          "description": "Demo"
                        },
                        "send_mode": {
                          "soap_send_id": "01",
                          "description": "Sunat",
                          "channel": "sunat",
                          "uses_pse": false
                        },
                        "sol_user": "20123456789VENTAS01",
                        "has_sol_password": true,
                        "soap_url": null,
                        "ose": {
                          "username": null,
                          "has_password": false
                        },
                        "sunat_api": {
                          "client_id": "8c1f2a9e-0b6d-4c1e-9f3a-2d7e5b4a1c90",
                          "has_client_secret": true
                        },
                        "has_certificate": false,
                        "certificate": null,
                        "pse": {
                          "enabled": false,
                          "provider": null,
                          "pse_provider_id": null,
                          "user_pse": null,
                          "has_password": false,
                          "has_credentials": false,
                          "url_signature_pse": null,
                          "url_send_cdr_pse": null,
                          "url_login_pse": null,
                          "client_id_pse": null
                        },
                        "ready_for_production": {
                          "ok": false,
                          "missing": [
                            {
                              "code": "certificate",
                              "message": "Suba el certificado digital (.pfx) de la empresa."
                            }
                          ]
                        },
                        "warnings": [
                          {
                            "code": "demo_documents",
                            "message": "Hay documentos creados en demo: bórrelos para evitar conflictos en producción.",
                            "types": [
                              {
                                "description": "Factura/Boleta o Nota de Crédito o Nota de Débito",
                                "count": 12
                              }
                            ]
                          }
                        ]
                      },
                      "message": "Certificado eliminado."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "En producción",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En producción",
                    "value": {
                      "success": false,
                      "message": "La empresa está en producción: no puede quedar sin certificado. Suba el nuevo certificado (reemplaza al actual) o vuelva primero a demo."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Sin certificado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin certificado",
                    "value": {
                      "success": false,
                      "message": "La empresa no tiene certificado."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/company/pse-providers": {
      "get": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Proveedores PSE",
        "operationId": "ProveedoresPse",
        "description": "Proveedores PSE activos para usar en **Configurar PSE**. `supports_connection_test` indica si **Probar conexión** puede validar sus credenciales.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` es un arreglo.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Proveedores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Proveedores",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "id": 2,
                          "name": "gior",
                          "description": "Gior Technology",
                          "supports_connection_test": true
                        },
                        {
                          "id": 3,
                          "name": "qpse",
                          "description": "QPSE",
                          "supports_connection_test": true
                        },
                        {
                          "id": 4,
                          "name": "sendfact",
                          "description": "SendFact",
                          "supports_connection_test": false
                        },
                        {
                          "id": 5,
                          "name": "validapse",
                          "description": "Validapse",
                          "supports_connection_test": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/company/pse-config": {
      "put": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Configurar PSE",
        "operationId": "ConfigurarPse",
        "description": "Activa o desactiva el envío por **PSE** (el proveedor firma y envía los comprobantes; no se necesita certificado propio) y guarda sus credenciales. Edición parcial: lo que no envías se conserva.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` trae la configuración PSE sin la contraseña (igual que `pse` en **Ver configuración SUNAT**).\n\n**Cuerpo (JSON):**\n\n| Campo | Tipo | Obligatorio | Descripción / valores permitidos |\n|---|---|---|---|\n| `send_document_to_pse` | boolean | No | `true` activa el envío por PSE; `false` vuelve al modo de envío (`soap_send_id`). |\n| `pse_provider_id` | integer | Si se activa | Id de **Proveedores PSE** (activo). |\n| `user_pse` | string (máx. 255) | Si se activa | Usuario del PSE. |\n| `password_pse` | string (máx. 255) | Si se activa y no hay una guardada | Contraseña del PSE. **Solo escritura**; vacía o ausente conserva la guardada. |\n| `client_id_pse` | string (máx. 255) | No | Client ID, si el proveedor lo pide. |\n| `url_signature_pse, url_send_cdr_pse, url_login_pse` | string (URL) | No | URL propias del proveedor, solo si las pide. |\n\n**Reglas:**\n- El proveedor usa el ambiente de la empresa (demo o producción) con las mismas credenciales.\n- Si la empresa está en producción y desactivas el PSE sin tener certificado vigente, responde `409`.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `422` `{success: false, message: {campo: [errores]}}` si falla la validación de campos. (proveedor inexistente o inactivo, falta el usuario o la contraseña al activar).\n- `409` con `missing` si la empresa está en producción y el cambio la dejaría sin poder emitir.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Guardado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Guardado",
                    "value": {
                      "success": true,
                      "data": {
                        "enabled": true,
                        "provider": {
                          "id": 3,
                          "name": "qpse",
                          "description": "QPSE",
                          "active": true
                        },
                        "pse_provider_id": 3,
                        "user_pse": "miusuario",
                        "has_password": true,
                        "has_credentials": true,
                        "url_signature_pse": null,
                        "url_send_cdr_pse": null,
                        "url_login_pse": null,
                        "client_id_pse": null
                      },
                      "message": "Configuración PSE guardada."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Faltan credenciales",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Faltan credenciales",
                    "value": {
                      "success": false,
                      "message": {
                        "user_pse": [
                          "Debe ingresar el usuario de autenticación."
                        ],
                        "password_pse": [
                          "Debe ingresar la contraseña de autenticación."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Producción sin certificado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Producción sin certificado",
                    "value": {
                      "success": false,
                      "message": "La empresa está en producción y el cambio la dejaría sin poder emitir.",
                      "missing": [
                        {
                          "code": "certificate",
                          "message": "Suba el certificado digital (.pfx) de la empresa."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "examples": {
                "e1": {
                  "summary": "Configurar PSE",
                  "value": {
                    "send_document_to_pse": true,
                    "pse_provider_id": "3",
                    "user_pse": "miusuario",
                    "password_pse": "********"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/company/sunat-config/test": {
      "post": {
        "tags": [
          "Configuración SUNAT"
        ],
        "summary": "Probar conexión",
        "operationId": "ProbarConexion",
        "description": "Prueba la configuración guardada **sin enviar comprobantes**: solo valida el certificado y pide tokens de acceso.\n\n**Quién puede usarlo:** solo usuarios de tipo administrador (`type = admin`). Con el token de un vendedor responde `403`.\n\n**Formato de respuesta:** estándar `{success, data, message?}` (registro único). `data` = `{ok, checks: {certificate, pse?, sunat_api, ose?}}`; cada prueba tiene `status` (`ok`, `error` o `skipped`) y `message`.\n\n**Qué prueba:**\n\n| Prueba | Cómo |\n|---|---|\n| `certificate` | Validación local: vigente y del RUC de la empresa. `skipped` con PSE. |\n| `pse` | Pide un token al proveedor PSE en el ambiente de la empresa (Gior, QPSE, Validapse). Otros proveedores: `skipped`. |\n| `sunat_api` | Pide un token a la API de SUNAT **producción** con el usuario SOL, la clave y el Client ID/Secret: confirma que las credenciales SOL son válidas. Sin Client ID/Secret: `skipped`. |\n| `ose` | `skipped`: un OSE solo se puede probar enviando un comprobante (hazlo en demo). |\n\n**Reglas:**\n- Máximo **5 pruebas por minuto** (luego `429`). SUNAT puede bloquear temporalmente un usuario SOL tras varios intentos fallidos: no repitas la prueba si falla, corrige las credenciales primero.\n- `ok` es `true` si ninguna prueba dio `error`.\n\n**Errores:**\n- `403` si el usuario no es administrador.\n- `429` si superas el límite de pruebas por minuto.\n- `401` sin token o con un token inválido.",
        "responses": {
          "200": {
            "description": "Resultado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Resultado",
                    "value": {
                      "success": true,
                      "data": {
                        "ok": true,
                        "checks": {
                          "certificate": {
                            "status": "ok",
                            "message": "Certificado vigente hasta 2027-11-01 10:15:00."
                          },
                          "sunat_api": {
                            "status": "ok",
                            "message": "SUNAT aceptó el usuario SOL y la aplicación (Client ID)."
                          }
                        }
                      }
                    }
                  },
                  "e2": {
                    "summary": "Con errores",
                    "value": {
                      "success": true,
                      "data": {
                        "ok": false,
                        "checks": {
                          "certificate": {
                            "status": "skipped",
                            "message": "Con PSE el proveedor firma los comprobantes."
                          },
                          "pse": {
                            "status": "error",
                            "message": "El PSE rechazó las credenciales o no respondió."
                          },
                          "sunat_api": {
                            "status": "skipped",
                            "message": "Configure usuario SOL, clave, Client ID y Client Secret para probar la API de SUNAT."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Usuario no administrador",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Usuario no administrador",
                    "value": {
                      "success": false,
                      "message": "Solo un administrador puede gestionar este recurso."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/sire/{sire_type}/periods": {
      "get": {
        "tags": [
          "SIRE"
        ],
        "summary": "Periodos del registro",
        "operationId": "PeriodosRegistro",
        "description": "Ejercicios y periodos (meses) del libro en SIRE con su estado. `{sire_type}`: `sale` (Registro de Ventas, RVIE) o `purchase` (Registro de Compras, RCE).\n\n**Quién puede usarlo:** administradores y usuarios con el nivel de acceso *Resumen de cuentas* (`account_summary`), el mismo que exige el panel en SIRE.\n\n**Formato de respuesta:** estándar `{success, data, message?}` con códigos HTTP reales.\n\nCada periodo trae `period` (AAAAMM), `status_code` y `status` tal como los devuelve SUNAT.\n\n**Errores comunes:** `422` faltan las credenciales SUNAT de la empresa o SUNAT las rechazó; `502` SUNAT respondió con error (su cuerpo va en `sunat_error` y su código en `sunat_code`); `504` no hubo conexión con SUNAT; `403` sin permiso.",
        "responses": {
          "200": {
            "description": "Periodos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Periodos",
                    "value": {
                      "success": true,
                      "data": [
                        {
                          "year": "2026",
                          "status": "Activo",
                          "periods": [
                            {
                              "period": "202610",
                              "status_code": "01",
                              "status": "Pendiente"
                            },
                            {
                              "period": "202609",
                              "status_code": "02",
                              "status": "Presentado"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Credenciales rechazadas",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Credenciales rechazadas",
                    "value": {
                      "success": false,
                      "message": "SIRE. SUNAT rechazó las credenciales de la empresa (usuario/clave SOL o Client ID/Secret).",
                      "sunat_code": 400,
                      "sunat_error": {
                        "error": "invalid_grant",
                        "error_description": "Usuario o clave incorrecto"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sire_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "sale"
          }
        ]
      }
    },
    "/api/sire/{sire_type}/periods/{sire_period}/ticket": {
      "post": {
        "tags": [
          "SIRE"
        ],
        "summary": "Pedir la propuesta (ticket)",
        "operationId": "PedirPropuestaTicket",
        "description": "Pide a SUNAT que genere la **propuesta** del periodo `{sire_period}` (AAAAMM) y devuelve el **ticket** del proceso. `{sire_type}`: `sale` (Registro de Ventas, RVIE) o `purchase` (Registro de Compras, RCE).\n\nSUNAT procesa en diferido: consulta el ticket con *Estado del ticket* hasta que `finished` sea `true` (estado `06`).\n\n**Quién puede usarlo:** administradores y usuarios con el nivel de acceso *Resumen de cuentas* (`account_summary`), el mismo que exige el panel en SIRE.\n\n**Formato de respuesta:** estándar `{success, data, message?}` con códigos HTTP reales.\n\nLímite: 10 peticiones por minuto.\n\n**Errores:** `422` periodo con formato distinto de AAAAMM. **Errores comunes:** `422` faltan las credenciales SUNAT de la empresa o SUNAT las rechazó; `502` SUNAT respondió con error (su cuerpo va en `sunat_error` y su código en `sunat_code`); `504` no hubo conexión con SUNAT; `403` sin permiso.",
        "responses": {
          "200": {
            "description": "Ticket generado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Ticket generado",
                    "value": {
                      "success": true,
                      "data": {
                        "type": "sale",
                        "period": "202610",
                        "ticket": "20260300000077"
                      },
                      "message": "SUNAT está generando la propuesta. Consulte el ticket hasta que su estado sea 06."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Periodo inválido",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Periodo inválido",
                    "value": {
                      "success": false,
                      "message": "El periodo debe tener el formato AAAAMM.",
                      "errors": {
                        "period": [
                          "El periodo debe tener el formato AAAAMM."
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Error de SUNAT",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error de SUNAT",
                    "value": {
                      "success": false,
                      "message": "SIRE. SUNAT respondió con error 500: Servicio no disponible",
                      "sunat_code": 500,
                      "sunat_error": {
                        "cod": "500",
                        "msg": "Servicio no disponible"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sire_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "sale"
          },
          {
            "name": "sire_period",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "202610"
          }
        ]
      }
    },
    "/api/sire/{sire_type}/tickets/{sire_ticket}": {
      "get": {
        "tags": [
          "SIRE"
        ],
        "summary": "Estado del ticket",
        "operationId": "EstadoTicket",
        "description": "Estado del proceso de SUNAT del ticket. `{sire_type}`: `sale` (Registro de Ventas, RVIE) o `purchase` (Registro de Compras, RCE).\n\n| Parámetro | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `period` | string | Sí | Periodo AAAAMM con el que se pidió el ticket. |\n| `page` | integer | No | Página de la consulta de SUNAT (por defecto 1). |\n\n`finished: true` (estado `06`) indica que la propuesta está lista: pasa a *Comparar propuesta con el sistema*.\n\n**Quién puede usarlo:** administradores y usuarios con el nivel de acceso *Resumen de cuentas* (`account_summary`), el mismo que exige el panel en SIRE.\n\n**Formato de respuesta:** estándar `{success, data, message?}` con códigos HTTP reales.\n\n**Errores:** `404` SUNAT no tiene registros para ese ticket y periodo; `422` falta `period` o no es AAAAMM. **Errores comunes:** `422` faltan las credenciales SUNAT de la empresa o SUNAT las rechazó; `502` SUNAT respondió con error (su cuerpo va en `sunat_error` y su código en `sunat_code`); `504` no hubo conexión con SUNAT; `403` sin permiso.",
        "responses": {
          "200": {
            "description": "En proceso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "En proceso",
                    "value": {
                      "success": true,
                      "data": {
                        "type": "sale",
                        "period": "202610",
                        "ticket": "20260300000077",
                        "status_code": "02",
                        "status": "En proceso",
                        "finished": false,
                        "filename": null
                      }
                    }
                  },
                  "e2": {
                    "summary": "Terminado",
                    "value": {
                      "success": true,
                      "data": {
                        "type": "sale",
                        "period": "202610",
                        "ticket": "20260300000077",
                        "status_code": "06",
                        "status": "Terminado",
                        "finished": true,
                        "filename": "LE2010000000120261000140400021112.zip"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Sin registros",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Sin registros",
                    "value": {
                      "success": false,
                      "message": "SIRE. No hay registros en esta página"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sire_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "sale"
          },
          {
            "name": "sire_ticket",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "20260300000077"
          },
          {
            "name": "period",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "202610",
            "description": "Periodo tributario AAAAMM (obligatorio)"
          }
        ]
      }
    },
    "/api/sire/{sire_type}/tickets/{sire_ticket}/comparison": {
      "get": {
        "tags": [
          "SIRE"
        ],
        "summary": "Comparar propuesta con el sistema",
        "operationId": "CompararPropuestaSistema",
        "description": "Descarga la propuesta del ticket terminado y la **cruza con el sistema**: comprobantes (ventas) o compras. `{sire_type}`: `sale` (Registro de Ventas, RVIE) o `purchase` (Registro de Compras, RCE).\n\nCruce por serie y número, priorizando el mismo tipo de comprobante; en compras además por RUC del proveedor (dos proveedores pueden repetir serie y número).\n\n`data.rows[]`: una fila por comprobante de la propuesta con `status`:\n- `match`: existe y el total coincide.\n- `total_mismatch`: existe con otro total (detalle en `differences.total`).\n- `not_in_system`: está en SUNAT y no en el sistema.\n\n`differences.date_of_issue` avisa si la fecha difiere (no cambia el estado). `data.only_in_system[]`: comprobantes del periodo en el sistema que la propuesta no trae (ventas: facturas, boletas y notas 01/03/07/08 que no estén rechazadas ni anuladas; compras: todas salvo anuladas). `data.summary`: conteos y totales.\n\n| Parámetro | Tipo | Obligatorio | Descripción |\n|---|---|---|---|\n| `period` | string | Sí | Periodo AAAAMM del ticket. |\n| `page` | integer | No | Página de la consulta del ticket (por defecto 1). |\n\n**Quién puede usarlo:** administradores y usuarios con el nivel de acceso *Resumen de cuentas* (`account_summary`), el mismo que exige el panel en SIRE.\n\n**Formato de respuesta:** estándar `{success, data, message?}` con códigos HTTP reales.\n\nLímite: 10 peticiones por minuto.\n\n**Errores:** `409` SUNAT aún no termina (trae `status_code` y `status`); `404` ticket sin registros. **Errores comunes:** `422` faltan las credenciales SUNAT de la empresa o SUNAT las rechazó; `502` SUNAT respondió con error (su cuerpo va en `sunat_error` y su código en `sunat_code`); `504` no hubo conexión con SUNAT; `403` sin permiso.",
        "responses": {
          "200": {
            "description": "Comparación",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Comparación",
                    "value": {
                      "success": true,
                      "data": {
                        "type": "sale",
                        "period": "202610",
                        "ticket": "20260300000077",
                        "rows": [
                          {
                            "status": "match",
                            "sunat": {
                              "car": "20123456789010F00100000123",
                              "date_of_issue": "05/10/2026",
                              "date_of_issue_iso": "2026-10-05",
                              "document_type_id": "01",
                              "series": "F001",
                              "number": 123,
                              "party_identity_document_type_id": "6",
                              "party_number": "20100000001",
                              "party_name": "CLIENTE S.A.C.",
                              "total": 118.0,
                              "total_raw": "118.00"
                            },
                            "system": {
                              "id": 5521,
                              "external_id": "0b6a1e7c-3f1d-4c4e-9a52-7b1f0d9c2e11",
                              "document_type_id": "01",
                              "series": "F001",
                              "number": 123,
                              "date_of_issue": "2026-10-05",
                              "party_number": "20100000001",
                              "party_name": "CLIENTE S.A.C.",
                              "currency_type_id": "PEN",
                              "state_type_id": "05",
                              "total": 118.0
                            },
                            "differences": []
                          },
                          {
                            "status": "not_in_system",
                            "sunat": {
                              "car": "20123456789010F00100000124",
                              "date_of_issue": "06/10/2026",
                              "date_of_issue_iso": "2026-10-06",
                              "document_type_id": "01",
                              "series": "F001",
                              "number": 124,
                              "party_identity_document_type_id": "6",
                              "party_number": "20100000002",
                              "party_name": "OTRO CLIENTE S.A.C.",
                              "total": 50.0,
                              "total_raw": "50.00"
                            },
                            "system": null,
                            "differences": []
                          }
                        ],
                        "only_in_system": [],
                        "summary": {
                          "sunat_count": 2,
                          "match": 1,
                          "total_mismatch": 0,
                          "not_in_system": 1,
                          "only_in_system": 0,
                          "sunat_total": 168.0,
                          "system_total": 118.0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Aún en proceso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Aún en proceso",
                    "value": {
                      "success": false,
                      "message": "SUNAT aún no termina de generar la propuesta.",
                      "status_code": "02",
                      "status": "En proceso"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sire_type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "sale"
          },
          {
            "name": "sire_ticket",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "20260300000077"
          },
          {
            "name": "period",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "202610",
            "description": "Periodo tributario AAAAMM (obligatorio)"
          }
        ]
      }
    },
    "/api/sire/sale/periods/{sire_period}/accept": {
      "post": {
        "tags": [
          "SIRE"
        ],
        "summary": "Aceptar la propuesta de ventas",
        "operationId": "AceptarPropuestaVentas",
        "description": "Acepta en SUNAT la **propuesta del Registro de Ventas** (RVIE) del periodo `{sire_period}` (AAAAMM). Solo existe para ventas: SUNAT no tiene esta operación para compras (RCE).\n\n**Importante:** aceptar la propuesta la deja como el registro de ventas del periodo ante SUNAT. Revisa antes la comparación.\n\n**Quién puede usarlo:** administradores y usuarios con el nivel de acceso *Resumen de cuentas* (`account_summary`), el mismo que exige el panel en SIRE.\n\n**Formato de respuesta:** estándar `{success, data, message?}` con códigos HTTP reales.\n\nLímite: 5 peticiones por minuto. `data.sunat` es la respuesta de SUNAT tal cual.\n\n**Errores:** `422` periodo inválido. **Errores comunes:** `422` faltan las credenciales SUNAT de la empresa o SUNAT las rechazó; `502` SUNAT respondió con error (su cuerpo va en `sunat_error` y su código en `sunat_code`); `504` no hubo conexión con SUNAT; `403` sin permiso.",
        "responses": {
          "200": {
            "description": "Aceptada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Aceptada",
                    "value": {
                      "success": true,
                      "data": {
                        "period": "202610",
                        "sunat": {
                          "numTicket": "20260300000099"
                        }
                      },
                      "message": "Propuesta del Registro de Ventas aceptada."
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Error de SUNAT",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "e1": {
                    "summary": "Error de SUNAT",
                    "value": {
                      "success": false,
                      "message": "SIRE. SUNAT respondió con error 500: Servicio no disponible",
                      "sunat_code": 500,
                      "sunat_error": {
                        "cod": "500",
                        "msg": "Servicio no disponible"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "sire_period",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "202610"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token del usuario (Obtener token o Configuración → Usuarios)."
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}