Skip to content

Every document is issued through the same route, POST /dte, and validated beforehand with POST /dte/validar:

{
"tipoDte": "01",
"datos": { "items": [{ "descripcion": "Servicio", "cantidad": 2, "precioUni": 11.3 }] },
"clienteId": "opcional",
"puntoVentaId": "opcional"
}
  • tipoDte: the document type (table below).
  • datos: the input of the @openfactura/dte SDK builder for that type (FacturaInput, CreditoFiscalInput, NotaInput…).
  • clienteId (optional): if you send it and datos.receptor is missing, the recipient is taken from the saved customer. Production only: saved customers don’t exist in test mode, where it responds 409 clientes_solo_produccion and the recipient goes in datos.receptor.
  • puntoVentaId (optional): the point of sale that issues; defaults to the issuer’s first one.
  1. POST /dte/validar → { dte, problemas[], total, receptorNombre }. It doesn’t consume a control number.
  2. Fix each entry in problemas[] (ruta, mensaje) and repeat until it comes back empty.
  3. POST /dte with an Idempotency-Key.
  4. Result:
    • 201, status procesado, with selloRecibido.
    • 202, status contingencia: the MH didn’t respond; see Contingency.
    • 422 dte_rechazado: the MH rejected it; details.mh.observaciones says why.
Situation tipoDte Recipient
Sale to a final consumer or to anyone not asking for tax credit 01 Optional (required from $25,000)
Sale to a VAT-registered taxpayer who asks for tax credit 03 NIT, NRC, name, activity (codActividad + descActividad), and address
Moving goods without a sale 04 Identified, with bienTitulo
Decreasing the value of an issued CCF 05 The one on the original document
Increasing the value of an issued CCF 06 The one on the original document
VAT withholding from a supplier 07 The withheld party
Sale abroad 11 Foreign, with codPais
Purchase from a person not registered for VAT 14 sujetoExcluido
As a commission agent, settling sales made on a third party’s behalf 08 The principal, with its NIT
As a collection agent, settling with an affiliate 09 The affiliate: NIT, activity, and email
Acknowledging a donation received 15 The donor

The document names, as Hacienda calls them: Factura (01, invoice), Comprobante de Crédito Fiscal or CCF (03, tax credit invoice), Nota de Remisión (04, delivery note), Nota de Crédito (05, credit note), Nota de Débito (06, debit note), Comprobante de Retención (07, withholding receipt), Comprobante de Liquidación (08, settlement receipt), Documento Contable de Liquidación (09, settlement accounting document), Factura de Exportación (11, export invoice), Factura de Sujeto Excluido (14, excluded subject invoice), and Comprobante de Donación (15, donation receipt).

A refund or return on an Invoice, Export Invoice, or Excluded Subject Invoice? You don’t issue a note: you register a Return Event.

  • Invoice (01): precioUni includes VAT (13%). It is the price the consumer pays.
  • Tax Credit Invoice (03), notes (05/06), and delivery note (04): precioUni is without VAT.
  • Saved products: their precioUnitario is without VAT.

descripcion, cantidad, precioUni, tipoItem (1 good, 2 service, 3 both, 4 other taxes; defaults to 1), codigo, uniMedida (CAT-014; 59 = unit), descuento (total for the line, not per unit), and tipoVenta (gravada by default, exenta, or noSujeta).

Payment: defaults to cash, paid in full. On credit: "condicionOperacion": 2 with "credito": { "plazo": "01", "periodo": 30 } (30 days). Other payment methods: pagos with CAT-017 codes.

Addresses: { departamento, municipio, distrito, complemento } with codes from CAT-012, CAT-013, and CAT-008 (query GET /catalogos/CAT-013?departamento=06). NIT, DUI, and NRC may be sent with or without hyphens.

The examples with clienteId are for production. In test mode, put the recipient in datos.receptor, as in the second Tax Credit example.

{
"tipoDte": "01",
"datos": {
"items": [
{ "descripcion": "Servicio de consultoría", "cantidad": 3, "precioUni": 56.5, "tipoItem": 2 }
]
}
}

With "retencionIva": true, the 1% VAT withholding is applied when the recipient is a withholding agent.

  • GET /dte?tipo=&estado=&q=&desde=&hasta=&pagina=&porPagina= lists the documents of the active environment. q searches by recipient, control number, or generation code.
  • GET /dte/{codigo} returns the document with its DTE, the MH response, and its events.
  • GET /dte/{codigo}/json and GET /dte/{codigo}/pdf: the files for the recipient.

Statuses: pendiente (awaiting MH confirmation) · procesado (valid, stamped) · contingencia (valid, transmitted later) · rechazado (no value) · invalidado (voided).

For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.