Emitir DTE por API: tu primera factura en TurboPyme

Integrar la facturación electrónica en tu propio software no tiene por qué ser un proyecto de meses. Con TurboPyme podés emitir DTE por API y dejar que el sistema resuelva la parte pesada: la criptografía, el JSON estricto de Hacienda, la firma, la transmisión y el manejo de correlativos. Vos solo mandás el payload del documento. Esta guía te lleva, paso a paso, desde cero hasta tu primera Factura aceptada por el Ministerio de Hacienda (MH).

Qué necesitás para emitir DTE por API

Antes de escribir la primera línea de código, tené a mano tres cosas. El flujo real de integración es corto —cinco pasos— y cada uno prepara el terreno para el siguiente:

Ese es todo el camino. Si venís de otro esquema y querés el panorama general de la integración, tenemos un artículo hermano sobre la API de facturación DTE en El Salvador y la referencia técnica completa en nuestra documentación para desarrolladores.

Paso 1: Obtené tu X-API-Key

Toda llamada a la API se autentica con una clave. Entrá al panel de administración de TurboPyme y generá tu X-API-Key. Esta clave está atada de forma permanente a un único Customer (tu empresa registrada), así que tratala como un secreto: no la subas a un repositorio ni la expongas en el navegador.

Cada request debe llevarla en el header:

X-API-Key: tu_clave_secreta_aqui

Paso 2: Subí tus credenciales de Hacienda

TurboPyme firma y transmite en tu nombre, pero para eso necesita las mismas credenciales que ya usás con el MH. Son dos llamadas.

Primero, subí tu certificado de firma (el archivo .crt o .xml) junto con su contraseña. Para pruebas usá key_type: "sandbox"; para producción, "prod":

curl -X POST https://test.turbopyme.com/api/v1/customers/{id}/certificate \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_xml": "<contenido crudo de tu .crt o .xml>",
    "private_key_password": "clave_de_tu_certificado",
    "key_type": "sandbox"
  }'

Segundo, registrá el API Password que generaste en el portal del MH:

curl -X POST https://test.turbopyme.com/api/v1/customers/{id}/hacienda-key \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "password": "tu_api_password_de_hacienda" }'

Podés verificar que ambas quedaron cargadas consultando tu perfil (GET /api/v1/customers/{id}): los campos has_valid_certificate y has_hacienda_password deben venir en true.

Paso 3: Configurá el perfil del emisor

Hacienda exige que el emisor esté completo y correcto. Actualizá el perfil de tu empresa con tu nombre, NRC y NIT usando PUT /api/v1/customers/{id}:

curl -X PUT https://test.turbopyme.com/api/v1/customers/{id} \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi Empresa S.A. de C.V.",
    "tax_id": "06140xxxxxxxxx",
    "nrc": "1234567",
    "email": "facturacion@miempresa.com"
  }'

Estos datos son el emisor que TurboPyme adjunta automáticamente a cada documento, así que basta con configurarlos una vez.

Paso 4: Sucursales y terminales (opcional)

Cuando se creó tu Customer, TurboPyme ya generó por vos una Sucursal por defecto (Code 00000001, EmitID M001). Si tenés una sola tienda, saltate este paso: tus documentos salen contra esa sucursal sin que hagas nada.

¿Tenés varias sucursales o cajas? Usá POST /api/v1/branches para crear cada sucursal y POST /api/v1/terminals para las terminales de punto de venta. Cada sucursal recibe su propio emit_id de Hacienda, y cada Factura lleva su correlativo independiente por terminal. Cuando emitas, podés indicar el terminal_id; si lo dejás vacío, se usa tu terminal principal.

Paso 5: Emití tu primera Factura

Este es el flujo completo de integración en una sola referencia: las tres llamadas de configuración, el POST que emite y la respuesta sellada. Copiá cada bloque con un clic.

curl -X POST https://test.turbopyme.com/api/v1/customers/{id}/certificate \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_xml": "<contenido crudo de tu .crt o .xml>",
    "private_key_password": "clave_de_tu_certificado",
    "key_type": "sandbox"
  }'

curl -X POST https://test.turbopyme.com/api/v1/customers/{id}/hacienda-key \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "password": "tu_api_password_de_hacienda" }'

curl -X PUT https://test.turbopyme.com/api/v1/customers/{id} \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi Empresa S.A. de C.V.",
    "tax_id": "06140xxxxxxxxx",
    "nrc": "1234567",
    "email": "facturacion@miempresa.com"
  }'

curl -X POST https://test.turbopyme.com/api/v1/dtes/factura \
  -H "X-API-Key: tu_clave_secreta_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "dte_object": {
      "identificacion": {
        "fecEmi": "2026-07-14",
        "horEmi": "12:30:00"
      },
      "receptor": {
        "tipoDocumento": "37",
        "numDocumento": "000000000",
        "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,
          "ventaNoSuj": 0.00,
          "ventaExenta": 0.00,
          "ventaGravada": 2.00,
          "psv": 0.00,
          "noGravado": 0.00,
          "ivaItem": 0.23
        }
      ],
      "resumen": {
        "totalNoSuj": 0.00,
        "totalExenta": 0.00,
        "totalGravada": 2.00,
        "subTotalVentas": 2.00,
        "descuNoSuj": 0.00,
        "descuExenta": 0.00,
        "descuGravada": 0.00,
        "porcentajeDescuento": 0.00,
        "totalDescu": 0.00,
        "subTotal": 2.00,
        "ivaRete1": 0.00,
        "reteRenta": 0.00,
        "montoTotalOperacion": 2.00,
        "totalNoGravado": 0.00,
        "totalPagar": 2.00,
        "totalLetras": "DOS DOLARES",
        "saldoFavor": 0.00,
        "condicionOperacion": 1
      }
    }
  }'

{
  "dte_id": "3f2c9b10-8e4a-4c7d-9a1b-2f6e5d0c1a44",
  "generation_code": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "control_number_str": "DTE-01-12345678-000000000000001",
  "status": "DTE_STATUS_ACCEPTED",
  "message": "Recibido",
  "sello_recepcion": "2026A1B2C3D4E5F6..."
}

Llegamos a lo importante. Enviás el payload base del documento dentro de dte_object y TurboPyme se encarga del resto: lo firma, le asigna el siguiente correlativo válido y lo transmite a Hacienda.

Un par de detalles que ahorran dolores de cabeza en la Factura (documento tipo 01): el receptor es opcional —si lo omitís, sale como “Clientes Varios”— y el ivaItem es el IVA implícito ya incluido en la venta gravada (ventaGravada - (ventaGravada / 1.13)), no un impuesto que se suma aparte. Si en cambio necesitás un Comprobante de Crédito Fiscal u otro tipo de documento, revisá qué tipos de DTE existen en El Salvador y cuál te toca emitir.

Verificá la respuesta

Si todo salió bien, Hacienda acepta el documento y la API te devuelve un objeto con los datos del DTE ya sellado. Fijate en tres campos:

• status: cuando vale DTE_STATUS_ACCEPTED, Hacienda aceptó la Factura.
• sello_recepcion: es el sello oficial de recepción del MH. Su presencia confirma que el documento quedó registrado.
• control_number_str y dte_id: guardalos. El control_number_str es tu correlativo; el dte_id te sirve para consultar o descargar el DTE (JSON y PDF) más adelante.

Detrás de esa única respuesta sellada, TurboPyme recorrió todo el camino por vos: firmó, correlacionó y transmitió tu payload hasta el sello de Hacienda.

De la primera factura a producción

Con estos cinco pasos ya emitiste tu primer DTE por API. A partir de acá, escalar es cuestión de reutilizar el mismo flujo: mismo header, mismo endpoint, distinto payload. La obligatoriedad de facturar electrónicamente llega por notificación individual al NIT de cada contribuyente, así que si ya recibiste la tuya, tener la integración lista con antelación te quita presión. Si querés el contexto normativo completo, leé nuestra guía de facturación electrónica en El Salvador.

¿Listo para conectar tu software? En turbopyme.com obtenés tu X-API-Key, probás en el sandbox y emitís tu primera Factura sellada por Hacienda sin escribir una sola línea de criptografía.