Issue documents
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/dteSDK builder for that type (FacturaInput,CreditoFiscalInput,NotaInput…).clienteId(optional): if you send it anddatos.receptoris missing, the recipient is taken from the saved customer. Production only: saved customers don’t exist in test mode, where it responds409 clientes_solo_produccionand the recipient goes indatos.receptor.puntoVentaId(optional): the point of sale that issues; defaults to the issuer’s first one.
Recommended flow
Section titled “Recommended flow”POST /dte/validar→{ dte, problemas[], total, receptorNombre }. It doesn’t consume a control number.- Fix each entry in
problemas[](ruta,mensaje) and repeat until it comes back empty. POST /dtewith anIdempotency-Key.- Result:
201, statusprocesado, withselloRecibido.202, statuscontingencia: the MH didn’t respond; see Contingency.422 dte_rechazado: the MH rejected it;details.mh.observacionessays why.
Which document applies?
Section titled “Which document applies?”| 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.
VAT in prices
Section titled “VAT in prices”- Invoice (01):
precioUniincludes VAT (13%). It is the price the consumer pays. - Tax Credit Invoice (03), notes (05/06), and delivery note (04):
precioUniis without VAT. - Saved products: their
precioUnitariois without VAT.
Common item fields
Section titled “Common item fields”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.
Examples
Section titled “Examples”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.
In production, with a saved customer (the recipient comes from the customer):
{ "tipoDte": "03", "clienteId": "c6de4c6c-d772-4f19-811a-5419655dcd06", "datos": { "items": [{ "descripcion": "Licencia anual", "cantidad": 1, "precioUni": 100, "tipoItem": 2 }] }}Or with the full recipient (in production and in test mode):
{ "tipoDte": "03", "datos": { "receptor": { "nit": "0614-290786-103-1", "nrc": "234567-8", "nombre": "CLIENTE CONTRIBUYENTE, S.A. DE C.V.", "codActividad": "46900", "descActividad": "Venta al por mayor de otros productos", "direccion": { "departamento": "06", "municipio": "23", "distrito": "14", "complemento": "Av. Olímpica #100" }, }, "items": [{ "descripcion": "Licencia anual", "cantidad": 1, "precioUni": 100, "tipoItem": 2 }] }}percepcionIva and retencionIva (true or an amount) apply the 1% when it corresponds.
{ "tipoDte": "04", "clienteId": "c6de4c6c-d772-4f19-811a-5419655dcd06", "datos": { "bienTitulo": "04", "items": [{ "descripcion": "Sillas plásticas", "cantidad": 20, "precioUni": 8 }] }}bienTitulo (CAT-025): 01 deposit, 02 ownership, 03 consignment, 04 transfer, 05 other.
A credit note on an electronic CCF (the debit note is the same with "tipoDte": "06"):
{ "tipoDte": "05", "clienteId": "c6de4c6c-d772-4f19-811a-5419655dcd06", "datos": { "documentosRelacionados": [ { "tipoDocumento": "03", "tipoGeneracion": 2, "numeroDocumento": "<codigoGeneracion of the CCF>", "fechaEmision": "2026-11-12" } ], "items": [{ "descripcion": "Devolución parcial", "cantidad": 1, "precioUni": 20 }] }}With a single related document, every item inherits it; with several, each item must state its
numeroDocumento.
{ "tipoDte": "07", "clienteId": "c6de4c6c-d772-4f19-811a-5419655dcd06", "datos": { "items": [ { "tipoDte": "03", "tipoGeneracion": 2, "numeroDocumento": "<codigoGeneracion of the CCF your supplier issued to you>", "fechaEmision": "2026-11-10", "montoSujetoGrav": 1000, "codigoRetencionMH": "22", "descripcion": "Compra de suministros" } ] }}codigoRetencionMH (CAT-006): 22 1% withholding, C4 13%, C9 other (state ivaRetenido).
montoSujetoGrav is without VAT.
{ "tipoDte": "11", "datos": { "receptor": { "nombre": "CLIENTE DEL EXTERIOR INC.", "tipoDocumento": "37", "numDocumento": "99-1234567", "codPais": "US", "complemento": "100 Main St, Miami, FL", "tipoPersona": 2, "descActividad": "Comercio al por mayor" }, "tipoItemExpor": 2, "items": [{ "descripcion": "Desarrollo de software", "cantidad": 1, "precioUni": 1500, "tipoItem": 2 }] }}For goods, also state recintoFiscal (CAT-027), tipoRegimen (CAT-033), regimen (CAT-028) and,
where applicable, codIncoterms, seguro, and flete.
The issuer is the one buying from a person not registered for VAT:
{ "tipoDte": "14", "datos": { "sujetoExcluido": { "tipoDocumento": "13", "numDocumento": "01234567-8", "nombre": "JUAN PÉREZ", "direccion": { "departamento": "06", "municipio": "23", "distrito": "14", "complemento": "Colonia Escalón" } }, "items": [{ "descripcion": "Servicio de jardinería", "cantidad": 1, "precioUni": 150, "tipoItem": 2 }], "retencionRenta": true }}retencionRenta: true applies the 10% income tax withholding on the subtotal (or state the amount).
The commission agent settles with the principal (the recipient, with its NIT) the sales made
on its behalf during the period. Each document goes with positive amounts, as they appear on it:
credit notes, returns, and voided documents (anulado: true) are subtracted automatically. Taxable
sales go without VAT.
{ "tipoDte": "08", "clienteId": "<id of the principal>", "datos": { "documentos": [ { "tipoDte": "03", "numeroDocumento": "<generation code>", "fechaEmision": "2026-11-03", "ventaGravada": 500, "ivaPercibido": 5 }, { "tipoDte": "05", "numeroDocumento": "<generation code>", "fechaEmision": "2026-11-04", "ventaGravada": 100 } ] }}For Invoices and Returns, also state iva (the “IVA 13 %” in their summary); FOVIAL, COTRANS, and
other taxes from section 1 of CAT-015 go in tributos: [{ codigo, valor }].
The collection agent (e.g. a card payment processor) settles a period’s operations with the affiliate. The SDK calculates the VAT, the 2% collection (percepción), the VAT on the commission, and the net amount payable:
{ "tipoDte": "09", "datos": { "receptor": { "nit": "0614-290786-103-1", "nombre": "COMERCIO AFILIADO, S.A. DE C.V.", "codActividad": "47190", "descActividad": "Venta al por menor", "correo": "[email protected]" }, "periodo": { "inicio": "2026-11-01", "fin": "2026-11-07" }, "valorOperaciones": 1130, "porcentComision": 3, "entrega": { "nombre": "Ana López", "documento": "01234567-8" } }}The entity authorized to receive donations (the donee) acknowledges to the donor what it received. The resolution that authorizes it (art. 6 LISR) is required, and a resident donor must carry an economic activity and an address (Hacienda rejects the receipt without them):
{ "tipoDte": "15", "datos": { "receptor": { "tipoDocumento": "13", "numDocumento": "01234567-8", "nombre": "María Gómez", "codActividad": "10005", "descActividad": "Otros", "direccion": { "departamento": "06", "municipio": "23", "distrito": "14", "complemento": "Colonia Escalón" } }, "documentosAsociados": [{ "descripcion": "Resolución", "detalle": "RES-01-2026" }], "items": [ { "tipoDonacion": 1, "descripcion": "Donación en efectivo", "valorUni": 100 }, { "tipoDonacion": 2, "descripcion": "Computadoras usadas", "cantidad": 3, "valorUni": 400, "depreciacion": 150 } ] }}tipoDonacion: 1 cash (quantity 1), 2 good, 3 service. Payment methods cover only what was donated
in cash (by default, bills and coins).
Querying
Section titled “Querying”GET /dte?tipo=&estado=&q=&desde=&hasta=&pagina=&porPagina=lists the documents of the active environment.qsearches 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}/jsonandGET /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.