Crear crédito fiscal

Emite un comprobante de crédito fiscal electrónico (CCF) a un cliente contribuyente de IVA. Úsalo desde tu ERP, SaaS o POS.

En lugar de armar el JSON del DTE, separar el IVA de los precios, calcular la retención o percepción de IVA cuando aplique, firmar digitalmente y llamar a recepción del MH, solo envías cliente, ítems y pagos. Lumen abstrae el proceso, 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/tax-invoices

HeadersCopy Anchor Link

Payload mínimoCopy Anchor Link

El CCF exige receptor contribuyente. Este es el payload mínimo para emitir a contado:

{
  "customer": {
    "name": "Distribuidora Morazán S.A. de C.V.",
    "taxIdentityNumber": "0614-280310-102-8",
    "taxRegistrationNumber": "298145-4",
    "taxpayerType": "MEDIUM",
    "economicActivityCode": "46900",
    "address": {
      "complement": "Blvd. Los Próceres, San Salvador",
      "departmentCode": "06",
      "districtCode": "13"
    }
  },
  "items": [
    {
      "description": "Servicio de consultoría",
      "quantity": 1,
      "unitPrice": 113.0
    }
  ],
  "payments": [
    {
      "paymentCode": "01",
      "amount": 113.0
    }
  ]
}

Respuesta exitosaCopy Anchor Link

Status: 201 Created

Guarda generationCode y controlNumber. El generationCode también lo necesitas para emitir notas de crédito que hagan referencia a este CCF.

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, el crédito fiscal es válido igualmente, los archivos se generan en la primera llamada a los endpoints de descarga. No vuelvas a emitir el comprobante.

El campo status indica el resultado:

Procesado (PROCESSED)Copy Anchor Link

{
  "status": "PROCESSED",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-03-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-03-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 nombre comercial, contacto, descuentos, ítems 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": "Distribuidora Morazán S.A. de C.V.",
    "tradeName": "Comercial Morazán",
    "taxIdentityNumber": "0614-280310-102-8",
    "taxRegistrationNumber": "298145-4",
    "email": "facturacion@morazan.com",
    "phone": "+503 2255-8888",
    "taxpayerType": "MEDIUM",
    "economicActivityCode": "46900",
    "address": {
      "complement": "Blvd. Los Próceres, 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": 113.0
    }
  ]
}

CustomerCopy Anchor Link

Receptor contribuyente. Siempre obligatorio en CCF, incluida su dirección.

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 $565.00 con $56.50 de descuento.

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

La línea queda en $950.00 sin IVA (1000.00 − 50.00) más $123.50 de IVA: total $1,073.50, que es 1130.00 − 56.50. En ítems gravados Lumen separa el IVA del descuento y calcula el IVA sobre el monto ya descontado; tú no tienes que separarlo. En ítems exentos o no sujetos el descuento se toma tal cual.

Significados de taxType:

Significados de itemType:

PaymentsCopy Anchor Link

Formas de pago. Mínimo 1. Puedes enviar más de una si la transacción se pagó con varios medios.

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. En ventas a crédito envía siempre el monto real de la venta.

Retención y percepción de IVACopy Anchor Link

No envías estos montos: Lumen los calcula con el taxpayerType de tu empresa y el del cliente. Solo aplican cuando el monto gravado neto (después de descuentos y sin IVA) es de $100.00 o más:

Ejemplo de solicitudCopy Anchor Link

curl -X POST https://api-sandbox.lumendte.com/v1/tax-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 '{
    "customer": {
      "name": "Distribuidora Morazán S.A. de C.V.",
      "taxIdentityNumber": "0614-280310-102-8",
      "taxRegistrationNumber": "298145-4",
      "taxpayerType": "MEDIUM",
      "economicActivityCode": "46900",
      "address": {
        "complement": "Blvd. Los Próceres, San Salvador",
        "departmentCode": "06",
        "districtCode": "13"
      }
    },
    "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 NIT o el NRC 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-03-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 backend B2B) 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.