API facturación electrónica El Salvador para devs

Si desarrollás un POS, un ERP o una app que factura, ya sabés que en El Salvador vender no basta: cada documento tiene que convertirse en un DTE firmado y transmitido al Ministerio de Hacienda. Y ahí es donde muchos equipos se estancan. Construir esa integración desde cero significa lidiar con criptografía, con el JSON exacto que Hacienda valida al carácter, con la firma electrónica, con la transmisión y con el manejo de correlativos. Meses de trabajo para algo que no es tu producto.

La alternativa es no construir nada de eso. La API de facturación electrónica de TurboPyme expone la emisión de DTE como un endpoint HTTP: le mandás el documento, ella hace el trabajo sucio y te devuelve el sello de Hacienda. Este artículo es la introducción para que un desarrollador entienda qué resuelve y cómo se ve el flujo de integración.

Qué resuelve la API de facturación electrónica en El Salvador

El valor está en lo que no tenés que escribir. La API se encarga de las cuatro cosas que hacen dolorosa la integración con Hacienda:

• Criptografía y firma. El documento se firma electrónicamente con tus credenciales, sin que tu código toque una sola librería de firma.
• Cumplimiento del JSON de Hacienda. Vos enviás un payload base; el sistema lo envuelve con las reglas del emisor y arma el JSON estricto que el Ministerio valida.
• Transmisión y sello. La API transmite el documento al Ministerio de Hacienda y te devuelve el sello de recepción oficial. Sin ese sello, un DTE no es válido.
• Correlativos automáticos. El siguiente número de control válido se asigna solo, por terminal. No tenés que llevar tu propia secuencia ni arriesgarte a duplicar un correlativo.

Dicho de otro modo: tu sistema sigue siendo tu sistema —tu POS, tu inventario, tu lógica de negocio— y TurboPyme es la capa de cumplimiento que se sienta entre vos y Hacienda. Si venís llegando al tema y querés el panorama completo de qué es un DTE y quién está obligado, la guía de facturación electrónica en El Salvador te ancla antes de integrar.

El flujo de integración en 5 pasos

La API está pensada para velocidad: en cuestión de minutos emitís tu primera Factura validada. El flujo son cinco pasos.

1. Obtené tu X-API-Key

Desde el panel de administración de TurboPyme obtenés tu X-API-Key. Cada llamada a la API la lleva en los headers (o como Authorization: Bearer <tu-clave>). Esa clave queda atada de forma permanente a un único Customer registrado —tu empresa emisora—, así que identifica quién factura en cada request.

2. Subí tus credenciales de Hacienda

Para que el sistema pueda firmar y transmitir en tu nombre, cargás dos cosas:

• El certificado de Hacienda (tu .crt o .xml) y su contraseña, vía POST /api/v1/customers/{id}/certificate.
• La contraseña/API de integración generada en el portal del MH, vía POST /api/v1/customers/{id}/hacienda-key.

Estas credenciales quedan resguardadas del lado del servidor. Tu código nunca manipula la llave privada de firma.

3. Configurá el perfil de tu empresa

Con PUT /api/v1/customers/{id} completás los datos del emisor: nombre de la empresa, NRC, NIT y correo. Son los datos que el sistema usa para armar el bloque emisor de cada DTE, para que no los mandés en cada emisión.

4. (Opcional) Sucursales y terminales

Cuando se crea tu Customer, se genera automáticamente una sucursal por defecto (Code 00000001, EmitID M001). Si tenés una sola tienda, saltate este paso. Si manejás varias sucursales o cajas, mapeás tu infraestructura con los endpoints de crear sucursal y crear terminal, y luego indicás el terminal_id al emitir.

5. Emití tu primera Factura

El paso final: POST /api/v1/dtes/factura. Mandás el dte_object con la identificación (fecha y hora), el receptor, el cuerpoDocumento (tus ítems) y el resumen con los totales. El sistema lo firma, le asigna el correlativo y lo transmite a Hacienda al instante.

Cómo se ve una llamada real

Una emisión de Factura es un POST con tu X-API-Key en el header y el documento en el cuerpo. En las pestañas de abajo tenés el flujo completo: cómo autenticás, cómo emitís la Factura y qué te responde Hacienda.

# Header en cada request
curl https://app.turbopyme.com/api/v1/customers/{id} \
  -H "X-API-Key: tu_api_key_aqui"

# Alternativa equivalente
curl https://app.turbopyme.com/api/v1/customers/{id} \
  -H "Authorization: Bearer tu_api_key_aqui"

curl -X POST https://app.turbopyme.com/api/v1/dtes/factura \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "dte_object": {
      "identificacion": { "fecEmi": "2026-07-14", "horEmi": "12:30:00" },
      "receptor": { "nombre": "Clientes Varios" },
      "cuerpoDocumento": [
        {
          "numItem": 1, "tipoItem": 1, "cantidad": 2,
          "codigo": "PRD-102", "uniMedida": 59,
          "descripcion": "Teclado Inalámbrico",
          "precioUni": 1.00, "montoDescu": 0.00,
          "ventaGravada": 2.00, "ivaItem": 0.23
        }
      ],
      "resumen": { "totalGravada": 2.00, "totalPagar": 2.00, "condicionOperacion": 1 }
    }
  }'

{
  "dte_id": "...",
  "control_number_str": "DTE-01-12345678-000000000000001",
  "sello_recepcion": "...",
  "status": "aceptado",
  "generation_code": "..."
}

Fijate en dos detalles del payload: el receptor es opcional —si lo omitís, el documento cae como “Clientes Varios”, ideal para una venta de mostrador—, y no mandás correlativo ni firma. Esos los pone el sistema.

La misma mecánica aplica para los otros tipos de documento —Crédito Fiscal, Notas de Crédito y Débito, Sujeto Excluido—, cada uno con su endpoint. Si todavía dudás cuál emitir en cada caso, revisá los tipos de DTE en El Salvador antes de cablear tu lógica.

Ambientes: sandbox y producción

No integres a ciegas contra producción. Hay dos servidores:

• Sandbox: test.turbopyme.com — para desarrollar y probar todo el flujo sin emitir documentos reales ni gastar correlativos.
• Producción: app.turbopyme.com — cuando ya validaste tu integración de punta a punta.

El patrón recomendado es construir contra el sandbox, correr tus pruebas de emisión, y recién cambiar el host cuando estés seguro. La documentación interactiva de todos los endpoints, con sus esquemas de request y response, vive en la sección de developers.

En resumen

• La API convierte la emisión de DTE en un simple POST: vos mandás el documento, ella hace criptografía, firma, JSON de Hacienda, transmisión y correlativos.
• El flujo son 5 pasos: X-API-Key, subir credenciales de Hacienda, configurar el perfil con PUT /api/v1/customers/{id}, (opcional) sucursales, y emitir con POST /api/v1/dtes/factura.
• La respuesta trae dte_id, control_number_str y sello_recepcion —con el sello, el DTE es válido.
• Desarrollás contra el sandbox (test.turbopyme.com) y pasás a producción (app.turbopyme.com) cuando estés listo.

Preguntas frecuentes

Si estás evaluando construir la integración con Hacienda por tu cuenta o apoyarte en una API que ya la resolvió, hacé cuentas: los meses de desarrollo y mantenimiento de la firma y la normativa rara vez salen a cuenta. Empezá por la doc interactiva de la API, y si querés dimensionar el costo frente a armarlo vos mismo, mirá los precios de sistemas DTE en 2026. Cuando quieras dar el paso, en turbopyme.com conectás tus credenciales y emitís tu primer DTE sellado sin volverte experto en la normativa técnica.