Crear crédito fiscal

Emite un comprobante de crédito fiscal a un cliente contribuyente de IVA. Úsalo desde tu ERP, Saas o backend B2B cuando el receptor necesita crédito fiscal.

En lugar de armar el JSON del DTE, calcular IVA, IVA percibido o retenido cuando aplique, firmar con certificado 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.

Método: POST

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

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

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

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

environment: SANDBOX o PRODUCTION.

Estructura completa del payload

Si necesitas nombre comercial, contacto, descuentos, ítems exentos o pagos a crédito/mixtos, envía el objeto completo:

{
  "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",
      "discount": {
        "amount": 0,
        "percentage": 0
      }
    }
  ],
  "payments": [
    {
      "paymentCode": "01",
      "amount": 113.0
    }
  ]
}

`customer`

Receptor contribuyente. Siempre obligatorio en CCF.

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 50.

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

`payments`

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:

Pagos enviados	Condición
Solo contado (cualquier código ≠ `13`)	Contado
Solo crédito (`13`)	Crédito
Crédito (`13`) + contado	Mixto

Campo	Tipo	Requerido	Descripción
`paymentCode`	`string`	Sí	Código de forma de pago. Ver Formas de pago
`amount`	`number`	Sí	Monto del pago. Envíalo siempre con el valor real de esa forma de pago.
`reference`	`string`	No	Referencia o código de autorización. Se omite en efectivo (`01`) y en crédito puro
`creditTerm`	`string \| null`	Condicional	Tipo de plazo CAT-018. Requerido si `paymentCode` es `13` (ej. `01` = Días)
`creditPeriod`	`number \| null`	Condicional	Cantidad de días/meses/años según `creditTerm` (1–999). Requerido si `paymentCode` es `13`
`methodDetail`	`string \| null`	Condicional	Requerido si `paymentCode` es `99` (Otros)

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. Envía el monto real; en crédito puro Lumen envía montoPago: 0.00 al MH.

Ejemplo de Solicitud

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

const axios = require("axios");

const config = {
  method: "post",
  url: "https://api-sandbox.lumendte.com/v1/tax-invoices",
  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: {
    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,
      },
    ],
  },
};

axios(config)
  .then((response) => {
    console.log(
      "Crédito fiscal aceptado:",
      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/tax-invoices',
    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={
        '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,
            },
        ],
    },
)

if response.ok:
    data = response.json()
    print('Crédito fiscal aceptado:', data['controlNumber'], data['pdfUrl'])
else:
    print('Error en la solicitud:', response.text)

Errores frecuentes

404 — Actividad económica no encontrada

El economicActivityCode del receptor no existe en el catálogo.

{
  "errorCode": "ECONOMIC_ACTIVITY_NOT_FOUND",
  "message": "Economic activity with code 46900 was not found",
  "error": "Not Found",
  "statusCode": 404
}

Fix: Usa un code válido del catálogo de Actividades económicas.

422 — Rechazo de Hacienda

El MH rechazó la recepción (contribuyente inactivo, normativa o autorización de emisión).

{
  "errorCode": "MH_RECEPTION_TAXPAYER_ERROR",
  "message": "The taxpayer is not active at the tax authority.",
  "statusCode": 422
}

Fix: Verifica que la empresa esté activa para emitir factura electrónica y que la configuración esté lista para el ambiente Sandbox o Producción. Confirma también NIT/NRC del receptor.