Crear nota de crédito

Emite una nota de crédito electrónica que disminuye el valor de un comprobante de crédito fiscal ya emitido. Úsalo desde tu ERP, SaaS o backend cuando hay una devolución, un descuento o bonificación posterior a la venta, o una corrección de montos a favor del cliente.

En lugar de armar y entender las especificaciones de la normativa para emitir una nota de crédito, resolver el documento relacionado, separar el IVA de los precios, replicar la retención o percepción de IVA del CCF original y mucho más, solo envías el documento a ajustar, el receptor y los ítems. Lumen valida el vínculo, calcula impuestos, reserva el correlativo, 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/credit-notes

HeadersCopy Anchor Link

Payload mínimoCopy Anchor Link

El caso más común es ajustar un CCF electrónico. Este es el payload mínimo:

{
  "relatedDocument": {
    "documentType": "ELECTRONIC",
    "documentNumber": "FF54E9DB-79C3-42CE-B432-EC552C97EFB9"
  },
  "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": "Devolución de servicio de consultoría",
      "quantity": 1,
      "unitPrice": 113.0
    }
  ]
}

documentNumber es el generationCode que recibiste al emitir el CCF. Para un CCF físico usa documentType: "PHYSICAL", el correlativo impreso como documentNumber y su fecha de emisión en issueDate (YYYY-MM-DD).

Respuesta exitosaCopy Anchor Link

Status: 201 Created

Guarda generationCode y controlNumber: el generationCode lo necesitarás más adelante para descargar el PDF/JSON y para cualquier consulta posterior.

Las URLs pdfUrl y jsonUrl expiran en 15 minutos. 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 nota de crédito es válida igualmente: los archivos se generarán en la primera llamada en los endpoints de descarga. No vuelvas a emitir la nota de crédito.

El campo status indica el resultado:

Procesada (PROCESSED)Copy Anchor Link

{
  "status": "PROCESSED",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-05-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-05-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 informar nombre comercial, contacto, descuentos o una condición de operación distinta a contado, envía el objeto completo. A diferencia de la factura y el CCF, la nota de crédito no lleva payments. No se aceptan campos adicionales a los documentados: si envías uno desconocido, la petición se rechaza con 400 INVALID_PARAMETERS.

{
  "relatedDocument": {
    "documentType": "PHYSICAL",
    "documentNumber": "0001234",
    "issueDate": "2026-06-13"
  },
  "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": "LARGE",
    "economicActivityCode": "46900",
    "address": {
      "complement": "Blvd. Los Próceres, San Salvador",
      "departmentCode": "06",
      "districtCode": "13"
    }
  },
  "items": [
    {
      "sku": "PROD-001",
      "description": "Bonificación por pronto pago",
      "quantity": 1,
      "unitPrice": 56.5,
      "taxType": "TAXABLE",
      "itemType": "SERVICE",
      "unitOfMeasure": "59",
      "discountAmount": 5.65
    }
  ],
  "paymentTerms": "CREDIT"
}

Documento relacionadoCopy Anchor Link

Documento único que se ajusta. Siempre obligatorio.

Para ELECTRONIC, el documento debe:

• Existir en tu cuenta y pertenecer a la empresa de x-company-tax-number.
• Estar en estado PROCESSED (aceptado por Hacienda). En sandbox sin credenciales de Hacienda también se acepta un CCF en DRAFT.

ClienteCopy Anchor Link

Receptor contribuyente. Siempre obligatorio en NC, incluida su dirección. Debe ser el mismo cliente del CCF.

ItemsCopy Anchor Link

Lo que se acredita al cliente. Mínimo 1, máximo 2000 (si te pasas, la API responde 400 INVOICE_ITEMS_LIMIT_EXCEEDED).

Significados de taxType:

Significados de itemType:

Forma de pagoCopy Anchor Link

Condición de la operación (CAT-016). Opcional; si no la envías se usa CASH.

Retención y percepción de IVACopy Anchor Link

Lumen los calcula según el documento relacionado.

Ejemplo de solicitudCopy Anchor Link

curl -X POST https://api-sandbox.lumendte.com/v1/credit-notes \
  -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 '{
    "relatedDocument": {
      "documentType": "ELECTRONIC",
      "documentNumber": "FF54E9DB-79C3-42CE-B432-EC552C97EFB9"
    },
    "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": "Devolución de servicio de consultoría",
        "quantity": 1,
        "unitPrice": 113.0
      }
    ]
  }'

IdempotenciaCopy Anchor Link

Idempotency-Key es obligatorio para todas las integraciones. Identifica una nota de crédito 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 devolución, id interno, un 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 nota de crédito.

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_DOCUMENT_ERROR",
  "message": "The amount exceeds the amount of the related document at the tax authority.",
  "statusCode": 422,
  "status": "REJECTED",
  "generationCode": "FF84E5DB-79C5-42CE-B415-EC510C53EFB5",
  "controlNumber": "DTE-05-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.