SDK Node.js / TypeScript

El SDK oficial de Reware Studios para Node.js y TypeScript permite integrar y consumir de manera sencilla la API pública de facturación electrónica FEL System en El Salvador. Proporciona tipado estricto, autocompletado y una gestión inteligente de los flujos de respuesta del Ministerio de Hacienda.

Instalación

Instala el paquete en tu proyecto utilizando tu gestor de paquetes favorito:

npm install @rewarestudios/fel-system

Configuración Inicial

Para consumir la API, necesitas inicializar la clase principal FELSystem proporcionando tu API Key y el entorno en el que vas a operar (test o production):

import { FELSystem } from "@rewarestudios/fel-system";

const fel = new FELSystem({
  apiKey: "tu-token-de-api-aqui",
  environment: "test", // Usa "production" para emisión real a Hacienda
  timeoutMs: 15000     // Opcional: Tiempo límite de espera (por defecto 10000ms)
});

Guía de Uso y Emisión

Emisión de DTEs

El SDK cuenta con validación de respuestas. Al emitir un documento, si es exitoso o entra en contingencia, retornará la estructura con la información. Si es rechazado por Hacienda, lanzará una excepción controlada.

A continuación, se muestra un ejemplo para emitir una Factura de Consumidor Final (DTE 01):

async function emitirFactura() {
  try {
    const factura = await fel.facturas.crear({
      receptor: {
        nombre: "CARLOS HERNANDEZ",
        tipoDocumento: "13", // DUI
        numDocumento: "123456789",
        correo: "cliente@ejemplo.com"
      },
      items: [
        {
          descripcion: "Corte de cabello caballero",
          cantidad: 1,
          precioUnitario: 5.00,
          tipoImpuesto: "GRAVADO"
        }
      ],
      condicionOperacion: 1, // Contado
      observaciones: "Pago en ventanilla"
    });

    console.log("DTE Generado con éxito!");
    console.log("Estado de Emisión:", factura.estado); // 'PROCESSED' o 'CONTINGENCIA'
    console.log("Código de Generación (UUID):", factura.codigoGeneracion);
    console.log("Número de Control:", factura.numeroControl);
    console.log("Enlace al PDF:", factura.dtePdfUrl);
  } catch (error) {
    manejarErrores(error);
  }
}

Manejo de Estados y Errores Normativos

El SDK clasifica el resultado de tus emisiones para automatizar tu flujo de negocio de acuerdo con las normativas del Ministerio de Hacienda:

🟢 ACEPTADO (`PROCESSED`)

El DTE fue firmado y aprobado por el Ministerio de Hacienda. La API devuelve los enlaces de descarga JSON, PDF y el sello de recepción. El SDK lo retorna normalmente.

🟡 CONTINGENCIA (`CONTINGENCIA`)

Por normativa tributaria, si hay fallas de transmisión o indisponibilidad en los servidores de Hacienda, el DTE se emite bajo contingencia. Este documento es legalmente válido, incorpora firmas, códigos de generación y número de control.

Acción del SDK: Retorna con éxito al igual que un DTE procesado. Tu flujo operativo debe registrar la factura normalmente. El desarrollador puede evaluar el campo factura.estado === 'CONTINGENCIA' si requiere realizar acciones secundarias.

🔴 RECHAZADO (`REJECTED`)

Ocurre si el DTE posee inconsistencias de formato, NITs/CRCs erróneos o violaciones a las reglas de validación de Hacienda. No tiene validez legal.

Acción del SDK: Lanza una excepción del tipo DteRejectedError. Puedes capturar esta excepción para obtener el detalle exacto de las observaciones:

import {
  DteRejectedError,
  FELSystemApiError,
  FELSystemConnectionError
} from "@rewarestudios/fel-system";

function manejarErrores(error: any) {
  if (error instanceof DteRejectedError) {
    // El DTE fue rechazado por Hacienda
    console.error("Rechazado por Hacienda. Causa:", error.message);
    console.error("UUID Rechazado:", error.codigoGeneracion);
    console.error("Errores específicos de validación:", error.erroresValidacion);
  } else if (error instanceof FELSystemApiError) {
    // La API devolvió un código de error HTTP (por ejemplo 401 Unauthorized o 429 Límite)
    console.error(`Error de API HTTP ${error.statusCode}:`, error.message);
  } else if (error instanceof FELSystemConnectionError) {
    // Problema de Red, DNS o Timeout
    console.error("Fallo de conexión o timeout superado:", error.message);
  } else {
    console.error("Error inesperado:", error);
  }
}

Recursos Disponibles del SDK

La clase FELSystem expone de forma ordenada todos los endpoints y utilidades de la API oficial a través de los siguientes recursos:

Propiedad	Tipo DTE / Recurso	Descripción / Parámetros Clave
`fel.facturas`	DTE 01	Factura de Consumidor Final.
`fel.creditoFiscal`	DTE 03	Comprobante de Crédito Fiscal. Soporta retención del 1% de IVA mediante `isRetenIva`.
`fel.sujetoExcluido`	DTE 14	Factura de Sujeto Excluido para compras a no contribuyentes. Soporta retención automática del 10% de Renta con `applyrent`.
`fel.retenciones`	DTE 07	Comprobante de Retención de IVA.
`fel.notas`	DTE 05 / 06	Notas de Crédito y Débito asociadas a DTEs originales mediante código de generación.
`fel.retornos`	DTE 18	Eventos de Retorno / Devolución de mercancía.
`fel.anulaciones`	Eventos	Invalidación de documentos por sustitución o rescisión de operaciones.
`fel.consultas`	Consultas	Obtención de representaciones gráficas en PDF (formatos `url` o `base64`), reenvío de correos, información general de sucursal y consultas masivas de transmisión.
`fel.reportes`	Reportes	Solicitud asíncrona de reportes mensuales comprimidos en formato ZIP.