Cómo emitir un DTE

Todos los tipos de DTE se emiten con el mismo endpoint. El campo type (catálogo CAT-002) indica el documento y sudte aplica sus reglas.

POST /v1/documents?mode=sync&dry_run=false
Authorization: Bearer sk_test_...
Idempotency-Key: venta-000123
Content-Type: application/json

Parámetro	Valores	Para qué
`mode`	`sync` (por defecto) o `async`	En `sync` la API espera la respuesta del MH hasta 20 segundos. En `async` responde de inmediato y el resultado llega por webhook.
`dry_run`	`true` o `false`	Calcula y valida sin firmar, sin transmitir y sin consumir número de control. No se cobra.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`emitter_id`	texto, obligatorio	Emisor (NIT) que emite.
`type`	texto, obligatorio	Tipo de DTE: `01`, `03`, `05`, `06`…
`establishment`	texto, obligatorio	Código MH del establecimiento (`M001`, `S001`…).
`point_of_sale`	texto, obligatorio	Código MH del punto de venta (`P001`…).
`items`	lista, obligatoria	De 1 a 2,000 ítems. Ver abajo.
`receiver`	objeto	Receptor. Obligatorio salvo en facturas a consumidor final menores a $25,000.
`payment`	objeto	`condition` (CAT-016) y `methods[]` con `code` (CAT-017), `amount`, `reference`, `term` (CAT-018) y `period`.
`external_id`	texto	Tu identificador (por ejemplo, el id de la factura en tu ERP). Sirve para buscar con `GET /v1/documents?external_id=…`.
`issued_at`	fecha y hora	Por defecto, ahora. No puede diferir más de 30 minutos del envío.
`related_documents`	lista	Documentos relacionados (`type`, `generation_code`, `issued_on`). Obligatorio en notas de crédito y débito.
`global_discount`	objeto	Descuento global por tipo de venta: `gravada`, `exenta`, `no_sujeta`.
`withholding`	objeto	`iva_1: true` aplica la retención de IVA del 1 %; `renta` es el monto de retención de renta.
`perception`	booleano	Aplica la percepción de IVA del 1 %.
`notes`	texto	Observaciones que aparecen en el documento.
`appendix`	lista	Hasta 10 campos adicionales (`field`, `label`, `value`) para la representación gráfica.
`send_email`	booleano	Por defecto `true`: sudte envía el JSON y el PDF al correo del receptor cuando el documento tiene sello.
`raw`	objeto	Avanzado: el JSON del MH ya armado, sin firma. sudte solo lo valida, firma y transmite.

Ítems

Campo	Descripción
`description`	Descripción del bien o servicio (hasta 1,000 caracteres).
`quantity`	Cantidad, como texto decimal.
`unit_price`	Precio unitario. Con IVA en la factura (01); sin IVA en crédito fiscal y notas.
`tax`	`gravada`, `exenta` o `no_sujeta`.
`type`	Tipo de ítem (CAT-011): `1` bienes (por defecto), `2` servicios, `3` ambos, `4` otros tributos.
`unit_code`	Unidad de medida (CAT-014); por defecto `59` (unidad).
`code`	Tu código de producto.
`discount`	Descuento del ítem, en monto.
`taxes`	Tributos adicionales del catálogo CAT-015. El IVA lo calcula sudte.
`related_document`	Código de generación del documento relacionado (notas).

Receptor

name, document_type (CAT-022: 36 NIT, 13 DUI, 03 pasaporte, 02 carné de residente, 37 otro), document_number, nrc, economic_activity (CAT-019), trade_name, email, phone, country (exportación) y address con department (CAT-012), municipality (CAT-013), district (CAT-008) y line.

Envía NIT, NRC y DUI sin guiones ni espacios. sudte normaliza espacios sobrantes, pero rechaza un DUI en el lugar de un NIT.

Respuestas

Estado	Cuándo	Cuerpo
`201 Created`	El MH selló el documento.	Documento con `status: "processed"` y `reception_stamp`.
`202 Accepted`	Modo `async`, o el MH no respondió dentro de 20 segundos.	Documento en `signed`, `sending` o `contingency`. El resultado llega por webhook.
`200 OK`	`dry_run=true`.	Totales calculados, sin número de control definitivo.
`422`	Datos inválidos (`validacion`) o rechazo del MH (`mh-rechazo`).	`application/problem+json` con `errors[]` y, si rechazó el MH, el objeto `mh`.
`409`	Misma `Idempotency-Key` con otro cuerpo.	Problema `idempotencia-conflicto`.

Un rechazo del MH incluye además document_id, generation_code y control_number: el documento queda guardado en estado rejected para que lo corrijas y reintentes.

Estados de un documento

Estado	Significado
`validated`	Pasó la validación local (solo en `dry_run`).
`signed`	Firmado y guardado; pendiente de transmitir.
`sending`	Transmitiéndose o esperando respuesta del MH.
`processed`	Sellado por el MH. Es el estado final exitoso.
`rejected`	El MH lo rechazó. Corrígelo y reintenta dentro de 24 horas.
`contingency`	El MH no respondió tras los reintentos; se transmitirá cuando se restablezca.
`voided`	Invalidado con un evento de invalidación sellado.
`error`	Error técnico sin respuesta definitiva; sudte reconcilia consultando al MH.

Después de emitir

GET /v1/documents/{id}: estado actualizado, sello, totales, historial de eventos y advertencias.
GET /v1/documents/{id}/pdf y /json: representación gráfica y JSON firmado con sello.
POST /v1/documents/{id}/send: reenvía el JSON y el PDF por correo (puedes indicar otros destinatarios en to).
POST /v1/documents/{id}/retry: retransmite un documento pendiente, o corrige y reenvía uno rechazado conservando su código de generación y número de control.
POST /v1/documents/{id}/void: invalidación.

Guías por tipo

Factura (01) Consumidor final, precios con IVA.

Crédito fiscal (03) Contribuyentes, IVA aparte.

Nota de crédito (05) Disminuye un CCF sellado.

Nota de débito (06) Aumenta un CCF sellado.