{
  "openapi": "3.0.3",
  "info": {
    "title": "DevByteX Facturador SUNAT API",
    "description": "API REST multi-tenant y multi-proyecto para facturación electrónica con la SUNAT (Perú) bajo el estándar UBL 2.1 sin intermediarios OSE ni PSE.",
    "version": "1.0.0",
    "contact": {
      "name": "DevByteX Soporte Técnico",
      "url": "https://devbytex.com"
    }
  },
  "servers": [
    {
      "url": "https://sunat.devbytex.com/api/v1",
      "description": "Servidor de Producción / Beta Cloud"
    },
    {
      "url": "http://localhost:8088/api/v1",
      "description": "Entorno Local Docker"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "ApiSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Secret"
      },
      "MasterKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Master-Key"
      }
    },
    "schemas": {
      "Cliente": {
        "type": "object",
        "required": ["tipo_doc", "num_doc", "razon_social"],
        "properties": {
          "tipo_doc": { "type": "string", "example": "6", "description": "6: RUC, 1: DNI, 4: CE, 7: Pasaporte, 0: Doc No Domiciliado" },
          "num_doc": { "type": "string", "example": "20555666777" },
          "razon_social": { "type": "string", "example": "CONFECCIONES INDUSTRIALES LIMA S.A.C." },
          "direccion": { "type": "string", "example": "Av. Los Fresnos 450, San Isidro - Lima" },
          "email": { "type": "string", "example": "facturacion@confeccioneslima.com" }
        }
      },
      "ItemComprobante": {
        "type": "object",
        "required": ["descripcion", "cantidad", "precio_unitario"],
        "properties": {
          "codigo": { "type": "string", "example": "POLO-01" },
          "descripcion": { "type": "string", "example": "Polo Algodón Pima 50/1 Cuello Redondo - Talla M" },
          "unidad": { "type": "string", "example": "NIU", "description": "Unidad de medida según Catálogo 03 SUNAT" },
          "cantidad": { "type": "number", "example": 12 },
          "precio_unitario": { "type": "number", "example": 35.00, "description": "Precio unitario final de venta (con IGV incluido)" },
          "tip_afe_igv": { "type": "string", "example": "10", "description": "10: Gravado, 20: Exonerado, 30: Inafecto" }
        }
      },
      "FacturaRequest": {
        "type": "object",
        "required": ["serie", "correlativo", "cliente", "items"],
        "properties": {
          "tipo_doc": { "type": "string", "example": "01" },
          "serie": { "type": "string", "example": "F001" },
          "correlativo": { "type": "integer", "example": 1 },
          "fecha_emision": { "type": "string", "format": "date", "example": "2026-11-03" },
          "tipo_moneda": { "type": "string", "example": "PEN" },
          "forma_pago": { "type": "string", "example": "Contado" },
          "observacion": { "type": "string", "example": "Orden de Compra OC-2026-889" },
          "cliente": { "$ref": "#/components/schemas/Cliente" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ItemComprobante" }
          }
        }
      },
      "ComprobanteResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "mensaje": { "type": "string", "example": "Comprobante F001-00000001 emitido exitosamente (ACEPTADO)" },
          "datos": {
            "type": "object",
            "properties": {
              "id": { "type": "integer", "example": 1 },
              "tipo_doc": { "type": "string", "example": "01" },
              "serie": { "type": "string", "example": "F001" },
              "correlativo": { "type": "string", "example": "00000001" },
              "numero_completo": { "type": "string", "example": "F001-00000001" },
              "fecha_emision": { "type": "string", "example": "2026-11-03" },
              "total_gravado": { "type": "number", "example": 549.15 },
              "total_igv": { "type": "number", "example": 98.85 },
              "total_importe": { "type": "number", "example": 648.00 },
              "monto_letras": { "type": "string", "example": "SON: SEISCIENTOS CUARENTA Y OCHO CON 00/100 SOLES" },
              "hash": { "type": "string", "example": "cT49L1Fv7aE+yD4+3bF9Kk0O9u4=" },
              "sunat_estado": { "type": "string", "example": "ACEPTADO" },
              "sunat_codigo": { "type": "string", "example": "0" },
              "sunat_mensaje": { "type": "string", "example": "La Factura numero F001-00000001, ha sido aceptada" },
              "enlaces": {
                "type": "object",
                "properties": {
                  "xml": { "type": "string", "example": "/api/v1/documentos/1/xml" },
                  "cdr": { "type": "string", "example": "/api/v1/documentos/1/cdr" },
                  "pdf_a4": { "type": "string", "example": "/api/v1/documentos/1/pdf?format=a4" },
                  "pdf_ticket_80": { "type": "string", "example": "/api/v1/documentos/1/pdf?format=ticket-80" },
                  "pdf_ticket_58": { "type": "string", "example": "/api/v1/documentos/1/pdf?format=ticket-58" }
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Verificar salud del sistema y extensiones PHP",
        "responses": {
          "200": { "description": "Estado operativo" }
        }
      }
    },
    "/empresa/credenciales": {
      "get": {
        "summary": "Obtener claves API (Test y Producción) de la empresa",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": {
          "200": { "description": "Credenciales retornadas con éxito" }
        }
      }
    },
    "/empresa": {
      "get": {
        "summary": "Consultar perfil fiscal y configuración de la empresa",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": { "200": { "description": "Datos de empresa" } }
      },
      "put": {
        "summary": "Actualizar datos fiscales, contacto y logo de la empresa",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": { "200": { "description": "Actualizado con éxito" } }
      }
    },
    "/facturas": {
      "post": {
        "summary": "Emitir Factura Electrónica (01) hacia SUNAT",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/FacturaRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Factura emitida y aceptada",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ComprobanteResponse" }
              }
            }
          }
        }
      }
    },
    "/boletas": {
      "post": {
        "summary": "Emitir Boleta de Venta Electrónica (03) hacia SUNAT",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/FacturaRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Boleta emitida y aceptada" }
        }
      }
    },
    "/notas-credito": {
      "post": {
        "summary": "Emitir Nota de Crédito Electrónica (07)",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": { "201": { "description": "Nota de Crédito emitida" } }
      }
    },
    "/notas-debito": {
      "post": {
        "summary": "Emitir Nota de Débito Electrónica (08)",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": { "201": { "description": "Nota de Débito emitida" } }
      }
    },
    "/guias-remision": {
      "post": {
        "summary": "Emitir Guía de Remisión Remitente (09)",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": { "201": { "description": "Guía de Remisión emitida" } }
      }
    },
    "/anulaciones": {
      "post": {
        "summary": "Comunicar Anulación / Baja de Comprobantes ante SUNAT",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "responses": { "201": { "description": "Comunicación de baja enviada a SUNAT" } }
      }
    },
    "/documentos/{id}/pdf": {
      "get": {
        "summary": "Descargar o visualizar PDF (formatos: a4, ticket-80, ticket-58)",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["a4", "ticket-80", "ticket-58"], "default": "a4" } }
        ],
        "responses": {
          "200": { "description": "Documento PDF", "content": { "application/pdf": {} } }
        }
      }
    },
    "/documentos/{id}/xml": {
      "get": {
        "summary": "Descargar archivo XML firmado digitalmente",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Archivo XML firmado", "content": { "application/xml": {} } }
        }
      }
    },
    "/documentos/{id}/cdr": {
      "get": {
        "summary": "Descargar archivo ZIP de constancia de recepción (CDR) de SUNAT",
        "security": [{ "ApiKeyAuth": [], "ApiSecretAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Archivo ZIP del CDR", "content": { "application/zip": {} } }
        }
      }
    },
    "/empresas": {
      "post": {
        "summary": "Registrar nueva empresa tenant en el facturador (Requiere X-Master-Key)",
        "security": [{ "MasterKeyAuth": [] }],
        "responses": {
          "201": { "description": "Nueva empresa registrada con credenciales generadas" }
        }
      }
    }
  }
}