Operaciones especiales

Facturas de exportación, en moneda extranjera, con AIU, mandatos, transporte de carga, notarios, divisas y sector salud por la API de Trevol.

Ver como Markdown

La misma POST /v1/invoices emite también la factura de exportación, en moneda extranjera, y las operaciones con tipo propio: AIU, mandatos, transporte de carga, notarios, compra y venta de divisas y sector salud.

Qué se puede emitir

Operación	Cómo se pide
Exportación	`document_type: "02"`, con `customer` en el exterior (`country` distinto de `"CO"`, sin `municipality_code`) y, si se factura en otra moneda, `currency`. `delivery_terms` lleva el incoterm.
Moneda extranjera	`currency: {"code", "exchange_rate", "rate_date"}` y, opcional, `alternative`. Los valores del pedido van en esa moneda; la factura y el CUFE van en pesos y `totals.currency` trae el equivalente.
AIU	`operation_type: "09"`; cada línea lleva `aiu` (`"A"`, `"I"` o `"U"`) y la línea A, el `aiu_contract`.
Mandatos	`operation_type: "11"`; la línea de un ingreso para terceros lleva `income: "third_party"` y su `mandator`.
Transporte de carga	`operation_type: "12"`; cada línea lleva su `consignment` (remesa del RNDC).
Notarios	`operation_type: "14"`; la línea lleva `notary` (matrícula y valor comercial).
Divisas	`operation_type: "15"` (compra) o `"16"` (venta), con `due_diligence` (`"01"` a `"04"`, obligatoria en esas dos).
Sector salud	`operation_type: "SS-CUFE"` con `interoperability` (obligatoria).

Un campo que no corresponde a la operación (un aiu fuera del 09, un consignment fuera del 12…) es validation_error con el campo exacto, antes de numerar.

Una exportación

El ejemplo de la especificación es una exportación en dólares:

POST /v1/invoices

cURL

curl -X POST "https://api.trevol.si/v1/invoices" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "EXP-77",
  "document_type": "02",
  "currency": {
    "code": "USD",
    "exchange_rate": "3950.12",
    "rate_date": "2026-10-21"
  },
  "delivery_terms": {
    "incoterm": "FOB",
    "conditions": "Puerto de Cartagena"
  },
  "customer": {
    "document_type": "50",
    "document_number": "US123456789",
    "name": "ACME INC",
    "country": "US",
    "city": "Miami",
    "region": "Florida",
    "postal_code": "33131",
    "address": "200 S Biscayne Blvd"
  },
  "items": [
    {
      "description": "Consultoría",
      "quantity": "1",
      "unit_price": "1000",
      "taxes": [
        {
          "code": "01",
          "excluded": true
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  }
}'

Probar en el Playground

La respuesta es la de toda factura (Facturas), con document_type, currency, delivery_terms y, si se pidieron, shipment e interoperability; totals siempre en pesos, y con moneda extranjera totals.currency con total_currency y total_cop.

Lo que hay que saber

Solo facturas. Las notas crédito y débito no admiten moneda extranjera, exportación ni tipos de operación: cada campo sale con un mensaje que lo dice.
shipment y delivery son distintos. El envío físico de la mercancía se pide en shipment (date, address, carrier). delivery es el estado del PDF, el ZIP y el correo en la respuesta y no se pide.
Contingencia. document_type: "03" y "04" y el campo contingency siguen sin estar disponibles.
Se valida a fondo antes de numerar, con la misma lógica del editor de Trevol: la fecha de la tasa de cambio no puede ser posterior a la factura, y las reglas de cada operación del Anexo técnico 1.9 se revisan antes de gastar el número.
Se cobra como cualquier factura.

Los campos de cada operación están en Objetos: Currency, DeliveryTerms, Shipment, Carrier, Interoperability, ItemMandator, ItemConsignment e ItemNotary.