Exportación y operaciones especiales

1. Qué se puede emitir

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.

2. Una exportación

Valida, numera, firma y envía una factura a la DIAN. Además de la factura nacional acepta la exportación (document_type: "02"), la moneda extranjera (currency), los términos de entrega (delivery_terms), el AIU, los mandatos, el transporte de carga, los notarios, las divisas y el sector salud (operation_type). El envío físico de la mercancía va en shipment (no en delivery: ese es el estado del PDF, el ZIP y el correo en la respuesta). Las notas crédito y débito no admiten estos campos.

curl https://api.trevol.si/v1/invoices \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -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
  }
}'

La respuesta es la de toda factura (guía), 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.

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

Las respuestas son las de toda la API: 201 cuando la DIAN valida, 422 dian_rejected con document cuando la rechaza, 422 validation_error si Trevol lo rechaza antes de numerar (no se gasta ningún número), 402 sin saldo, y con la DIAN sin contestar un 202 processing (versión 2026-10-22) o un 503 dian_unavailable (2026-10-21). Idempotency-Key es obligatoria al crear o corregir, y external_id es opcional.

4. Campos

Moneda extranjera (currency)

Moneda alterna (currency.alternative)

Términos de entrega (delivery_terms)

Envío físico (shipment)

Transportador (shipment.carrier)

Dirección (shipment.address)

Interoperabilidad (interoperability)

Colección de interoperabilidad

Dato de interoperabilidad

Mandante (items[].mandator)

Remesa de transporte de carga (items[].consignment)

Notario (items[].notary)

Propiedad de la línea (items[].properties[])