API de Facturación Electrónica SRI - Ejemplos de Documentos

Este documento proporciona ejemplos de cómo enviar solicitudes y las respuestas esperadas para todos los tipos de documentos soportados en el Sistema de Facturación Electrónica SRI.

📚 Conjunto de Documentación Completa

Para ejemplos completos y reglas de validación, consulta:

INVOICE_EXAMPLES.md - Ejemplos completos de facturas con diferentes tipos de clientes
CREDIT_NOTE_EXAMPLES.md - Ejemplos de notas de crédito para todos los escenarios
RETENTION_EXAMPLES.md - Ejemplos de certificados de retención
VALIDATION_RULES.md - Reglas de validación detalladas y solución de problemas

Tipos de Documentos Soportados

Tabla de Impuestos del Sistema

La siguiente tabla resume los impuestos configurados actualmente en el sistema y usados por la validación de documentos.

Tipo de Documento	Código	Descripción	Endpoint	Documentación
---------------	------	-------------	----------	----------------
Factura	`01`	Factura de venta	`POST /api/document`	Ejemplos de Facturas
Nota de Crédito	`04`	Nota de crédito	`POST /api/document`	Ejemplos de Notas de Crédito
Retención	`07`	Comprobante de retención	`POST /api/document`	Ejemplos de Retenciones
PDF RIDE	-	Descargar PDF RIDE	`GET /api/document/{accessKey}/ride`	Ver abajo
Tipo	Código SRI	Código porcentaje SRI	Nombre	Porcentaje	Estado
------	------------	----------------------	--------	------------	--------
IVA	`2`	`0`	0%	0.00%	Activo
IVA	`2`	`2`	13%	13.00%	Activo
IVA	`2`	`5`	5% - Construcción	5.00%	Activo
IVA	`2`	`6`	No Objeto de Impuesto	0.00%	Activo
IVA	`2`	`7`	Exento de IVA	0.00%	Activo
IVA	`2`	`2`	12%	12.00%	Inactivo
IVA	`2`	`3`	14%	14.00%	Inactivo
IVA	`2`	`4`	15%	15.00%	Activo
IRBPNR	`5`	`2`	Plásticos	2.00%	Activo
ICE	`3`	`3031`	Bebidas Alcohólicas	0.00%	Activo
ICE	`3`	`3011`	Cigarrillos	0.00%	Activo
ICE	`3`	`3051`	Bebidas Gaseosas	0.00%	Activo
ICE	`3`	`3041`	Cerveza	0.00%	Activo
ICE	`3`	`3073`	Vehículos	0.00%	Activo

Reglas de validación

En facturas (01) y notas de crédito (04), la combinación codigo + codigoPorcentaje debe existir en sri_taxes y estar activa.
Solo se aceptan los códigos de impuesto 2, 3 y 5 en detalles con impuestos.
Los impuestos inactivos permanecen registrados para trazabilidad, pero no deben usarse en nuevas emisiones.
detallesAdicionales es opcional para cada detalle en facturas (01) y notas de crédito (04), con máximo 10 elementos por ítem; cada elemento requiere nombre y valor (máx. 300 caracteres).

Estructura Común de Solicitud

Todas las solicitudes de documentos comparten una estructura común:

{
  "ruc": "ruc_empresa",
  "tipo": "codigo_documento",
  "id_externo": "id_externo_unico",
  "[campos_especificos_del_documento]": {...},
  "detalles": [...],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://webhook.ejemplo.com"
  }
}

Header obligatorio de idempotencia

Para crear documentos (individual o lote), debes enviar Idempotency-Key.

Encabezados recomendados

Authorization: Bearer TU_TOKEN
Content-Type: application/json
Idempotency-Key: 2f5d7fc4-0ce8-4b44-9730-a29cd5b7f3f8

Reglas de uso

Operación nueva -> nueva key.
Reintento de la misma operación -> misma key.
Misma key con payload distinto -> 409 Conflict.
Misma key en estado processing -> 409 Conflict.

> El manejo de idempotencia es compartido entre POST /api/document/register y POST /api/document/batch/register para mantener comportamiento consistente.

Registro de Documentos en Lotes

Endpoint: POST /api/document/batch/register

Permite registrar múltiples comprobantes en una sola solicitud y procesarlos de forma asíncrona en cola.

Reglas del lote

Máximo 50 documentos por lote.
Tamaño total máximo de XML: 512 KB.
Todos los documentos del lote deben ser del mismo tipo (01, 04 o 07).
id_externo no puede repetirse dentro del mismo lote.
La combinación serie + secuencial no puede repetirse dentro del lote.
Se valida cupo billing antes de registrar el lote.

Estados del procesamiento

Lote: PENDING -> PROCESSING -> COMPLETED o FAILED
Item de lote: PENDING -> PROCESSING -> COMPLETED o FAILED

Ejemplo rápido (lote de facturas)

POST /api/document/batch/register
Content-Type: application/json

{
  "ruc": "0707012605001",
  "tipo": "01",
  "documentos": [
    {
      "id_externo": "BATCH-INV-001",
      "factura": {
        "fecha": "18/05/2026",
        "establecimiento": "001",
        "puntoEmision": "001",
        "secuencial": "000010101",
        "descuento": 0,
        "propina": 0,
        "total": 115,
        "cliente": {
          "nombre": "Diego Jimenez",
          "tipoIdentificacion": "05",
          "documento": "0912345678",
          "correo": "[email protected]",
          "direccion": "Machala"
        }
      },
      "detalles": [
        {
          "codigoPrincipal": "P-001",
          "descripcion": "Producto A",
          "cantidad": 1,
          "precioUnitario": 100,
          "descuento": 0,
          "precioTotalSinImpuesto": 100,
          "impuestos": [
            {
              "codigo": "2",
              "codigoPorcentaje": "4",
              "tarifa": 15,
              "baseImponible": 100,
              "valor": 15
            }
          ]
        }
      ],
      "pagos": [
        {
          "formaPago": "01",
          "total": 115,
          "plazo": 0,
          "unidadTiempo": "dias"
        }
      ]
    }
  ]
}

Respuesta inicial

{
  "status": "ok",
  "code": 201,
  "message": "Lote registrado correctamente",
  "data": {
    "batch_id": 18,
    "batch_key": "01JVJZYQ4NWS4HYAYN1R3C9A6P",
    "tipo": "01",
    "documents_count": 1,
    "total_size_bytes": 10564,
    "status": "PENDING"
  }
}

> Nota: la respuesta inicial confirma el registro del lote. La creación efectiva de cada documento ocurre en segundo plano mediante cola.

⚠️ Importantee: Validación Consumidor Final

Si obtienes este error:

Las facturas con consumidor final no deben marcar operaciones anulables.

Opciones de Solución Rápida:

Opción 1: Usar Identificación Regular de Cliente

{
  "factura": {
    "cliente": {
      "tipoIdentificacion": "05",
      "documento": "0912345678", // Tu documento real
      "nombre": "Diego Jimenez"
    }
  }
}

Opción 2: Usar Formato Consumidor Final Correcto

{
  "factura": {
    "cliente": {
      "tipoIdentificacion": "07",
      "documento": "9999999999999", // Código consumidor final
      "nombre": "CONSUMIDOR FINAL"
    }
  }
}

Para explicación detallada y soluciones, consulta VALIDATION_RULES.md#escenario-1-error-de-validacion-consumidor-final

📋 Ejemplos de Referencia Rápida

⚠️ Importantee: Para ejemplos completos con diferentes escenarios, consulta los archivos de documentación específicos vinculados arriba.

1. Factura Básica (Tipo `01`)

POST /api/document
Content-Type: application/json

{
  "ruc": "0707012605001",
  "tipo": "01",
  "id_externo": "INV-2025-BASIC",
  "factura": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "001",
    "secuencial": "000012343",
    "descuento": 0,
    "propina": 0,
    "total": 115.00,
    "cliente": {
      "nombre": "Diego Jimenez",
      "tipoIdentificacion": "05",
      "documento": "0912345678",
      "correo": "[email protected]",
      "direccion": "Av. Siempre Viva"
    }
  },
  "detalles": [
    {
      "codigoPrincipal": "P-001",
      "descripcion": "Producto A",
      "cantidad": 2,
      "precioUnitario": 50.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 100.00,
      "impuestos": [
        { 
          "codigo": "2", 
          "codigoPorcentaje": "4", 
          "tarifa": 15, 
          "baseImponible": 100.00, 
          "valor": 15.00 
        }
      ]
    }
  ],
  "pagos": [
    { 
      "formaPago": "01", 
      "total": 115.00, 
      "plazo": 0, 
      "unidadTiempo": "dias" 
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://miapp.com/webhooks/sri"
  }
}

Ejemplo de detallesAdicionales dentro de un detalle de factura:

{
  "codigoPrincipal": "P-001",
  "descripcion": "Producto A",
  "cantidad": 2,
  "precioUnitario": 50.00,
  "descuento": 0,
  "precioTotalSinImpuesto": 100.00,
  "impuestos": [
    {
      "codigo": "2",
      "codigoPorcentaje": "4",
      "tarifa": 15,
      "baseImponible": 100.00,
      "valor": 15.00
    }
  ],
  "detallesAdicionales": [
    {
      "nombre": "Lote",
      "valor": "L-2026-0001"
    },
    {
      "nombre": "Serie",
      "valor": "SN-ABC-12345"
    }
  ]
}

2. Nota de Crédito Básica (Tipo `04`)

POST /api/document
Content-Type: application/json

{
  "ruc": "0707012605001",
  "tipo": "04",
  "id_externo": "NC-2025-BASIC",
  "nota": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "001",
    "secuencial": "000001234",
    "motivo": "DEVOLUCION - Producto defectuoso recibido por cliente",
    "cliente": {
      "nombre": "DIEGO JIMENEZ",
      "tipoIdentificacion": "05",
      "documento": "0912345678",
      "correo": "[email protected]",
      "direccion": "Av. Principal #123"
    },
    "docModificado": {
      "tipo": "01",
      "numero": "001-001-000012343",
      "fechaEmision": "01/12/2025"
    },
    "total": 115.00
  },
  "detalles": [
    {
      "codigoPrincipal": "P-001",
      "descripcion": "Producto A devuelto - falla en fabricación",
      "cantidad": -2,
      "precioUnitario": 50.00,
      "descuento": 0,
      "precioTotalSinImpuesto": -100.00,
      "impuestos": [
        { 
          "codigo": "2", 
          "codigoPorcentaje": "4", 
          "tarifa": 15, 
          "baseImponible": -100.00, 
          "valor": -15.00 
        }
      ]
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://miapp.com/webhooks/credit-notes"
  }
}

Ejemplo de detallesAdicionales dentro de un detalle de nota de crédito:

{
  "codigoPrincipal": "P-001",
  "descripcion": "Producto A devuelto - falla en fabricación",
  "cantidad": -2,
  "precioUnitario": 50.00,
  "descuento": 0,
  "precioTotalSinImpuesto": -100.00,
  "impuestos": [
    {
      "codigo": "2",
      "codigoPorcentaje": "4",
      "tarifa": 15,
      "baseImponible": -100.00,
      "valor": -15.00
    }
  ],
  "detallesAdicionales": [
    {
      "nombre": "MotivoTecnico",
      "valor": "Defecto de fabrica"
    },
    {
      "nombre": "Lote",
      "valor": "L-2025-009"
    }
  ]
}

3. Retención Básica (Tipo `07`)

POST /api/document
Content-Type: application/json

{
  "ruc": "0707012605001",
  "tipo": "07",
  "id_externo": "RET-2025-BASIC",
  "retencion": {
    "fecha": "07/12/2025",
    "establecimiento": "001",
    "puntoEmision": "001",
    "secuencial": "000000123",
    "periodoFiscal": "12/2025",
    "sujetoRetenido": {
      "tipoIdentificacion": "04",
      "documento": "1791234567001",
      "nombre": "PROVEEDOR DE SERVICIOS S.A.",
      "direccion": "Av. Industrial #789"
    },
    "total": 30.00
  },
  "detalles": [
    {
      "codigo": "2",
      "codigoRetencion": "1",
      "baseImponible": 100.00,
      "porcentajeRetener": 30.0,
      "valorRetenido": 30.00,
      "codDocSustento": "01",
      "numDocSustento": "001-001-000001234",
      "fechaEmisionSustento": "01/12/2025"
    }
  ],
  "notificaciones": {
    "email": "[email protected]",
    "webhook_url": "https://proveedor.com/webhooks/retentions"
  }
}

Flujo de Estado del Documento

Todos los documentos siguen el mismo progreso de estado:

GENERATED → SIGNED → RECEIVED → AUTHORIZED
                    ↓
                 REJECTED/ERROR/RETURNED

Consultar Estado del Documento

Ejemplo de Solicitud

GET /api/document/status?ruc=1712345678001&external_id=INV-2025-001&include_xml=true

Ejemplo de Respuesta

{
  "status": "ok",
  "code": 200,
  "message": "Estado del documento obtenido exitosamente",
  "data": {
    "id": 1,
    "company_id": 1,
    "external_id": "INV-2025-001",
    "document_type": "01",
    "access_key": "2812202501171234567800110010000000011234567890",
    "series": "001001",
    "sequential": "000000001",
    "status": "AUTHORIZED",
    "authorization_number": "2812202501171234567800110010000000011234567890",
    "authorization_date": "28/12/2025 14:30:00",
    "issue_date": "2025-12-28",
    "document_status": "AUTHORIZED",
    "xml_sri": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
    "notification_email": "[email protected]",
    "webhook_url": "https://webhook.ejemplo.com/invoice",
    "created_at": "2025-12-28T12:00:00.000000Z",
    "updated_at": "2025-12-28T14:30:00.000000Z"
  }
}

Respuestas de Error

Ejemplo de Error de Validación

{
  "status": "error",
  "code": 422,
  "message": "Los datos proporcionados no son válidos.",
  "errors": {
    "factura.total": [
      "El campo factura.total es obligatorio cuando el tipo es 01."
    ],
    "detalles": [
      "El campo detalles debe tener al menos 1 elemento."
    ]
  }
}

Ejemplo de Error de Lógica de Negocio

{
  "status": "error",
  "code": 422,
  "message": "Descuadre total: base(100.00) + impuestos(12.00) = 112.00, factura.total = 115.00"
}

Reglas de Validación Comunes

Formato de Número de Documento

Factura: XXX-XXX-XXXXXXXXX (establecimiento-puntoEmision-secuencial)
Nota de Crédito: XXX-XXX-XXXXXXXXX (mismo formato)
Retención: XXX-XXX-XXXXXXXXX (mismo formato)

Formatos de Fecha

Fecha de Emisión: dd/mm/YYYY (ej., 28/12/2025)
Período Fiscal: mm/YYYY (ej., 12/2025) - solo para retenciones

Códigos de Impuestos

IVA: Código 2 con códigos de porcentaje 0, 2, 6, etc.
IR: Código 1 (para retenciones)
ICE: Código 3

Códigos de Pago

20: Crédito
01: Efectivo
15: Transferencia bancaria
etc. (según catálogo SRI)

Notas Importantees

Restricciones Únicas: Cada tipo de documento debe tener números secuenciales únicos por establecimiento y punto de emisión
Validación Total: Todos los valores monetarios deben ser consistentes con tolerancia de 0.01
Notificaciones Webhook: La URL de webhook opcional recibe actualizaciones de estado durante el procesamiento del documento
Notificaciones por Email: Email opcional para enviar actualizaciones de estado del documento
Almacenamiento XML: El XML generado se almacena en la base de datos, el XML autorizado se almacena después de la aprobación del SRI

Pruebas

Usa los archivos de prueba proporcionados para cada tipo de documento:

test_invoice.php - Datos de prueba de facturas
test_credit_note.php - Datos de prueba de notas de crédito
test_retention.php - Datos de prueba de retenciones

📄 Descargar PDF RIDE

Descarga el PDF RIDE (Representación Impresa de Documentos Electrónicos) para documentos autorizados.

Endpoint

GET /api/document/{accessKey}/ride?ruc={ruc_empresa}

Autenticación

Requerido: Sí (Token Sanctum)
Headers:

` Authorization: Bearer {token} Content-Type: application/json `

Parámetros

Parámetro	Tipo	Requerido	Descripción
-----------	------	----------	-------------
`accessKey`	string	Sí	Clave de acceso de 49 dígitos del documento (parámetro URL)
`ruc`	string	Sí	RUC de la empresa (parámetro de consulta)

Ejemplo de Solicitud

curl -X GET "https://tu-dominio.com/api/document/1234567890123456789012345678901234567890123456789012/ride?ruc=1234567890123" \
  -H "Authorization: Bearer {token}" \
  -o "RIDE_documento.pdf"

Respuesta Exitosa

Estado: 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="RIDE_{accessKey}.pdf"
Cuerpo: Contenido del archivo PDF

Respuestas de Error

#### Documento No Encontrado (404)

{
    "status": "error",
    "code": 404,
    "message": "Documento no encontrado o acceso denegado"
}

#### Documento No Autorizado (422)

{
    "status": "error", 
    "code": 422,
    "message": "Solo los documentos autorizados pueden descargar RIDE PDF. Estado actual: RECEIVED"
}

#### Empresa No Encontrada (404)

{
    "status": "error",
    "code": 404,
    "message": "Empresa no encontrada"
}

#### Archivo RIDE No Disponible (404)

{
    "status": "error",
    "code": 404,
    "message": "Archivo RIDE no encontrado. Por favor intenta regenerar."
}

Notas Importantees

Estado del Documento: Solo documentos con estado AUTHORIZED pueden descargar PDF RIDE
Acceso de Empresa: Los usuarios solo pueden descargar RIDE de sus propias empresas (validación RUC)
Auto-Generación: Si el PDF RIDE no existe, se generará automáticamente
Nombrado de Archivo: Formato de nombre de descarga: RIDE_{accessKey}.pdf
Seguridad: El acceso se valida en múltiples niveles (autenticación → empresa → documento → estado)
Registro: Todas las descargas se registran para auditoría

Solución de Problemas

Problema	Solución
-------	----------
"Documento no encontrado"	Verifica que la accessKey y RUC sean correctos, el documento pertenece a la empresa
"Solo documentos autorizados"	El documento debe tener estado `AUTHORIZED`, primero verifica el estado del documento
"Archivo RIDE no encontrado"	Intenta regenerar el RIDE o contacta al soporte

Soporte

Para soporte técnico o preguntas sobre la API:

Revisa los mensajes de error de validación para problemas específicos de campos
Consulta la documentación técnica del SRI
Contacta al equipo de desarrollo para preguntas relacionadas con la API