sri-ec
v0.3.0
Published
Cliente Node.js/TypeScript para facturación electrónica del SRI Ecuador (port de teran-sri-ec).
Maintainers
Readme
sri-ec
Librería de Facturación Electrónica del SRI Ecuador para Node.js/TypeScript: documentos tipados, validación (zod + BusinessValidator), serialización XML, carga de certificados .p12, firma XAdES-BES, transporte SOAP sobre fetch nativo y envío masivo (BatchEmitter). Agnóstico de framework y sin dependencias nativas (nada de node-gyp).
Es el port oficial de amephia/sri-ec (PHP): misma firma XAdES-BES, verificada byte a byte contra el paquete original.
- 📖 Documentación completa: https://github.com/JonathanTeran/teran-sri-ec-node
- 🐛 Reportar un problema: https://github.com/JonathanTeran/teran-sri-ec-node/issues
Características
- Los 6 comprobantes electrónicos: Factura (
01), Liquidación de Compra (03), Nota de Crédito (04), Nota de Débito (05), Guía de Remisión (06) y Comprobante de Retención (07). - RIDE conforme al Anexo 2 del SRI (PDF con código de barras Code 128 por defecto; QR opcional) de los 6 comprobantes vía el subpath opcional
sri-ec/ride(npm install pdfkit— añadeqrcodesolo si usasincluirQr: true; ver RIDE). - Certificados
.p12/.pfxmodernos y legacy (RC2/3DES pre-2024), sin depender de la versión de OpenSSL del sistema. - Firma RSA y ECDSA, digest configurable (
sha1por defecto — lo que el SRI valida hoy — osha256). - Validación estructural (zod) y de negocio (coherencia aritmética de totales, impuestos y retenciones).
- Dual ESM + CommonJS con tipos incluidos (
.d.ts/.d.cts).
Instalación
npm install sri-ecRequiere Node.js >= 20.
Uso
import { readFileSync } from 'node:fs';
import {
Ambiente,
FormaPago,
loadCertificate,
SriClient,
TipoComprobante,
TipoEmision,
type Factura,
} from 'sri-ec';
const certificate = loadCertificate(readFileSync('firma.p12'), process.env['SRI_P12_PASSWORD']!);
const sri = new SriClient({ ambiente: Ambiente.Pruebas, certificate });
const factura: Factura = {
tipo: TipoComprobante.Factura,
infoTributaria: {
ambiente: Ambiente.Pruebas,
razonSocial: 'MI EMPRESA S.A.',
ruc: '1790011001001',
estab: '001',
ptoEmi: '001',
secuencial: '000000001',
dirMatriz: 'Quito, Ecuador',
tipoEmision: TipoEmision.Normal,
},
fechaEmision: '26/01/2026',
tipoIdentificacionComprador: '05',
razonSocialComprador: 'CLIENTE FINAL',
identificacionComprador: '9999999999',
totalSinImpuestos: '100.00',
totalDescuento: '0.00',
importeTotal: '112.00',
totalConImpuestos: [
{ codigo: '2', codigoPorcentaje: '2', baseImponible: '100.00', valor: '12.00' },
],
detalles: [
{
codigoPrincipal: 'PROD001',
descripcion: 'Producto de prueba',
cantidad: '1.00',
precioUnitario: '100.00',
descuento: '0.00',
precioTotalSinImpuesto: '100.00',
impuestos: [
{ codigo: '2', codigoPorcentaje: '2', tarifa: '12.00', baseImponible: '100.00', valor: '12.00' },
],
},
],
pagos: [{ formaPago: FormaPago.EFECTIVO, total: '112.00' }],
};
const resultado = await sri.emit(factura);
console.log(resultado.status); // 'AUTORIZADO' | 'RECHAZADO' | 'EN_PROCESO'
if (resultado.status === 'AUTORIZADO') {
console.log(resultado.numeroAutorizacion, resultado.fechaAutorizacion);
} else {
for (const m of resultado.messages) console.log(`[${m.identificador}] ${m.mensaje}`);
}Factura también admite dirEstablecimiento y contribuyenteEspecial (opcionales, no usados en el ejemplo mínimo de arriba): dirección del establecimiento emisor y número de resolución de contribuyente especial — el RIDE los imprime en el bloque emisor cuando están presentes.
Firmar sin emitir (prepare)
Para firmar ahora y despachar después (cola, lote, worker):
const { claveAcceso, signedXml } = sri.prepare(factura);
// Persista SIEMPRE el par antes de enviarlo: la claveAcceso es el único
// identificador con el que se puede resolver el comprobante ante el SRI.
await miRepositorio.guardar(claveAcceso, signedXml);Ante un fallo de red
Un CommunicationError no se convierte en EmissionResult — se lanza, porque no permite saber si el comprobante llegó a procesarse. El error trae el comprobante en vuelo:
import { CommunicationError } from 'sri-ec';
try {
await sri.emit(factura);
} catch (err) {
if (err instanceof CommunicationError && err.claveAcceso) {
await miRepositorio.guardar(err.claveAcceso, err.signedXml!);
// Resuelva el estado real con authorize(), NUNCA con un emit() nuevo:
// un emit() nuevo acuñaría otra clave y duplicaría el secuencial.
const estado = await sri.authorize(err.claveAcceso);
console.log(estado.estado);
}
throw err;
}API principal
| Miembro | Descripción |
|---|---|
| new SriClient({ ambiente, certificate, transport?, signer?, validate? }) | Cliente de emisión individual. |
| sri.emit(doc, claveAcceso?) | Valida → firma → recepción → autorización. Devuelve EmissionResult. |
| sri.prepare(doc, claveAcceso?) | Valida → firma, sin tocar la red. Devuelve { claveAcceso, signedXml }. |
| sri.authorize(claveAcceso) | Re-consulta el estado de una clave ya enviada. |
| sri.sign(xml) | Firma un XML ya serializado. |
| new BatchEmitter({ ambiente, ... }) | Envío masivo con reintentos y backoff configurables. |
| loadCertificate(p12, password) | Carga un .p12/.pfx (moderno o legacy). |
| generarClaveAcceso({ ... }) | Clave de acceso de 49 dígitos (Módulo 11). |
| validarRucLocal / validarRucChecksum / validarRucOnline | Validación de RUC. |
La referencia completa (envío masivo, transporte propio, troubleshooting de zona horaria y certificados legacy) está en el README del repositorio.
RIDE (PDF + QR)
El RIDE de los 6 comprobantes reproduce la maqueta oficial del Anexo 2 de la Ficha Técnica del SRI y vive en el subpath opcional sri-ec/ride, para que emitir/firmar no pague el costo de sus dependencias.
Cambio en 0.3.0: el predeterminado pasó de QR (
incluirQr: trueen 0.2.0) a código de barras Code 128 (codigoBarras: true), conforme a la maqueta oficial. Si vienes de 0.2.0 y quieres seguir generando el QR, pasaopciones: { incluirQr: true }explícitamente.
Con las opciones por defecto solo hace falta pdfkit; instala también qrcode solo si vas a usar incluirQr: true:
npm install pdfkit qrcodeimport { writeFileSync } from 'node:fs';
import { generarRide } from 'sri-ec/ride';
const pdf: Uint8Array = await generarRide({
documento: factura, // cualquiera de los 6 comprobantes (unión `Comprobante`)
claveAcceso: resultado.claveAcceso,
autorizacion:
resultado.status === 'AUTORIZADO'
? { numero: resultado.numeroAutorizacion!, fecha: resultado.fechaAutorizacion! }
: undefined, // opcional: sin ella, el RIDE sale marcado "NO AUTORIZADO"
opciones: {
codigoBarras: true, // Code 128 bajo CLAVE DE ACCESO, default true
incluirQr: false, // QR alternativo (requiere `qrcode`), default false
},
});
writeFileSync('factura.pdf', pdf);Si pdfkit/qrcode no están instalados al llamar a generarRide(), se lanza un SriError con el mensaje exacto de qué instalar, en vez del error crudo de Node. Detalle completo (todas las opciones, las etiquetas exactas de cada maqueta, atajos por tipo) en el README del repositorio.
NestJS
Para aplicaciones NestJS existe el módulo de inyección de dependencias complementario: sri-ec-nestjs.
Licencia
MIT © Jonathan Terán — ver LICENSE.md.
