Documento equivalente

Tiquete POS (20) y los otros nueve documentos equivalentes electrónicos, con su nota de ajuste, por la API de Trevol.

Emite el tiquete POS (20) y los otros nueve documentos equivalentes electrónicos de la DIAN —boleta de cine, espectáculos, juegos, transporte, peajes, extracto, tiquete aéreo, bolsa de valores y servicios públicos— y su nota de ajuste crédito (94) o débito (93).

Los diez tipos

`document_type`	Documento	Información propia (`extension`)	Numeración
`20` (por defecto)	Tiquete POS	No lleva; lleva `pos.register` (la caja)	Tu resolución POS
`25`	Boleta de cine	`cinema`	Consecutivo propio (`DEC`)
`27`	Espectáculos públicos	`show`	`DEEP`
`30`	Juegos localizados y no localizados (se acepta `32`)	`games` (sin `customer`: el adquirente es la DIAN)	`DEJL`
`35`	Transporte de pasajeros	`transport`	`DETT`
`40`	Peajes	No lleva	`DEP`
`45`	Extracto	No lleva	`EXT`
`50`	Tiquete aéreo	`air` (obligatoria)	`DETA`
`55`	Bolsa de valores	`stock_exchange`	`DEBV`
`60`	Servicios públicos	`public_services`	`SPD`

extension lleva UNA sola clave, la de su tipo ({"cinema": {…}}); otra clave es validation_error. El prefijo de los consecutivos propios se puede cambiar con prefix.

Antes de emitir

La empresa habilitada ante la DIAN, con su software del modo de documentos equivalentes (reason: "missing_software" si falta).
Para el POS: una resolución POS registrada en la app, vigente y con números libres (numbering_unavailable, reason: "no_resolution"). Si la empresa tiene varias cajas o establecimientos, elige la resolución de la caja con numbering: {"prefix": "POS2"}; GET /v1/company → capabilities.equivalent_documents.pos_numbering lista los prefijos. Los demás tipos usan su consecutivo propio.
Se comprueba antes de numerar; el documento se arma en seco para que lo que el XML no admita salga como validation_error sin gastar el número.

Emitir un tiquete POS

POST /v1/equivalent_documents

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_documents" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

En el POS, un comprador sin identificar es "customer": {"final_consumer": true}; la respuesta lo muestra igual.

La nota de ajuste

POST /v1/equivalent_document_adjustments

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_document_adjustments" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground

Contingencia, set de pruebas y entrega

Entrega. PDF, ZIP y correo como la factura: se hacen después del 201 (espera equivalent_document.delivered o consulta delivery.status).
Contingencia. La 07 (transcribes un documento físico) se pide con contingency. La 08 (la DIAN no contestó) la decide Trevol: la respuesta es 202 con status: "contingency", Trevol reenvía y, en el POS, manda el respaldo POS 20; contingency.backup lo muestra.
Set de pruebas (habilitación). Es automático, por tipo: no mandas ningún test_set_id. Mientras la DIAN valida el set, la respuesta es 202 con status: "validating" en las dos versiones: no es un error, no vuelvas a emitir; Trevol solo consulta, nunca lo manda otra vez. PUT en ese estado es 409 invalid_state.
El external_id es único entre facturas, notas, documentos soporte y equivalentes (y sus notas).
Cuenta como facturación en el cobro.

Referencia: Documento equivalente y su nota de ajuste.