Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Carlos-Gnd/FERRED-Inventario-y-Ventas/llms.txt

Use this file to discover all available pages before exploring further.

Ferred implementa la facturación electrónica según el estándar DTE (Documento Tributario Electrónico) del Ministerio de Hacienda de El Salvador. Cada venta genera automáticamente una Factura de Consumidor Final (tipo 01) que se construye, firma y envía al sistema de Hacienda de forma asíncrona. Si el servicio de Hacienda no está disponible en el momento de la venta, esta igual queda registrada y el DTE puede reenviarse después.

​
¿Qué es un DTE?

Un DTE (Documento Tributario Electrónico) es el comprobante fiscal digital obligatorio en El Salvador desde la implementación del sistema de facturación electrónica del Ministerio de Hacienda. Ferred genera exclusivamente el tipo 01: Factura de Consumidor Final, orientada a ventas al público en general sin necesidad de identificar al comprador. Cada DTE contiene:
  • Un codigoGeneracion (UUID v4 en mayúsculas) que identifica unívocamente el documento.
  • Un numeroControl con formato DTE-01-<sucursal>P001-<secuencia>.
  • Un JSON estructurado que incluye datos del emisor, receptor, items vendidos y resumen fiscal.
  • Un código QR apuntando al portal de consulta pública de Hacienda.

​
Ciclo de vida del DTE

Una FacturaDte transita entre los siguientes estados:
EstadoDescripción
SIMULADOEstado inicial tras crear la venta. También se usa cuando el sandbox de Hacienda no está disponible (timeout de red).
PENDIENTEEstado temporal que se asigna al iniciar un reenvío manual con POST /api/dte/:id/reenviar.
PROCESADOHacienda respondió con estado: "PROCESADO" y devolvió un selloRecibido. El DTE es válido fiscalmente.
ERROR_HACIENDAHacienda respondió con un código HTTP 4xx/5xx o con un estado distinto de PROCESADO. Requiere revisión.
ERROR_INTERNOEl sistema de Ferred no pudo construir o enviar el DTE por un error interno (base de datos, etc.).
La generación del DTE es asíncrona. Si Hacienda está caído en el momento de la venta, la factura queda en estado SIMULADO y la venta no se revierte. El cajero puede continuar operando con normalidad. Para reintentar el envío, usa POST /api/dte/:id/reenviar cuando el servicio de Hacienda vuelva a estar disponible.

​
Estructura del JSON DTE

El servicio construirJsonDTE en dte.service.ts genera el siguiente documento: 
{
  "identificacion": {
    "version": 1,
    "ambiente": "00",
    "tipoDte": "01",
    "numeroControl": "DTE-01-0001P001-000000000000042",
    "codigoGeneracion": "550E8400-E29B-41D4-A716-446655440000",
    "tipoModelo": 1,
    "tipoOperacion": 1,
    "tipoContingencia": null,
    "motivoContin": null,
    "fecEmi": "2026-05-07",
    "horEmi": "14:30:00",
    "tipoMoneda": "USD"
  },
  "emisor": {
    "nit": "00000000000000",
    "nrc": "0000000",
    "nombre": "FERRED Inventario y Ventas",
    "codActividad": "47592",
    "descActividad": "Venta al por menor de articulos de ferreteria",
    "nombreComercial": "FERRED",
    "tipoEstablecimiento": "01",
    "direccion": {
      "departamento": "05",
      "municipio": "23",
      "complemento": "San Miguel, El Salvador"
    },
    "telefono": "00000000",
    "correo": "info@ferred.com.sv"
  },
  "receptor": {
    "tipoDocumento": null,
    "numDocumento": null,
    "nombre": "Consumidor Final",
    "correo": null
  },
  "cuerpoDocumento": [
    {
      "numItem": 1,
      "codigo": "TOR-014",
      "descripcion": "Tornillo 1/4",
      "cantidad": 10,
      "uniMedida": 59,
      "precioUni": 0.15,
      "ventaNoSuj": 0,
      "ventaExenta": 0,
      "ventaGravada": 1.50,
      "tributos": null
    }
  ],
  "resumen": {
    "totalNoSuj": 0,
    "totalExenta": 0,
    "totalGravada": 1.50,
    "subTotalVentas": 1.50,
    "descuGravada": 0,
    "totalDescu": 0,
    "tributos": [
      { "codigo": "20", "descripcion": "Impuesto al Valor Agregado 13%", "valor": 0.20 }
    ],
    "subTotal": 1.50,
    "montoTotalOperacion": 1.70,
    "totalPagar": 1.70,
    "totalLetras": "1 DOLARES CON 70/100",
    "totalIva": 0.20,
    "condicionOperacion": 1,
    "pagos": [
      { "codigo": "01", "montoPago": 1.70, "referencia": "", "periodo": null, "plazo": null }
    ]
  }
}
Los códigos de unidad de medida (uniMedida) se mapean desde el tipoUnidad del producto según el catálogo de Hacienda:
tipoUnidad en FerredCódigo HaciendaDescripción
PESO32Kilogramo
MEDIDA52Metro
LOTE26Caja
UNIDAD / otros59Unidad

​
Generación del QR

El QR se genera como imagen base64 usando la librería qrcode y apunta al portal público de consulta de Hacienda: 
const url = `https://admin.factura.gob.sv/consultaPublica?ambiente=${ambiente}&codGen=${codigoGeneracion}&fechaEmi=${fechaEmi}`;
Para obtener el QR de una factura existente: 
GET /api/dte/:id/qr
El endpoint devuelve { "qrBase64": "data:image/png;base64,..." }. Requiere que la factura ya tenga un codigoGeneracion asignado (es decir, que el DTE haya sido construido al menos una vez).

​
Reenvío de DTEs fallidos

Si un DTE quedó en estado ERROR_HACIENDA o SIMULADO y deseas reenviarlo: 
POST /api/dte/:id/reenviar
Roles permitidos: ADMIN, CAJERO (solo su sucursal). El servicio reenviarDTE:
  1. Actualiza el estado de la factura a PENDIENTE.
  2. Llama a enviarDteHacienda(facturaId) de forma síncrona y devuelve el resultado.
No es necesario pasar ningún cuerpo en la solicitud. La respuesta indica el estado final (PROCESADO, ERROR_HACIENDA, etc.) y, si fue exitoso, el selloRecibido de Hacienda y el qrBase64.

​
Modo sandbox vs producción

El ambiente del DTE se controla con la variable de entorno DTE_ENV:
Valor DTE_ENVCampo ambiente en el JSONDescripción
sandbox"00"Envíos al sandbox de pruebas de Hacienda
cualquier otro"01"Envíos al sistema productivo de Hacienda
El sandbox acepta los mismos DTEs que producción pero no tiene validez fiscal. Úsalo durante el desarrollo y las pruebas de integración. Para pasar a producción, cambia DTE_ENV y configura las credenciales reales (DTE_AUTH_TOKEN o DTE_SANDBOX_USER / DTE_SANDBOX_PASS).

Build docs developers (and LLMs) love

Get started for freeTalk to us