Crear factura

Lumen firma el DTE y lo transmite a Hacienda en una sola llamada. Úsalo desde tu POS, Saas, ERP o checkout cuando el cliente paga y necesitas el documento tributario listo.

La emisión es síncrona: en una sola petición obtienes el resultado final de Hacienda.

Método: POST

EndpointCopy Anchor Link

https://api-sandbox.lumendte.com/v1/invoices

HeadersCopy Anchor Link

Payload mínimoCopy Anchor Link

Para operaciones de hasta $25,000 USD, la normativa permite omitir los datos del cliente. Este es el payload mínimo para emitir una factura de contado:

{
  "items": [
    {
      "description": "Servicio de consultoría",
      "quantity": 1,
      "unitPrice": 113.0
    }
  ],
  "payments": [
    {
      "paymentCode": "01",
      "amount": 113.0
    }
  ]
}

Respuesta exitosaCopy Anchor Link

Status: 201 Created

Si la misma Idempotency-Key ya tiene una factura en PROCESSED, la API responde 200 OK con el mismo cuerpo: el generationCode, el controlNumber y el receivedStamp guardados, y URLs temporales nuevas. No vuelve a transmitir el documento a Hacienda.

Guarda generationCode y controlNumber. Las URLs pdfUrl y jsonUrl expiran en 15 minutos: descárgalas o reenvíalas al cliente de inmediato desde tu backend. No las persistas en tu base de datos para uso posterior; cuando expiren, pide unas nuevas con Descargar PDF y Descargar JSON usando el generationCode.

Si pdfUrl o jsonUrl llegan en null, la factura es válida igualmente, los archivos se generan en la primera llamada a los endpoints de descarga. No vuelvas a emitir la factura.

El campo status indica el resultado:

Procesada (PROCESSED)Copy Anchor Link

{
  "status": "PROCESSED",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-01-M001P001-000000000000001",
  "receivedStamp": "20219E9D4DC0292F4681AD759B0B0F5CA99DC23G",
  "environment": "SANDBOX",
  "pdfUrl": "https://files.example.com/invoices/1/FF84E5DB-79C5-42CE-B415-EC510C53EFB5.pdf?X-Amz-Expires=900",
  "jsonUrl": "https://files.example.com/invoices/1/FF84E5DB-79C5-42CE-B415-EC510C53EFB5.json?X-Amz-Expires=900"
}

Borrador sandbox (DRAFT)Copy Anchor Link

En sandbox sin credenciales listas, Lumen crea el documento como borrador: no llama a firma ni a Hacienda. receivedStamp es null. El PDF y el JSON sí quedan disponibles.

{
  "status": "DRAFT",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-01-M001P001-000000000000001",
  "receivedStamp": null,
  "environment": "SANDBOX",
  "pdfUrl": "https://files.example.com/invoices/1/FF84E5DB-79C5-42CE-B415-EC510C53EFB5.pdf?X-Amz-Expires=900",
  "jsonUrl": "https://files.example.com/invoices/1/FF84E5DB-79C5-42CE-B415-EC510C53EFB5.json?X-Amz-Expires=900"
}

environment: SANDBOX o PRODUCTION.

Estructura completa del payloadCopy Anchor Link

Si la venta es mayor a $25,000 USD, o necesitas informar datos del cliente, descuentos, productos exentos o pagos a crédito/mixtos, envía el objeto completo. No se aceptan campos adicionales a los documentados: si envías uno desconocido, la petición se rechaza con 400 INVALID_PARAMETERS.

{
  "customer": {
    "name": "Juan Perez",
    "email": "juan.perez@example.com",
    "phone": "7777-7777",
    "document": {
      "type": "DUI",
      "number": "01010101-1"
    },
    "address": {
      "complement": "Col. Escalón, San Salvador",
      "departmentCode": "06",
      "districtCode": "13"
    }
  },
  "items": [
    {
      "sku": "PROD-001",
      "description": "Servicio de consultoría",
      "quantity": 1,
      "unitPrice": 113.0,
      "taxType": "TAXABLE",
      "itemType": "SERVICE",
      "unitOfMeasure": "59",
      "discountAmount": 0
    }
  ],
  "payments": [
    {
      "paymentCode": "01",
      "amount": 56.5
    },
    {
      "paymentCode": "03",
      "amount": 56.5,
      "reference": "AUTH-998877"
    }
  ]
}

CustomerCopy Anchor Link

Datos del cliente. Puedes omitirlo en ventas de hasta $25,000 USD. En ventas mayores a $25,000 USD la normativa exige identificar al cliente.

ItemsCopy Anchor Link

Líneas del documento. Mínimo 1, máximo 2000 (si te pasas, la API responde 400 INVOICE_ITEMS_LIMIT_EXCEEDED).

Ejemplo: 2 unidades a $56.50 con $5.00 de descuento.

{
  "description": "Servicio de consultoría",
  "quantity": 2,
  "unitPrice": 56.5,
  "discountAmount": 5.0
}

La línea queda en $108.00 con IVA incluido (113.00 − 5.00), de los cuales $12.42 son IVA. Lumen calcula el IVA sobre el monto ya descontado; tú no tienes que separarlo.

Significados de taxType:

Indica si el producto o servicio a facturar es gravado, exento o no sujeto a IVA.

Significados de itemType:

Indica si el ítem es un producto, un servicio o ambos.

PaymentsCopy Anchor Link

Formas de pago. Mínimo 1. Puedes enviar más de una si la transacción se pagó con varios medios (por ejemplo 50 % con tarjeta y 50 % en efectivo).

Lumen establece la condición de la operación (CAT-016) automáticamente según los pagos enviados:

Cuando paymentCode es 13 (cuentas por pagar), debes indicar plazo y periodo. Ejemplo para un pago a crédito de 30 días:

{
  "payments": [
    {
      "paymentCode": "13",
      "amount": 150.0,
      "creditTerm": "01",
      "creditPeriod": 30
    }
  ]
}

creditTerm (01) = días; creditPeriod (30) = 30 días de plazo.

Ejemplo de solicitudCopy Anchor Link

curl -X POST https://api-sandbox.lumendte.com/v1/invoices \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tu_access_token" \
  -H "x-company-tax-number: 123456-7" \
  -H "x-establishment-code: M001" \
  -H "x-point-of-sale-code: P001" \
  -H "Idempotency-Key: order-9981" \
  -d '{
    "items": [
      {
        "description": "Servicio de consultoría",
        "quantity": 1,
        "unitPrice": 113.0
      }
    ],
    "payments": [
      {
        "paymentCode": "01",
        "amount": 113.0
      }
    ]
  }'

IdempotenciaCopy Anchor Link

Idempotency-Key es obligatorio para todas las integraciones. Identifica una venta de tu empresa en el ambiente actual (SANDBOX o PRODUCTION) y para este tipo de DTE.

Usa un identificador estable de tu sistema, por ejemplo el id del pedido, id interno, etc. Si la petición hace timeout o falla la red, reenvía el mismo POST con la misma clave, internamente se conserva el correlativo y no se emite un segundo DTE.

No omitas el header ni envíes un valor vacío o solo espacios. En esos casos, la petición queda sin protección contra duplicados y cada POST genera y transmite un DTE nuevo.

Para corregir un rechazo del DTE ante Hacienda, reenvía el POST con la misma Idempotency-Key, el mismo x-establishment-code, el mismo x-point-of-sale-code y el body corregido. Esto es útil en casos cuando por ejemplo el número de identificación del cliente es incorrecto.

ErroresCopy Anchor Link

Todas las respuestas de error comparten esta estructura:

{
  "errorCode": "MH_RECEPTION_TAXPAYER_ERROR",
  "message": "The taxpayer is not active at the tax authority.",
  "statusCode": 422,
  "status": "REJECTED",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-01-M001P001-000000000000001",
  "observations": ["..."]
}

Cómo actuar según statusCopy Anchor Link

El campo status indica hasta qué etapa avanzó la emisión del documento. Úsalo para decidir si debes corregir y reintentar la petición o verificar primero el documento para evitar una emisión duplicada.

Al reintentar, envía la misma Idempotency-Key, el mismo x-establishment-code y el mismo x-point-of-sale-code. Consulta Idempotencia para conocer todas las reglas de reutilización de la clave.

Códigos de errorCopy Anchor Link

Cada error incluye un errorCode estable que no cambia entre versiones. Úsalo para decidir qué hacer en tu integración (POS, ERP, SaaS o checkout) y para mostrar a tus usuarios mensajes claros en su idioma. No dependas del texto de message, que está en inglés y puede cambiar, ni solo del código HTTP, porque varios errores comparten el mismo.