Documento soporte

1. Antes de emitir

La empresa necesita, en la app de Trevol:

• la habilitación ante la DIAN y su software asociado al modo de documento soporte (si falta: 422 company_not_enabled, reason: "missing_software");
• un rango de documento soporte registrado, vigente y con números libres (si no: 422 numbering_unavailable, reason: "no_resolution"). GET /v1/company lo lista en capabilities.support_documents.numbering, con el next de cada uno;
• el certificado de firma.

La nota de ajuste no usa rango: tiene su consecutivo propio. Todo esto se comprueba antes de numerar: un pedido que no puede salir no gasta número.

2. Emitir un documento soporte

Genera un documento soporte (tipo 05): el respaldo de una compra a quien no está obligado a facturar (una persona natural, un campesino, un proveedor del exterior). Trevol valida a fondo ANTES de reservar un número, numera con el rango de documento soporte vigente más nuevo (o el del prefijo de numbering), firma con el certificado de la empresa y lo manda a la DIAN. Se genera, no se expide: no hay PDF, ZIP ni correo; el XML y la respuesta de la DIAN se descargan en las dos versiones. La empresa necesita su software registrado ante la DIAN (company_not_enabled con reason: missing_software) y un rango vigente con números libres (numbering_unavailable, no_resolution). La purchase_date de cada línea no puede ser posterior a hoy (DSFC02b/c). Cuenta como documento de facturación en el cobro.

curl https://api.trevol.si/v1/support_documents \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "notes": [
    "Compra de la semana 42 de octubre"
  ]
}'

HTTP/1.1 201 Created
Location: /v1/support_documents/sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b

{
  "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "support_document",
  "environment": "test",
  "status": "accepted",
  "number": "DS994001",
  "prefix": "DS",
  "external_id": "OC-991",
  "origin": "api",
  "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "transmission": "per_operation",
  "adjustment_note": null,
  "totals": {
    "subtotal": "216000.00",
    "discounts": "0.00",
    "line_extension": "216000.00",
    "tax_exclusive": "0.00",
    "taxes": [],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "216000.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "216000.00",
        "discount": "0.00",
        "line_extension": "216000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": null,
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": null
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

3. La nota de ajuste

Genera la nota de ajuste de un documento soporte (95): corrige o anula una compra ya validada. El documento que ajusta es de Trevol (support_document.id) o de otra plataforma (number, cuds, issue_date y total). concept 1 a 5; el 2 anula y lleva exactamente los valores del documento. Sin seller hereda el del documento de Trevol. La suma de las notas no puede pasar del saldo del documento. Un documento soporte rechazado no se ajusta: se corrige con PUT.

curl https://api.trevol.si/v1/support_document_adjustments \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991-ANULA",
  "concept": "2",
  "description": "Anulación: la compra de leche se registró dos veces en el ERP",
  "support_document": {
    "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ]
}'

El documento que se ajusta se referencia por su id ("support_document": {"id": "sd_…"}, uno de Trevol) o, si es de otra plataforma, por sus datos (number, cuds, issue_date y total); en ese caso hay que mandar también el seller (y, para anularlo, el total). El concept va de 1 a 5: 1 devolución parcial, 2 anulación (lleva exactamente los valores del documento), 3 rebaja o descuento, 4 ajuste de precio y 5 otros. Trevol revisa antes de numerar que las notas no pasen del saldo del documento.

4. Lo que es distinto de una factura

• Se genera, no se expide. No hay PDF, ZIP ni correo: delivery.status es siempre null. Se descargan …/xml y …/dian_response, en las dos versiones de la API.
• No hay customer: la empresa es la compradora. El que cuenta es el seller.
• El código de seguridad se llama cuds.
• Retenciones: solo las de cada línea (items[].withholdings). Las del documento no se publican.
• numbering: {"prefix": "…"} (opcional) elige el rango por su prefijo; sin él, el más nuevo vigente.
• purchase_date de una línea no puede ser posterior a hoy.
• El external_id es único entre facturas, notas, documentos soporte y equivalentes (y sus notas) de la empresa y el ambiente.
• Cuenta como facturación en el cobro: lo que se cobra al validarse un documento de producción.

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.

5. Rutas

6. Avisos (webhooks)

Salen por cualquier camino (la API o la app). El data es un resumen: nunca el vendedor ni las líneas.

{
  "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "event",
  "type": "support_document.accepted",
  "timestamp": "2026-10-23T14:15:03Z",
  "environment": "test",
  "api_version": "2026-10-22",
  "data": {
    "object": "support_document",
    "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
    "status": "accepted",
    "environment": "test",
    "number": "DS994001",
    "prefix": "DS",
    "external_id": "OC-991",
    "origin": "api",
    "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
    "issued_at": "2026-10-23T09:15:02-05:00",
    "total": "216000.00",
    "delivery": null,
    "dian": {
      "status_code": "00",
      "rules": []
    }
  }
}

7. Campos

SupportItemTax

SupportItemCharge

SupportItemWithholding

SupportItem

SupportAdjustmentItem

SupportCurrency

SupportDocumentInput

SupportDocumentAdjustmentInput

SupportDocumentReference

• id (obligatorios: id)
• number, cuds, issue_date, total (obligatorios: number, cuds, issue_date)

SupportAdjustmentReference

• id (obligatorios: id)
• number, cuds, issue_date (obligatorios: number, cuds, issue_date)

SupportDocument

Un documento soporte en adquisiciones a no obligados a facturar (Invoice 05). Se genera, no se expide: archivos xml y dian_response.

SupportDocumentAdjustment

Una nota de ajuste de un documento soporte (CreditNote 95). Se genera, no se expide: archivos xml y dian_response.

Seller

Numbering