Ver .md Abrir en ChatGPT Abrir en Claude

🏷️ Guía: Factura con Descuentos

📋 Introducción

Esta guía te enseñará cómo emitir una factura electrónica con descuentos comerciales. Los descuentos se aplican a nivel de línea y reducen la base imponible para el cálculo de impuestos.

🎯 ¿Cuándo usar esta guía?

✅ Cliente mayorista con descuento

✅ Descuento por volumen o promoción

✅ Descuento comercial o rebaja

✅ Operación con incentivo al cliente

⚠️ Punto Crítico

En el API MATIAS, los descuentos se aplican usando allowance_charges dentro de cada línea del producto, NO como campo separado global.

📦 Requisitos Previos

Antes de empezar, asegúrate de tener:

✅ Token de autenticación válido (ver guía)
✅ Resolución de facturación activa
✅ Información completa del cliente
✅ Productos con precio base y porcentaje de descuento

🔧 Estructura de Descuentos en el API

En MATIAS API, los descuentos se manejan así:

"allowance_charges": [
  {
    "amount": "VALOR_DESCUENTO",
    "base_amount": "VALOR_ORIGINAL",
    "charge_indicator": false,
    "allowance_charge_reason": "Promocion"
  }
]

📊 Descripción de Campos

Campo	Tipo	Descripción	Ejemplo
`amount`	decimal	Valor del descuento en dinero	`22.00`
`base_amount`	decimal	Valor original (price_amount × quantity)	`220.00`
`charge_indicator`	boolean	`false` = descuento, `true` = cargo	`false`
`allowance_charge_reason`	string	Motivo del descuento	`"Promocion"`

🧮 La Matemática de Descuentos

La fórmula correcta es:

PASO 1: PRECIO UNITARIO × CANTIDAD = SUBTOTAL
↓
PASO 2: SUBTOTAL - DESCUENTO = VALOR FINAL
↓
PASO 3: VALOR FINAL × TASA IVA = IMPUESTO
↓
PASO 4: VALOR FINAL + IMPUESTO = TOTAL

💡 Ejemplo Práctico

📊 Datos Iniciales

💵 Precio unitario: $220.00
📦 Cantidad: 1
➕ Subtotal: $220.00

✅ Resultado Final

🏷️ Descuento (10%): $22.00
💰 Valor final: $198.00
📋 Impuesto (0%): $0.00
🎯 TOTAL: $198.00

📄 Paso 1: Ejemplo Real del API

JSON Listo para Usar

Este es el JSON real y completo que acepta MATIAS API. Puedes copiarlo y adaptarlo a tu caso.

factura-con-descuento.json
{
  "resolution_number": "18764074347312",
  "prefix": "FEV",
  "notes": "Factura con descuento comercial",
  "document_number": "2005",
  "graphic_representation": 0,
  "send_email": 1,
  "operation_type_id": 1,
  "type_document_id": 7,
  
  "payments": [
    {
      "payment_method_id": 1,
      "means_payment_id": 10,
      "value_paid": "198.00"
    }
  ],
  
  "customer": {
    "country_id": "45",
    "city_id": "1041",
    "identity_document_id": "3",
    "type_organization_id": 2,
    "tax_regime_id": 2,
    "tax_level_id": 5,
    "company_name": "CONSUMIDOR FINAL",
    "dni": "222222222222",
    "mobile": "3043965204",
    "email": "compras@cliente.com",
    "address": "CALLE 22 NRO. 32 29",
    "postal_code": "76834"
  },
  
  "lines": [
    {
      "invoiced_quantity": "1",
      "quantity_units_id": "1093",
      "line_extension_amount": "198.00",
      "free_of_charge_indicator": false,
      "description": "CALZADO OSIRIS D3 2001",
      "code": "A50824",
      "type_item_identifications_id": "4",
      "reference_price_id": "1",
      "price_amount": "220.00",
      "base_quantity": "1",
      
      "allowance_charges": [
        {
          "amount": "22.00",
          "base_amount": "220.00",
          "charge_indicator": false,
          "allowance_charge_reason": "Promocion"
        }
      ]
    }
  ],
  
  "legal_monetary_totals": {
    "line_extension_amount": "198.00",
    "tax_exclusive_amount": "0.00",
    "tax_inclusive_amount": "198.00",
    "payable_amount": 198.00
  }
}

🔍 Paso 2: Entender la Estructura

🎯 Campos Clave para Descuentos

Analicemos el JSON línea por línea:

Campo	Valor	Explicación	Fórmula
`price_amount`	`220.00`	💵 Precio SIN descuento	Precio base
`base_amount`	`220.00`	📊 Base para descuento	`price_amount × quantity`
`amount` (descuento)	`22.00`	🏷️ Valor del descuento	`220.00 × 0.10` (10%)
`line_extension_amount`	`198.00`	💰 Precio FINAL	`220.00 - 22.00`
`charge_indicator`	`false`	⬇️ Tipo de ajuste	`false` = descuento

💡 Regla de Oro

line_extension_amount siempre debe ser igual a: (price_amount × quantity) - descuentos

🏪 Paso 3: Caso Mayorista con Descuento por Volumen

Caso Real

Cliente mayorista que compra 100 unidades y recibe 15% de descuento por volumen.

{
  "resolution_number": "18764074347312",
  "prefix": "LZT",
  "document_number": "5045",
  "operation_type_id": 1,
  "type_document_id": 7,
  "graphic_representation": 0,
  "send_email": 1,
  
  "customer": {
    "country_id": "45",
    "city_id": "76",
    "identity_document_id": "2",
    "type_organization_id": 2,
    "tax_regime_id": 1,
    "tax_level_id": 5,
    "company_name": "CLIENTE MAYORISTA",
    "dni": "8001234567",
    "email": "compras@mayorista.com",
    "address": "Calle 100 #50-80",
    "postal_code": "050001"
  },
  
  "lines": [
    {
      "invoiced_quantity": "100",
      "quantity_units_id": "1093",
      "price_amount": "10000.00",
      "line_extension_amount": "850000.00",
      "description": "PRODUCTO A - 100 unidades",
      "code": "PRD-A",
      "type_item_identifications_id": "4",
      "reference_price_id": "1",
      "base_quantity": "100",
      
      "allowance_charges": [
        {
          "amount": "150000.00",
          "base_amount": "1000000.00",
          "charge_indicator": false,
          "allowance_charge_reason": "Descuento volumen 15%"
        }
      ],
      
      "tax_totals": [
        {
          "tax_id": "1",
          "tax_amount": 161500.00,
          "taxable_amount": 850000.00,
          "percent": 19
        }
      ]
    }
  ],
  
  "legal_monetary_totals": {
    "line_extension_amount": "850000.00",
    "tax_exclusive_amount": "850000.00",
    "tax_inclusive_amount": "1011500.00",
    "payable_amount": 1011500.00
  },
  
  "tax_totals": [
    {
      "tax_id": "1",
      "tax_amount": 161500.00,
      "taxable_amount": 850000.00,
      "percent": 19
    }
  ],
  
  "payments": [
    {
      "payment_method_id": 1,
      "means_payment_id": 10,
      "value_paid": "1011500.00"
    }
  ]
}

🧮 Desglose de Cálculos

💰 Cálculo Paso a Paso

💵 Precio unitario:	$10,000.00
📦 Cantidad:	100
➕ Subtotal:	$1,000,000.00
🏷️ Descuento (15%):	- $150,000.00
💰 Valor final:	$850,000.00
📊 IVA (19%):	+ $161,500.00
🎯 TOTAL A PAGAR:	$1,011,500.00

🚀 Paso 4: Enviar a la API

🔐 Requisito: Token de Autenticación

Asegúrate de tener un token válido. Si no tienes uno, obtén tu token aquí.

curl -X POST {{url}}/invoice \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @factura-descuento.json

Respuesta Exitosa

{
  "message": "El documento ha sido procesado por la DIAN.",
  "send_to_queue": 0,
  "XmlDocumentKey": "d45f3b2ed042ce0e075891591c3b3a7ae3a9c176ca191dab1bd23e5cdd3b48b8c548a088dfcbe20ee7baa2bed2dccd48",
  "response": {
    "ErrorMessage": {
      "string": []
    },
    "IsValid": "true",
    "StatusCode": "00",
    "StatusDescription": "Procesado Correctamente.",
    "StatusMessage": "La Factura electrónica FEV2005, ha sido autorizada.",
    "XmlDocumentKey": "d45f3b2ed042ce0e075891591c3b3a7ae3a9c176ca191dab1bd23e5cdd3b48b8c548a088dfcbe20ee7baa2bed2dccd48",
    "XmlFileName": "fv09010914030002500000096"
  },
  "AttachedDocument": {
    "path": "1/ad/ad09010914030002500000042.xml",
    "url": "https://sandbox-api.matias-api.com/attachments/1/ad/ad09010914030002500000042.xml"
  },
  "pdf": {
    "path": "1/fv09010914030002500000096.pdf",
    "url": "https://sandbox-api.matias-api.com/pdf/1/fv09010914030002500000096.pdf"
  },
  "success": true
}

✅ Respuesta Exitosa

Indicadores de éxito:

✅ success: true
✅ StatusCode: "00"
✅ IsValid: "true"
✅ CUFE generado (XmlDocumentKey)
✅ URLs de PDF y XML disponibles

📝 Paso 5: Razones de Descuento Válidas

💬 Descripción del Descuento

En el campo allowance_charge_reason usa una descripción clara del motivo del descuento:

🎉

Promocion
Descuento promocional

📦

Volumen
Descuento por cantidad

⚡

Pronto pago
Pago inmediato

🎁

Bonificacion
Bonificación especial

💰

Rebaja
Rebaja comercial

✅ Validaciones Críticas

⚠️ Verificar ANTES de Enviar

Estas validaciones son obligatorias para que la DIAN acepte tu factura:

🔐 Checklist de Validación

☐ allowance_charges[].amount ≤ allowance_charges[].base_amount
El descuento no puede ser mayor al precio base

☐ line_extension_amount = price_amount × quantity - descuentos
El valor final debe reflejar el descuento aplicado

☐ tax_amount = taxable_amount × (percent / 100)
El impuesto se calcula sobre el valor CON descuento

☐ tax_exclusive_amount = suma de line_extension_amount
Total sin impuestos = suma de líneas finales

☐ tax_inclusive_amount = tax_exclusive_amount + impuestos
Total con impuestos incluidos

☐ payable_amount = tax_inclusive_amount
Monto a pagar = total con impuestos

☐ charge_indicator = false para descuentos
false = descuento, true = cargo adicional

🔧 Troubleshooting

❌ Error: "allowance_charges amount exceeds base amount"

❌ Causa: El descuento es mayor al precio original
✅ Solución: Verifica que amount ≤ base_amount

❌ Error: "Tax calculated on wrong amount"

❌ Causa: Impuesto calculado sobre el precio SIN descuento
✅ Solución: Calcula impuesto sobre line_extension_amount (después del descuento)

❌ Error: "Total mismatch"

❌ Causa: Los totales no coinciden
✅ Solución: Usa la herramienta TotalCalculator para validar

🎯 Próximos Pasos

📄

Factura Simple
Guía básica sin descuentos

🌎

Exportación
Facturas internacionales

⚠️

Errores Comunes
Troubleshooting

🧮

Calculadora
Herramientas interactivas

📅 Última actualización: Febrero 2026 • ⏱️ Tiempo estimado: 20 minutos • 🎯 Nivel: ⭐⭐ Intermedio

📋 Introducción​

🎯 ¿Cuándo usar esta guía?​

📦 Requisitos Previos​

🔧 Estructura de Descuentos en el API​

📊 Descripción de Campos​

🧮 La Matemática de Descuentos​

💡 Ejemplo Práctico​

📊 Datos Iniciales

✅ Resultado Final

📄 Paso 1: Ejemplo Real del API​

🔍 Paso 2: Entender la Estructura​

🎯 Campos Clave para Descuentos​

🏪 Paso 3: Caso Mayorista con Descuento por Volumen​

🧮 Desglose de Cálculos​

💰 Cálculo Paso a Paso

🚀 Paso 4: Enviar a la API​

Respuesta Exitosa​

📝 Paso 5: Razones de Descuento Válidas​

✅ Validaciones Críticas​

🔐 Checklist de Validación​

🔧 Troubleshooting​

❌ Error: "allowance_charges amount exceeds base amount"​

❌ Error: "Tax calculated on wrong amount"​

❌ Error: "Total mismatch"​

🎯 Próximos Pasos​