Crear nota de crédito

Emite una nota de crédito que ajusta un comprobante de crédito fiscal ya emitido. Úsalo desde tu ERP, Saas o backend cuando hay una devolución, anulación parcial o corrección sobre un CCF.

En lugar de armar el JSON del DTE tipo 05, resolver el documento relacionado, calcular IVA y firmar/transmitir a Hacienda, solo envías el documento a ajustar, el receptor y los ítems. Lumen valida el vínculo, reserva el correlativo, transmite y te devuelve PDF/JSON con URLs prefirmadas.

Método: POST

https://api-sandbox.lumendte.com/v1/credit-notes

https://api.lumendte.com/v1/credit-notes

Headers

Campo	Tipo	Requerido	Descripción
`Authorization`	`string`	Sí	`Bearer <access_token>` (Client Credentials)
`x-company-tax-number`	`string`	Sí	NRC de la empresa emisora (con o sin guiones)
`x-establishment-code`	`string`	Sí	Código dado por MH para el establecimiento (ej. `M001`)
`x-point-of-sale-code`	`string`	Sí	Código dado por MH para el punto de venta (ej. `P001`)

Payload mínimo

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 (UUID) del CCF electrónico. En documentos físicos usa documentType: "PHYSICAL", en físicos documentNumber es el correlativo/serie impreso y issueDate (YYYY-MM-DD).

Respuesta exitosa

Status: 201 Created

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.

El campo status indica el resultado:

`status`	Cuándo aplica
`TRANSMITTED`	El DTE se firmó y se envió a Hacienda
`DRAFT`	Solo en sandbox, sin credenciales de facturación y certificado: no se firma ni se transmite

Transmitida (`TRANSMITTED`)

{
  "status": "TRANSMITTED",
  "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`)

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-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 payload

Si necesitas nombre comercial, contacto, descuentos o un documento relacionado físico, envía el objeto completo:

{
  "relatedDocument": {
    "documentType": "PHYSICAL",
    "documentNumber": "S221001345",
    "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": "MEDIUM",
    "economicActivityCode": "46900",
    "address": {
      "complement": "Blvd. Los Próceres, San Salvador",
      "departmentCode": "06",
      "districtCode": "13"
    }
  },
  "items": [
    {
      "sku": "PROD-001",
      "description": "Ajuste por devolución",
      "quantity": 1,
      "unitPrice": 113.0,
      "taxType": "TAXABLE",
      "itemType": "SERVICE",
      "unitOfMeasure": "59",
      "discount": {
        "amount": 0,
        "percentage": 0
      }
    }
  ]
}

`relatedDocument`

Documento único que se ajusta. Siempre obligatorio.

Campo	Tipo	Requerido	Descripción
`documentType`	`string`	Sí	`PHYSICAL` o `ELECTRONIC`
`documentNumber`	`string`	Sí	UUID (`generationCode`) si es electrónico; correlativo/serie impreso si es físico
`issueDate`	`string`	Condicional	`YYYY-MM-DD`. Obligatorio si `documentType` es `PHYSICAL`. En electrónicos ya esta gestionado por Lumen

Para ELECTRONIC, Lumen exige que el DTE exista, sea un CCF y esté en TRANSMITTED o ACCEPTED.

`customer`

Receptor contribuyente. Siempre obligatorio en NC.

Campo	Tipo	Requerido	Descripción
`name`	`string`	Sí	Nombre o razón social del cliente
`taxIdentityNumber`	`string`	Sí	NIT del cliente (con o sin guiones)
`taxRegistrationNumber`	`string`	Sí	NRC del cliente (con o sin guiones)
`taxpayerType`	`string`	Sí	`SMALL`, `MEDIUM` o `LARGE`
`economicActivityCode`	`string`	Sí	Código de actividad económica (1–5). Ver Actividades económicas
`tradeName`	`string`	No	Nombre comercial del cliente
`email`	`string`	No	Correo del cliente
`phone`	`string`	No	Teléfono nacional o internacional (ej. `2255-8888`, `+503 2255-8888`)
`address.complement`	`string`	No	Complemento de dirección (calle, colonia, etc.)
`address.departmentCode`	`string`	No	Código de departamento. Ver Departamentos
`address.districtCode`	`string`	No	Código de distrito. Ver Distritos

`items`

Líneas del documento. Mínimo 1, máximo 2000.

Campo	Tipo	Requerido	Descripción
`description`	`string`	Sí	Descripción del ítem
`quantity`	`number`	Sí	Cantidad (> 0)
`unitPrice`	`number`	Sí	Precio unitario con IVA incluido (> 0)
`sku`	`string \| null`	No	Código interno del producto
`taxType`	`string`	No	`TAXABLE` (default), `EXEMPT`, `NOT_SUBJECT`
`itemType`	`string`	No	`GOODS`, `SERVICE` (default), `BOTH`
`unitOfMeasure`	`string`	No	Unidad de medida del producto. Default: `"59"` (Unidad). Ver Unidades de medida
`discount.amount`	`number`	No	Descuento monetario de la línea (≥ 0). Default: `0`
`discount.percentage`	`number`	No	Porcentaje de descuento (0–100). Default: `0`

Significados de taxType:

Valor	Significado
`TAXABLE`	Venta gravada
`EXEMPT`	Venta exenta
`NOT_SUBJECT`	Venta no sujeta

Significados de itemType:

Valor	Significado
`GOODS`	Productos o bienes
`SERVICE`	Servicio
`BOTH`	Implica tanto servicio como producto a la vez

Ejemplo de Solicitud

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" \
  -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
      }
    ]
  }'

const axios = require("axios");

const config = {
  method: "post",
  url: "https://api-sandbox.lumendte.com/v1/credit-notes",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    Authorization: "Bearer tu_access_token",
    "x-company-tax-number": "123456-7",
    "x-establishment-code": "M001",
    "x-point-of-sale-code": "P001",
  },
  data: {
    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,
      },
    ],
  },
};

axios(config)
  .then((response) => {
    console.log(
      "Nota de crédito aceptada:",
      response.data.controlNumber,
      response.data.pdfUrl,
    );
  })
  .catch((error) => {
    console.error(
      "Error en la solicitud:",
      error.response ? error.response.data : error.message,
    );
  });

import requests

response = requests.post(
    'https://api-sandbox.lumendte.com/v1/credit-notes',
    headers={
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer tu_access_token',
        'x-company-tax-number': '123456-7',
        'x-establishment-code': 'M001',
        'x-point-of-sale-code': 'P001',
    },
    json={
        '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,
            },
        ],
    },
)

if response.ok:
    data = response.json()
    print('Nota de crédito aceptada:', data['controlNumber'], data['pdfUrl'])
else:
    print('Error en la solicitud:', response.text)

Errores frecuentes

400 — Documento relacionado no es CCF

El DTE electrónico relacionado existe, pero no es un comprobante de crédito fiscal.

{
  "errorCode": "RELATED_DOCUMENT_INVALID_TYPE",
  "message": "Related electronic document must be a tax credit voucher (03). Found document type 01",
  "statusCode": 400
}

Fix: Usa el generationCode de un crédito fiscal, no de otro tipo de documento.

400 — Estado inválido del documento relacionado

El CCF electrónico existe, pero aún no está listo para ser ajustado.

{
  "errorCode": "ELECTRONIC_INVOICE_INVALID_STATUS",
  "message": "Related electronic document must be TRANSMITTED or ACCEPTED (current: DRAFT)",
  "statusCode": 400
}

Fix: Espera a que el CCF quede en TRANSMITTED o ACCEPTED. Un borrador de sandbox (DRAFT) no se puede referenciar como documento relacionado.