{"openapi":"3.1.0","info":{"title":"factura.bo API","description":"\n## Facturación electrónica para Bolivia — API REST\n\nIntegración simplificada con el **SIAT (Sistema Integrado de Administración Tributaria)**\nde Impuestos Nacionales de Bolivia.\n\n### Primeros pasos\n\n1. Obtén tu `API_KEY` en el panel de administración.\n2. Incluye la cabecera `X-API-KEY: <tu_key>` en cada petición protegida.\n3. Llama a `POST /v1/sincronizar` una vez para inicializar tu punto de venta.\n4. Emite facturas con `POST /v1/facturas`.\n\n### Flujo básico\n\n```\nPOST /v1/sincronizar              →  Obtiene CUIS + CUFD del SIAT\nPOST /v1/facturas                 →  Emite y registra la factura\nGET  /v1/facturas/{cuf}           →  Consulta el estado registrado\nGET  /v1/facturas/{cuf}/estado-siat → Verifica en tiempo real ante el SIAT\nPOST /v1/facturas/{cuf}/anular    →  Anula si es necesario\n```\n\n### Sectores soportados (15)\n\nCompra y Venta (1), Alquiler (2), Exportación (3), Libre Consignación (4),\nTurismo (6), Tasa Cero (8), Educativo (11), Servicio Básico (13), ICE (14),\nHotel (16), Hospital (17), Exportación de Servicios (28) y Notas de\nCrédito/Débito (24, 47, 48). Consulta `GET /v1/catalogos/sectores`.\n\n### Modalidades SIAT soportadas\n\n| Modalidad | Descripción | Requiere |\n|-----------|-------------|---------|\n| **Electrónica en Línea** | Firma digital XML con certificado .p12 | Certificado digital |\n| **Computarizada en Línea** | Sin firma, usa código de control numérico | Solo token SIAT |\n\n### Entornos\n\n| Entorno | URL Base |\n|---------|----------|\n| Producción | `https://api.factura.bo` |\n| Sandbox | `https://apisandbox.factura.bo` |\n\n### Respuesta estándar\n\nTodos los endpoints devuelven el mismo formato:\n\n```json\n{\n  \"ok\": true,\n  \"datos\": { ... },\n  \"error\": null,\n  \"timestamp\": \"2024-01-15T14:30:00+00:00\"\n}\n```\n\nEn caso de error:\n\n```json\n{\n  \"ok\": false,\n  \"datos\": null,\n  \"error\": \"Descripción del problema\",\n  \"timestamp\": \"2024-01-15T14:30:00+00:00\"\n}\n```\n","contact":{"name":"SimplifyIT S.R.L.","url":"https://factura.bo/","email":"gm@simplifyit.com.bo"},"version":"1.0.0"},"servers":[{"url":"https://api.factura.bo","description":"Producción"},{"url":"https://apisandbox.factura.bo","description":"Sandbox (SIAT piloto)"}],"paths":{"/v1/facturas":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Compra y Venta (Sector 1)","description":"Emite una factura de compra y venta general.\n\nEs el tipo más utilizado. Aplica para comercios, servicios profesionales\ny cualquier actividad que no tenga un sector específico.\n\n**Ejemplo de respuesta exitosa:**\n```json\n{\n  \"ok\": true,\n  \"datos\": {\n    \"cuf\": \"3001000100001000000001241220000071\",\n    \"numero_factura\": 42,\n    \"estado\": \"EMITIDA\",\n    \"url_pdf\": \"https://storage.googleapis.com/...\",\n    \"url_xml\": \"https://storage.googleapis.com/...\",\n    \"pdf_base64\": \"JVBERi0xLjQK...\",\n    \"respuesta_siat\": { \"transaccion\": true, \"codigoRecepcion\": \"...\" }\n  }\n}\n```","operationId":"emitir_factura_comercial_v1_facturas_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaComercial"}}}},"responses":{"200":{"description":"Factura emitida. `datos.estado` será `EMITIDA` (en línea) u `OFFLINE` (contingencia).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Facturas"],"summary":"Listar facturas emitidas","description":"Devuelve el historial de facturas del cliente autenticado, ordenadas de la más reciente a la más antigua.\n\nPuedes combinar todos los filtros en una sola consulta.","operationId":"listar_facturas_v1_facturas_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"limite","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Cantidad máxima de resultados a devolver.","default":20,"title":"Limite"},"description":"Cantidad máxima de resultados a devolver."},{"name":"desde","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtrar desde esta fecha. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-01`.","title":"Desde"},"description":"Filtrar desde esta fecha. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-01`."},{"name":"hasta","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtrar hasta esta fecha. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-30`.","title":"Hasta"},"description":"Filtrar hasta esta fecha. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-30`."},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtrar por estado: `EMITIDA`, `ANULADA` u `OFFLINE`.","title":"Estado"},"description":"Filtrar por estado: `EMITIDA`, `ANULADA` u `OFFLINE`."},{"name":"nit_cliente","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtrar por NIT o CI del cliente.","title":"Nit Cliente"},"description":"Filtrar por NIT o CI del cliente."}],"responses":{"200":{"description":"Lista de facturas con paginación.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/facturas/exportacion":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Exportación (Sector 3)","description":"Emite una factura para ventas al exterior.\n\nEl cliente puede ser una empresa extranjera (sin NIT boliviano).\nEn ese caso, usa `tipo_documento=0` y `numero_documento=0` en el objeto `cliente`.","operationId":"emitir_factura_exportacion_v1_facturas_exportacion_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaExportacion"}}},"required":true},"responses":{"200":{"description":"Factura de exportación emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/hotel":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Turismo y Hospedaje (Sector 16)","description":"Emite una factura para servicios de alojamiento y turismo.\n\nIncluye información de huéspedes y habitaciones requerida por el SIAT para el sector hotelero.","operationId":"emitir_factura_hotel_v1_facturas_hotel_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaHotel"}}},"required":true},"responses":{"200":{"description":"Factura de hospedaje emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/hospital":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Hospital y Clínica (Sector 17)","description":"Emite una factura para servicios médicos.\n\nCada ítem puede incluir información del médico tratante y la especialidad.","operationId":"emitir_factura_hospital_v1_facturas_hospital_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaHospital"}}},"required":true},"responses":{"200":{"description":"Factura médica emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/educacion":{"post":{"tags":["Facturas"],"summary":"Emitir factura del Sector Educativo (Sector 11)","description":"Emite una factura para servicios de educación formal o de capacitación.\n\nAplica para colegios, institutos, universidades y centros de formación técnica.","operationId":"emitir_factura_educacion_v1_facturas_educacion_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaEducacion"}}},"required":true},"responses":{"200":{"description":"Factura educativa emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/servicio-basico":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Servicio Básico (Sector 13)","description":"Emite una factura para empresas distribuidoras de agua potable, gas natural domiciliario o electricidad.\n\nIncluye campos específicos del sector: número de medidor, consumo del período y descuentos especiales (Ley 1886, Tarifa Dignidad).","operationId":"emitir_factura_servicio_basico_v1_facturas_servicio_basico_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaServicioBasico"}}},"required":true},"responses":{"200":{"description":"Factura de servicio básico emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/alquiler":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Alquiler de Bien Inmueble (Sector 2)","description":"Emite una factura para arrendadores de propiedades (casas, departamentos, locales comerciales).","operationId":"emitir_factura_alquiler_v1_facturas_alquiler_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaAlquilerInmueble"}}},"required":true},"responses":{"200":{"description":"Factura de alquiler emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/turismo":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Servicio Turístico y Hospedaje (Sector 6)","description":"Emite una factura de servicio turístico y hospedaje **sin derecho a crédito fiscal** (Ley 292).\n\nAplica para paquetes turísticos y hospedaje de turistas extranjeros de paso.\nPara hospedaje regular con crédito fiscal usa `POST /v1/facturas/hotel`.","operationId":"emitir_factura_turismo_v1_facturas_turismo_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaTurismo"}}},"required":true},"responses":{"200":{"description":"Factura turística emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/tasa-cero":{"post":{"tags":["Facturas"],"summary":"Emitir factura Tasa Cero (Sector 8)","description":"Emite una factura para ventas exentas de IVA por ley.\n\nAplica para venta de libros (Ley 366), transporte internacional de carga\n(Ley 3249) y otras actividades con tasa cero. No genera débito fiscal.","operationId":"emitir_factura_tasa_cero_v1_facturas_tasa_cero_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaTasaCero"}}},"required":true},"responses":{"200":{"description":"Factura tasa cero emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/ice":{"post":{"tags":["Facturas"],"summary":"Emitir factura Alcanzada por el ICE (Sector 14)","description":"Emite una factura para productos alcanzados por el **Impuesto a los Consumos Específicos**.\n\nAplica para productores e importadores de bebidas alcohólicas, cigarrillos\ny vehículos. Cada ítem detalla sus alícuotas y montos ICE.","operationId":"emitir_factura_ice_v1_facturas_ice_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaIce"}}},"required":true},"responses":{"200":{"description":"Factura ICE emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/exportacion-libre-consignacion":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Exportación en Libre Consignación (Sector 4)","description":"Emite una factura de exportación en libre consignación.\n\nPara mercadería enviada al exterior sin venta en firme. Los ítems aceptan\nel código arancelario `codigo_nandina`.","operationId":"emitir_factura_libre_consignacion_v1_facturas_exportacion_libre_consignacion_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaLibreConsignacion"}}},"required":true},"responses":{"200":{"description":"Factura de libre consignación emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/exportacion-servicios":{"post":{"tags":["Facturas"],"summary":"Emitir factura de Exportación de Servicios (Sector 28)","description":"Emite una factura por servicios prestados desde Bolivia a clientes del exterior.\n\nIdeal para empresas de software, consultoría y BPO que exportan servicios.","operationId":"emitir_factura_exportacion_servicios_v1_facturas_exportacion_servicios_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacturaExportacionServicios"}}},"required":true},"responses":{"200":{"description":"Factura de exportación de servicios emitida correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/lote":{"post":{"tags":["Facturas"],"summary":"Emitir hasta 20 facturas en una sola llamada (éxito parcial)","description":"Emite un lote de facturas con modelo de **éxito parcial**: cada factura se\nprocesa de forma independiente y las que fallan no afectan a las demás\n(una factura fiscal recibida por el SIAT no puede revertirse, solo anularse).\n\n**Cómo leer la respuesta:** `datos.resultados[i]` corresponde a\n`facturas[i]` del request, en el mismo orden. Corrige solo las entradas\ncon `ok: false` y reenvíalas en otro lote.\n\n- Los números de factura se asignan secuencialmente en el orden del array.\n- Los créditos se descuentan únicamente por las facturas exitosas.\n- Si los créditos se agotan a mitad del lote, las restantes fallan con ese error.\n- Cada factura exitosa dispara su webhook `factura.emitida` normalmente.\n- La respuesta **no incluye** `pdf_base64` (sería demasiado pesada): descarga\n  los PDF con `url_pdf` o el enlace permanente `url_publica`.\n\n**Ejemplo de respuesta:**\n```json\n{\n  \"ok\": true,\n  \"datos\": {\n    \"total\": 3, \"exitosas\": 2, \"fallidas\": 1,\n    \"resultados\": [\n      {\"indice\": 0, \"ok\": true, \"cuf\": \"3001...\", \"numero_factura\": 43, \"url_publica\": \"https://...\"},\n      {\"indice\": 1, \"ok\": false, \"error\": \"items.0.codigo_sin: Field required\"},\n      {\"indice\": 2, \"ok\": true, \"cuf\": \"3001...\", \"numero_factura\": 44, \"url_publica\": \"https://...\"}\n    ]\n  }\n}\n```","operationId":"emitir_lote_facturas_v1_facturas_lote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteFacturasRequest"}}},"required":true},"responses":{"200":{"description":"Lote procesado. Revisa `datos.resultados`: las exitosas quedan emitidas aunque otras fallen.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/facturas/{cuf}/anular":{"post":{"tags":["Facturas"],"summary":"Anular una factura emitida","description":"Anula una factura previamente emitida usando su CUF.\n\nLa anulación se informa al SIAT. Solo se pueden anular facturas en estado `EMITIDA`.\nSi anulaste por error, puedes revertirla con `POST /v1/facturas/{cuf}/revertir-anulacion`.\n\n**Motivos de anulación comunes:**\n- `1` — Error en la dirección del emisor\n- `2` — Error en el valor total\n- `3` — Error en el NIT del cliente","operationId":"anular_factura_v1_facturas__cuf__anular_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF) a anular.","title":"Cuf"},"description":"Código Único de Factura (CUF) a anular."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnulacionRequest"}}}},"responses":{"200":{"description":"Factura anulada. El SIAT confirma la anulación.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/facturas/{cuf}/revertir-anulacion":{"post":{"tags":["Facturas"],"summary":"Revertir la anulación de una factura","description":"Revierte una anulación previa: la factura recupera su validez fiscal ante el SIAT.\n\nSolo aplica a facturas en estado `ANULADA` cuya anulación fue confirmada por el SIAT.","operationId":"revertir_anulacion_factura_v1_facturas__cuf__revertir_anulacion_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"CUF de la factura anulada que se desea reactivar.","title":"Cuf"},"description":"CUF de la factura anulada que se desea reactivar."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReversionAnulacionRequest"}}}},"responses":{"200":{"description":"Anulación revertida. La factura vuelve a estar vigente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"409":{"description":"La factura no está anulada."},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/facturas/{cuf}":{"get":{"tags":["Facturas"],"summary":"Obtener una factura por su CUF","description":"Devuelve los datos de una factura específica usando su CUF.\n\nIncluye las URLs para descargar el PDF y XML, y el estado actual (EMITIDA, ANULADA, OFFLINE).","operationId":"obtener_factura_v1_facturas__cuf__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","title":"Cuf"}}],"responses":{"200":{"description":"Datos completos de la factura incluyendo URLs de PDF y XML.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"CUF no encontrado."},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/facturas/{cuf}/estado-siat":{"get":{"tags":["Facturas"],"summary":"Verificar el estado de una factura directamente en el SIAT","description":"Consulta **en tiempo real al SIAT** el estado de recepción de una factura.\n\nA diferencia de `GET /v1/facturas/{cuf}` (que devuelve el estado registrado\nen nuestra base), este endpoint pregunta directamente a Impuestos Nacionales.\nÚsalo para confirmar que una factura fue validada, especialmente después de\nenviar paquetes de contingencia.","operationId":"verificar_estado_factura_siat_v1_facturas__cuf__estado_siat_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF) a verificar.","title":"Cuf"},"description":"Código Único de Factura (CUF) a verificar."},{"name":"debug","in":"query","required":false,"schema":{"type":"boolean","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false,"title":"Debug"},"description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT."}],"responses":{"200":{"description":"Estado devuelto por el SIAT en tiempo real.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/facturas/{cuf}/reenviar-email":{"post":{"tags":["Facturas"],"summary":"Enviar o reenviar la factura por email","description":"Envía (o reenvía) la factura por email con el PDF adjunto y el enlace público.\n\nCasos de uso:\n- El cliente no recibió el email original o lo borró.\n- Quiere recibirla en otra dirección (usa el parámetro `email`).\n- La factura se emitió sin correo y ahora el cliente lo proporcionó.","operationId":"reenviar_email_factura_v1_facturas__cuf__reenviar_email_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF).","title":"Cuf"},"description":"Código Único de Factura (CUF)."},{"name":"email","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Destinatario alternativo. Si se omite, se usa el correo registrado al emitir la factura.","title":"Email"},"description":"Destinatario alternativo. Si se omite, se usa el correo registrado al emitir la factura."}],"responses":{"200":{"description":"Email enviado correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"No hay destinatario: la factura no tiene correo y no se envió el parámetro `email`."},"403":{"description":"Envío de emails deshabilitado: en sandbox nunca se envían, o la cuenta lo tiene desactivado."},"404":{"description":"CUF no encontrado."},"502":{"description":"El servicio de email no aceptó el envío."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/notas":{"post":{"tags":["Notas"],"summary":"Emitir nota de crédito, débito o descuento (Sector 47)","description":"Emite una nota de ajuste que referencia una factura previamente emitida.\n\nUsa este endpoint cuando necesites:\n- **Devolver** mercadería o un servicio ya facturado.\n- **Corregir** un error en el monto de una factura.\n- **Aplicar** un descuento posterior a la emisión.\n\nLa nota no elimina la factura original — la ajusta. Ambos documentos quedan registrados en el SIAT.\n\n**Estructura del detalle** (`items`): por cada producto que ajustes, manda dos\nlíneas con el mismo `nro_item`:\n\n| `codigo_detalle_transaccion` | Qué representa |\n|---|---|\n| `1` | Línea que replica el ítem tal cual está en la factura original (cantidad y precio idénticos). |\n| `2` | Línea propia de esta nota — el ajuste real (para una devolución total, igual a la línea `1`). |\n\n`monto_total_devuelto` y `monto_efectivo_credito_debito` se calculan sobre las\nlíneas tipo `2`, no sobre el total de la factura original. Ejemplo de devolución\ntotal de un ítem de 100 Bs: dos líneas idénticas (`1` y `2`, cantidad 1, precio\n100), `monto_total_devuelto=100.00`, `monto_efectivo_credito_debito=13.00` (13% de\n`monto_total_devuelto`).","operationId":"emitir_nota_v1_notas_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotaCreditoDebito"}}},"required":true},"responses":{"200":{"description":"Nota emitida y registrada en el SIAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/notas/fiscal":{"post":{"tags":["Notas"],"summary":"Emitir nota fiscal de crédito/débito (Sector 24)","description":"Emite una **nota fiscal** de crédito/débito (Sector 24).\n\nVariante de la nota estándar para los casos que el SIAT clasifica como\nnota fiscal. Si tienes dudas de cuál usar, la mayoría de los ajustes\ncorresponden al Sector 47 (`POST /v1/notas`).","operationId":"emitir_nota_fiscal_v1_notas_fiscal_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotaCreditoDebito"}}},"required":true},"responses":{"200":{"description":"Nota fiscal emitida y registrada en el SIAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/notas/ice":{"post":{"tags":["Notas"],"summary":"Emitir nota de crédito/débito con ICE (Sector 48)","description":"Emite una nota de ajuste para facturas de productos alcanzados por el **ICE** (Sector 48).\n\nUsa este endpoint para devolver o ajustar facturas emitidas con\n`POST /v1/facturas/ice`. Cada ítem incluye sus campos ICE.","operationId":"emitir_nota_ice_v1_notas_ice_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotaCreditoDebitoIce"}}},"required":true},"responses":{"200":{"description":"Nota ICE emitida y registrada en el SIAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/contingencia/evento":{"post":{"tags":["Contingencia"],"summary":"Registrar inicio de evento de contingencia","description":"Informa al SIAT que ocurrió un corte o interrupción en tu sistema.\n\n**Flujo de contingencia:**\n1. Llama a este endpoint cuando pierdas conexión.\n2. Emite facturas normalmente con `contingencia: true` en el body.\n3. Cuando se restablezca la conexión, llama a `POST /v1/contingencia/paquete` para enviar las facturas acumuladas.\n\n**Tipos de evento** (catálogo real `eventos_significativos` — consulta\n`GET /v1/catalogos/eventos_significativos` para la lista vigente):\n\n| Código | Descripción |\n|--------|-------------|\n| `1` | Corte del servicio de internet |\n| `2` | Inaccesibilidad al servicio web de la Administración Tributaria |\n| `3` | Ingreso a zonas sin internet por despliegue de punto de venta |\n| `4` | Venta en lugares sin internet |\n| `5` | Virus informático o falla de software |\n| `6` | Cambio de infraestructura de sistema o falla de hardware |\n| `7` | Corte de suministro de energía eléctrica |","operationId":"registrar_evento_contingencia_v1_contingencia_evento_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventoContingenciaRequest"}}},"required":true},"responses":{"200":{"description":"Evento registrado. Puedes emitir con `contingencia: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"El SIAT rechazó el evento."},"403":{"description":"API Key inválida."},"404":{"description":"Punto de venta no sincronizado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/contingencia/paquete":{"post":{"tags":["Contingencia"],"summary":"Enviar paquete de facturas offline al SIAT","description":"Empaqueta y transmite al SIAT todas las facturas emitidas en modo offline durante un evento de contingencia.\n\nLlama a este endpoint una vez que recuperes la conexión con el SIAT. El\nenvío solo confirma que el SIAT *recibió* el paquete — todavía no valida\nfactura por factura. Llamá después a `POST /v1/contingencia/validar-paquete`:\nahí es cuando cada factura pasa de `OFFLINE` a `EMITIDA` y descuenta su\ncrédito (solo las que el SIAT validó individualmente; las observadas\nquedan `OFFLINE` sin cobrarse).","operationId":"enviar_paquete_contingencia_v1_contingencia_paquete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnviarPaqueteRequest"}}},"required":true},"responses":{"200":{"description":"Paquete enviado. El SIAT confirma la recepción.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/contingencia/validar-paquete":{"post":{"tags":["Contingencia"],"summary":"Validar el procesamiento de un paquete enviado","description":"Consulta al SIAT el resultado del procesamiento de un paquete de contingencia.\n\nEl envío del paquete (`POST /v1/contingencia/paquete`) devuelve un `codigo_recepcion`;\nel SIAT procesa el paquete de forma asíncrona y este endpoint confirma si las\nfacturas fueron validadas u observadas.\n\nCada factura que el SIAT valida acá pasa de `OFFLINE` a `EMITIDA` y\ndescuenta un crédito (las observadas —ver `mensajes` en la respuesta—\nquedan `OFFLINE` sin cobrarse). Podés llamar este endpoint varias veces\npara el mismo `codigo_recepcion`: no vuelve a descontar créditos ya\ncobrados.","operationId":"validar_paquete_contingencia_v1_contingencia_validar_paquete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidarPaqueteRequest"}}},"required":true},"responses":{"200":{"description":"Resultado de la validación del paquete en el SIAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/contingencia/eventos":{"get":{"tags":["Contingencia"],"summary":"Consultar eventos significativos registrados","description":"Lista los eventos significativos (cortes, contingencias) registrados ante el SIAT en una fecha.","operationId":"consultar_eventos_contingencia_v1_contingencia_eventos_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"fecha","in":"query","required":true,"schema":{"type":"string","description":"Fecha del evento a consultar. Formato `YYYY-MM-DD`.","title":"Fecha"},"description":"Fecha del evento a consultar. Formato `YYYY-MM-DD`."},{"name":"sucursal","in":"query","required":false,"schema":{"type":"integer","description":"Sucursal a consultar.","default":0,"title":"Sucursal"},"description":"Sucursal a consultar."},{"name":"punto_venta","in":"query","required":false,"schema":{"type":"integer","description":"Punto de venta a consultar.","default":0,"title":"Punto Venta"},"description":"Punto de venta a consultar."},{"name":"debug","in":"query","required":false,"schema":{"type":"boolean","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false,"title":"Debug"},"description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT."}],"responses":{"200":{"description":"Eventos significativos registrados en la fecha consultada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sincronizar":{"post":{"tags":["Sincronización"],"summary":"Inicializar CUIS y CUFD para un punto de venta","description":"Solicita al SIAT los códigos **CUIS** y **CUFD** y los guarda en base de datos.\n\n**¿Cuándo llamar?**\n- Al dar de alta un nuevo punto de venta.\n- Todos los días antes de facturar (el CUFD vence a medianoche).\n- Después de un corte prolongado.\n\nEl `codigo_sistema` lo asigna el SIAT cuando registras tu sistema de facturación.\nConsulta con tu administrador tributario.","operationId":"sincronizar_v1_sincronizar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SincronizarRequest"}}},"required":true},"responses":{"200":{"description":"Sincronización exitosa. CUFD guardado y válido por 24 horas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Falta configuración del token SIAT."},"404":{"description":"Empresa no registrada."},"502":{"description":"El SIAT no respondió."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/sincronizar/catalogos":{"post":{"tags":["Sincronización"],"summary":"Descargar y actualizar catálogos del SIAT","description":"Descarga y almacena los catálogos parametricos del SIAT para tu empresa.\n\n**¿Qué se descarga?** Los 18 catálogos del SIAT: actividades económicas,\nleyendas, métodos de pago, tipos de documento de identidad, productos y\nservicios, motivos de anulación, eventos significativos, países, monedas,\nunidades de medida, tipos de emisión, tipos de factura, tipos de punto de\nventa, tipos de habitación, documento sector y fecha/hora oficial.\n\n**¿Cuándo llamar?** Al dar de alta la empresa y cada vez que el SIAT actualice sus catálogos (aprox. mensual).\n\nUna vez sincronizados, consulta los catálogos con `GET /v1/catalogos/{nombre}`.","operationId":"sincronizar_catalogos_v1_sincronizar_catalogos_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SincronizarRequest"}}},"required":true},"responses":{"200":{"description":"Catálogos actualizados exitosamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado."},"502":{"description":"Error al consultar el SIAT."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/catalogos/sectores":{"get":{"tags":["Catálogos"],"summary":"Tipos de factura disponibles (sectores SIAT)","description":"Devuelve todos los tipos de documento (sectores) que esta API soporta,\njunto con el endpoint correspondiente para emitir cada uno.\n\nSi tu actividad no aparece en la lista, usa el sector general `Compra y Venta` (Sector 1).","operationId":"catalogos_sectores_v1_catalogos_sectores_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}}}}},"/v1/catalogos/{nombre}":{"get":{"tags":["Catálogos"],"summary":"Consultar un catálogo SIAT específico","description":"Devuelve los datos de un catálogo del SIAT previamente sincronizado.\n\n**Catálogos disponibles:** `actividades`, `actividades_documento_sector`,\n`eventos_significativos`, `fecha_hora`, `leyendas`, `mensajes_servicios`,\n`metodos_pago`, `motivos_anulacion`, `paises`, `productos_servicios`,\n`tipos_documento_identidad`, `tipos_documento_sector`, `tipos_emision`,\n`tipos_factura`, `tipos_habitacion`, `tipos_moneda`, `tipos_punto_venta`,\n`unidades_medida`.\n\nSi el catálogo no está disponible, ejecuta primero `POST /v1/sincronizar/catalogos`.","operationId":"obtener_catalogo_v1_catalogos__nombre__get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"nombre","in":"path","required":true,"schema":{"type":"string","title":"Nombre"}}],"responses":{"200":{"description":"Datos del catálogo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Catálogo no encontrado o no sincronizado."},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/operaciones/puntos-venta":{"post":{"tags":["Operaciones"],"summary":"Registrar un nuevo punto de venta en el SIAT","description":"Registra un nuevo punto de venta ante el SIAT.\n\nDebe hacerse **una sola vez** por cada caja o terminal de facturación.\nDespués del registro, usa el código asignado en `emisor.punto_venta` al emitir facturas.\n\nRequiere que la sucursal ya esté sincronizada con `POST /v1/sincronizar`.","operationId":"registrar_punto_venta_v1_operaciones_puntos_venta_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PuntoVentaRequest"}}}},"responses":{"200":{"description":"Punto de venta registrado. El SIAT asigna un código.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Operaciones"],"summary":"Consultar puntos de venta registrados","description":"Consulta al SIAT los puntos de venta registrados para una sucursal.","operationId":"consultar_puntos_venta_v1_operaciones_puntos_venta_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"sucursal","in":"query","required":false,"schema":{"type":"integer","description":"Código de sucursal a consultar. Usa `0` para la casa matriz.","default":0,"title":"Sucursal"},"description":"Código de sucursal a consultar. Usa `0` para la casa matriz."},{"name":"debug","in":"query","required":false,"schema":{"type":"boolean","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false,"title":"Debug"},"description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT."}],"responses":{"200":{"description":"Lista de puntos de venta registrados en el SIAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"404":{"description":"Punto de venta no sincronizado"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/operaciones/puntos-venta/{codigo_punto_venta}":{"delete":{"tags":["Operaciones"],"summary":"Cerrar (dar de baja) un punto de venta","description":"Cierra definitivamente un punto de venta registrado en el SIAT.\n\nUn punto de venta cerrado no puede volver a usarse para emitir; si lo\nnecesitas de nuevo, registra uno nuevo con `POST /v1/operaciones/puntos-venta`.","operationId":"cerrar_punto_venta_v1_operaciones_puntos_venta__codigo_punto_venta__delete","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"codigo_punto_venta","in":"path","required":true,"schema":{"type":"integer","description":"Código del punto de venta a cerrar (asignado por el SIAT al registrarlo).","title":"Codigo Punto Venta"},"description":"Código del punto de venta a cerrar (asignado por el SIAT al registrarlo)."},{"name":"sucursal","in":"query","required":false,"schema":{"type":"integer","description":"Sucursal a la que pertenece el punto de venta.","default":0,"title":"Sucursal"},"description":"Sucursal a la que pertenece el punto de venta."},{"name":"debug","in":"query","required":false,"schema":{"type":"boolean","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false,"title":"Debug"},"description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT."}],"responses":{"200":{"description":"Punto de venta cerrado en el SIAT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado"},"400":{"description":"Datos inválidos o falta configuración"},"402":{"description":"Créditos de facturación agotados"},"403":{"description":"API Key inválida o cliente inactivo"},"502":{"description":"El SIAT no respondió o devolvió un error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/nit/validar":{"post":{"tags":["Utilidades"],"summary":"Verificar si un NIT es válido ante el SIAT","description":"Verifica en tiempo real si un NIT está habilitado en el SIAT para recibir facturas.\n\nÚtil para validar el NIT del cliente **antes de emitir** una factura, evitando rechazos del SIAT.\n\n**Respuesta de ejemplo:**\n```json\n{\n  \"ok\": true,\n  \"datos\": {\n    \"nit\": 12345678,\n    \"valido\": true,\n    \"descripcion\": \"NIT ACTIVO\"\n  }\n}\n```","operationId":"validar_nit_v1_nit_validar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidarNitRequest"}}},"required":true},"responses":{"200":{"description":"Resultado de la validación. Ver campo `datos.valido`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Punto de venta no sincronizado."},"502":{"description":"El SIAT no respondió."},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/auth/solicitar-acceso":{"post":{"tags":["Autenticación"],"summary":"Solicita un link de inicio de sesión de Firebase y delega el envío de correo a Odoo","description":"Recibe un correo y solicita el enlace de inicio de sesión sin contraseña de Firebase.\nLuego, reenvía la petición a Odoo para que este envíe el correo con\nsu propio formato y SMTP.\n\nFirebase genera el link pero **no manda nada** (`returnOobLink`), así que el\ncorreo sale del mismo Odoo que ya manda la API Key demo: mismo remitente,\nmisma plantilla, mismo rastro comercial.","operationId":"solicitar_acceso_v1_auth_solicitar_acceso_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolicitudAcceso"}}},"required":true},"responses":{"200":{"description":"Enlace generado y enviado a Odoo exitosamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Correo o dominio de redirección inválido."},"502":{"description":"Error al comunicarse con Firebase o con Odoo."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/registro/prueba":{"post":{"tags":["Utilidades"],"summary":"Alta de cuenta de prueba para un usuario de app.factura.bo","description":"Da de alta la cuenta de prueba del usuario autenticado y devuelve su NIT demo.\n\nEl usuario ya se registró en Firebase (link por correo, así que el correo está\nverificado); acá se le crea el tenant demo en Odoo —que es quien emite el\n`api_token`, lleva el CRM y los créditos— y se guarda el mapeo `uid → NIT`\nque después usa `get_tenant` en cada petición de la app.\n\nEs idempotente: si el usuario ya tiene cuenta, devuelve la misma sin crear otra.","operationId":"registro_prueba_v1_registro_prueba_post","responses":{"200":{"description":"Cuenta de prueba lista (o la que el usuario ya tenía).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Falta el ID token de Firebase o no es válido."},"502":{"description":"No se pudo crear la cuenta en el backoffice."}},"security":[{"HTTPBearer":[]}]}},"/v1/cuenta":{"get":{"tags":["Utilidades"],"summary":"Estado de tu cuenta: créditos y configuración","description":"Devuelve el estado actual de tu cuenta: créditos disponibles, modalidad y estado de activación.\n\nÚsalo para verificar cuántas facturas te quedan antes de recargar.","operationId":"estado_cuenta_v1_cuenta_get","responses":{"200":{"description":"Datos de la cuenta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"403":{"description":"API Key inválida."}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/cuenta/api-key":{"get":{"tags":["Utilidades"],"summary":"Ver la API Key de tu cuenta","description":"Devuelve la API Key de tu cuenta, para integrarla en tu propio sistema.\n\nLa app no la necesita para emitir —autentica con tu sesión de Firebase—,\nasí que se pide a demanda y no viaja en cada carga de pantalla. Es la misma\nllave que llega por correo al crear la cuenta.\n\nSolo el propietario: un cajero puede emitir, pero no llevarse la llave que\nda acceso total a la cuenta desde cualquier lado.","operationId":"ver_api_key_v1_cuenta_api_key_get","responses":{"200":{"description":"La API Key de la cuenta y dónde usarla.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"403":{"description":"No sos el propietario de la cuenta."}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/cuenta/api-key/regenerar":{"post":{"tags":["Utilidades"],"summary":"Regenerar la API Key de tu cuenta","description":"Cambia la API Key de tu cuenta por una nueva.\n\n**La anterior deja de servir inmediatamente**: cualquier integración que la\nesté usando se corta hasta que pegues la nueva. Úsalo si se te filtró.\n\nQuien manda es Odoo, que es donde vive la llave; este endpoint solo se la\npide y devuelve el resultado. Si algo falla en el camino, la llave vieja\nsigue siendo la válida.","operationId":"regenerar_api_key_v1_cuenta_api_key_regenerar_post","responses":{"200":{"description":"La API Key nueva. La anterior deja de funcionar en el acto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"403":{"description":"No sos el propietario de la cuenta."},"502":{"description":"No se pudo regenerar; la llave anterior sigue vigente."}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/cuenta/solicitar-produccion":{"post":{"tags":["Utilidades"],"summary":"Pedir el paso de cuenta de prueba a cuenta real","description":"Registra que querés pasar de la cuenta de prueba a una con valor legal.\n\n**No activa nada por sí solo, y eso es a propósito**: una cuenta real necesita\ntu certificado digital `.p12` y tu token del SIAT, que se sacan del portal del\nSIN y nadie puede generar por vos. Esto abre la conversación con el equipo,\nque te guía por ese trámite y activa la cuenta cuando tengas las dos cosas.\n\nSolo desde el portal: depende del ID token de Firebase para saber a qué\ncorreo contactar, así que una integración por `X-API-KEY` recibe 401.","operationId":"solicitar_produccion_v1_cuenta_solicitar_produccion_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolicitudProduccionRequest"}}},"required":true},"responses":{"200":{"description":"Solicitud registrada; alguien del equipo te contacta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"403":{"description":"No sos el propietario de la cuenta."},"502":{"description":"No se pudo registrar la solicitud."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/cuenta/consumo":{"get":{"tags":["Utilidades"],"summary":"Historial de consumo de créditos","description":"Cuántos créditos consumiste en un período, agrupados por día o por mes —\na diferencia de `GET /v1/cuenta` (que solo da el saldo actual), esto te\ndeja entender tu ritmo de consumo.\n\nCada factura o nota **emitida en línea** (no offline/contingencia,\nesas no descuentan crédito hasta que su paquete es validado) cuenta como\nuna unidad consumida, sin importar el sector.","operationId":"consumo_creditos_v1_cuenta_consumo_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"desde","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Desde esta fecha. Formato `YYYY-MM-DD`. Por defecto, los últimos 30 días.","title":"Desde"},"description":"Desde esta fecha. Formato `YYYY-MM-DD`. Por defecto, los últimos 30 días."},{"name":"hasta","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hasta esta fecha. Formato `YYYY-MM-DD`. Por defecto, hoy.","title":"Hasta"},"description":"Hasta esta fecha. Formato `YYYY-MM-DD`. Por defecto, hoy."},{"name":"agrupar_por","in":"query","required":false,"schema":{"type":"string","pattern":"^(dia|mes)$","description":"`dia` o `mes`.","default":"dia","title":"Agrupar Por"},"description":"`dia` o `mes`."}],"responses":{"200":{"description":"Consumo de créditos agrupado por día o por mes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/estado":{"get":{"tags":["Utilidades"],"summary":"Estado de la API y del SIAT en tiempo real","description":"Devuelve el estado operativo de la API **y del SIAT de Impuestos Nacionales**\n(producción y piloto): `OPERATIVO`, `DEGRADADO` o `CAIDO`, con uptime de los\núltimos 30 días. El SIAT se sondea cada 5 minutos con `verificarComunicacion`.\n\nNo requiere autenticación y es gratuito. Versión web: [/estado](/estado).\nPara reaccionar automáticamente a caídas, suscríbete a los eventos webhook\n`siat.caido` y `siat.recuperado`.","operationId":"health_check_v1_estado_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/guia":{"get":{"tags":["Utilidades"],"summary":"Guía de integración en formato HTML","description":"Devuelve la guía de integración completa (quickstart, sectores, ejemplos)\nrenderizada como página web. No requiere autenticación.\n\nLa misma referencia interactiva está disponible en `/docs` (Swagger) y `/redoc`.","operationId":"guia_integracion_guia_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/f/{cuf}":{"get":{"tags":["Acceso público"],"summary":"Página pública de verificación de una factura","description":"Página web pública y permanente de una factura, para compartir con el\ncliente final. **No requiere autenticación**: el CUF actúa como token.\n\nMuestra los datos de verificación y permite descargar el PDF y el XML\ncon `GET /f/{cuf}/pdf` y `GET /f/{cuf}/xml`.","operationId":"pagina_publica_factura_f__cuf__get","parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF).","title":"Cuf"},"description":"Código Único de Factura (CUF)."}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/f/{cuf}/pdf":{"get":{"tags":["Acceso público"],"summary":"Descargar el PDF de una factura (público)","description":"Redirige a una URL firmada fresca (10 minutos de vigencia) para descargar\nla representación gráfica en PDF. **No requiere autenticación.**\n\nEl enlace `/f/{cuf}/pdf` es permanente y siempre entrega el archivo,\naunque las URLs firmadas anteriores hayan expirado.","operationId":"descargar_pdf_publico_f__cuf__pdf_get","parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF).","title":"Cuf"},"description":"Código Único de Factura (CUF)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/f/{cuf}/xml":{"get":{"tags":["Acceso público"],"summary":"Descargar el XML fiscal de una factura (público)","description":"Redirige a una URL firmada fresca (10 minutos de vigencia) para descargar\nel XML fiscal del documento. **No requiere autenticación.**","operationId":"descargar_xml_publico_f__cuf__xml_get","parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF).","title":"Cuf"},"description":"Código Único de Factura (CUF)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/f/{cuf}/ticket":{"get":{"tags":["Acceso público"],"summary":"Descargar el ticket de 80mm de una factura (público)","description":"Redirige a una URL firmada fresca (10 minutos de vigencia) para descargar\nla representación en **ticket de 80mm** para impresoras térmicas.\n**No requiere autenticación.**\n\nDisponible para facturas emitidas después de julio 2026; las anteriores\nsolo tienen el formato A4 (`/f/{cuf}/pdf`).","operationId":"descargar_ticket_publico_f__cuf__ticket_get","parameters":[{"name":"cuf","in":"path","required":true,"schema":{"type":"string","description":"Código Único de Factura (CUF).","title":"Cuf"},"description":"Código Único de Factura (CUF)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reportes/libro-ventas":{"get":{"tags":["Reportes"],"summary":"Libro de Ventas IVA del mes (CSV formato RCV)","description":"Genera el **Libro de Ventas IVA** del período en CSV con las columnas del\nRegistro de Compras y Ventas (RCV) del SIAT, listo para revisión del contador.\n\n- Facturas `EMITIDA` van con estado `V` (válida); `ANULADA` con estado `A`.\n- Exportaciones (sectores 3, 4, 28) van en la columna de exportaciones exentas.\n- Tasa cero (sector 8) va en su columna, sin débito fiscal.\n- El débito fiscal se calcula al 13% sobre la base sujeta a IVA.\n\nEl archivo se abre directo en Excel (UTF-8 con BOM, separado por `;`).","operationId":"libro_ventas_v1_reportes_libro_ventas_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"gestion","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":2020,"description":"Año de la gestión. Ejemplo: `2026`.","title":"Gestion"},"description":"Año de la gestión. Ejemplo: `2026`."},{"name":"mes","in":"query","required":true,"schema":{"type":"integer","maximum":12,"minimum":1,"description":"Mes del período (1-12).","title":"Mes"},"description":"Mes del período (1-12)."}],"responses":{"200":{"description":"Archivo CSV con el detalle de ventas del período.","content":{"application/json":{"schema":{}},"text/csv":{}}},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/reportes/respaldo":{"get":{"tags":["Reportes"],"summary":"Respaldo mensual: ZIP con todos los XML y PDF del período","description":"Descarga en un solo ZIP todos los documentos fiscales del mes, para el\nresguardo documental que exige la normativa.\n\nEstructura interna: `{numero_factura}_{cuf}.xml` y `.pdf`.\nMáximo 1000 facturas por request; para volúmenes mayores descarga por mes.","operationId":"respaldo_mensual_v1_reportes_respaldo_get","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"gestion","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":2020,"description":"Año de la gestión.","title":"Gestion"},"description":"Año de la gestión."},{"name":"mes","in":"query","required":true,"schema":{"type":"integer","maximum":12,"minimum":1,"description":"Mes del período (1-12).","title":"Mes"},"description":"Mes del período (1-12)."},{"name":"formato","in":"query","required":false,"schema":{"type":"string","pattern":"^(xml|pdf|ambos)$","description":"Qué incluir: `xml`, `pdf` o `ambos`.","default":"ambos","title":"Formato"},"description":"Qué incluir: `xml`, `pdf` o `ambos`."}],"responses":{"200":{"description":"Archivo ZIP con los documentos fiscales del mes.","content":{"application/json":{"schema":{}},"application/zip":{}}},"404":{"description":"No hay facturas en el período."},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes":{"post":{"tags":["Administración"],"summary":"Crear o actualizar un cliente","description":"Crea o actualiza la configuración de un cliente en el sistema.\n\nEste endpoint está destinado a sistemas de backoffice (Odoo, panel de administración).\n**No debe exponerse públicamente.**\n\n**Operaciones que realiza:**\n- Guarda o actualiza el `api_token`, `token_siat` y `modalidad`.\n- Incrementa el saldo de créditos (facturas disponibles).\n- Si se incluye `p12_base64`, sube el certificado digital a Secret Manager.","operationId":"admin_crear_cliente_v1_admin_clientes_post","parameters":[{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClienteAdmin"}}}},"responses":{"200":{"description":"Cliente aprovisionado correctamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes/{nit}":{"get":{"tags":["Administración"],"summary":"Consultar datos de un cliente","description":"Devuelve la información de un cliente registrado.\n\nLos campos sensibles (`api_token`, `token_siat`) se omiten de la respuesta por seguridad.","operationId":"admin_obtener_cliente_v1_admin_clientes__nit__get","parameters":[{"name":"nit","in":"path","required":true,"schema":{"type":"integer","title":"Nit"}},{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"responses":{"200":{"description":"Datos del cliente (sin tokens sensibles).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"404":{"description":"Cliente no encontrado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes/{nit}/puntos-venta/{sucursal}/{punto_venta}/cuis":{"delete":{"tags":["Administración"],"summary":"Forzar renovación del CUIS/CUFD de un punto de venta","description":"Descarta el CUIS/CUFD guardado para este punto de venta.\n\n`POST /v1/sincronizar` ya se autorrecupera solo cuando el SIAT rechaza el\nCUIS guardado (código 913/929 — token o codigo_sistema rotado, o\nvencimiento anual del CUIS). Este endpoint es la vía de escape manual\npara forzar lo mismo bajo demanda (o diagnosticar otros casos), sin\nnecesidad de tocar Firestore directamente.","operationId":"admin_forzar_renovacion_cuis_v1_admin_clientes__nit__puntos_venta__sucursal___punto_venta__cuis_delete","parameters":[{"name":"nit","in":"path","required":true,"schema":{"type":"integer","title":"Nit"}},{"name":"sucursal","in":"path","required":true,"schema":{"type":"integer","title":"Sucursal"}},{"name":"punto_venta","in":"path","required":true,"schema":{"type":"integer","title":"Punto Venta"}},{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"responses":{"200":{"description":"CUIS/CUFD descartados; el próximo /v1/sincronizar pide credenciales nuevas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"404":{"description":"Punto de venta no sincronizado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes/{nit}/puntos-venta":{"get":{"tags":["Administración"],"summary":"Diagnóstico de puntos de venta sincronizados (sin datos sensibles)","description":"Lista, para soporte, el estado de sincronización de cada punto de venta\nde un cliente: si tiene CUIS/CUFD guardado, si el CUFD sigue vigente\n(menos de 24h desde la última sincronización) y el último número de\nfactura correlativo.\n\nPor seguridad **no devuelve** los valores crudos de `cuis`, `cufd` ni\n`codigo_control` — son credenciales de sesión frente al SIAT, no datos\nde negocio, y no aportan nada al diagnóstico. Si un punto de venta quedó\ncon credenciales inválidas, usa\n`DELETE /v1/admin/clientes/{nit}/puntos-venta/{sucursal}/{punto_venta}/cuis`\npara forzar su renovación.","operationId":"admin_listar_puntos_venta_v1_admin_clientes__nit__puntos_venta_get","parameters":[{"name":"nit","in":"path","required":true,"schema":{"type":"integer","title":"Nit"}},{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"responses":{"200":{"description":"Estado de sincronización por sucursal/punto de venta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"404":{"description":"Cliente no encontrado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes/{nit}/catalogos":{"get":{"tags":["Administración"],"summary":"Estado de sincronización de catálogos SIAT (sin volcar los datos)","description":"Lista, para soporte, cuáles de los 18 catálogos paramétricos del SIAT\nestán sincronizados para este cliente y cuándo se actualizaron por\núltima vez (`POST /v1/sincronizar/catalogos`).\n\nNo devuelve el contenido de los catálogos (pueden ser listas largas y no\naportan al diagnóstico) — solo nombre y fecha. Incluye los 18 catálogos\nconocidos aunque nunca se hayan sincronizado, para detectar de un vistazo\ncuáles faltan.","operationId":"admin_listar_catalogos_v1_admin_clientes__nit__catalogos_get","parameters":[{"name":"nit","in":"path","required":true,"schema":{"type":"integer","title":"Nit"}},{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"responses":{"200":{"description":"Fecha de última actualización por catálogo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"404":{"description":"Cliente no encontrado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes/{nit}/errores":{"get":{"tags":["Administración"],"summary":"Últimos errores del SIAT para un cliente (Cloud Logging)","description":"Para soporte: trae los últimos rechazos/errores del SIAT de un cliente\ndirectamente desde Cloud Logging (nunca desde Firestore), así se puede\ndiagnosticar un \"no puedo emitir\" sin pedirle datos al cliente.\n\nNo requiere que el NIT tenga un tenant sincronizado — busca directo en logs.","operationId":"admin_listar_errores_v1_admin_clientes__nit__errores_get","parameters":[{"name":"nit","in":"path","required":true,"schema":{"type":"integer","title":"Nit"}},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Cantidad máxima de eventos a devolver.","default":20,"title":"Limite"},"description":"Cantidad máxima de eventos a devolver."},{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"responses":{"200":{"description":"Últimos eventos de error registrados para este NIT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clientes/{nit}/facturas":{"get":{"tags":["Administración"],"summary":"Listar documentos emitidos por un cliente en un mes","description":"Devuelve el detalle informativo de los documentos del mes, para consumo del\nbackoffice (Odoo). Incluye facturas, notas y anuladas, con su estado actual.","operationId":"admin_listar_facturas_v1_admin_clientes__nit__facturas_get","parameters":[{"name":"nit","in":"path","required":true,"schema":{"type":"integer","title":"Nit"}},{"name":"gestion","in":"query","required":true,"schema":{"type":"integer","maximum":2100,"minimum":2020,"description":"Año del período. Ejemplo: `2026`.","title":"Gestion"},"description":"Año del período. Ejemplo: `2026`."},{"name":"mes","in":"query","required":true,"schema":{"type":"integer","maximum":12,"minimum":1,"description":"Mes del período (1-12).","title":"Mes"},"description":"Mes del período (1-12)."},{"name":"x-admin-key","in":"header","required":true,"schema":{"type":"string","description":"Llave secreta de administración (`ADMIN_SECRET_KEY`).","title":"X-Admin-Key"},"description":"Llave secreta de administración (`ADMIN_SECRET_KEY`)."}],"responses":{"200":{"description":"Documentos del período (facturas y notas, incluye anuladas).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"401":{"description":"Llave de administración inválida."},"404":{"description":"Cliente no encontrado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar webhooks registrados","description":"Lista tus webhooks. El secreto nunca se devuelve: si lo perdiste, rota con `POST /v1/webhooks/{id}/rotar`.","operationId":"listar_webhooks_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]},"post":{"tags":["Webhooks"],"summary":"Registrar un webhook","description":"Registra una URL de tu servidor para recibir eventos en tiempo real.\n\n**Guarda el `secreto` devuelto** (`whsec_...`): lo necesitas para verificar\nla firma de cada entrega y solo se muestra en esta respuesta.\n\n**Verificación de la firma** (en tu servidor):\n```python\nimport base64, hashlib, hmac\n\ndef verificar(secreto, headers, cuerpo_crudo):\n    llave = base64.b64decode(secreto.split(\"_\", 1)[1])\n    contenido = f\"{headers['webhook-id']}.{headers['webhook-timestamp']}.{cuerpo_crudo}\"\n    esperada = \"v1,\" + base64.b64encode(\n        hmac.new(llave, contenido.encode(), hashlib.sha256).digest()).decode()\n    return hmac.compare_digest(esperada, headers[\"webhook-signature\"])\n```\n\nLas entregas fallidas se reintentan automáticamente con backoff exponencial.\nUsa el header `Webhook-Id` para descartar duplicados.","operationId":"registrar_webhook_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"}}},"required":true},"responses":{"200":{"description":"Webhook creado. Guarda el `secreto`: se muestra solo aquí.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"URL inválida."},"403":{"description":"API Key inválida."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}]}},"/v1/webhooks/{webhook_id}":{"delete":{"tags":["Webhooks"],"summary":"Eliminar un webhook","description":"Elimina el webhook. Las entregas pendientes en cola se descartan al ejecutarse.","operationId":"eliminar_webhook_v1_webhooks__webhook_id__delete","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Webhook no encontrado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/rotar":{"post":{"tags":["Webhooks"],"summary":"Rotar el secreto de un webhook","description":"Genera un secreto nuevo (invalida el anterior de inmediato). Actualiza tu servidor antes de rotar.","operationId":"rotar_secreto_webhook_v1_webhooks__webhook_id__rotar_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Webhook no encontrado."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/probar":{"post":{"tags":["Webhooks"],"summary":"Enviar un evento de prueba","description":"Envía un evento `webhook.prueba` firmado, de forma **síncrona**, y devuelve\nla respuesta de tu servidor. Úsalo para validar tu verificación de firma.","operationId":"probar_webhook_v1_webhooks__webhook_id__probar_post","security":[{"APIKeyHeader":[]},{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"404":{"description":"Webhook no encontrado."},"502":{"description":"Tu servidor no respondió 2xx."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ExchangeRate":{"get":{"tags":["Tipo de cambio"],"summary":"Tipo de cambio oficial del Banco Central de Bolivia","description":"Devuelve el tipo de cambio oficial publicado por el **Banco Central de Bolivia**\n(https://www.bcb.gob.bo/). Se actualiza automáticamente cada noche a las 00:00\nhora Bolivia (UTC-4).\n\n**Campos devueltos:**\n- `usd_bob`: bolivianos por 1 dólar estadounidense (USD → BOB)\n- `ufv_bob`: valor en bolivianos de 1 UFV (Unidad de Fomento a la Vivienda)\n- `fecha_actualizacion`: fecha y hora en que se obtuvo el dato (ISO 8601 UTC)\n\nEste endpoint es **público y gratuito**, no requiere autenticación.","operationId":"get_exchange_rate_ExchangeRate_get","responses":{"200":{"description":"USD/BOB y UFV actualizados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"503":{"description":"Datos no disponibles todavía (el scraper aún no ha corrido)."}}}},"/ExchangeRate/history":{"get":{"tags":["Tipo de cambio"],"summary":"Listado del historial de tipos de cambio","description":"Retorna una lista de tipos de cambio históricos ordenados desde el más reciente al más antiguo.","operationId":"get_exchange_rate_history_ExchangeRate_history_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Número de registros históricos a retornar.","default":30,"title":"Limit"},"description":"Número de registros históricos a retornar."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ExchangeRate/history/{fecha}":{"get":{"tags":["Tipo de cambio"],"summary":"Tipo de cambio de una fecha específica","description":"Busca el tipo de cambio oficial del BCB registrado para una fecha específica (formato YYYY-MM-DD).","operationId":"get_exchange_rate_by_date_ExchangeRate_history__fecha__get","parameters":[{"name":"fecha","in":"path","required":true,"schema":{"type":"string","description":"Fecha en formato YYYY-MM-DD. Ejemplo: 2026-06-29","title":"Fecha"},"description":"Fecha en formato YYYY-MM-DD. Ejemplo: 2026-06-29"}],"responses":{"200":{"description":"Tipo de cambio de la fecha solicitada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaAPI"}}}},"400":{"description":"Formato de fecha inválido. Debe usar YYYY-MM-DD."},"404":{"description":"No se encontraron datos para la fecha especificada."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AnulacionRequest":{"properties":{"motivo":{"type":"integer","title":"Motivo","description":"Código de motivo de anulación según catálogo SIAT (`GET /v1/catalogos/motivos_anulacion`). `1`=Factura mal emitida, `2`=Nota crédito-débito mal emitida, `3`=Datos de emisión incorrectos, `4`=Factura o nota crédito-débito devuelta."},"sucursal":{"type":"integer","title":"Sucursal","description":"Sucursal donde fue emitida la factura.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Punto de venta donde fue emitida la factura.","default":0},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["motivo"],"title":"AnulacionRequest"},"Cliente":{"properties":{"tipo_documento":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Tipo Documento","description":"Código del tipo de documento de identidad del cliente según catálogo SIAT: `1`=Cédula de Identidad (CI), `2`=Cédula de Identidad de Extranjero (CEX), `3`=Pasaporte (PAS), `4`=Otro Documento (OD), `5`=NIT.","default":1},"numero_documento":{"type":"string","title":"Numero Documento","description":"Número de NIT, CI o pasaporte del cliente. Usa `0` para consumidor final sin documento."},"razon_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social","description":"Nombre completo o razón social del cliente. Requerido cuando `tipo_documento=5` (NIT)."},"complemento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Complemento","description":"Complemento del CI (letra + número). Ejemplo: `1A`. Solo aplica para `tipo_documento=1`."},"correo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correo","description":"Email del cliente. Si se envía, se entregará una copia digital de la factura."},"codigo_pais":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Pais","description":"Código de país del comprador según catálogo SIAT. Solo para facturas de exportación."},"direccion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direccion","description":"Dirección del comprador en el exterior. Solo para facturas de exportación."}},"type":"object","required":["numero_documento"],"title":"Cliente"},"ClienteAdmin":{"properties":{"nit":{"type":"integer","title":"Nit","description":"NIT de la empresa a aprovisionar."},"api_token":{"type":"string","title":"Api Token","description":"Token de API que se asignará al cliente."},"creditos_iniciales":{"type":"integer","minimum":0.0,"title":"Creditos Iniciales","description":"Cantidad de facturas a acreditar. Se suma al saldo existente."},"p12_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P12 Base64","description":"Certificado digital .p12 codificado en Base64. Solo para modalidad electrónica."},"token_siat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Siat","description":"Token SIAT (apiKey) de Impuestos Nacionales asignado a la empresa."},"modalidad":{"type":"integer","title":"Modalidad","description":"Modalidad de facturación: `1`=Electrónica en Línea, `2`=Computarizada en Línea.","default":1},"activo":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Activo","description":"Habilita o suspende la cuenta. Si se omite, no se modifica (los clientes nuevos se crean activos)."},"envio_email":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Envio Email","description":"Envío automático de facturas por email. Si se omite, no se modifica (los clientes nuevos se crean con `true`). Nunca se envían emails en sandbox."},"envio_whatsapp":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Envio Whatsapp","description":"Envío de facturas por WhatsApp (reservado, aún no operativo). Si se omite, no se modifica (los clientes nuevos se crean con `false`)."},"razon_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social","description":"Razón social del emisor, tal como figura en el SIAT. Aparece en el PDF."},"direccion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direccion","description":"Dirección de la casa matriz. Aparece en el PDF."},"municipio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio","description":"Municipio del emisor. Aparece en el PDF."},"telefono":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefono","description":"Teléfono del emisor. Aparece en el PDF."},"es_mockup":{"type":"boolean","title":"Es Mockup","description":"Si es `true`, el cliente se guarda en la colección demo (`clientes_siat_test`), totalmente aislada de los clientes reales — ver `es_mock` en la emisión. Nunca toca al SIAT real, sin importar `token_siat`.","default":false}},"type":"object","required":["nit","api_token","creditos_iniciales"],"title":"ClienteAdmin"},"Emisor":{"properties":{"sucursal":{"type":"integer","title":"Sucursal","description":"Código de sucursal registrado en el SIAT. Usa `0` para la casa matriz.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Código de punto de venta registrado en el SIAT. Usa `0` si solo tienes uno.","default":0},"actividad_economica":{"type":"string","title":"Actividad Economica","description":"Código de actividad económica CAEB de 6 dígitos. Ejemplo: `620000` para Programación."}},"type":"object","required":["actividad_economica"],"title":"Emisor"},"EntradaLote":{"properties":{"sector":{"type":"integer","title":"Sector","description":"Código de sector SIAT de esta factura. Por defecto `1` (Compra y Venta). Sectores válidos: 1, 2, 3, 4, 6, 8, 11, 13, 14, 16, 17, 28. Las notas de crédito/débito no se aceptan en lote.","default":1},"factura":{"additionalProperties":true,"type":"object","title":"Factura","description":"Cuerpo de la factura, con la misma estructura que el endpoint individual del sector."}},"type":"object","required":["factura"],"title":"EntradaLote"},"EnviarPaqueteRequest":{"properties":{"sucursal":{"type":"integer","title":"Sucursal","description":"Sucursal cuyas facturas offline se van a enviar.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Punto de venta cuyas facturas offline se van a enviar.","default":0},"tipo_evento":{"type":"integer","title":"Tipo Evento","description":"Código del evento de contingencia previamente registrado."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["tipo_evento"],"title":"EnviarPaqueteRequest"},"EventoContingenciaRequest":{"properties":{"sucursal":{"type":"integer","title":"Sucursal","description":"Sucursal afectada por el corte.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Punto de venta afectado.","default":0},"tipo_evento":{"type":"integer","title":"Tipo Evento","description":"Código del evento según catálogo SIAT. Valores comunes: `1`=Corte de internet, `2`=Corte de energía, `3`=Falla del sistema."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción textual del evento ocurrido."},"fecha_inicio":{"type":"string","title":"Fecha Inicio","description":"Fecha y hora de inicio del corte. Formato ISO 8601: `2024-06-15T10:00:00`."},"fecha_fin":{"type":"string","title":"Fecha Fin","description":"Fecha y hora de finalización del corte. Formato ISO 8601: `2024-06-15T12:30:00`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["tipo_evento","descripcion","fecha_inicio","fecha_fin"],"title":"EventoContingenciaRequest"},"FacturaAlquilerInmueble":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemFactura"},"type":"array","title":"Items","description":"Conceptos del alquiler (arriendo mensual, expensas, etc.)."},"periodo_facturado":{"type":"string","title":"Periodo Facturado","description":"Período de alquiler facturado. Ejemplo: `Junio 2024`, `2024-06`."},"ciudad":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ciudad","description":"Ciudad donde se ubica el inmueble. Ejemplo: `La Paz`."},"zona":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zona","description":"Zona o barrio del inmueble. Ejemplo: `Miraflores`."}},"type":"object","required":["emisor","cliente","items","periodo_facturado"],"title":"FacturaAlquilerInmueble","description":"Factura de Alquiler de Bien Inmueble — Sector 2.\n\nPara personas naturales o empresas que alquilan propiedades (casas, departamentos, locales comerciales)."},"FacturaComercial":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemFactura"},"type":"array","title":"Items","description":"Lista de productos o servicios facturados. Mínimo 1 ítem."},"monto_gift_card":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Monto Gift Card","description":"Monto pagado con tarjeta de regalo o bono prepago. Solo informativo."},"numero_tarjeta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Tarjeta","description":"Primeros 4 y últimos 4 dígitos de la tarjeta de crédito/débito. Ejemplo: `1234****5678`. Solo cuando `metodo_pago` es tarjeta."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaComercial","description":"Factura de Compra y Venta general — Sector 1.\n\nEl tipo más común. Aplica para comercios, servicios y cualquier actividad\neconómica que no tenga un sector específico."},"FacturaEducacion":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemFactura"},"type":"array","title":"Items","description":"Servicios educativos facturados (matrícula, mensualidad, cursos, etc.)."},"nombre_estudiante":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre Estudiante","description":"Nombre completo del estudiante beneficiario del servicio educativo."},"periodo_facturado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Periodo Facturado","description":"Período académico al que corresponde el cobro. Ejemplo: `1er Semestre 2024`, `Febrero 2024`."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaEducacion","description":"Factura del Sector Educativo — Sector 11.\n\nPara institutos, colegios, universidades y centros de formación."},"FacturaExportacion":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemExportacion"},"type":"array","title":"Items","description":"Productos exportados. Cada ítem acepta `codigo_nandina`."},"incoterm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incoterm","description":"Término de comercio internacional. Ejemplo: `FOB`, `CIF`, `EXW`."},"incoterm_detalle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incoterm Detalle","description":"Descripción o condiciones adicionales del Incoterm pactado."},"puerto_destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Puerto Destino","description":"Puerto o lugar de entrega de la exportación. Ejemplo: `Puerto de Arica, Chile`."},"lugar_destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lugar Destino","description":"País o ciudad de destino final de la mercadería."},"informacion_adicional":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacion Adicional","description":"Información complementaria de la exportación (número de DUE, aduana, etc.)."},"costos_gastos_nacionales":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Costos Gastos Nacionales","description":"Desglose de costos y gastos nacionales hasta puerto de embarque. Ejemplo: `{\"transporte\": 500.0, \"aduana\": 120.5}`."},"costos_gastos_internacionales":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Costos Gastos Internacionales","description":"Desglose de costos y gastos internacionales (flete marítimo, seguro internacional, etc.)."},"total_gastos_nacionales_fob":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Total Gastos Nacionales Fob","description":"Valor FOB total. Si no se envía, se calcula como suma de ítems + costos nacionales."},"total_gastos_internacionales":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Total Gastos Internacionales","description":"Total de gastos internacionales. Si no se envía, se calcula del desglose."},"numero_descripcion_paquetes_bultos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Descripcion Paquetes Bultos","description":"Número y descripción de paquetes o bultos exportados. Ejemplo: `10 cajas de 25 kg`."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaExportacion","description":"Factura Comercial de Exportación — Sector 3.\n\nPara ventas de bienes a compradores en el exterior.\nEl cliente puede ser una empresa extranjera (sin NIT boliviano)."},"FacturaExportacionServicios":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemFactura"},"type":"array","title":"Items","description":"Servicios exportados."},"lugar_destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lugar Destino","description":"País o ciudad donde se aprovecha el servicio. Ejemplo: `CHILE`."},"informacion_adicional":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacion Adicional","description":"Información complementaria de la exportación del servicio."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaExportacionServicios","description":"Factura Comercial de Exportación de Servicios — Sector 28.\n\nPara servicios prestados desde Bolivia a clientes en el exterior\n(software, consultoría, BPO, etc.)."},"FacturaHospital":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemHospital"},"type":"array","title":"Items","description":"Servicios médicos prestados."},"modalidad_servicio":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Modalidad Servicio","description":"Modalidad del servicio médico según catálogo SIAT (consulta, cirugía, hospitalización, etc.)."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaHospital","description":"Factura de Hospital y Clínica — Sector 17.\n\nPara clínicas, hospitales, consultorios médicos y laboratorios clínicos.\nPermite detallar el médico tratante y la especialidad por cada ítem de servicio."},"FacturaHotel":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemHotel"},"type":"array","title":"Items","description":"Servicios de hospedaje y consumos adicionales."},"fecha_ingreso":{"type":"string","title":"Fecha Ingreso","description":"Fecha de ingreso del huésped. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-15`."},"cantidad_huespedes":{"type":"integer","minimum":1.0,"title":"Cantidad Huespedes","description":"Número total de huéspedes registrados."},"cantidad_habitaciones":{"type":"integer","minimum":1.0,"title":"Cantidad Habitaciones","description":"Número total de habitaciones ocupadas."},"cantidad_mayores":{"type":"integer","minimum":0.0,"title":"Cantidad Mayores","description":"Cantidad de huéspedes mayores de 18 años.","default":0},"cantidad_menores":{"type":"integer","minimum":0.0,"title":"Cantidad Menores","description":"Cantidad de huéspedes menores de 18 años.","default":0}},"type":"object","required":["emisor","cliente","items","fecha_ingreso","cantidad_huespedes","cantidad_habitaciones"],"title":"FacturaHotel","description":"Factura de Hotel — Sector 16.\n\nPara hoteles, hostales, apart-hoteles y cualquier servicio de alojamiento.\nCon derecho a crédito fiscal."},"FacturaIce":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemIce"},"type":"array","title":"Items","description":"Productos alcanzados por el ICE con sus alícuotas."},"monto_ice_especifico":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Monto Ice Especifico","description":"Suma total del ICE específico de la factura (Bs)."},"monto_ice_porcentual":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Monto Ice Porcentual","description":"Suma total del ICE porcentual de la factura (Bs)."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaIce","description":"Factura Alcanzada por el ICE — Sector 14.\n\nPara productores e importadores de bienes con Impuesto a los Consumos\nEspecíficos: bebidas alcohólicas, cigarrillos, vehículos, etc."},"FacturaLibreConsignacion":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemExportacion"},"type":"array","title":"Items","description":"Productos exportados. Cada ítem acepta `codigo_nandina`."},"incoterm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incoterm","description":"Término de comercio internacional. Ejemplo: `FOB`, `CIF`, `EXW`."},"incoterm_detalle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incoterm Detalle","description":"Descripción o condiciones adicionales del Incoterm pactado."},"puerto_destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Puerto Destino","description":"Puerto o lugar de entrega de la exportación. Ejemplo: `Puerto de Arica, Chile`."},"lugar_destino":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lugar Destino","description":"País o ciudad de destino final de la mercadería."},"informacion_adicional":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacion Adicional","description":"Información complementaria de la exportación (número de DUE, aduana, etc.)."},"costos_gastos_nacionales":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Costos Gastos Nacionales","description":"Desglose de costos y gastos nacionales hasta puerto de embarque. Ejemplo: `{\"transporte\": 500.0, \"aduana\": 120.5}`."},"costos_gastos_internacionales":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Costos Gastos Internacionales","description":"Desglose de costos y gastos internacionales (flete marítimo, seguro internacional, etc.)."},"total_gastos_nacionales_fob":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Total Gastos Nacionales Fob","description":"Valor FOB total. Si no se envía, se calcula como suma de ítems + costos nacionales."},"total_gastos_internacionales":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Total Gastos Internacionales","description":"Total de gastos internacionales. Si no se envía, se calcula del desglose."},"numero_descripcion_paquetes_bultos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Descripcion Paquetes Bultos","description":"Número y descripción de paquetes o bultos exportados. Ejemplo: `10 cajas de 25 kg`."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaLibreConsignacion","description":"Factura Comercial de Exportación en Libre Consignación — Sector 4.\n\nPara mercadería enviada al exterior sin venta en firme (el precio se\ndefine cuando el consignatario la vende)."},"FacturaServicioBasico":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemFactura"},"type":"array","title":"Items","description":"Conceptos facturados (consumo, tasas, cargos fijos)."},"mes":{"type":"integer","maximum":12.0,"minimum":1.0,"title":"Mes","description":"Mes al que corresponde el consumo facturado (1=Enero, 12=Diciembre)."},"gestion":{"type":"integer","minimum":2000.0,"title":"Gestion","description":"Año de gestión al que corresponde el consumo. Ejemplo: `2024`."},"numero_medidor":{"type":"string","title":"Numero Medidor","description":"Número identificador del medidor del cliente."},"domicilio_cliente":{"type":"string","title":"Domicilio Cliente","description":"Dirección del suministro (no necesariamente la del cliente)."},"consumo_periodo":{"type":"number","minimum":0.0,"title":"Consumo Periodo","description":"Cantidad consumida en el período (en la unidad que corresponda: m³, kWh, etc.)."},"beneficiario_ley_1886":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Beneficiario Ley 1886","description":"Código de beneficio de la Ley 1886 (subsidio de energía). `1`=Sí aplica."},"monto_descuento_ley_1886":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Monto Descuento Ley 1886","description":"Monto del descuento aplicado por la Ley 1886 (Bs)."},"monto_descuento_tarifa_dignidad":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Monto Descuento Tarifa Dignidad","description":"Monto del descuento correspondiente a la Tarifa Dignidad (Bs)."},"tasa_aseo":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Tasa Aseo","description":"Monto de la tasa de aseo urbano incluida en la factura (Bs)."},"tasa_alumbrado":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Tasa Alumbrado","description":"Monto de la tasa de alumbrado público incluida en la factura (Bs)."},"ciudad":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ciudad","description":"Ciudad del suministro. Ejemplo: `La Paz`."},"zona":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zona","description":"Zona o barrio del suministro."},"ajuste_no_sujeto_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ajuste No Sujeto Iva","description":"Monto de ajuste no sujeto a IVA (Bs)."},"detalle_ajuste_no_sujeto_iva":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detalle Ajuste No Sujeto Iva","description":"Detalle del ajuste no sujeto a IVA."},"ajuste_sujeto_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ajuste Sujeto Iva","description":"Monto de ajuste sujeto a IVA (Bs)."},"detalle_ajuste_sujeto_iva":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detalle Ajuste Sujeto Iva","description":"Detalle del ajuste sujeto a IVA."},"otros_pagos_no_sujeto_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Otros Pagos No Sujeto Iva","description":"Otros pagos no sujetos a IVA (Bs)."},"detalle_otros_pagos_no_sujeto_iva":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detalle Otros Pagos No Sujeto Iva","description":"Detalle de otros pagos no sujetos a IVA."},"otras_tasas":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Otras Tasas","description":"Otras tasas municipales incluidas (Bs)."}},"type":"object","required":["emisor","cliente","items","mes","gestion","numero_medidor","domicilio_cliente","consumo_periodo"],"title":"FacturaServicioBasico","description":"Factura de Servicio Básico — Sector 13.\n\nPara empresas de distribución de agua, gas domiciliario y electricidad."},"FacturaTasaCero":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemFactura"},"type":"array","title":"Items","description":"Productos o servicios con tasa cero de IVA."},"monto_gift_card":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Monto Gift Card","description":"Monto pagado con tarjeta de regalo."},"numero_tarjeta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Tarjeta","description":"Primeros 4 y últimos 4 dígitos de la tarjeta, completando con ceros. Ejemplo: `1234000000005678`."}},"type":"object","required":["emisor","cliente","items"],"title":"FacturaTasaCero","description":"Factura Tasa Cero — Sector 8.\n\nPara ventas exentas de IVA por ley: libros (Ley 366), transporte\ninternacional de carga (Ley 3249) y otros. Sin débito fiscal."},"FacturaTurismo":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemHotel"},"type":"array","title":"Items","description":"Servicios de hospedaje y consumos adicionales."},"fecha_ingreso":{"type":"string","title":"Fecha Ingreso","description":"Fecha de ingreso del huésped. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-15`."},"cantidad_huespedes":{"type":"integer","minimum":1.0,"title":"Cantidad Huespedes","description":"Número total de huéspedes registrados."},"cantidad_habitaciones":{"type":"integer","minimum":1.0,"title":"Cantidad Habitaciones","description":"Número total de habitaciones ocupadas."},"cantidad_mayores":{"type":"integer","minimum":0.0,"title":"Cantidad Mayores","description":"Cantidad de huéspedes mayores de 18 años.","default":0},"cantidad_menores":{"type":"integer","minimum":0.0,"title":"Cantidad Menores","description":"Cantidad de huéspedes menores de 18 años.","default":0},"razon_social_operador":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razon Social Operador","description":"Razón social de la agencia u operadora de turismo, si la reserva vino a través de un intermediario."}},"type":"object","required":["emisor","cliente","items","fecha_ingreso","cantidad_huespedes","cantidad_habitaciones"],"title":"FacturaTurismo","description":"Factura de Servicio Turístico y Hospedaje — Sector 6.\n\nPara paquetes turísticos y hospedaje de turistas extranjeros\n(Ley 292). Sin derecho a crédito fiscal."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ItemExportacion":{"properties":{"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto o servicio en tu propio sistema."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código del producto según el catálogo de bienes y servicios del SIAT. Consulta `GET /v1/catalogos/productos_servicios`."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto o servicio que aparecerá en la factura."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad vendida. Acepta hasta 5 decimales."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida según catálogo SIAT. Ejemplo: `1`=Unidad, `2`=Kilogramo. Consulta `GET /v1/catalogos/unidades_medida`.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario en la moneda indicada. Acepta hasta 5 decimales."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","description":"Monto de descuento aplicado a este ítem específico. Usa `descuento_adicional` en la cabecera para descuentos globales.","default":0.0},"numero_serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Serie","description":"Número de serie del producto (electrodomésticos, equipos). Opcional, solo sector Compra y Venta."},"numero_imei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Imei","description":"Número IMEI del equipo móvil. Opcional, solo sector Compra y Venta."},"codigo_nandina":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo Nandina","description":"Código arancelario NANDINA del producto exportado. Ejemplo: `0901.11.10.00`."}},"type":"object","required":["codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario"],"title":"ItemExportacion"},"ItemFactura":{"properties":{"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto o servicio en tu propio sistema."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código del producto según el catálogo de bienes y servicios del SIAT. Consulta `GET /v1/catalogos/productos_servicios`."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto o servicio que aparecerá en la factura."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad vendida. Acepta hasta 5 decimales."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida según catálogo SIAT. Ejemplo: `1`=Unidad, `2`=Kilogramo. Consulta `GET /v1/catalogos/unidades_medida`.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario en la moneda indicada. Acepta hasta 5 decimales."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","description":"Monto de descuento aplicado a este ítem específico. Usa `descuento_adicional` en la cabecera para descuentos globales.","default":0.0},"numero_serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Serie","description":"Número de serie del producto (electrodomésticos, equipos). Opcional, solo sector Compra y Venta."},"numero_imei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Imei","description":"Número IMEI del equipo móvil. Opcional, solo sector Compra y Venta."}},"type":"object","required":["codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario"],"title":"ItemFactura"},"ItemHospital":{"properties":{"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto o servicio en tu propio sistema."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código del producto según el catálogo de bienes y servicios del SIAT. Consulta `GET /v1/catalogos/productos_servicios`."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto o servicio que aparecerá en la factura."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad vendida. Acepta hasta 5 decimales."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida según catálogo SIAT. Ejemplo: `1`=Unidad, `2`=Kilogramo. Consulta `GET /v1/catalogos/unidades_medida`.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario en la moneda indicada. Acepta hasta 5 decimales."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","description":"Monto de descuento aplicado a este ítem específico. Usa `descuento_adicional` en la cabecera para descuentos globales.","default":0.0},"numero_serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Serie","description":"Número de serie del producto (electrodomésticos, equipos). Opcional, solo sector Compra y Venta."},"numero_imei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Imei","description":"Número IMEI del equipo móvil. Opcional, solo sector Compra y Venta."},"especialidad":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Especialidad","description":"Código de especialidad médica según catálogo SIAT."},"especialidad_detalle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Especialidad Detalle","description":"Descripción textual de la especialidad."},"nombre_medico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nombre Medico","description":"Nombre y apellidos del médico tratante."},"nit_medico":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Nit Medico","description":"NIT o número de documento del médico."},"nro_matricula_medico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nro Matricula Medico","description":"Número de matrícula del médico en el colegio médico."},"especialidad_medico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Especialidad Medico","description":"Especialidad del médico tratante."},"nro_quirofano_sala_operaciones":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Nro Quirofano Sala Operaciones","description":"Número de quirófano o sala de operaciones."},"nro_factura_medico":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Nro Factura Medico","description":"Número de factura emitida por el médico, si aplica."}},"type":"object","required":["codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario"],"title":"ItemHospital"},"ItemHotel":{"properties":{"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto o servicio en tu propio sistema."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código del producto según el catálogo de bienes y servicios del SIAT. Consulta `GET /v1/catalogos/productos_servicios`."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto o servicio que aparecerá en la factura."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad vendida. Acepta hasta 5 decimales."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida según catálogo SIAT. Ejemplo: `1`=Unidad, `2`=Kilogramo. Consulta `GET /v1/catalogos/unidades_medida`.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario en la moneda indicada. Acepta hasta 5 decimales."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","description":"Monto de descuento aplicado a este ítem específico. Usa `descuento_adicional` en la cabecera para descuentos globales.","default":0.0},"numero_serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Serie","description":"Número de serie del producto (electrodomésticos, equipos). Opcional, solo sector Compra y Venta."},"numero_imei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Imei","description":"Número IMEI del equipo móvil. Opcional, solo sector Compra y Venta."},"tipo_habitacion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tipo Habitacion","description":"Código del tipo de habitación según catálogo SIAT (simple, doble, suite, etc.)."},"detalle_huespedes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detalle Huespedes","description":"Descripción o lista de los huéspedes asignados a esta habitación."}},"type":"object","required":["codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario"],"title":"ItemHotel"},"ItemIce":{"properties":{"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto o servicio en tu propio sistema."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código del producto según el catálogo de bienes y servicios del SIAT. Consulta `GET /v1/catalogos/productos_servicios`."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto o servicio que aparecerá en la factura."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad vendida. Acepta hasta 5 decimales."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida según catálogo SIAT. Ejemplo: `1`=Unidad, `2`=Kilogramo. Consulta `GET /v1/catalogos/unidades_medida`.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario en la moneda indicada. Acepta hasta 5 decimales."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","description":"Monto de descuento aplicado a este ítem específico. Usa `descuento_adicional` en la cabecera para descuentos globales.","default":0.0},"numero_serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Serie","description":"Número de serie del producto (electrodomésticos, equipos). Opcional, solo sector Compra y Venta."},"numero_imei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Imei","description":"Número IMEI del equipo móvil. Opcional, solo sector Compra y Venta."},"marca_ice":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Marca Ice","description":"Código de marca del producto según catálogo ICE del SIAT."},"alicuota_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alicuota Iva","description":"Alícuota del IVA aplicada al ítem (normalmente `0.13`)."},"precio_neto_venta_ice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Precio Neto Venta Ice","description":"Precio neto de venta sujeto al ICE (sin IVA)."},"alicuota_especifica":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alicuota Especifica","description":"Alícuota específica del ICE en Bs por unidad de medida."},"alicuota_porcentual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alicuota Porcentual","description":"Alícuota porcentual del ICE. Ejemplo: `0.05`."},"monto_ice_especifico":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto Ice Especifico","description":"Monto del ICE específico calculado para este ítem (Bs)."},"monto_ice_porcentual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto Ice Porcentual","description":"Monto del ICE porcentual calculado para este ítem (Bs)."},"cantidad_ice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cantidad Ice","description":"Cantidad sujeta al ICE (litros, unidades, etc.)."}},"type":"object","required":["codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario"],"title":"ItemIce","description":"Ítem con campos del Impuesto a los Consumos Específicos (bebidas alcohólicas, cigarrillos, etc.)."},"ItemNotaCreditoDebito":{"properties":{"nro_item":{"type":"integer","minimum":1.0,"title":"Nro Item","description":"Número de ítem correspondiente en la factura original que se está ajustando."},"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto (debe coincidir con la factura original)."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código de producto SIAT."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto o servicio ajustado."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad a devolver o ajustar."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida SIAT.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario del producto ajustado."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","default":0.0},"codigo_detalle_transaccion":{"type":"integer","title":"Codigo Detalle Transaccion","description":"Etiqueta **estructural** de la línea, no un motivo de ajuste: `1`=línea que replica el ítem tal cual está en la factura original (cantidad y precio idénticos — el SIAT rechaza con el código 1049 si no coinciden exacto), `2`=línea propia de esta nota, el ajuste real que se está aplicando. Por cada ítem que ajustes debes mandar AMBAS líneas (mismo `nro_item`), aunque sean iguales en una devolución total. El XSD exige un mínimo de 2 líneas de `detalle` en total."}},"type":"object","required":["nro_item","codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario","codigo_detalle_transaccion"],"title":"ItemNotaCreditoDebito"},"ItemNotaIce":{"properties":{"nro_item":{"type":"integer","minimum":1.0,"title":"Nro Item","description":"Número de ítem correspondiente en la factura original."},"codigo_producto":{"type":"string","title":"Codigo Producto","description":"Código interno del producto (debe coincidir con la factura original)."},"codigo_sin":{"type":"integer","title":"Codigo Sin","description":"Código de producto SIAT."},"descripcion":{"type":"string","title":"Descripcion","description":"Descripción del producto ajustado."},"cantidad":{"type":"number","exclusiveMinimum":0.0,"title":"Cantidad","description":"Cantidad a devolver o ajustar."},"unidad_medida":{"type":"integer","title":"Unidad Medida","description":"Código de unidad de medida SIAT.","default":1},"precio_unitario":{"type":"number","exclusiveMinimum":0.0,"title":"Precio Unitario","description":"Precio unitario del producto ajustado."},"descuento":{"type":"number","minimum":0.0,"title":"Descuento","default":0.0},"codigo_detalle_transaccion":{"type":"integer","title":"Codigo Detalle Transaccion","description":"Etiqueta **estructural** de la línea, no un motivo: `1`=línea que replica el ítem tal cual está en la factura original, `2`=línea propia de esta nota (el ajuste real). El SIAT exige al menos una línea de cada tipo por ítem ajustado — envía ambas para el mismo `nro_item`. Mismo criterio que en `POST /v1/notas` (ver su documentación para el detalle completo)."},"marca_ice":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Marca Ice","description":"Código de marca del producto según catálogo ICE del SIAT."},"alicuota_iva":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alicuota Iva","description":"Alícuota del IVA aplicada al ítem."},"precio_neto_venta_ice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Precio Neto Venta Ice","description":"Precio neto de venta sujeto al ICE."},"alicuota_especifica":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alicuota Especifica","description":"Alícuota específica del ICE en Bs."},"alicuota_porcentual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Alicuota Porcentual","description":"Alícuota porcentual del ICE."},"monto_ice_especifico":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto Ice Especifico","description":"Monto del ICE específico (Bs)."},"monto_ice_porcentual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monto Ice Porcentual","description":"Monto del ICE porcentual (Bs)."},"cantidad_ice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cantidad Ice","description":"Cantidad sujeta al ICE."}},"type":"object","required":["nro_item","codigo_producto","codigo_sin","descripcion","cantidad","precio_unitario","codigo_detalle_transaccion"],"title":"ItemNotaIce","description":"Ítem de nota de crédito/débito para productos alcanzados por el ICE (Sector 48)."},"LoteFacturasRequest":{"properties":{"facturas":{"items":{"$ref":"#/components/schemas/EntradaLote"},"type":"array","maxItems":20,"minItems":1,"title":"Facturas","description":"Entre 1 y 20 facturas por lote. Para volúmenes mayores, envía varios lotes."}},"type":"object","required":["facturas"],"title":"LoteFacturasRequest"},"NotaCreditoDebito":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemNotaCreditoDebito"},"type":"array","title":"Items","description":"Detalle de la nota: por cada ítem ajustado, una línea `codigo_detalle_transaccion=1` (replica la factura original) y una línea `codigo_detalle_transaccion=2` (el ajuste real). Mínimo 2 líneas."},"cuf_factura_original":{"type":"string","title":"Cuf Factura Original","description":"CUF de la factura original que se está ajustando. Se puede obtener de `GET /v1/facturas/{cuf}`."},"numero_factura_original":{"type":"integer","title":"Numero Factura Original","description":"Número correlativo de la factura original que se ajusta."},"fecha_emision_factura_original":{"type":"string","title":"Fecha Emision Factura Original","description":"Fecha en que se emitió la factura original. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-01`."},"monto_total_original":{"type":"number","exclusiveMinimum":0.0,"title":"Monto Total Original","description":"Monto total de la factura original en bolivianos."},"monto_total_devuelto":{"type":"number","exclusiveMinimum":0.0,"title":"Monto Total Devuelto","description":"Monto ajustado por esta nota, calculado sobre las líneas `codigo_detalle_transaccion=2` del detalle (cantidad × precio_unitario − descuento), NO el total de la factura original. Debe ser mayor a 0 (el SIAT lo exige así incluso para casos límite)."},"descuento_credito_debito":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Descuento Credito Debito","description":"Monto de descuento adicional aplicado en esta nota (en bolivianos)."},"monto_efectivo_credito_debito":{"type":"number","exclusiveMinimum":0.0,"title":"Monto Efectivo Credito Debito","description":"Monto efectivo que se devuelve al cliente en efectivo o se aplica como crédito (en bolivianos). Confirmado empíricamente contra el SIAT (piloto): equivale al 13% (IVA) de `monto_total_devuelto`, redondeado a 2 decimales."}},"type":"object","required":["emisor","cliente","items","cuf_factura_original","numero_factura_original","fecha_emision_factura_original","monto_total_original","monto_total_devuelto","monto_efectivo_credito_debito"],"title":"NotaCreditoDebito","description":"Nota de Crédito, Débito o Descuento — Sector 47.\n\nAjusta o revierte parcial o totalmente una factura emitida previamente.\nLa nota debe referenciar el CUF exacto de la factura original.\n\n**El detalle no es una simple copia de la factura original.** Por cada\nítem que se ajusta hace falta mandar dos líneas en `items`, distinguidas\npor `codigo_detalle_transaccion`:\n1. Una línea `codigo_detalle_transaccion=1` que replica el ítem exacto\n   (cantidad y precio) tal cual aparece en la factura original.\n2. Una línea `codigo_detalle_transaccion=2` con el ajuste real de esta\n   nota (para una devolución total, es idéntica a la línea 1; para una\n   devolución/descuento parcial, ahí es donde se refleja la diferencia).\n\n`monto_total_devuelto` y `monto_efectivo_credito_debito` se calculan\nsobre las líneas tipo `2` (el ajuste), no sobre la factura original."},"NotaCreditoDebitoIce":{"properties":{"emisor":{"$ref":"#/components/schemas/Emisor"},"cliente":{"$ref":"#/components/schemas/Cliente"},"metodo_pago":{"type":"integer","title":"Metodo Pago","description":"Código del método de pago según catálogo SIAT. Consulta `GET /v1/catalogos/metodos_pago`. Valores comunes: `1`=Efectivo, `2`=Tarjeta débito, `3`=Tarjeta crédito, `7`=Transferencia.","default":1},"moneda":{"type":"integer","title":"Moneda","description":"Código de moneda según catálogo SIAT. `1`=Bolivianos (por defecto), `2`=Dólares americanos.","default":1},"tipo_cambio":{"type":"number","minimum":1.0,"title":"Tipo Cambio","description":"Tipo de cambio respecto al boliviano. Solo aplica cuando `moneda != 1`. Usar el tipo de cambio oficial del BCB.","default":1.0},"descuento_adicional":{"type":"number","minimum":0.0,"title":"Descuento Adicional","description":"Descuento global aplicado al total de la factura (en bolivianos). Se suma a los descuentos individuales por ítem.","default":0.0},"contingencia":{"type":"boolean","title":"Contingencia","description":"Indica que la factura se emite en modo fuera de línea. Requiere haber registrado previamente un evento de contingencia con `POST /v1/contingencia/evento`. Las facturas offline se acumulan y se envían al SIAT con `POST /v1/contingencia/paquete`.","default":false},"usuario":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usuario","description":"Identificador del cajero o usuario que genera la factura. Se guarda para auditoría."},"leyenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leyenda","description":"Leyenda legal que aparece en la factura. Si no se envía, se asigna automáticamente una leyenda vigente según la actividad económica."},"codigo_excepcion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Codigo Excepcion","description":"Usa `1` para autorizar la emisión aunque el NIT del cliente esté inválido ante el SIAT. Por defecto la emisión se rechaza si el NIT no es válido."},"cafc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cafc","description":"Código de Autorización de Facturación por Contingencia, otorgado por el SIAT para emisión masiva fuera de línea. Solo con `contingencia: true`."},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.respuesta_siat.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false},"items":{"items":{"$ref":"#/components/schemas/ItemNotaIce"},"type":"array","title":"Items","description":"Ítems a ajustar con sus campos ICE."},"cuf_factura_original":{"type":"string","title":"Cuf Factura Original","description":"CUF de la factura original que se está ajustando. Se puede obtener de `GET /v1/facturas/{cuf}`."},"numero_factura_original":{"type":"integer","title":"Numero Factura Original","description":"Número correlativo de la factura original que se ajusta."},"fecha_emision_factura_original":{"type":"string","title":"Fecha Emision Factura Original","description":"Fecha en que se emitió la factura original. Formato `YYYY-MM-DD`. Ejemplo: `2024-06-01`."},"monto_total_original":{"type":"number","exclusiveMinimum":0.0,"title":"Monto Total Original","description":"Monto total de la factura original en bolivianos."},"monto_total_devuelto":{"type":"number","exclusiveMinimum":0.0,"title":"Monto Total Devuelto","description":"Monto ajustado por esta nota, calculado sobre las líneas `codigo_detalle_transaccion=2` del detalle (cantidad × precio_unitario − descuento), NO el total de la factura original. Debe ser mayor a 0 (el SIAT lo exige así incluso para casos límite)."},"descuento_credito_debito":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Descuento Credito Debito","description":"Monto de descuento adicional aplicado en esta nota (en bolivianos)."},"monto_efectivo_credito_debito":{"type":"number","exclusiveMinimum":0.0,"title":"Monto Efectivo Credito Debito","description":"Monto efectivo que se devuelve al cliente en efectivo o se aplica como crédito (en bolivianos). Confirmado empíricamente contra el SIAT (piloto): equivale al 13% (IVA) de `monto_total_devuelto`, redondeado a 2 decimales."}},"type":"object","required":["emisor","cliente","items","cuf_factura_original","numero_factura_original","fecha_emision_factura_original","monto_total_original","monto_total_devuelto","monto_efectivo_credito_debito"],"title":"NotaCreditoDebitoIce","description":"Nota de Crédito/Débito con ICE — Sector 48.\n\nIgual que la nota estándar, pero para productos alcanzados por el\nImpuesto a los Consumos Específicos."},"PuntoVentaRequest":{"properties":{"sucursal":{"type":"integer","title":"Sucursal","description":"Código de la sucursal donde se registra el punto de venta.","default":0},"nombre":{"type":"string","title":"Nombre","description":"Nombre descriptivo del punto de venta. Ejemplo: `Caja 1 — Planta Baja`."},"tipo_punto_venta":{"type":"integer","title":"Tipo Punto Venta","description":"Tipo de punto de venta según catálogo SIAT. `1`=Fijo, `2`=Móvil.","default":1},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["nombre"],"title":"PuntoVentaRequest"},"RespuestaAPI":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"Indica si la operación fue exitosa"},"datos":{"anyOf":[{},{"type":"null"}],"title":"Datos","description":"Resultado de la operación"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Descripción del error (solo cuando ok=false)"},"timestamp":{"type":"string","title":"Timestamp","description":"Fecha y hora UTC de la respuesta"}},"type":"object","required":["ok"],"title":"RespuestaAPI"},"ReversionAnulacionRequest":{"properties":{"sucursal":{"type":"integer","title":"Sucursal","description":"Sucursal donde fue emitida la factura.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Punto de venta donde fue emitida la factura.","default":0},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","title":"ReversionAnulacionRequest"},"SincronizarRequest":{"properties":{"nit":{"type":"integer","title":"Nit","description":"NIT de la empresa emisora."},"codigo_sistema":{"type":"string","title":"Codigo Sistema","description":"Código de sistema asignado por el SIAT al registrar tu sistema de facturación."},"sucursal":{"type":"integer","title":"Sucursal","description":"Código de sucursal. Usa `0` para la casa matriz.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Código de punto de venta. Usa `0` para el punto principal.","default":0},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["nit","codigo_sistema"],"title":"SincronizarRequest"},"SolicitudAcceso":{"properties":{"email":{"type":"string","title":"Email"},"continue_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continue Url"}},"type":"object","required":["email"],"title":"SolicitudAcceso"},"SolicitudProduccionRequest":{"properties":{"nit":{"type":"integer","title":"Nit","description":"El NIT real de tu empresa, el que te dio el SIN."},"razon_social":{"type":"string","minLength":2,"title":"Razon Social","description":"Razón social tal como figura en tu NIT."},"telefono":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefono","description":"Teléfono de contacto."},"modalidad":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Modalidad","description":"`1` electrónica en línea, `2` computarizada en línea. Si no sabés, dejalo vacío."}},"type":"object","required":["nit","razon_social"],"title":"SolicitudProduccionRequest"},"ValidarNitRequest":{"properties":{"nit":{"type":"integer","title":"Nit","description":"NIT a verificar."},"sucursal":{"type":"integer","title":"Sucursal","description":"Sucursal desde la que se hace la consulta.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Punto de venta desde el que se hace la consulta.","default":0},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["nit"],"title":"ValidarNitRequest"},"ValidarPaqueteRequest":{"properties":{"sucursal":{"type":"integer","title":"Sucursal","description":"Sucursal desde la que se envió el paquete.","default":0},"punto_venta":{"type":"integer","title":"Punto Venta","description":"Punto de venta desde el que se envió el paquete.","default":0},"codigo_recepcion":{"type":"string","title":"Codigo Recepcion","description":"Código de recepción devuelto por `POST /v1/contingencia/paquete`."},"sector_documento":{"type":"integer","title":"Sector Documento","description":"Sector de los documentos del paquete. Por defecto `1` (Compra y Venta).","default":1},"debug":{"type":"boolean","title":"Debug","description":"Si es `true`, incluye en `datos.debug_siat` el XML crudo del request y response SOAP enviados y recibidos del SIAT. Úsalo para diagnosticar rechazos junto al soporte del SIAT.","default":false}},"type":"object","required":["codigo_recepcion"],"title":"ValidarPaqueteRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookRequest":{"properties":{"url":{"type":"string","title":"Url","description":"URL HTTPS de tu servidor que recibirá los eventos. Debe responder 2xx en menos de 10 segundos."},"eventos":{"items":{"type":"string"},"type":"array","title":"Eventos","description":"Eventos a los que te suscribes. Acepta `*` (todos), prefijos como `factura.*`, o nombres exactos: `factura.emitida`, `factura.offline`, `factura.anulada`, `factura.anulacion_revertida`, `nota.emitida`, `contingencia.paquete_enviado`, `creditos.bajos`, `siat.caido`, `siat.recuperado`, `webhook.prueba`.","default":["*"]}},"type":"object","required":["url"],"title":"WebhookRequest"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-KEY"},"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Facturas","description":"Emisión, consulta y anulación de facturas fiscales por sector."},{"name":"Notas","description":"Notas de crédito, débito y descuento (Sector 47). Ajustan o anulan parcialmente una factura previa."},{"name":"Contingencia","description":"Gestión de emisión fuera de línea. Registra el evento de corte, emite facturas offline y luego envía el paquete al SIAT cuando se restablece la conexión."},{"name":"Sincronización","description":"Inicialización de códigos CUIS y CUFD por punto de venta. El CUFD debe renovarse cada 24 horas."},{"name":"Operaciones","description":"Alta y consulta de puntos de venta registrados en el SIAT."},{"name":"Catálogos","description":"Tablas paramétricas del SIAT: actividades, productos, métodos de pago, unidades de medida y más."},{"name":"Utilidades","description":"Validación de NIT, estado de cuenta y health check."},{"name":"Acceso público","description":"Consulta y descarga de facturas **sin autenticación**, usando el CUF como token. Comparte `GET /f/{cuf}` con el cliente final: es un enlace permanente con los datos de verificación y las descargas de PDF y XML."},{"name":"Reportes","description":"Reportes para contabilidad: **Libro de Ventas IVA** (formato RCV del SIAT) y **respaldo mensual** de todos los XML/PDF en un ZIP."},{"name":"Webhooks","description":"Notificaciones en tiempo real a tu servidor cuando ocurre un evento (factura emitida, anulada, contingencia...). Cada entrega va **firmada con HMAC-SHA256** (estándar [Standard Webhooks](https://www.standardwebhooks.com/)) y se reintenta automáticamente con backoff exponencial si tu servidor no responde."},{"name":"Administración","description":"Gestión interna de clientes — solo para sistemas de backoffice (Odoo). Requiere `X-ADMIN-KEY`."}]}