{"openapi":"3.0.3","info":{"title":"RAVEN DTE — Facturación Electrónica SaaS","version":"7.0.0","description":"\n## Plataforma SaaS de Facturación Electrónica — El Salvador\n\nRAVEN DTE es una plataforma multi-tenant para la emisión, firma y transmisión de Documentos Tributarios Electrónicos (DTEs) ante el Ministerio de Hacienda de El Salvador.\n\n### Autenticación\n\nLa API soporta dos métodos de autenticación:\n\n1. **JWT Bearer Token** — Para usuarios humanos autenticados vía login.\n2. **API Key** — Para integraciones M2M (Machine-to-Machine). Enviar en el header `X-API-Key`.\n\n### Tipos de DTE Soportados (Normativa 2.0 DGII)\n\n| Código | Tipo de Documento Tributario Electrónico | Estado |\n|--------|------------------------------------------|--------|\n| 01 | Factura Electrónica (Consumidor Final) | ✅ Disponible |\n| 03 | Comprobante de Crédito Fiscal Electrónico (CCF) | ✅ Disponible |\n| 04 | Nota de Remisión Electrónica | ✅ Disponible |\n| 05 | Nota de Crédito Electrónica (NCE) | ✅ Disponible |\n| 06 | Nota de Débito Electrónica (NDE) | ✅ Disponible |\n| 07 | Comprobante de Retención Electrónico (CRE) | ✅ Disponible |\n| 08 | Comprobante de Liquidación (CL) | ✅ Disponible |\n| 09 | Documento Contable de Liquidación (DCL) | ✅ Disponible |\n| 11 | Factura de Exportación Electrónica (FEX) | ✅ Disponible |\n| 14 | Factura de Sujeto Excluido (FSE) | ✅ Disponible |\n| 15 | Comprobante de Donación (CD) | ✅ Disponible |\n\n### Rate Limits\n\n- **Rutas públicas (PDF/JSON):** 10 solicitudes por minuto por IP.\n- **Rutas autenticadas:** 100 solicitudes por minuto por usuario.\n- **API Keys:** Configurable por llave (default: 500/hora).\n    ","contact":{"name":"RAVEN Tech","email":"soporte@raventech.sv"},"license":{"name":"Propietario","url":"https://raventech.sv"}},"servers":[{"url":"https://api.raventech.com.sv/v1","description":"Producción / Sandbox (Oficial)"},{"url":"/v1","description":"Servidor local / relativo"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtenido desde /api/v1/auth/login"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API Key generada desde el panel de la empresa (raven_live_xxx o raven_test_xxx)"}},"schemas":{"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"admin@empresa.com"},"password":{"type":"string","format":"password","example":"MiPassword123!"}}},"LoginResponse":{"type":"object","properties":{"message":{"type":"string","example":"Login exitoso"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"nombre":{"type":"string"},"rol":{"type":"string"},"tenant_id":{"type":"integer"},"sysadmin":{"type":"boolean"}}}}},"EmitirDTERequest":{"type":"object","required":["tipoDte","receptor","cuerpoDocumento"],"properties":{"tipoDte":{"type":"string","enum":["01","03","04","05","06","07","08","09","11","14","15"],"description":"Código del tipo de DTE según catálogo oficial MH (01=FE, 03=CCF, 04=NR, 05=NCE, 06=NDE, 07=CRE, 08=CL, 09=DCL, 11=FEX, 14=FSE, 15=CD)"},"receptor":{"type":"object","properties":{"tipoDocumento":{"type":"string","description":"Tipo de documento del receptor (36=NIT, 13=DUI, etc.)"},"numDocumento":{"type":"string","example":"0614-260000-000-0"},"nrc":{"type":"string","example":"123456-7","description":"Número de Registro de Contribuyente"},"nombre":{"type":"string","example":"Empresa Receptora S.A. de C.V."},"correo":{"type":"string","format":"email"},"codActividad":{"type":"string","example":"47190"},"descActividad":{"type":"string"},"telefono":{"type":"string"},"direccion":{"type":"object","properties":{"departamento":{"type":"string","example":"06"},"municipio":{"type":"string","example":"14"},"complemento":{"type":"string"}}}}},"cuerpoDocumento":{"type":"array","minItems":1,"items":{"type":"object","properties":{"numItem":{"type":"integer","minimum":1},"tipoItem":{"type":"integer","enum":[1,2,3,4],"description":"1=Bien, 2=Servicio, 3=Ambos, 4=Otros"},"codigo":{"type":"string"},"descripcion":{"type":"string","example":"Servicio de consultoría"},"cantidad":{"type":"number","example":1},"uniMedida":{"type":"integer","example":59,"description":"Unidad de medida según catálogo MH"},"precioUni":{"type":"number","example":100},"montoDescu":{"type":"number","example":0},"ventaNoSuj":{"type":"number","example":0},"ventaExenta":{"type":"number","example":0},"ventaGravada":{"type":"number","example":100}}}},"esContingencia":{"type":"boolean","default":false},"tipoContingencia":{"type":"integer"},"motivoContingencia":{"type":"string"}}},"DTEResponse":{"type":"object","properties":{"message":{"type":"string","example":"DTE emitido exitosamente"},"codigoGeneracion":{"type":"string","format":"uuid"},"numeroControl":{"type":"string","example":"DTE-01-00000001-000000000000001"},"selloRecepcion":{"type":"string"},"estado":{"type":"string","enum":["ACCEPTED","REJECTED","PENDING","CONTINGENCY"]},"fechaProcesamiento":{"type":"string","format":"date-time"}}},"DTEListResponse":{"type":"object","properties":{"dtes":{"type":"array","items":{"$ref":"#/components/schemas/DTESummary"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"DTESummary":{"type":"object","properties":{"id":{"type":"integer"},"tipo_dte":{"type":"string"},"codigo_generacion":{"type":"string","format":"uuid"},"numero_control":{"type":"string"},"fecha_emision":{"type":"string","format":"date"},"receptor_nombre":{"type":"string"},"receptor_num_doc":{"type":"string"},"total_pagar":{"type":"number"},"estado":{"type":"string"},"sello_recepcion":{"type":"string"}}},"AnularDTERequest":{"type":"object","required":["codigoGeneracion","tipoAnulacion","motivoAnulacion"],"properties":{"codigoGeneracion":{"type":"string","format":"uuid","description":"Código del DTE a anular"},"tipoAnulacion":{"type":"integer","enum":[1,2,3],"description":"1=Error en documento (reemplazo), 2=Rescisión de operación, 3=Otro"},"motivoAnulacion":{"type":"string","example":"Error en datos del receptor"},"codigoGeneracionR":{"type":"string","format":"uuid","description":"Código del DTE de reemplazo (obligatorio para Tipo 1)"},"nombreResponsable":{"type":"string"},"tipoDocResponsable":{"type":"string"},"numDocResponsable":{"type":"string"},"nombreSolicita":{"type":"string"},"tipoDocSolicita":{"type":"string"},"numDocSolicita":{"type":"string"}}},"Tenant":{"type":"object","properties":{"id":{"type":"integer"},"nit":{"type":"string","example":"0614-260000-000-0"},"nrc":{"type":"string"},"nombre":{"type":"string"},"nombre_comercial":{"type":"string"},"telefono":{"type":"string"},"correo":{"type":"string","format":"email"},"cod_actividad":{"type":"string"},"desc_actividad":{"type":"string"},"direccion":{"type":"object"},"logo_url":{"type":"string"},"mh_ambiente":{"type":"string","enum":["dev","00","01"]},"mh_configurado":{"type":"boolean"},"activo":{"type":"boolean"}}},"CertificateInfo":{"type":"object","properties":{"id":{"type":"integer"},"nombre":{"type":"string","example":"CN=EMPRESA S.A."},"fechaEmision":{"type":"string","format":"date"},"fechaExpiracion":{"type":"string","format":"date"},"activo":{"type":"boolean"}}},"ApiKeyCreateRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"POS Sucursal Centro"},"permissions":{"type":"array","items":{"type":"string","enum":["emit_dte","query_dte","download_dte"]},"default":["emit_dte","query_dte"]},"isTest":{"type":"boolean","default":false}}},"ApiKeyResponse":{"type":"object","properties":{"message":{"type":"string"},"apiKey":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"key_prefix":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"raw_key":{"type":"string","description":"⚠️ Se muestra UNA SOLA VEZ al ser creada"}}}}},"CreateUserRequest":{"type":"object","required":["email","nombre","rol","password"],"properties":{"email":{"type":"string","format":"email"},"nombre":{"type":"string","example":"Juan Pérez"},"rol":{"type":"string","enum":["ADMIN","MANAGER","USER"]},"password":{"type":"string","format":"password","minLength":8}}},"User":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"nombre":{"type":"string"},"rol":{"type":"string"},"activo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}},"CommercialCapabilitiesResponse":{"type":"object","properties":{"hasActiveCertificate":{"type":"boolean","example":false},"canIssueCommercial":{"type":"boolean","example":true},"supportedTypes":{"type":"array","items":{"type":"string"},"example":["01","03","11"]},"reason":{"type":"string","example":"Empresa sin certificado activo: habilitada para emisión comercial no fiscal."}}},"CommercialDocumentCreateRequest":{"type":"object","required":["tipo_documento","cuerpoDocumento"],"properties":{"tipo_documento":{"type":"string","enum":["01","03","11"],"example":"01"},"branch_id":{"type":"integer","example":1},"pos_id":{"type":"integer","example":1},"receptor":{"type":"object"},"cuerpoDocumento":{"type":"array","items":{"type":"object"}},"condicion_operacion":{"type":"integer","enum":[1,2],"example":1},"pagos":{"type":"array","items":{"type":"object"}},"observaciones":{"type":"string"}}},"CommercialDocumentResponse":{"type":"object","properties":{"id":{"type":"integer","example":1},"numero":{"type":"string","example":"COM-01-M001-2026-00000001"},"tipo_documento":{"type":"string","example":"01"},"total_pagar":{"type":"number","example":113},"estado":{"type":"string","enum":["EMITIDO_NO_TRIBUTARIO","CONVERTIDO","ANULADO"]},"created_at":{"type":"string","format":"date-time"}}},"CommercialConvertResponse":{"type":"object","properties":{"message":{"type":"string","example":"Comprobante comercial convertido a DTE fiscal exitosamente"},"commercial_document_id":{"type":"integer"},"dte_id":{"type":"integer"},"codigo_generacion":{"type":"string","format":"uuid"},"numero_control":{"type":"string"},"sello_recepcion":{"type":"string"},"estado":{"type":"string","example":"ACCEPTED"}}},"PurchaseCreateRequest":{"type":"object","required":["tipo_dte","numero_control","proveedor_nombre","total_compra"],"properties":{"tipo_dte":{"type":"string","enum":["03","14"],"example":"03"},"numero_control":{"type":"string","example":"DTE-03-M001P001-000000000000012"},"codigo_generacion":{"type":"string","format":"uuid"},"sello_recepcion":{"type":"string"},"fh_emision":{"type":"string","format":"date-time"},"proveedor_nombre":{"type":"string","example":"SERGIO GUEVARA"},"proveedor_nit":{"type":"string","example":"0614-010180-101-1"},"proveedor_nrc":{"type":"string","example":"123456-7"},"sector":{"type":"integer","enum":[1,2,3,4],"example":1},"total_gravado":{"type":"number","example":340},"monto_iva":{"type":"number","example":44.2},"total_compra":{"type":"number","example":384.2},"retencion_monto":{"type":"number","example":3.4}}},"IncomeWithholdingCreateRequest":{"type":"object","required":["codigo_retencion","monto_sujeto","monto","fecha"],"properties":{"codigo_retencion":{"type":"string","example":"22","description":"Código CAT-006 (22=Servicios profesionales 10% Art. 156)"},"monto_sujeto":{"type":"number","example":340},"porcentaje":{"type":"number","example":10},"monto":{"type":"number","example":34},"fecha":{"type":"string","format":"date","example":"2026-09-28"},"notas":{"type":"string"}}},"IncomeWithholdingResponse":{"type":"object","properties":{"id":{"type":"integer"},"numero":{"type":"string","example":"ISR-2026-00000001"},"purchase_id":{"type":"integer"},"estado":{"type":"string","enum":["EMITIDA","ANULADA"]},"monto":{"type":"number","example":34},"neto_pagado":{"type":"number","example":346.8}}},"TenantReportsResponse":{"type":"object","properties":{"reports":{"type":"object"},"totals":{"type":"object"},"kpis":{"type":"object"},"metadata":{"type":"object","properties":{"total_records":{"type":"integer"},"has_more":{"type":"boolean"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}},"ContactLeadRequest":{"type":"object","required":["empresa","email"],"properties":{"nombre":{"type":"string","example":"Carlos Mendoza"},"empresa":{"type":"string","example":"Distribuidora Cuscatlán"},"email":{"type":"string","format":"email","example":"carlos@cuscatlan.sv"},"telefono":{"type":"string","example":"+503 7123-4567"},"origen":{"type":"string","example":"login_modal"}}},"ContactLeadResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"message":{"type":"string"},"leadId":{"type":"integer"},"whatsappUrl":{"type":"string"}}},"ShiftOpenRequest":{"type":"object","required":["montoApertura"],"properties":{"branchId":{"type":"integer","example":1},"posId":{"type":"integer","example":1},"montoApertura":{"type":"number","example":50},"observaciones":{"type":"string","example":"Apertura de turno matutino"}}},"ShiftCloseRequest":{"type":"object","required":["montoDeclarado"],"properties":{"montoDeclarado":{"type":"number","example":320.5},"desgloseDeclarado":{"type":"object"},"observaciones":{"type":"string","example":"Cierre de turno sin faltantes"}}},"AccountPaymentRequest":{"type":"object","required":["monto"],"properties":{"monto":{"type":"number","example":75},"forma_pago":{"type":"string","example":"01","description":"Código CAT-017 (01=Efectivo, 02=Cheque, 03=Transferencia, etc.)"},"num_documento":{"type":"string","example":"TR-987654"},"notas":{"type":"string","example":"Abono parcial a factura"}}},"ContingencyBatchRequest":{"type":"object","required":["motivo","dtes"],"properties":{"motivo":{"type":"string","example":"Falla general en suministro eléctrico y telecomunicaciones"},"tipoContingencia":{"type":"integer","enum":[1,2,3,4],"example":1,"description":"CAT-005 (1=No disponibilidad sistema, 2=Falla energía, 3=Falla internet, 4=Otro)"},"dtes":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Lista de códigos de generación (UUID) emitidos en contingencia (máximo 50 por lote)","example":["242F3604-D500-482A-A9F4-EB7B4A7818AA"]}}},"EventoRetornoRequest":{"type":"object","required":["codigoGeneracion","motivo"],"properties":{"codigoGeneracion":{"type":"string","format":"uuid","description":"UUID del DTE emitido previamente a relacionar","example":"3B410659-A624-4646-B3A0-602F04047908"},"motivo":{"type":"string","example":"Devolución de mercaderías por daño de transporte"},"responsable":{"type":"object","properties":{"nombre":{"type":"string","example":"Juan Pérez"},"tipoDoc":{"type":"string","example":"13"},"numDoc":{"type":"string","example":"01234567-8"}}}}},"EventoOperacionesEspecialesRequest":{"type":"object","required":["codigoGeneracion","tipoOperacion","motivo"],"properties":{"codigoGeneracion":{"type":"string","format":"uuid","example":"3B410659-A624-4646-B3A0-602F04047908"},"tipoOperacion":{"type":"string","example":"01"},"motivo":{"type":"string","example":"Ajuste operativo de conformidad a resolución DGII"}}}}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"tags":[{"name":"Autenticación","description":"Login, logout, tokens y gestión de sesión"},{"name":"DTEs","description":"Emisión, consulta y anulación de Documentos Tributarios Electrónicos"},{"name":"DTEs Públicos","description":"Descarga pública de PDF y JSON (sin autenticación)"},{"name":"Comprobantes Comerciales","description":"Emisión no fiscal para empresas sin certificado y conversión segura a DTE"},{"name":"Compras y Retenciones","description":"Registro de compras fiscales y constancias de retención de renta ISR 10% (F14)"},{"name":"Reportes","description":"Analítica operativa, gerencial T-01 a T-07 y exportación multiformato (Excel/PDF)"},{"name":"Cuentas por Cobrar","description":"Gestión de cartera comercial, saldos y aplicación de abonos"},{"name":"Libros de IVA","description":"Libros de compras, ventas y generación de anexos oficiales F-07 y F-14"},{"name":"Sucursales y Cajas","description":"Establecimientos M001/P001, asignación de usuarios y control de turnos"},{"name":"Eventos y Contingencia","description":"Transmisión de lotes de contingencia y eventos especiales (Tipos 17 y 18)"},{"name":"Simulación / Demo","description":"Utilidades de prueba efímera y renderizado en memoria sin efectos fiscales"},{"name":"Tenants","description":"Gestión de empresas (multi-tenant)"},{"name":"Certificados","description":"Gestión de certificados digitales de firma electrónica"},{"name":"API Keys","description":"Gestión de credenciales M2M para integraciones"},{"name":"Usuarios","description":"Gestión RBAC de usuarios por empresa"},{"name":"Clientes","description":"Clientes / Receptores de la empresa"},{"name":"Productos","description":"Catálogo de productos y servicios"},{"name":"Catálogos","description":"Catálogos del Ministerio de Hacienda (departamentos, municipios, actividades)"},{"name":"Webhooks","description":"Configuración de notificaciones webhook"},{"name":"Configuración","description":"Ajustes SMTP y preferencias del tenant"},{"name":"Salud","description":"Health checks y diagnóstico del sistema"}],"paths":{"/auth/login":{"post":{"tags":["Autenticación"],"summary":"Iniciar sesión","description":"Obtener tokens JWT (access + refresh) con credenciales de usuario.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Login exitoso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"401":{"description":"Credenciales inválidas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cuenta desactivada"}}}},"/auth/refresh":{"post":{"tags":["Autenticación"],"summary":"Renovar access token","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Token renovado"},"401":{"description":"Refresh token inválido o revocado"}}}},"/auth/logout":{"post":{"tags":["Autenticación"],"summary":"Cerrar sesión (revocar refresh token)","responses":{"200":{"description":"Sesión cerrada"}}}},"/auth/contact-request":{"post":{"tags":["Autenticación"],"summary":"Registrar solicitud de asesoría comercial / Lead","description":"Registra un prospecto comercial desde el modal público de login o landing page, enviando notificación y retornando enlace para chat inmediato por WhatsApp.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactLeadRequest"}}}},"responses":{"201":{"description":"Lead registrado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactLeadResponse"}}}},"400":{"description":"Datos incompletos o error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dtes/{codigoGeneracion}/json":{"get":{"tags":["DTEs Públicos"],"summary":"Descargar DTE en JSON (público)","description":"Descarga el JSON firmado del DTE. Rate limit: 10 req/min.","security":[],"parameters":[{"name":"codigoGeneracion","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Archivo JSON del DTE","content":{"application/json":{}}},"404":{"description":"DTE no encontrado"}}}},"/dtes/{codigoGeneracion}/pdf":{"get":{"tags":["DTEs Públicos"],"summary":"Descargar DTE en PDF (público)","description":"Genera y descarga el PDF del DTE. Rate limit: 10 req/min.","security":[],"parameters":[{"name":"codigoGeneracion","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Archivo PDF","content":{"application/pdf":{}}},"404":{"description":"DTE no encontrado"}}}},"/dtes":{"get":{"tags":["DTEs"],"summary":"Listar DTEs del tenant","description":"Lista DTEs con filtros opcionales y paginación.","parameters":[{"name":"tipo_dte","in":"query","schema":{"type":"string","enum":["01","03","05","06","07","11","14"]}},{"name":"estado","in":"query","schema":{"type":"string","enum":["PENDING","ACCEPTED","REJECTED","CANCELLED"]}},{"name":"fecha_desde","in":"query","schema":{"type":"string","format":"date"}},{"name":"fecha_hasta","in":"query","schema":{"type":"string","format":"date"}},{"name":"receptor_num_doc","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Búsqueda libre por nombre, NIT o código"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Lista de DTEs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DTEListResponse"}}}}}},"post":{"tags":["DTEs"],"summary":"Emitir nuevo DTE","description":"Emite un nuevo DTE (Factura, CCF, etc.), lo firma electrónicamente y lo transmite al MH.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirDTERequest"}}}},"responses":{"201":{"description":"DTE emitido exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DTEResponse"}}}},"400":{"description":"Error de validación o certificado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No autenticado"}}}},"/dtes/anular":{"post":{"tags":["DTEs"],"summary":"Anular (invalidar) DTE","description":"Envía evento de invalidación al MH para anular un DTE previamente aceptado.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnularDTERequest"}}}},"responses":{"200":{"description":"DTE anulado exitosamente"},"400":{"description":"Error de validación (plazo vencido, estado incorrecto, etc.)"}}}},"/dtes/nota-credito":{"post":{"tags":["DTEs"],"summary":"Emitir Nota de Crédito (NCE)","description":"Emite una Nota de Crédito Electrónica referenciando un DTE existente.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirDTERequest"}}}},"responses":{"201":{"description":"NCE emitida exitosamente"},"400":{"description":"Error de validación"}}}},"/dtes/nota-debito":{"post":{"tags":["DTEs"],"summary":"Emitir Nota de Débito (NDE)","description":"Emite una Nota de Débito Electrónica referenciando un DTE existente.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirDTERequest"}}}},"responses":{"201":{"description":"NDE emitida exitosamente"},"400":{"description":"Error de validación"}}}},"/dtes/comprobante-retencion":{"post":{"tags":["DTEs"],"summary":"Emitir Comprobante de Retención (CRE)","description":"Emite un Comprobante de Retención Electrónico.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirDTERequest"}}}},"responses":{"201":{"description":"CRE emitido exitosamente"},"400":{"description":"Error de validación"}}}},"/dtes/factura-exportacion":{"post":{"tags":["DTEs"],"summary":"Emitir Factura de Exportación (FEX)","description":"Emite una Factura de Exportación Electrónica.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirDTERequest"}}}},"responses":{"201":{"description":"FEX emitida exitosamente"},"400":{"description":"Error de validación"}}}},"/tenants":{"get":{"tags":["Tenants"],"summary":"Listar todas las empresas (SysAdmin)","description":"Requiere rol SysAdmin.","responses":{"200":{"description":"Lista de tenants","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tenant"}}}}},"403":{"description":"Acceso denegado"}}}},"/tenants/{id}":{"get":{"tags":["Tenants"],"summary":"Obtener datos de empresa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Datos del tenant"},"404":{"description":"No encontrado"}}},"put":{"tags":["Tenants"],"summary":"Actualizar datos de empresa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"responses":{"200":{"description":"Tenant actualizado"}}}},"/tenants/{id}/certificate":{"get":{"tags":["Certificados"],"summary":"Ver certificado activo del tenant","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Información del certificado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateInfo"}}}}}},"post":{"tags":["Certificados"],"summary":"Subir certificado digital (.p12 / .pfx)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"certificate":{"type":"string","format":"binary","description":"Archivo .p12 o .pfx"},"password":{"type":"string","description":"Contraseña del certificado"}}}}}},"responses":{"200":{"description":"Certificado procesado y almacenado exitosamente"},"400":{"description":"Archivo o contraseña inválidos"}}}},"/tenants/{id}/mh-credentials":{"post":{"tags":["Tenants"],"summary":"Configurar credenciales MH","description":"Guardar la contraseña de integración y el ambiente del MH.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mh_password","mh_ambiente"],"properties":{"mh_password":{"type":"string"},"mh_ambiente":{"type":"string","enum":["dev","00","01"]}}}}}},"responses":{"200":{"description":"Credenciales guardadas"},"403":{"description":"No autorizado"}}}},"/tenants/{id}/logo":{"post":{"tags":["Tenants"],"summary":"Subir logo de empresa","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logo":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Logo subido exitosamente"}}}},"/apikeys":{"get":{"tags":["API Keys"],"summary":"Listar API Keys del tenant","responses":{"200":{"description":"Lista de API Keys (sin mostrar claves)"}}},"post":{"tags":["API Keys"],"summary":"Generar nueva API Key","description":"⚠️ La clave raw se muestra UNA SOLA VEZ en la respuesta.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateRequest"}}}},"responses":{"201":{"description":"API Key generada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}}}}},"/apikeys/{id}":{"delete":{"tags":["API Keys"],"summary":"Revocar API Key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"API Key revocada permanentemente"},"404":{"description":"No encontrada"}}}},"/users":{"get":{"tags":["Usuarios"],"summary":"Listar usuarios del tenant","description":"Solo accesible por rol ADMIN del tenant.","responses":{"200":{"description":"Lista de usuarios","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}}}}}},"post":{"tags":["Usuarios"],"summary":"Crear usuario en el tenant","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}}},"responses":{"201":{"description":"Usuario creado exitosamente"},"400":{"description":"Email duplicado o datos inválidos"}}}},"/users/{id}/status":{"put":{"tags":["Usuarios"],"summary":"Activar/Desactivar usuario","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"activo":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Estado actualizado"}}}},"/clients":{"get":{"tags":["Clientes"],"summary":"Listar clientes del tenant","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Buscar por nombre, NIT o NRC"}],"responses":{"200":{"description":"Lista de clientes"}}}},"/products":{"get":{"tags":["Productos"],"summary":"Listar productos del tenant","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lista de productos"}}}},"/catalogs/departamentos":{"get":{"tags":["Catálogos"],"summary":"Obtener departamentos de El Salvador","responses":{"200":{"description":"Lista de departamentos con códigos MH"}}}},"/catalogs/municipios":{"get":{"tags":["Catálogos"],"summary":"Obtener municipios por departamento","parameters":[{"name":"dept","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de municipios"}}}},"/catalogs/actividades":{"get":{"tags":["Catálogos"],"summary":"Buscar actividades económicas","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de actividades"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar webhooks configurados","responses":{"200":{"description":"Lista de webhooks"}}},"post":{"tags":["Webhooks"],"summary":"Crear webhook","description":"Registra un endpoint receptor de eventos fiscales y del sistema para el tenant actual.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","eventos"],"properties":{"url":{"type":"string","format":"uri","example":"https://miempresa.com/api/webhooks/raven"},"eventos":{"type":"array","items":{"type":"string","enum":["dte.created","dte.accepted","dte.rejected","dte.cancelled","certificate.uploaded","certificate.expired","contingency.activated","contingency.deactivated"]},"example":["dte.accepted","dte.rejected"]},"secret":{"type":"string","description":"Clave secreta compartida para validar firma HMAC-SHA256 (se autogenera si se omite)","example":"secreto-seguro-compartido"},"headers":{"type":"object","description":"Cabeceras HTTP personalizadas opcionales a incluir en cada disparo del webhook","example":{"X-Custom-Auth":"Token abc"}}}}}}},"responses":{"201":{"description":"Webhook registrado exitosamente","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Webhook registrado exitosamente"},"webhook":{"type":"object","properties":{"id":{"type":"integer","example":1},"tenant_id":{"type":"integer","example":1},"url":{"type":"string","example":"https://miempresa.com/api/webhooks/raven"},"eventos":{"type":"array","items":{"type":"string"},"example":["dte.accepted","dte.rejected"]},"secret":{"type":"string","example":"4a8b...64hex"},"activo":{"type":"boolean","example":true}}}}}}}},"400":{"description":"Parámetros inválidos o eventos no soportados"}}}},"/commercial-documents/capabilities":{"get":{"tags":["Comprobantes Comerciales"],"summary":"Consultar capacidades comerciales del tenant","description":"Determina si la empresa puede emitir comprobantes comerciales no tributarios (COM-01, COM-03, COM-11) por carecer de certificado digital activo ante MH.","responses":{"200":{"description":"Capacidades comerciales","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCapabilitiesResponse"}}}}}}},"/commercial-documents":{"get":{"tags":["Comprobantes Comerciales"],"summary":"Listar comprobantes comerciales","description":"Lista comprobantes comerciales emitidos por la empresa con paginación.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Número de página"}],"responses":{"200":{"description":"Listado de comprobantes comerciales","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/CommercialDocumentResponse"}},"total":{"type":"integer"},"page":{"type":"integer"}}}}}}}},"post":{"tags":["Comprobantes Comerciales"],"summary":"Emitir comprobante comercial no fiscal","description":"Emite comprobante no tributario con serie COM-XX y genera representación PDF propia sin firma ni sellos fiscales de Hacienda.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialDocumentCreateRequest"}}}},"responses":{"201":{"description":"Comprobante comercial emitido exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialDocumentResponse"}}}},"422":{"description":"Error de validación comercial"}}}},"/commercial-documents/{id}":{"get":{"tags":["Comprobantes Comerciales"],"summary":"Obtener detalle de comprobante comercial","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Detalle del comprobante comercial"},"404":{"description":"Comprobante no encontrado"}}}},"/commercial-documents/{id}/pdf":{"get":{"tags":["Comprobantes Comerciales"],"summary":"Descargar PDF de comprobante comercial","description":"Descarga la representación gráfica en PDF con membrete propio de RAVEN Commercial.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Documento PDF","content":{"application/pdf":{}}},"404":{"description":"Comprobante no encontrado"}}}},"/commercial-documents/{id}/convert":{"post":{"tags":["Comprobantes Comerciales"],"summary":"Convertir comprobante comercial a DTE fiscal oficial","description":"Convierte un comprobante comercial pre-existente en un DTE fiscal transmitido al MH con fecha actual y firma digital RS512.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"boolean","example":true,"description":"Confirmación explícita para emisión fiscal con fecha actual"}}}}}},"responses":{"200":{"description":"Comprobante convertido a DTE fiscal exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialConvertResponse"}}}},"422":{"description":"Error en la conversión o rechazo tributario"}}}},"/purchases":{"get":{"tags":["Compras y Retenciones"],"summary":"Listar compras fiscales del tenant","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"sector","in":"query","schema":{"type":"integer","enum":[1,2,3,4]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Listado de compras registradas"}}}},"/purchases/import":{"post":{"tags":["Compras y Retenciones"],"summary":"Importar DTE JSON de compra","description":"Importa un JSON de DTE recibido de un proveedor para registrarlo automáticamente en el libro de compras.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonDte"],"properties":{"jsonDte":{"type":"object","description":"Objeto JSON del DTE emitido por el proveedor"},"sector":{"type":"integer","enum":[1,2,3,4],"default":1,"description":"Sector tributario F-07 (1=Comercio, 2=Servicios, 3=Industria, 4=Construcción)"}}}}}},"responses":{"201":{"description":"Compra importada exitosamente"},"400":{"description":"DTE inválido o duplicado"}}}},"/purchases/{id}":{"get":{"tags":["Compras y Retenciones"],"summary":"Obtener detalle de compra fiscal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Detalle de compra"},"404":{"description":"No encontrada"}}},"delete":{"tags":["Compras y Retenciones"],"summary":"Eliminar registro de compra","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Compra eliminada"},"404":{"description":"No encontrada"}}}},"/purchases/{id}/sector":{"patch":{"tags":["Compras y Retenciones"],"summary":"Actualizar sector tributario de compra (F-07)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sector"],"properties":{"sector":{"type":"integer","enum":[1,2,3,4],"example":1}}}}}},"responses":{"200":{"description":"Sector tributario actualizado"}}}},"/purchases/{id}/retencion":{"post":{"tags":["Compras y Retenciones"],"summary":"Emitir Comprobante de Retención 1% (CRE 07) sobre compra","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"CRE 07 emitido y transmitido exitosamente"},"400":{"description":"Error al emitir retención"}}}},"/purchases/{id}/retenciones-renta":{"get":{"tags":["Compras y Retenciones"],"summary":"Listar constancias de retención de renta ISR 10% (Art. 156 CT)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resumen y lista de constancias ISR emitidas sobre la compra"}}},"post":{"tags":["Compras y Retenciones"],"summary":"Emitir constancia de retención de renta ISR 10%","description":"Registra constancia independiente de retención de renta ISR (10% por servicios profesionales, Art. 156 CT / Anexo F14).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomeWithholdingCreateRequest"}}}},"responses":{"201":{"description":"Constancia de retención ISR generada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomeWithholdingResponse"}}}},"400":{"description":"Error en cálculo o compra no sujeta a retención"}}}},"/purchases/{id}/retenciones-renta/{retentionId}/pdf":{"get":{"tags":["Compras y Retenciones"],"summary":"Descargar PDF de constancia de retención ISR","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"retentionId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Constancia ISR en PDF","content":{"application/pdf":{}}},"404":{"description":"Constancia no encontrada"}}}},"/purchases/{id}/retenciones-renta/{retentionId}/anular":{"post":{"tags":["Compras y Retenciones"],"summary":"Anular constancia de retención ISR","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"retentionId","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"motivo":{"type":"string","example":"Error en monto de honorarios"}}}}}},"responses":{"200":{"description":"Constancia ISR anulada"}}}},"/reports/tenant":{"get":{"tags":["Reportes"],"summary":"Consultar reporte analítico del tenant (T-01 a T-07)","description":"Obtiene reportes operativos y gerenciales calculados sobre el 100% de la base de datos con paginación limpia (T-01 Ventas, T-02 Detalle DTEs, T-03 Clientes, T-04 Compras, T-05 CxC, T-06 Inventario, T-07 Anulaciones).","parameters":[{"name":"codes","in":"query","schema":{"type":"string","example":"T-01,T-02"},"description":"Códigos de reporte separados por coma"},{"name":"fecha_desde","in":"query","schema":{"type":"string","format":"date"}},{"name":"fecha_hasta","in":"query","schema":{"type":"string","format":"date"}},{"name":"branch_id","in":"query","schema":{"type":"integer"}},{"name":"pos_id","in":"query","schema":{"type":"integer"}},{"name":"ambiente","in":"query","schema":{"type":"string","enum":["00","01"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Reporte generado con totales y KPIs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantReportsResponse"}}}}}}},"/reports/export":{"get":{"tags":["Reportes"],"summary":"Exportar reporte analítico en Excel (.xlsx) o PDF apaisado","description":"Exporta el universo filtrado completo (sin truncamiento) en libro Excel multihoja o documento PDF apaisado con métricas KPI ejecutivas.","parameters":[{"name":"codes","in":"query","schema":{"type":"string","example":"T-01"}},{"name":"single_code","in":"query","schema":{"type":"string","example":"T-01"}},{"name":"format","in":"query","schema":{"type":"string","enum":["xlsx","pdf"],"default":"xlsx"}},{"name":"fecha_desde","in":"query","schema":{"type":"string","format":"date"}},{"name":"fecha_hasta","in":"query","schema":{"type":"string","format":"date"}},{"name":"branch_id","in":"query","schema":{"type":"integer"}},{"name":"pos_id","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Archivo exportado","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{},"application/pdf":{}}}}}},"/accounts-receivable":{"get":{"tags":["Cuentas por Cobrar"],"summary":"Listar cuentas por cobrar","parameters":[{"name":"estado","in":"query","schema":{"type":"string","enum":["PENDIENTE","PAGADO","VENCIDO"]}},{"name":"clientId","in":"query","schema":{"type":"integer"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Listado de cuentas por cobrar"}}}},"/accounts-receivable/stats":{"get":{"tags":["Cuentas por Cobrar"],"summary":"Métricas generales de cartera CxC","responses":{"200":{"description":"Resumen consolidado de saldos pendientes y vencidos"}}}},"/accounts-receivable/sync":{"post":{"tags":["Cuentas por Cobrar"],"summary":"Sincronizar DTEs a crédito pendientes retroactivamente","responses":{"200":{"description":"Sincronización completada"}}}},"/accounts-receivable/{id}":{"get":{"tags":["Cuentas por Cobrar"],"summary":"Detalle de cuenta por cobrar y abonos","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Detalle de cuenta"},"404":{"description":"No encontrada"}}}},"/accounts-receivable/{id}/payments":{"post":{"tags":["Cuentas por Cobrar"],"summary":"Registrar abono / pago a cuenta por cobrar","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPaymentRequest"}}}},"responses":{"201":{"description":"Abono registrado exitosamente"},"400":{"description":"Monto inválido o excede saldo"}}}},"/accounts-receivable/payments/{paymentId}":{"delete":{"tags":["Cuentas por Cobrar"],"summary":"Revertir / anular abono registrado","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Abono revertido"},"400":{"description":"Error al revertir"}}}},"/accounts-receivable/payments/{paymentId}/ticket":{"get":{"tags":["Cuentas por Cobrar"],"summary":"Generar ticket térmico de comprobante de abono (HTML)","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"width","in":"query","schema":{"type":"string","enum":["58","80"],"default":"80"}}],"responses":{"200":{"description":"Ticket térmico en HTML auto-imprimible","content":{"text/html":{}}},"404":{"description":"Abono no encontrado"}}}},"/iva-books/settings":{"get":{"tags":["Libros de IVA"],"summary":"Consultar configuración fiscal de libros de IVA","responses":{"200":{"description":"Configuración actual"}}},"put":{"tags":["Libros de IVA"],"summary":"Actualizar configuración fiscal de libros de IVA","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resolucion_emision":{"type":"string"},"serie_autorizada":{"type":"string"},"foliado_inicial":{"type":"integer"}}}}}},"responses":{"200":{"description":"Configuración actualizada"}}}},"/iva-books/periods/{periodo}":{"get":{"tags":["Libros de IVA"],"summary":"Resumen fiscal de período tributario (YYYY-MM)","parameters":[{"name":"periodo","in":"path","required":true,"schema":{"type":"string","example":"2026-10"}},{"name":"ambiente","in":"query","schema":{"type":"string","enum":["00","01"]}}],"responses":{"200":{"description":"Resumen fiscal del período"}}}},"/iva-books/periods/{periodo}/annexes/{key}/csv":{"get":{"tags":["Libros de IVA"],"summary":"Exportar anexo oficial en CSV (; windows-1252)","description":"Genera anexo oficial (F-07 ventas contribuyente/consumidor/exportación o F-14 retenciones) con formato exacto para el portal del Ministerio de Hacienda.","parameters":[{"name":"periodo","in":"path","required":true,"schema":{"type":"string","example":"2026-10"}},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"f07_ventas_contribuyentes"}},{"name":"ambiente","in":"query","schema":{"type":"string","enum":["00","01"]}}],"responses":{"200":{"description":"Archivo CSV descargado","content":{"text/csv; charset=windows-1252":{}}},"404":{"description":"Anexo o período no encontrado"}}}},"/iva-books/periods/{periodo}/close":{"post":{"tags":["Libros de IVA"],"summary":"Cerrar formalmente período tributario","description":"Genera snapshot inmutable de libros de IVA para el período y ambiente especificados.","parameters":[{"name":"periodo","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Período cerrado exitosamente"}}}},"/iva-books/periods/{periodo}/reopen":{"post":{"tags":["Libros de IVA"],"summary":"Reabrir período tributario cerrado","parameters":[{"name":"periodo","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"motivo":{"type":"string","example":"Inclusión de compras tardías aprobadas"}}}}}},"responses":{"200":{"description":"Período reabierto"}}}},"/iva-books/periods/{periodo}/late-purchases/{purchaseId}":{"post":{"tags":["Libros de IVA"],"summary":"Asignar / desasignar compra extemporánea a período","parameters":[{"name":"periodo","in":"path","required":true,"schema":{"type":"string"}},{"name":"purchaseId","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"include":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Estado de compra extemporánea actualizado"}}}},"/branches":{"get":{"tags":["Sucursales y Cajas"],"summary":"Listar sucursales y bodegas del tenant","parameters":[{"name":"active","in":"query","schema":{"type":"boolean"}},{"name":"with_pos","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Lista de sucursales"}}}},"/branches/main":{"get":{"tags":["Sucursales y Cajas"],"summary":"Obtener Casa Matriz del tenant (M001)","responses":{"200":{"description":"Datos de la Casa Matriz"}}}},"/shifts":{"get":{"tags":["Sucursales y Cajas"],"summary":"Listar historial de turnos de caja","parameters":[{"name":"branch_id","in":"query","schema":{"type":"integer"}},{"name":"pos_id","in":"query","schema":{"type":"integer"}},{"name":"user_id","in":"query","schema":{"type":"integer"}},{"name":"estado","in":"query","schema":{"type":"string","enum":["ABIERTO","CERRADO"]}}],"responses":{"200":{"description":"Historial de turnos"}}}},"/shifts/active":{"get":{"tags":["Sucursales y Cajas"],"summary":"Consultar turno activo para una caja","parameters":[{"name":"pos_id","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Turno activo o null"}}}},"/shifts/open":{"post":{"tags":["Sucursales y Cajas"],"summary":"Abrir turno de caja POS","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShiftOpenRequest"}}}},"responses":{"201":{"description":"Turno de caja abierto"},"400":{"description":"Ya existe turno activo"}}}},"/shifts/{id}/summary":{"get":{"tags":["Sucursales y Cajas"],"summary":"Resumen de ventas del turno (pre-arqueo)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Resumen de ventas por forma de pago"},"404":{"description":"Turno no encontrado"}}}},"/shifts/{id}/close":{"post":{"tags":["Sucursales y Cajas"],"summary":"Cerrar turno de caja y asentar arqueo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShiftCloseRequest"}}}},"responses":{"200":{"description":"Turno de caja cerrado exitosamente"},"400":{"description":"Error al cerrar turno"}}}},"/shifts/{id}/ticket":{"get":{"tags":["Sucursales y Cajas"],"summary":"Generar ticket térmico de corte de caja (HTML)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"width","in":"query","schema":{"type":"string","enum":["58","80"],"default":"80"}}],"responses":{"200":{"description":"Ticket de corte de caja en HTML","content":{"text/html":{}}},"404":{"description":"Turno no encontrado"}}}},"/dtes/eventos/retorno":{"post":{"tags":["Eventos y Contingencia"],"summary":"Emitir Evento de Retorno de Mercancías (Tipo 18)","description":"Transmite evento oficial de Retorno de mercancías o servicios ante el Ministerio de Hacienda (esquema fe-eret-v1).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventoRetornoRequest"}}}},"responses":{"201":{"description":"Evento de Retorno transmitido exitosamente"},"400":{"description":"Error de validación o rechazo MH"}}}},"/dtes/eventos/operaciones-especiales":{"post":{"tags":["Eventos y Contingencia"],"summary":"Emitir Evento de Operaciones Especiales (Tipo 17)","description":"Transmite evento oficial de Operaciones Especiales ante el Ministerio de Hacienda (esquema fe-eop-v1).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventoOperacionesEspecialesRequest"}}}},"responses":{"201":{"description":"Evento de Operaciones Especiales transmitido exitosamente"},"400":{"description":"Error de validación o rechazo MH"}}}},"/dtes/eventos/historial":{"get":{"tags":["Eventos y Contingencia"],"summary":"Consultar historial de eventos tributarios del tenant","parameters":[{"name":"ambiente","in":"query","schema":{"type":"string","enum":["00","01"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Historial de eventos transmitidos"}}}},"/contingency/pending":{"get":{"tags":["Eventos y Contingencia"],"summary":"Listar DTEs en contingencia pendientes de lote","responses":{"200":{"description":"Lista de comprobantes pendientes"}}}},"/contingency/transmit-batch":{"post":{"tags":["Eventos y Contingencia"],"summary":"Transmitir lote de contingencia al MH","description":"Agrupa hasta 50 comprobantes emitidos en contingencia y genera el evento de contingencia normativo ante el Ministerio de Hacienda.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContingencyBatchRequest"}}}},"responses":{"200":{"description":"Lote de contingencia transmitido exitosamente"},"400":{"description":"Error al transmitir lote"}}}},"/contingency/events":{"get":{"tags":["Eventos y Contingencia"],"summary":"Historial de eventos de contingencia","responses":{"200":{"description":"Eventos de contingencia"}}}},"/contingency/stats":{"get":{"tags":["Eventos y Contingencia"],"summary":"Estadísticas de contingencia del tenant","responses":{"200":{"description":"Métricas de contingencia"}}}},"/simulation/catalog":{"get":{"tags":["Simulación / Demo"],"summary":"Catálogo de datos de prueba y simulación (público)","description":"Retorna datos comerciales públicos de productos, clientes de prueba y catálogos para alimentar el Modo Demo interactivo.","security":[],"responses":{"200":{"description":"Catálogo de prueba"}}}},"/simulation/render-pdf":{"post":{"tags":["Simulación / Demo"],"summary":"Renderizar PDF efímero de DTE simulado","description":"Genera representación PDF en memoria sin escribir en base de datos ni interactuar con el Ministerio de Hacienda.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["record"],"properties":{"record":{"type":"object"},"company":{"type":"object"}}}}}},"responses":{"200":{"description":"Documento PDF simulado","content":{"application/pdf":{}}},"400":{"description":"Estructura inválida"}}}},"/simulation/render-income-pdf":{"post":{"tags":["Simulación / Demo"],"summary":"Renderizar PDF efímero de constancia ISR simulada","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["record"],"properties":{"record":{"type":"object"}}}}}},"responses":{"200":{"description":"Constancia ISR en PDF","content":{"application/pdf":{}}},"400":{"description":"Estructura inválida"}}}},"/simulation/render-report-pdf":{"post":{"tags":["Simulación / Demo"],"summary":"Renderizar PDF efímero de reporte simulado","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reportData"],"properties":{"reportData":{"type":"object"},"singleCode":{"type":"string","example":"T-01"}}}}}},"responses":{"200":{"description":"Reporte simulado en PDF","content":{"application/pdf":{}}},"400":{"description":"Estructura inválida"}}}},"/health":{"get":{"tags":["Salud"],"summary":"Health check básico","security":[],"responses":{"200":{"description":"Sistema operativo"}}}},"/health/detailed":{"get":{"tags":["Salud"],"summary":"Health check detallado (Restringido a SysAdmin o red interna)","description":"Diagnóstico detallado del estado operativo de componentes (PostgreSQL, Redis, Ministerio de Hacienda MH). Por motivos de seguridad para prevenir enumeración de infraestructura, este endpoint está restringido a llamadas de red interna / loopback o a administradores globales autenticados con token SysAdmin (BearerAuth). Peticiones públicas o externas sin credenciales de SysAdmin son rechazadas con HTTP 403 Forbidden.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Estado detallado de todos los servicios (DB, Redis, MH, etc.)"},"403":{"description":"Acceso restringido: requiere token de SysAdmin o red interna (código HEALTH_DETAILED_FORBIDDEN)"}}}}}}