Emitir un DTE

POST /v1/dte reserva el correlativo, construye y valida el documento contra el esquema oficial, lo firma con el certificado de la empresa y lo transmite al Ministerio — todo en una sola llamada. Es la ruta normal: use preparar y firmar por separado solo cuando necesite revisar el documento antes de firmarlo (vea Preparar y firmar por separado).

Lo mínimo para emitir

Tres cosas, siempre: el tipoDte, la lista de items y, según el tipo, un receptor. El emisor, el ambiente, el establecimiento y el punto de venta salen de la base a partir de la llave — usted no los escribe nunca.

curl -X POST "$FACTA_API_BASE_URL/v1/dte" \
  -H "X-Facta-Key: $FACTA_API_KEY" \
  -H "X-Facta-Sign-Key: $FACTA_SIGN_KEY" \
  -H "Idempotency-Key: venta-2026-09-02-00417" \
  -H "Content-Type: application/json" \
  -d '{
        "tipoDte": "01",
        "items": [
          { "descripcion": "Café", "cantidad": 2, "precioUni": 1.5 }
        ]
      }'

El precio de la línea depende del tipo

El servidor no adivina: en una factura (01) precioUni incluye el IVA; en un crédito fiscal (03) y en las notas (05/06) lo excluye; en una exportación (11) no hay IVA que incluir; en un comprobante de sujeto excluido (14) el precio es el precio, sin tocarlo. Así lo definen los esquemas oficiales del Ministerio, y mezclar uno con otro produce un total equivocado que el esquema no puede atrapar por sí solo.

Con un cliente ya guardado

Si el receptor ya existe en Facta, nómbrelo por customerId en vez de escribir sus datos de nuevo. Lo explícito gana sobre lo guardado, así que puede combinar los dos: un correo distinto para esta venta no obliga a editar la ficha del cliente.

{
  "tipoDte": "03",
  "receptor": { "customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea" },
  "items": [
    { "descripcion": "Integración de la API de facturación electrónica", "cantidad": 1, "precioUni": 25 }
  ]
}

Un crédito fiscal exige además numDocumento (el NIT), nrc, nombre, codActividad, direccion y correo — completos, en el receptor guardado o en el que se escribe en la petición.

Qué puede contestar

Un 200 trae selloRecibido: es un documento fiscal. Un 202 significa que quedó firmado y Hacienda no respondió — no se reintenta, se retransmite en contingencia. Un 422 puede ser cuatro cosas distintas y solo una gasta correlativo; la referencia de POST /v1/dte las detalla una por una.

Archive siempre el jws, nunca el documento. Volver a serializar el JSON no reproduce los bytes cuya firma validó Hacienda — es la única forma de probar después que el documento es el que se emitió.

Otras guías