{
    "openapi": "3.0.3",
    "info": {
        "title": "API Facturación Electrónica DIAN Colombia (UBL 2.1)",
        "description": "Especificación interactiva de la API REST para emisión, firma digital XAdES-EPES, compresión ZIP y validación en vivo de documentos electrónicos ante la DIAN conforme al Anexo Técnico 1.9.",
        "version": "1.0.0",
        "contact": {
            "name": "Soporte Técnico Facturación DIAN"
        }
    },
    "servers": [
        {
            "url": "http://localhost:8085",
            "description": "Servidor Local IIS"
        },
        {
            "url": "/",
            "description": "Servidor Actual"
        }
    ],
    "components": {
        "securitySchemes": {
            "PartnerKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Partner-Key",
                "description": "Clave de Partner para administración multi-empresa (dian_partner_...)"
            },
            "BearerCompanyAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "API Key",
                "description": "Token de emisión de la empresa (dian_live_...)"
            },
            "AdminKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Admin-Key",
                "description": "Clave maestra de Super Administrador"
            }
        }
    },
    "paths": {
        "/api/health": {
            "get": {
                "tags": [
                    "Salud del Sistema"
                ],
                "summary": "Health Check del Servicio",
                "description": "Verifica el estado del servicio, conexión a PostgreSQL y tiempo de respuesta.",
                "responses": {
                    "200": {
                        "description": "Servicio operando con normalidad",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "healthy",
                                    "app": "FacturacionElectronica",
                                    "environment": "local",
                                    "timestamp": "2026-10-14T11:59:00-05:00",
                                    "php_version": "8.5.11",
                                    "database": {
                                        "status": "connected",
                                        "driver": "pgsql",
                                        "database": "facturacionelectronica_torres"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/companies": {
            "get": {
                "tags": [
                    "Gestión de Empresas (Partner)"
                ],
                "summary": "Listar Empresas del Partner",
                "description": "Retorna exclusivamente las empresas que pertenecen a la cuenta del Partner autenticado.",
                "security": [
                    {
                        "PartnerKeyAuth": []
                    },
                    {
                        "AdminKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista de empresas"
                    }
                }
            },
            "post": {
                "tags": [
                    "Gestión de Empresas (Partner)"
                ],
                "summary": "Crear Nueva Empresa Hija",
                "description": "Registra una nueva empresa en el sistema y retorna automáticamente su 'api_token' de emisión.",
                "security": [
                    {
                        "PartnerKeyAuth": []
                    },
                    {
                        "AdminKeyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "nit": "901999888",
                                "business_name": "Empresa Cliente Aliada S.A.S.",
                                "trade_name": "Cliente Aliado",
                                "document_type": "31",
                                "taxpayer_type": "1",
                                "tax_scheme": "01",
                                "tax_level_code": "O-48",
                                "address": "Carrera 15 # 93-60",
                                "city_code": "11001",
                                "city_name": "Bogotá, D.C.",
                                "department_code": "11",
                                "department_name": "Bogotá",
                                "email": "facturacion@clientealiado.com",
                                "environment": "habilitacion",
                                "software_id": "313c1a3d-6415-4614-a643-ffc44c04ea7e",
                                "software_pin": "12345",
                                "test_set_id": "9f49bbee-c805-4386-984d-848e7243d558"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Empresa creada exitosamente con su token de emisión"
                    }
                }
            }
        },
        "/api/company": {
            "get": {
                "tags": [
                    "Mi Empresa"
                ],
                "summary": "Consultar Datos de Mi Empresa",
                "description": "Retorna el perfil, ambiente y estado de certificado de la empresa autenticada.",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Datos de la empresa"
                    }
                }
            },
            "put": {
                "tags": [
                    "Mi Empresa"
                ],
                "summary": "Actualizar Datos de Mi Empresa",
                "description": "Permite modificar datos de contacto, software DIAN o ambiente.",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "business_name": "Empresa Actualizada S.A.S.",
                                "phone": "3013988094",
                                "email": "contacto@miempresa.com",
                                "environment": "produccion"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Empresa actualizada"
                    }
                }
            }
        },
        "/api/companies/{company}/certificate": {
            "post": {
                "tags": [
                    "Certificado Digital"
                ],
                "summary": "Cargar Certificado Digital (.p12 / .pfx)",
                "description": "Sube el certificado digital en formato Base64 o binario multipart.",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    },
                    {
                        "PartnerKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "company",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "name": "Certificado Digital 2026",
                                "certificate_base64": "MIIKogIBAzCCCm8GCSqGSIb3DQEHA...",
                                "password": "clave_del_certificado"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Certificado cargado y validado"
                    }
                }
            }
        },
        "/api/resolutions": {
            "get": {
                "tags": [
                    "Resoluciones de Facturación"
                ],
                "summary": "Listar Resoluciones",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista de resoluciones vigentes"
                    }
                }
            },
            "post": {
                "tags": [
                    "Resoluciones de Facturación"
                ],
                "summary": "Registrar Rango de Numeración",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "resolution_number": "18760000001",
                                "resolution_date": "2024-01-19",
                                "prefix": "SETP",
                                "from_number": 990000000,
                                "to_number": 995000000,
                                "valid_date_from": "2024-01-19",
                                "valid_date_to": "2030-01-19",
                                "technical_key": "fc8eac422eba16e22ffd8c6f94b3f40a6e38162c",
                                "document_type": "01",
                                "is_active": true
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Resolución registrada exitosamente"
                    }
                }
            }
        },
        "/api/resolutions/dian-query": {
            "get": {
                "tags": [
                    "Resoluciones de Facturación"
                ],
                "summary": "Consultar Rangos Autorizados en DIAN (GetNumberingRange)",
                "description": "Consulta en tiempo real vía SOAP WebService oficial de la DIAN los rangos de numeración autorizados y asociados al Software ID de la empresa, retornando prefijo, fechas, clave técnica y si ya está registrada.",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Rangos de numeración obtenidos de la DIAN",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Rangos de numeración consultados exitosamente desde la DIAN.",
                                    "total_found": 1,
                                    "numbering_ranges": [
                                        {
                                            "resolution_number": "18764000001",
                                            "prefix": "SETP",
                                            "resolution_date": "2026-01-01",
                                            "from_number": 990000000,
                                            "to_number": 995000000,
                                            "valid_date_from": "2026-01-01",
                                            "valid_date_to": "2027-01-01",
                                            "technical_key": "fc8eac422eba16e22ffd8c6f94b3f40a6e38162c",
                                            "is_registered": false,
                                            "registered_resolution_id": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Error al comunicar con el WebService de la DIAN o falta de certificado/software ID"
                    }
                }
            }
        },
        "/api/customers": {
            "post": {
                "tags": [
                    "Clientes (Adquirentes)"
                ],
                "summary": "Registrar Cliente / Adquirente",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "identification_number": "1020304050",
                                "document_type": "13",
                                "business_name": "Juan Pérez Gómez",
                                "tax_scheme": "01",
                                "tax_level_code": "R-99-PN",
                                "address": "Calle 100 # 15 - 30",
                                "city_code": "11001",
                                "city_name": "Bogotá, D.C.",
                                "department_code": "11",
                                "department_name": "Bogotá",
                                "country_code": "CO",
                                "phone": "3109876543",
                                "email": "cliente.prueba@ejemplo.com"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Cliente registrado exitosamente"
                    }
                }
            }
        },
        "/api/invoices": {
            "post": {
                "tags": [
                    "Facturación Electrónica"
                ],
                "summary": "Crear Factura Borrador (DRAFT)",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "customer_id": 2,
                                "payment_means_code": "1",
                                "payment_method_code": "10",
                                "notes": "Servicios de software",
                                "lines": [
                                    {
                                        "item_code": "SERV-01",
                                        "item_description": "Licenciamiento Mensual",
                                        "quantity": 1,
                                        "unit_price": 100000,
                                        "tax_percent": 19
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Factura borrador creada con cálculos y CUFE preliminar"
                    }
                }
            }
        },
        "/api/invoices/{invoice}/send": {
            "post": {
                "tags": [
                    "Facturación Electrónica"
                ],
                "summary": "Emitir y Transmitir a la DIAN",
                "description": "Firma digitalmente en XAdES-EPES, empaqueta en ZIP, transmite vía SOAP y devuelve el veredicto oficial DIAN de validación en tiempo real.",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "invoice",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Respuesta con resultado oficial de la DIAN",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Proceso de emisión DIAN ejecutado exitosamente.",
                                    "dian_result": {
                                        "track_id": "a546feb5-9357-4ac5-8c5c-1fb3360b0ffb",
                                        "error_messages": []
                                    },
                                    "invoice": {
                                        "id": 25,
                                        "full_number": "SETP990000020",
                                        "prefix": "SETP",
                                        "number": 990000020,
                                        "dian_status": "validated",
                                        "dian_status_label": "Validado",
                                        "cufe": "f8a05c754d9c79faef51590b1bf418a0026e47f9850...",
                                        "track_id": "a546feb5-9357-4ac5-8c5c-1fb3360b0ffb",
                                        "dian_url": "https://vpfe-hab.dian.gov.co/WcfDianCustomerServices.svc?wsdl",
                                        "dian_verification_url": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=f8a05c754d9c79faef51590b1bf418a0026e47f9850...",
                                        "dian_environment": "habilitacion",
                                        "dian_environment_label": "Habilitación (Pruebas)",
                                        "issue_date": "2026-10-15",
                                        "issue_time": "02:15:00-05:00",
                                        "created_at": "2026-10-15T02:14:30-05:00",
                                        "sent_at": "2026-10-15T02:15:01-05:00",
                                        "validated_at": "2026-10-15T02:15:02-05:00"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/invoices/{invoice}/xml": {
            "get": {
                "tags": [
                    "Facturación Electrónica"
                ],
                "summary": "Descargar XML Firmado UBL 2.1",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "invoice",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Archivo XML UBL 2.1 firmado electrónicamente"
                    }
                }
            }
        },
        "/api/credit-notes": {
            "post": {
                "tags": [
                    "Notas Crédito"
                ],
                "summary": "Crear Nota Crédito",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "invoice_id": 25,
                                "correction_code": "1",
                                "correction_reason": "Devolución o anulación acordada"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Nota crédito creada"
                    }
                }
            }
        },
        "/api/credit-notes/{creditNote}/send": {
            "post": {
                "tags": [
                    "Notas Crédito"
                ],
                "summary": "Transmitir Nota Crédito a la DIAN",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "creditNote",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Nota crédito transmitida"
                    }
                }
            }
        },
        "/api/documents": {
            "get": {
                "tags": [
                    "Historial de Documentos"
                ],
                "summary": "Consultar Todos los Documentos de la Empresa",
                "description": "Historial unificado de facturas y notas crédito con filtros y paginación.",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 15
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "invoice",
                                "credit_note",
                                "support_document",
                                "support_document_adjustment"
                            ]
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "draft",
                                "sent",
                                "validated",
                                "rejected"
                            ]
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Historial consolidado con metadatos y enlaces de descarga"
                    }
                }
            }
        },
        "/api/support-documents": {
            "get": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Listar Documentos Soporte",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "document_type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "05",
                                "95"
                            ]
                        }
                    },
                    {
                        "name": "dian_status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listado paginado de documentos soporte y notas de ajuste"
                    }
                }
            },
            "post": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Crear Documento Soporte (Tipo 05)",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "customer_id": 1,
                                "operation_type": "10",
                                "payment_means_code": "1",
                                "payment_method_code": "10",
                                "notes": "Pago por servicios profesionales o mantenimiento",
                                "lines": [
                                    {
                                        "item_code": "SRV-01",
                                        "item_description": "Servicios prestados por sujeto no obligado",
                                        "quantity": 1,
                                        "unit_price": 350000,
                                        "tax_percent": 0,
                                        "retention_percent": 4,
                                        "retention_amount": 14000,
                                        "retention_type": "06"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Documento soporte borrador creado exitosamente"
                    }
                }
            }
        },
        "/api/support-documents/{supportDocument}": {
            "get": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Consultar Documento Soporte por ID",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "supportDocument",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detalle del documento con líneas y estado DIAN"
                    }
                }
            }
        },
        "/api/support-documents/{supportDocument}/send": {
            "post": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Emitir Documento Soporte a la DIAN",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "supportDocument",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resultado de validación sincrónica de la DIAN"
                    }
                }
            }
        },
        "/api/support-documents/{supportDocument}/adjustments": {
            "post": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Crear Nota de Ajuste de Documento Soporte (Tipo 95)",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "supportDocument",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "discrepancy_code": "2",
                                "discrepancy_description": "Anulación del documento soporte",
                                "notes": "Ajuste convenido con el proveedor"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Nota de ajuste creada"
                    }
                }
            }
        },
        "/api/support-documents/{supportDocument}/send-adjustment": {
            "post": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Emitir Nota de Ajuste a la DIAN",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "supportDocument",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resultado de validación DIAN"
                    }
                }
            }
        },
        "/api/support-documents/{supportDocument}/status": {
            "get": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Consultar Estado DIAN por TrackID",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "supportDocument",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Estado en DIAN"
                    }
                }
            }
        },
        "/api/support-documents/{supportDocument}/xml": {
            "get": {
                "tags": [
                    "Documentos Soporte"
                ],
                "summary": "Descargar XML Firmado",
                "security": [
                    {
                        "BearerCompanyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "supportDocument",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Archivo XML UBL 2.1 firmado"
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "Documentos Soporte",
            "description": "Emisión y ajuste de Documentos Soporte en Adquisiciones Efectuadas a Sujetos No Obligados a Facturar (Tipo 05) y Notas de Ajuste (Tipo 95)."
        }
    ]
}