# Issue documents

> The issuance body, which DTE type fits each operation, and VAT in prices, with examples of every type.

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

```json
{
  "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`](https://docs.openfactura.co/en/herramientas/sdk/) 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.

> **Tip**
>
> Don't calculate taxes or totals. Open Factura calculates VAT (IVA), withholdings, rounding (body to 8
> decimals, summary to 2), and the total in words. Always show the `total` the API returns.

## Recommended flow

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`](https://docs.openfactura.co/en/guias/idempotencia/).
4. Result:
   - `201`, status `procesado`, with `selloRecibido`.
   - `202`, status `contingencia`: the MH didn't respond; see [Contingency](https://docs.openfactura.co/en/guias/contingencia/).
   - `422 dte_rechazado`: the MH rejected it; `details.mh.observaciones` says why.

## 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](https://docs.openfactura.co/en/guias/retorno/).

## VAT in prices

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

## 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

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

#### 01 Invoice

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

#### 03 Tax Credit

In production, with a saved customer (the recipient comes from the customer):

```json
{
  "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):

```json
{
  "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"
      },
      "correo": "compras@cliente.com.sv"
    },
    "items": [{ "descripcion": "Licencia anual", "cantidad": 1, "precioUni": 100, "tipoItem": 2 }]
  }
}
```

`percepcionIva` and `retencionIva` (`true` or an amount) apply the 1% when it corresponds.

#### 04 Delivery Note

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

#### 05/06 Notes

A credit note on an electronic CCF (the debit note is the same with `"tipoDte": "06"`):

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

#### 07 Withholding

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

#### 11 Export

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

#### 14 Excluded Subject

The issuer is the one **buying** from a person not registered for VAT:

```json
{
  "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).

#### 08 Settlement

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.

```json
{
  "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 }]`.

#### 09 Settlement Accounting Doc.

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:

```json
{
  "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": "pagos@comercio.com.sv" },
    "periodo": { "inicio": "2026-11-01", "fin": "2026-11-07" },
    "valorOperaciones": 1130,
    "porcentComision": 3,
    "entrega": { "nombre": "Ana López", "documento": "01234567-8" }
  }
}
```

#### 15 Donation

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):

```json
{
  "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

- `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).
