Guía de Integración API

Versión: 3.9 (Extended Technical Documentation)
Plataforma: Facturación Electrónica (Ecuador)

Esta API permite a sistemas externos (ERP, POS, E-commerce, CRMs) emitir documentos electrónicos legales en Ecuador a través de una sola llamada simplificada. Al basarse en estándares web (REST/JSON), admite integración desde cualquier lenguaje de programación, incluyendo PHP (Laravel), Python (Django/Flask), Java, Node.js, C# (.NET) y más.

El motor interno de KoaDoc se encarga de todo el ciclo de vida del documento electrónico dictaminado por el Servicio de Rentas Internas (SRI):

• Registro: Persistencia en base de datos transaccional con control de atomicidad.
• Generación XML: Estructuración del documento bajo el esquema XSD oficial del SRI.
• Firma Digital: Firma criptográfica (XAdES-BES) usando el certificado .p12 de la empresa.
• Envío y Autorización: Comunicación SOAP con los Web Services del SRI.
• Notificación: Envío automático del comprobante (XML y RIDE PDF) al cliente.

1. Autenticación

Todas las peticiones requieren el header Authorization. Existen dos métodos dependiendo de la arquitectura de su integración:

A. Token de Empresa (Prefijo VSR)

Ideal para aplicaciones exclusivas de una empresa, donde la integración no necesita saber el ID interno de la empresa en KoaDoc. Nota: "VSR" es el prefijo de seguridad interno específico de KoaDoc para identificar tokens de empresa única.

• Header: Authorization: Token vsr_XXXXXXXXXXXXXXXXX
• Comportamiento: La API identifica la empresa automáticamente según el prefijo vsr_. No incluya el campo company en el JSON.

B. Token de Usuario (Multi-Empresa)

Ideal para integradores (SaaS) que manejan múltiples empresas desde una sola cuenta administrativa.

• Header: Authorization: Token XXXXXXXXXXXXXXXXX
• Comportamiento: Requiere obligatoriamente enviar el campo company: ID (entero) en la raíz del cuerpo JSON.

2. Endpoint Principal: Emisión Completa

Estructura del JSON (Request)

{ 
  "issue_date": "2025-08-04", 
  "customer_identification_type": "05", 
  "customer_identification": "1234567890", 
  "customer_name": "JUAN CARLOS PÉREZ LÓPEZ", 
  "customer_address": "Av. Principal 123, Quito", 
  "customer_email": "[email protected]", 
  "customer_phone": "0987654321", 
  "service_period": "Agosto 2025",
  "expiration_date": "2025-08-15",
  "payment_methods": [
    {
      "payment_method_code": "01",
      "amount": 103.50,
      "payment_term": 0,
      "time_unit": "dias"
    }
  ],
  "items": [ 
    { 
      "main_code": "PROD-001", 
      "auxiliary_code": "AUX-001", 
      "description": "Producto de ejemplo", 
      "quantity": 2.00, 
      "unit_price": 50.00, 
      "discount": 5.00,
      "tax_rate": 15
    } 
  ] 
}

Detalle de Campos Raíz (Root)

Detalle de Items

3. Consulta de Comprobante Completo

Para obtener todos los detalles completos de una factura (incluyendo los items individuales que compró el cliente, los impuestos desglosados y el estado final del SRI), debes usar este endpoint de lectura o consulta. El JSON devuelto en la creación es un resumen, pero para armar tu comprobante o voucher completo, debes hacer una petición GET.

Respuesta Esperada

Te devolverá un JSON detallado con toda la información necesaria para dibujar tu ticket. Presta especial atención a los bloques items, taxes y payment_methods.

{
    "id": 1234,
    "company": 1,
    "company_name": "Helados S.A.",
    "company_ruc": "0999999999001",
    "document_type": "INVOICE",
    "document_number": "001-001-000000123",
    "access_key": "1308202601179000000000120010010000001231234567812",
    "issue_date": "2026-08-13",
    "status": "AUTHORIZED",
    "status_display": "Autorizado",
    
    "customer_identification": "0999999999",
    "customer_name": "Juan Pérez",
    "customer_address": "Av. Principal y Secundaria",
    "customer_email": "[email protected]",
    
    "subtotal_without_tax": "4.50",
    "total_tax": "0.68",
    "total_amount": "5.18",
    
    "sri_authorization_code": "13082026011790...",
    "sri_authorization_date": "2026-08-13T12:05:00Z",
    
    "items": [
        {
            "main_code": "HEL-001",
            "description": "Cono de Vainilla",
            "quantity": "2.000000",
            "unit_price": "1.500000",
            "discount": "0.00",
            "subtotal": "3.00",
            "taxes": [
                {
                    "tax_code_display": "IVA",
                    "percentage_code_display": "15%",
                    "rate": "15.00",
                    "taxable_base": "3.00",
                    "tax_amount": "0.45"
                }
            ]
        },
        {
            "main_code": "HEL-002",
            "description": "Tarrina de Chocolate",
            "quantity": "1.000000",
            "unit_price": "1.500000",
            "discount": "0.00",
            "subtotal": "1.50",
            "taxes": [
                {
                    "tax_code_display": "IVA",
                    "percentage_code_display": "15%",
                    "rate": "15.00",
                    "taxable_base": "1.50",
                    "tax_amount": "0.23"
                }
            ]
        }
    ],
    
    "payment_methods": [
        {
            "payment_method_code_display": "SIN UTILIZACION DEL SISTEMA FINANCIERO",
            "amount": "5.18",
            "payment_term": 0,
            "time_unit": "dias"
        }
    ],
    
    "pdf_file_url": "https://tu-dominio.com/mediafiles/sri/pdfs/001-001-000000123.pdf",
    "xml_file_url": "https://tu-dominio.com/mediafiles/sri/xmls/001-001-000000123.xml"
}

4. Ten en cuenta la codificación del SRI

El éxito de la integración recae en usar los catálogos técnicos correctos exigidos por el SRI para evitar rechazos en los comprobantes.

Tipos de Identificación (customer_identification_type)

Porcentajes de IVA (tax_rate)

Formas de Pago (payment_method_code)

5. Respuestas y Arquitectura

El facturador electrónico posee un conmutador de Procesamiento Sincrónico vs Asincrónico para manejar el throughput de las llamadas en función de la latencia del SRI.

Respuesta en Modo Asincrónico (Recomendado)

Para evitar Timeouts causados por demoras en los servidores del SRI, el Facturador insertará el documento en base de datos, lo colocará en la cola y responderá instantáneamente.

{ 
  "success": true, 
  "message": "Factura recibida y puesta en cola para procesamiento (SRI asíncrono)", 
  "invoice": { 
    "id": 175, 
    "number": "001-001-000001102", 
    "access_key": "04082025011234567890...", 
    "status": "QUEUED"
  } 
}

Tipos de Respuestas en Emisión (Vouchers y Devoluciones)

Al generar o procesar un documento, la API puede devolver distintos mensajes que tu sistema debe ser capaz de interpretar para mostrar al cliente final o al cajero. Manejar correctamente estas devoluciones es clave para una buena integración:

• Procesamiento Exitoso: Factura recibida y puesta en cola... -> Muestra al cajero que la transacción fue exitosa y procede a imprimir el voucher (haciendo el GET).
• Rechazo por SRI (Ej. Duplicidad): La clave de acceso ya se encuentra registrada... -> El sistema del SRI ya tiene esta factura.
• Error de Validación: Datos inconsistentes en el ítem X... -> Indica al usuario que revise los precios o impuestos.
• Errores de Laboratorio de Calidad: En entornos de prueba (Laboratorio), podrías recibir respuestas que evalúan la calidad de tu integración, por ejemplo: Simulación de timeout en el SRI o Error de calidad: Certificado no corresponde al ambiente. Estas devoluciones sirven para probar la robustez de tu sistema.

6. Reglas Legales y de Validación SRI

Para evitar que el SRI rechace tus comprobantes, nuestro sistema y la ley exigen el cumplimiento estricto de las siguientes reglas de negocio:

• Tope para Consumidor Final: Las facturas emitidas a "Consumidor Final" (Tipo de identificación 07) no pueden superar los $50.00 USD en su total. Si el monto es mayor, debes obligatoriamente emitir la factura a nombre de una persona natural (Cédula) o jurídica (RUC) con sus datos completos.
• Fechas de Emisión: La fecha de emisión (issue_date) no puede ser una fecha futura (posterior al día de hoy). Tampoco puede ser demasiado antigua; por regla general del SRI, no debe superar 1 mes de antigüedad desde la fecha actual de envío.
• Cálculos Exactos: El SRI es estricto con los decimales. No envíes totales redondeados arbitrariamente. Deja que nuestra API calcule los impuestos en base a la cantidad, precio unitario y descuento.

8. Manejo de Errores (Extendido)

Es vital que tu sistema lea el código interno (Internal Code) y el mensaje de error para dar retroalimentación útil a los usuarios en sus sistemas de Punto de Venta. A continuación detallamos el catálogo exhaustivo de errores que puede emitir la API de KoaDoc:

9. Notas Técnicas y Matemáticas

• Cálculos Automáticos e Integridad: La API utiliza aritmética de clase Decimal para evitar errores de coma flotante. El IVA se calcula a nivel de línea sobre el subtotal neto de cada ítem.
• Secuenciales Automáticos: El Facturador extrae su propio lock transaccional de la base de datos para garantizar secuenciales únicos y contiguos. No es necesario enviar el número de factura.