<!-- Fuente: https://docs.matias-api.com/docs/use-cases/export-scenarios -->
# 🌎 Guía: Exportaciones e Internacionalización

## 📋 Introducción

Esta guía te enseñará cómo emitir facturas de **exportación**. Las facturas de exportación tienen características especiales: cliente en el exterior, moneda extranjera, y están exentas de IVA.

---

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

✅ **Venta a cliente** en el exterior

✅ **Transacción en moneda** extranjera (USD, EUR)

✅ **Productos salen** de Colombia

✅ **Cliente sin NIT** colombiano

✅ **Requiere tasa** de cambio especificada

:::warning ⚠️ Punto Crítico
En API MATIAS, la exportación se marca con:
- 📑 **`type_document_id: 8`** (Factura de Exportación)
- 🔄 **`operation_type_id: 1`** (NO usar `operation_type_id: 2`)
:::

---

## 📦 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 del cliente extranjero
- ✅ Tasa de cambio (TRM) del día
- ✅ Documentos de exportación (si aplica)

---

## 🔑 Características Clave de Exportación

| Característica | Valor | 📝 Descripción |
|---|---|---|
| **Tipo de Documento** | `type_document_id: 8` | 🌎 Factura de Exportación |
| **Operación** | `operation_type_id: 1` | 🔄 Operación estándar |
| **Moneda** | `currency_id: 272` | 💵 Dólares USD (u otra moneda) |
| **IVA** | Exento (0%) | 🚫 Sin impuestos |
| **Cliente** | País ≠ Colombia | 🌍 Extranjero |
| **Tasa de Cambio** | `payment_exchange_rate` | 💱 TRM del día |

## Paso 1: Información del Cliente Exterior

El cliente debe ser de otro país:

```json
{
  "country_id": "239",
  "identity_document_id": "10",
  "type_organization_id": 1,
  "company_name": "AMAZON",
  "dni": "444444055",
  "address": "NORTE DE VIRGINIA H10",
  "city_name": "VIRGINIA",
  "postal_code": "110121"
}
```

### 🌍 Códigos de País Comunes

🇺🇸 **Estados Unidos:** 239

🇲🇽 **México:** 137

🇧🇷 **Brasil:** 37

🇵🇦 **Panamá:** 155

🇪🇨 **Ecuador:** 70

🇨🇦 **Canadá:** 41

🇪🇸 **España:** 217

### 📍 Tipos de Documento para Extranjeros

| Código | Tipo de Documento | 📝 Uso |
|--------|------------------|------|
| `10` | **Pasaporte** | Personas naturales extranjeras |
| `3` | **Cédula Extranjería** | Extranjeros residentes en Colombia |
| `12` | **NIT Extranjero** | Empresas internacionales |

---

## 💱 Paso 2: Configurar Moneda y Tasa de Cambio

:::info TRM - Tasa Representativa del Mercado
Usa la **TRM oficial** del día de la transacción. Puedes consultarla en el [Banco de la República](https://www.banrep.gov.co/es/estadisticas/trm).
:::

```json
{
  "currency_id": 272,
  "payment_exchange_rate": {
    "exchange_rate": "4243.80",
    "base_rate": "4243.80",
    "rate_date": "2025-05-05",
    "currency_id": 188
  }
}
```

### 📊 Descripción de Campos

| Campo | Tipo | Descripción | Ejemplo |
|-------|------|-------------|----------|
| `currency_id` | integer | 💵 Moneda del documento | `272` (USD) |
| `exchange_rate` | decimal | 💱 TRM del día (pesos/dólar) | `"4243.80"` |
| `base_rate` | decimal | 📊 Tasa base (igual a exchange_rate) | `"4243.80"` |
| `rate_date` | date | 📅 Fecha de la transacción | `"2025-05-05"` |
| `currency_id` (dentro) | integer | 💴 Moneda base (COP = 188) | `188` |

### 💵 Códigos de Moneda Comunes

💵 **USD (Dólar):** 272

💶 **EUR (Euro):** 273

💴 **COP (Peso):** 170

💵 **MXN (Peso MX):** 274

💶 **BRL (Real):** 275

---

## 📄 Paso 3: Ejemplo Real de Exportación

:::tip JSON Listo para Usar
Este es el JSON **real y completo** para una factura de exportación a Estados Unidos.
:::

```json title="factura-exportacion.json"
{
  "resolution_number": "18764074347312",
  "prefix": "LZT",
  "document_number": "2055",
  "operation_type_id": 1,
  "type_document_id": 8,
  "currency_id": 272,
  "graphic_representation": 0,
  "send_email": 1,
  
  "payments": [
    {
      "payment_method_id": 1,
      "means_payment_id": 42,
      "value_paid": "4243.80"
    }
  ],
  
  "payment_exchange_rate": {
    "exchange_rate": "4243.80",
    "base_rate": "4243.80",
    "rate_date": "2025-05-05",
    "currency_id": 188
  },
  
  "customer": {
    "country_id": "239",
    "identity_document_id": "10",
    "type_organization_id": 1,
    "company_name": "AMAZON",
    "dni": "444444055",
    "address": "NORTE DE VIRGINIA H10",
    "city_name": "VIRGINIA",
    "postal_code": "110121"
  },
  
  "lines": [
    {
      "invoiced_quantity": "1.00",
      "quantity_units_id": "1093",
      "line_extension_amount": "4243.80",
      "free_of_charge_indicator": false,
      "description": "HONORARIOS REPRESENTACION LEGAL",
      "code": "999-001",
      "type_item_identifications_id": "4",
      "reference_price_id": "1",
      "price_amount": "4243.80",
      "base_quantity": 1.00
    }
  ],
  
  "legal_monetary_totals": {
    "line_extension_amount": "4243.80",
    "tax_exclusive_amount": "0.00",
    "tax_inclusive_amount": "4243.80",
    "payable_amount": 4243.80
  }
}
```

### 🧮 Desglose de Cálculos

#### 💰 Cálculo en USD

| 💵 Precio unitario (USD): | **$4,243.80** |
|---|---|

| 📦 Cantidad: | **1** |

| ➕ Subtotal (USD): | **$4,243.80** |

| 🚫 Impuesto: | **$0.00 (Exento)** |

| 🎯 TOTAL (USD): | **$4,243.80** |

#### 💱 Conversión a COP

**TRM:** 4,243.80 COP/USD  

**Equivalente en COP:** $4,243.80 USD × 4,243.80 = ~$18,000,000 COP

---

## 📦 Paso 4: Exportación con Múltiples Líneas

:::info Caso Real
Exportación de **textiles a México** con múltiples productos.
:::

```json
{
  "resolution_number": "18764074347312",
  "prefix": "EXP",
  "document_number": "2100",
  "operation_type_id": 1,
  "type_document_id": 8,
  "currency_id": 272,
  "graphic_representation": 0,
  "send_email": 1,
  
  "payments": [
    {
      "payment_method_id": 1,
      "means_payment_id": 42,
      "value_paid": "12500.00"
    }
  ],
  
  "payment_exchange_rate": {
    "exchange_rate": "4243.80",
    "base_rate": "4243.80",
    "rate_date": "2025-05-05",
    "currency_id": 188
  },
  
  "customer": {
    "country_id": "137",
    "city_id": "100001",
    "identity_document_id": "10",
    "type_organization_id": 2,
    "company_name": "GRUPO COMERCIAL MEXICO",
    "dni": "AAA123456789",
    "mobile": "+52-555-1234567",
    "email": "compras@grupocomercial.com.mx",
    "address": "Avenida Paseo de la Reforma 505",
    "postal_code": "06500"
  },
  
  "lines": [
    {
      "invoiced_quantity": "100",
      "quantity_units_id": "1093",
      "line_extension_amount": "7500.00",
      "free_of_charge_indicator": false,
      "description": "TEXTILES - Tela de algodón 100%",
      "code": "TEX-001",
      "type_item_identifications_id": "4",
      "reference_price_id": "1",
      "price_amount": "75.00",
      "base_quantity": "100"
    },
    {
      "invoiced_quantity": "50",
      "quantity_units_id": "1093",
      "line_extension_amount": "5000.00",
      "free_of_charge_indicator": false,
      "description": "TEXTILES - Hilo de poliéster",
      "code": "TEX-002",
      "type_item_identifications_id": "4",
      "reference_price_id": "1",
      "price_amount": "100.00",
      "base_quantity": "50"
    }
  ],
  
  "legal_monetary_totals": {
    "line_extension_amount": "12500.00",
    "tax_exclusive_amount": "0.00",
    "tax_inclusive_amount": "12500.00",
    "payable_amount": 12500.00
  }
}
```

---

## 🚀 Paso 5: 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-exportacion.json
```

### Respuesta Exitosa

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

:::tip ✅ Respuesta Exitosa
**Indicadores de éxito:**
- ✅ `success: true`
- ✅ `StatusCode: "00"`
- ✅ `IsValid: "true"`
- ✅ CUFE generado (`XmlDocumentKey`)
- ✅ URLs de PDF y XML disponibles
- ✅ Documento registrado en DIAN
:::

---

## 📃 Documentación Requerida para DIAN

✅ **Certificado de origen**  

(si aplica según destino)

✅ **Documentos de aduanas**  

Declaración de exportación

✅ **Declaración de exportación**  

Formulario DIAN

✅ **Comprobante de cambio**  

TRM aplicada

✅ **Comprobante de envío**  

Guía internacional

---

## ✅ Validaciones Críticas

:::danger ⚠️ Verificar ANTES de Enviar
Estas validaciones son **obligatorias** para facturas de exportación:
:::

### 🔐 Checklist de Validación

☐ `country_id` ≠ 45 (No es Colombia)  

El cliente debe ser de un país diferente a Colombia

☐ `identity_document_id` es de extranjero (10, 3, 12)  

Usar pasaporte, cédula extranjería o NIT extranjero

☐ `type_document_id: 8` (Exportación)  

Tipo de documento específico para exportación

☐ `currency_id: 272` (USD) u otra moneda válida  

Especificar moneda extranjera correcta

☐ `payment_exchange_rate` completado  

TRM del día con todos los campos requeridos

☐ IVA = 0% (exento)  

Las exportaciones no pagan IVA

☐ Totales = suma de líneas  

Verificar cálculos de totales

☐ `payable_amount` = `tax_inclusive_amount`  

Monto a pagar coincide con total

---

## 🔧 Troubleshooting

### ❌ Error: "Invalid country for export"

**❌ Causa:** `country_id` es 45 (Colombia)  

**✅ Solución:** Especifica un `country_id` válido del exterior (ej: 239 para USA)

### ❌ Error: "Currency mismatch"

**❌ Causa:** Moneda no coincide entre línea y totales  

**✅ Solución:** Usa `currency_id: 272` (USD) en **todo el documento**

### ❌ Error: "Exchange rate required"

**❌ Causa:** `payment_exchange_rate` no está definido  

**✅ Solución:** Añade `payment_exchange_rate` con TRM del día

### ❌ Error: "Tax not allowed for exports"

**❌ Causa:** Se incluyó IVA en una exportación  

**✅ Solución:** Las exportaciones **NO pagan IVA**. Elimina `tax_totals` o ponlo vacío: `[]`

---

## 🎯 Próximos Pasos

[📄 **Factura Simple** Guía básica nacional](https://docs.matias-api.com/docs/use-cases/simple-invoice.md)
[🏷️ **Factura con Descuentos** Descuentos comerciales](https://docs.matias-api.com/docs/use-cases/invoice-with-discounts.md)
[⚠️ **Errores Comunes** Troubleshooting](https://docs.matias-api.com/docs/use-cases/common-errors.md)
[📋 **Campos del Documento** Diccionario técnico](https://docs.matias-api.com/docs/billing-fields.md)

---

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