Documento equivalente electrónico

1. Los diez tipos

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.

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

3. Emitir un tiquete POS

Genera un documento equivalente electrónico: el tiquete POS (20, por defecto) o cualquiera de los otros nueve tipos de la tabla 16.3 (document_type: 25 cine, 27 espectáculos, 30 juegos, 35 transporte, 40 peajes, 45 extracto, 50 tiquete aéreo, 55 bolsa de valores, 60 servicios públicos; cada uno con su información propia en extension). El POS lleva su caja en pos.register y, si la empresa tiene varias cajas, el prefijo de su resolución en numbering.prefix. Se expide como la factura: PDF, ZIP y correo después del 201 (espera equivalent_document.delivered o consulta delivery.status). La contingencia 07 (documento físico) se pide con contingency; la 08 (la DIAN no contestó) la decide Trevol y responde 202 con status: contingency. En habilitación, el set de pruebas por tipo es automático: mientras la DIAN lo valida responde 202 validating en las dos versiones y reintentar no vuelve a mandarlo. Cómo se calcula el CUDE del POS depende del despliegue del servicio, no de la empresa.

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

HTTP/1.1 201 Created
Location: /v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b

{
  "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.

4. La nota de ajuste

Genera la nota de ajuste de un documento equivalente: crédito (94) o débito (93) según note_type. El documento que ajusta es de Trevol (equivalent_document.id) o de otra plataforma. concept 1 a 5 (el 2 anula y lleva exactamente los valores del documento). Sin customer toma el del documento; en juegos el adquirente es la DIAN. Se expide como el documento: PDF, ZIP y correo.

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

5. 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.
• Cómo se calcula el CUDE del POS (con el PIN del software o con la clave técnica de la resolución) depende de la configuración del servicio de Trevol, no de tu empresa.
• El external_id es único entre facturas, notas, documentos soporte y equivalentes (y sus notas).
• Cuenta como facturación en el cobro.

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.

6. Rutas

7. Avisos (webhooks)

Salen por cualquier camino. El data es un resumen: nunca el comprador ni las líneas.

{
  "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "event",
  "type": "equivalent_document.delivered",
  "timestamp": "2026-10-23T14:15:03Z",
  "environment": "test",
  "api_version": "2026-10-22",
  "data": {
    "object": "equivalent_document",
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
    "status": "accepted",
    "environment": "test",
    "number": "POS2994001",
    "prefix": "POS2",
    "external_id": "TIQ-1",
    "origin": "api",
    "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
    "issued_at": "2026-10-23T09:15:02-05:00",
    "total": "25140.00",
    "document_type": "20",
    "dian": {
      "status_code": "00",
      "rules": []
    },
    "delivery": {
      "pdf": true,
      "zip": true,
      "email": {
        "status": "sent"
      }
    }
  }
}

8. Campos

Documento equivalente (cuerpo de POST y PUT)

Línea (items[])

Caja del POS (pos)

Caja (pos.register)

Comprador (pos.buyer)

Numeración (numbering)

Contingencia (contingency)

Documento físico (contingency.physical_document)

Nota de origen (origin_note)

Información propia del tipo (extension)

La información propia del tipo de documento equivalente: UNA clave, la de su document_type (cinema 25, show 27, games 30, transport 35, air 50, stock_exchange 55, public_services 60).

CinemaScreening

CinemaExtension

ShowProducer

ShowEvent

ShowExtension

GamesVenue

Game

GameCredit

GamesExtension

TransportExtension

AirCollection

AirExtension

StockExchangePrices

StockExchangeExtension

ConsumptionAdjustment

Meter

Consumption

ThirdPartyCompany

ThirdPartyCharge

PublicServicesExtension

Nota de ajuste (cuerpo)

Línea de la nota

Documento que ajusta (equivalent_document)

• id (obligatorios: id)
• number, cude, issue_date, document_type, total (obligatorios: number, cude, issue_date, document_type)