Crear sujeto excluido

Emite una factura de sujeto excluido electrónica en El Salvador cuando tu empresa compra un bien o servicio a un proveedor que no es contribuyente de IVA. Úsalo desde tu ERP, SaaS o módulo de cuentas por pagar al registrar esa compra.

En lugar de entender la normativa para emitir una factura de sujeto excluido, manejar reglas de holgura o redondeo para retención de renta, firmar y transmitir a Hacienda, solo envías proveedor, ítems, si retienes renta y los pagos. Lumen reserva el correlativo, firma, transmite y te devuelve PDF/JSON con URLs prefirmadas.

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/excluded-taxpayers

HeadersCopy Anchor Link

Payload mínimoCopy Anchor Link

El proveedor es obligatorio. Este es el payload mínimo para emitir a contado sin retención de renta:

{
  "supplier": {
    "name": "Juan Perez",
    "documentType": "DUI",
    "documentNumber": "01010101-1",
    "address": {
      "complement": "Col. Escalón, San Salvador",
      "departmentCode": "06",
      "districtCode": "13"
    }
  },
  "items": [
    {
      "description": "Servicio de mantenimiento",
      "quantity": 1,
      "unitPrice": 100.0
    }
  ],
  "withholdIncomeTax": false,
  "payments": [
    {
      "paymentCode": "01",
      "amount": 100.0
    }
  ]
}

Respuesta exitosaCopy Anchor Link

Status: 201 Created

Guarda generationCode y controlNumber. Las URLs pdfUrl y jsonUrl expiran en 15 minutos: descárgalas 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, el documento es válido igualmente: los archivos se generarán 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-14-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 y no tiene validez fiscal. receivedStamp es null. El PDF y el JSON sí quedan disponibles.

{
  "status": "DRAFT",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-14-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 necesitas contacto del proveedor, actividad económica, descuentos, tipo de ítem o pagos a crédito, 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.

Con withholdIncomeTax: true, Lumen aplica retención de renta del 10% sobre el subtotal y la resta del total a pagar: el monto de payments debe ser lo que efectivamente pagas al proveedor.

{
  "supplier": {
    "name": "Juan Perez",
    "email": "juan.perez@example.com",
    "phone": "7777-7777",
    "documentType": "DUI",
    "documentNumber": "01010101-1",
    "economicActivityCode": "62010",
    "address": {
      "complement": "Col. Escalón, San Salvador",
      "departmentCode": "06",
      "districtCode": "13"
    }
  },
  "items": [
    {
      "sku": "SERV-001",
      "description": "Servicio de consultoría",
      "quantity": 1,
      "unitPrice": 100.0,
      "discountAmount": 0,
      "itemType": "SERVICE",
      "unitOfMeasure": "59"
    }
  ],
  "withholdIncomeTax": true,
  "payments": [
    {
      "paymentCode": "05",
      "amount": 90.0,
      "reference": "TRX-98765"
    }
  ]
}

En este ejemplo: subtotal 100, retención 10, total a pagar 90.

Proveedor (sujeto excluido)Copy Anchor Link

Siempre obligatorio.

ÍtemsCopy Anchor Link

Líneas del documento. Mínimo 1, máximo 2000 (si te pasas, la API responde 400 INVOICE_ITEMS_LIMIT_EXCEEDED). Este DTE no lleva IVA: unitPrice es el precio del servicio o bien adquirido.

Significados de itemType:

Retención de rentaCopy Anchor Link

Formas de pagoCopy Anchor Link

Mínimo 1. Puedes enviar más de una si la compra se pagó con varios medios. El monto debe corresponder al total a pagar (después de la retención, si aplica).

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": 250.0,
      "creditTerm": "01",
      "creditPeriod": 30
    }
  ]
}

creditTerm (01) = días; creditPeriod (30) = 30 días de plazo. Envía el monto real; en crédito puro Lumen envía montoPago: 0.00 al MH.

Ejemplo de solicitudCopy Anchor Link

curl -X POST https://api-sandbox.lumendte.com/v1/excluded-taxpayers \
  -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 '{
    "supplier": {
      "name": "Juan Perez",
      "documentType": "DUI",
      "documentNumber": "01010101-1",
      "address": {
        "complement": "Col. Escalón, San Salvador",
        "departmentCode": "06",
        "districtCode": "13"
      }
    },
    "items": [
      {
        "description": "Servicio de mantenimiento",
        "quantity": 1,
        "unitPrice": 100.0
      }
    ],
    "withholdIncomeTax": false,
    "payments": [
      {
        "paymentCode": "01",
        "amount": 100.0
      }
    ]
  }'

IdempotenciaCopy Anchor Link

Idempotency-Key es obligatorio para todas las integraciones. Identifica una compra 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 de la compra, id interno, UUID, 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 una segunda factura.

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 DUI o el NIT del proveedor 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-14-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 (ERP, SaaS o cuentas por pagar) 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.