<!-- Fuente: https://docs.matias-api.com/docs/use-cases/invoice-with-discounts -->
# 🏷️ 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

:::warning ⚠️ 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](https://docs.matias-api.com/docs/intro#obtener-el-token-de-acceso))
- ✅ 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í:

```json
"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

:::tip JSON Listo para Usar
Este es el JSON **real y completo** que acepta MATIAS API. Puedes copiarlo y adaptarlo a tu caso.
:::

```json title="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 |

:::tip 💡 Regla de Oro
**`line_extension_amount`** siempre debe ser igual a:
`(price_amount × quantity) - descuentos`
:::

---

## 🏪 Paso 3: Caso Mayorista con Descuento por Volumen

:::info Caso Real
Cliente mayorista que compra **100 unidades** y recibe **15% de descuento** por volumen.
:::

```json
{
  "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

:::warning 🔐 Requisito: Token de Autenticación
Asegúrate de tener un token válido. Si no tienes uno, [obtén tu token aquí](https://docs.matias-api.com/docs/intro#obtener-el-token-de-acceso).
:::

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

### Respuesta Exitosa

```json
{
  "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
}
```

:::tip ✅ 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

:::tip 💬 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

:::danger ⚠️ 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](https://docs.matias-api.com/docs/interactive-tools.md) para validar

---

## 🎯 Próximos Pasos

[📄 **Factura Simple** Guía básica sin descuentos](https://docs.matias-api.com/docs/use-cases/simple-invoice.md)
[🌎 **Exportación** Facturas internacionales](https://docs.matias-api.com/docs/use-cases/export-scenarios.md)
[⚠️ **Errores Comunes** Troubleshooting](https://docs.matias-api.com/docs/use-cases/common-errors.md)
[🧮 **Calculadora** Herramientas interactivas](https://docs.matias-api.com/docs/interactive-tools.md)

---

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