API Facturación SRI

Introducción

Esta API permite emitir facturas y notas de crédito electrónicas al SRI desde tu sistema (POS/ERP). Todos los ejemplos usan la URL base de esta instalación.

URL base: reemplaza https://tu-dominio.com por el dominio donde está instalada esta API (en pruebas locales: http://localhost:3000).

Autenticación

Crea una API Key en la sección «API Keys» y envíala en la cabecera X-API-Key en cada petición. La API Key identifica al negocio; no necesitas enviar el RUC.

X-API-Key: tu_api_key_aqui
Content-Type: application/json

Alternativamente, las apps internas pueden usar un token JWT con Authorization: Bearer <token> obtenido en /api/auth/login.

POST /api/factura/emitir

Emite, firma y autoriza una factura ante el SRI en una sola llamada.

Ejemplo mínimo

curl -X POST https://tu-dominio.com/api/factura/emitir \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "estab": "001",
    "ptoEmi": "001",
    "regimenFiscal": "general",
    "detalles": [
      { "descripcion": "Servicio de consultoría", "cantidad": 1, "precioUnitario": 100.00 }
    ]
  }'

Sin más datos: comprador = CONSUMIDOR FINAL, IVA 15%, secuencial automático, fecha = hoy.

Ejemplo completo (a empresa, con email)

{
  "ambiente": "produccion",
  "estab": "001",
  "ptoEmi": "001",
  "regimenFiscal": "general",
  "tipoIdentificacionComprador": "04",
  "identificacionComprador": "1790012345001",
  "razonSocialComprador": "EMPRESA CLIENTE S.A.",
  "direccionComprador": "Av. Principal 123, Quito",
  "detalles": [
    { "codigoPrincipal": "SERV001", "descripcion": "Consultoría mensual",
      "cantidad": 1, "precioUnitario": 500.00, "descuento": 0,
      "codigoPorcentajeIVA": "4" }
  ],
  "pagos": [ { "formaPago": "20", "total": 575.00 } ],
  "infoAdicional": [ { "nombre": "Email", "valor": "cliente@empresa.com" } ],
  "referencia": "VENTA-12345"
}

referencia (opcional): tu ID de venta. Evita duplicados si reintentas la misma venta.

Respuesta (éxito)

{
  "exito": true,
  "mensaje": "Factura autorizada correctamente",
  "claveAcceso": "2106...0510",
  "numeroAutorizacion": "2106...0510",
  "sri": { "estado": "AUTORIZADO", "etapa": "AUTORIZACION", "mensajes": [] },
  "comprobante": { "tipo": "FACTURA", "numeroCompleto": "001-001-000000001" },
  "totales": { "subtotal": 500.00, "iva": 75.00, "total": 575.00 },
  "archivos": {
    "xml": "/api/comprobante/2106...0510/xml",
    "pdf": "/api/comprobante/2106...0510/pdf"
  }
}

Campos principales

Campo	Req.	Descripción
estab	Sí	Establecimiento, ej. "001"
ptoEmi	Sí	Punto de emisión, ej. "001"
regimenFiscal	Sí*	"general", "rimpe_emprendedor" o "rimpe_negocio_popular". *Puede venir ya configurado en el negocio.
detalles[]	Sí	Líneas: descripcion, cantidad, precioUnitario, descuento, codigoPorcentajeIVA
ambiente	No	"pruebas" o "produccion" (por defecto el del negocio)
secuencial	No	Automático si se omite
fechaEmision	No	DD/MM/YYYY. Default: hoy
infoAdicional[]	No	Pares nombre/valor. Usa "Email" para enviar el comprobante al cliente

POST /api/nota-credito/emitir

Emite una nota de crédito sobre una factura ya autorizada (devoluciones, descuentos).

{
  "estab": "001",
  "ptoEmi": "001",
  "regimenFiscal": "general",
  "codDocModificado": "01",
  "numDocModificado": "001-001-000000001",
  "fechaEmisionDocSustento": "21/01/2026",
  "motivo": "Devolución parcial",
  "identificacionComprador": "1790012345001",
  "razonSocialComprador": "EMPRESA CLIENTE S.A.",
  "detalles": [
    { "descripcion": "Consultoría mensual", "cantidad": 1, "precioUnitario": 100.00, "codigoPorcentajeIVA": "4" }
  ]
}

Campo	Req.	Descripción
codDocModificado	Sí	Tipo del documento modificado: "01" (factura)
numDocModificado	Sí	Número del documento: "001-001-000000001"
fechaEmisionDocSustento	Sí	Fecha del documento original (DD/MM/YYYY)
motivo	Sí	Razón de la nota de crédito
detalles[]	Sí	Ítems devueltos/corregidos

Consultar, descargar y enviar

GET /api/comprobante/<claveAcceso>

Estado del comprobante en el SRI.

GET /api/comprobante/<claveAcceso>/xml

Descarga el XML autorizado.

GET /api/comprobante/<claveAcceso>/pdf

Descarga el RIDE en PDF.

POST /api/comprobante/<claveAcceso>/email

Envía el comprobante por correo. Cuerpo: { "email": "cliente@correo.com" }

GET /api/comprobantes

Lista los comprobantes emitidos. Filtros: ?tipo=01&desde=2026-01-01&hasta=2026-01-31

GET /api/secuencial/<tipo>/<estab>/<ptoEmi>

Siguiente secuencial disponible. tipo = 01 (factura) o 04 (nota de crédito). Ej: /api/secuencial/01/001/001

Tablas de referencia

Tipo de identificación del comprador

Código	Tipo
04	RUC
05	Cédula
06	Pasaporte
07	Consumidor final (default)

Código de IVA (codigoPorcentajeIVA)

Código	Tarifa
4	15% (default)
0	0%
7	Exento de IVA

Forma de pago (formaPago)

Código	Forma
01	Sin utilización del sistema financiero (efectivo)
19	Tarjeta de crédito
20	Otros con utilización del sistema financiero

Códigos de respuesta HTTP: 200 emitido · 400 datos inválidos · 401 API Key inválida · 429 límite alcanzado.