@rewarestudios/fel-system

SDK Oficial de Reware Studios para Node.js y TypeScript que permite integrar y consumir de manera sencilla la API pública de facturación electrónica FEL System en El Salvador.

Características

• ⚡ Compilación Híbrida: Soporte nativo para ESM (import) y CommonJS (require).
• 🛡️ TypeScript Nativo: Tipado estricto y autocompletado inteligente para todos los payloads de DTEs.
• ⚙️ Manejo de Estados de Transmisión: Control automático de los tres estados normativos de Hacienda: Aceptado (PROCESSED), Contingencia (CONTINGENCIA) y Rechazado (REJECTED).
• 🛑 Excepciones Detalladas: Clases de errores personalizadas para diagnosticar revalidaciones de Hacienda de forma limpia en tu código.

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

1. Emisión de DTEs (Ejemplo: Factura Consumidor Final - DTE 01)

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.

async function emitirFactura() {
  try {
    const factura = await fel.facturas.crear({
      receptor: {
        nombre: "CARLOS HERNANDEZ",
        tipoDocumento: "13", // DUI
        numDocumento: "123456789",
        correo: "[email protected]"
      },
      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:

🟢 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 del SDK

El SDK expone de forma ordenada todos los endpoints y utilidades de la API oficial:

• fel.facturas (DTE 01)
• fel.creditoFiscal (DTE 03 - Soporta retención del 1% de IVA mediante el parámetro isRetenIva)
• fel.sujetoExcluido (DTE 14)
• fel.retenciones (DTE 07)
• fel.notas (DTE 05/06 - Notas de Crédito y Débito asociadas a DTEs originales)
• fel.retornos (DTE 18 - Eventos de Retorno)
• fel.anulaciones (Eventos de Invalidación por Sustitución o Rescisión de operaciones)
• fel.consultas (Obtención de PDF en formato url o base64, reenvío manual de correos, información de sucursal y consultas masivas de transmisión)
• fel.reportes (Solicitud asíncrona de reportes mensuales ZIP)

Licencia

Este proyecto está bajo la Licencia MIT. Desarrollado por Reware Studios.