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.
Sin guardar el cliente en Facta
No es necesario crear una ficha de cliente para facturar. Puede enviar los datos fiscales del receptor directamente en receptor; la API los usa para este DTE y no crea ni actualiza el catálogo de clientes. Tampoco necesita FACTA_UNLOCK_KEY ni sincronizar el catálogo si todos los datos viajan en la petición.
Una factura (01) a consumidor final puede omitir receptor por completo. Si necesita identificar a un comprador en una FE, puede enviar sus campos inline. Un crédito fiscal (03), en cambio, exige los datos completos del contribuyente receptor; nombre no se puede omitir. El customerId solo es un atajo opcional del SDK para resolver una ficha que ya esté incluida en el snapshot de esa llave.
const dte = await facta.issue({
tipoDte: "03",
receptor: {
nombre: "Comercial Ejemplo, S.A. de C.V.",
tipoDocumento: "36",
numDocumento: "06141234567890",
nrc: "1234567",
codActividad: "46510",
descActividad: "Venta al por mayor de equipo",
direccion: {
departamento: "06",
municipio: "20",
complemento: "Colonia Centro, San Miguel",
},
correo: "compras@example.com",
},
items: [{ descripcion: "Equipo", cantidad: 1, precioUni: 125 }],
}, { idempotencyKey: "pedido-ERP-1042" });Si se trata de una FE anónima, la petición mínima no lleva receptor:
const dte = await facta.issue({
tipoDte: "01",
items: [{ descripcion: "Café", cantidad: 2, precioUni: 1.50 }],
}, { idempotencyKey: "venta-POS-000417" });La llamada HTTP directa envía el mismo cuerpo y las cabeceras de API y firma. En HTTP no envíe customerId: ese identificador solo lo resuelve localmente el SDK; incluya los campos del receptor que el tipo de DTE exige. Vea el modelo completo de Receptor y la guía del SDK TypeScript.
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: pedido-ERP-1042" \
-H "Content-Type: application/json" \
-d '{
"tipoDte": "03",
"receptor": {
"nombre": "Comercial Ejemplo, S.A. de C.V.",
"tipoDocumento": "36",
"numDocumento": "06141234567890",
"nrc": "1234567",
"codActividad": "46510",
"descActividad": "Venta al por mayor de equipo",
"direccion": {
"departamento": "06",
"municipio": "20",
"complemento": "Colonia Centro, San Miguel"
},
"correo": "compras@example.com"
},
"items": [{ "descripcion": "Equipo", "cantidad": 1, "precioUni": 125 }]
}'Dos tipos que no son una venta: 04 y 07
La nota de remisión (04) mueve mercadería sin venderla (consignación, traslado, depósito): lleva el valor de los bienes y un receptor.bienTitulo obligatorio, pero no cobra nada. El comprobante de retención (07) lo emite solo un agente de retención designado por Hacienda: sus líneas son retenciones (montoSujetoGrav y codigoRetencionMH), no productos, y una empresa que no es agente recibe 403 retention_agent_required. Ninguno de los dos lleva pagos: pagos, formaPago, condicionOperacion, plazo y periodo se ignoran con una advertencia campo_ignorado. La llave debe llevar el tipo (una acuñada antes del 04 y el 07 lleva solo los seis anteriores).
{
"tipoDte": "04",
"receptor": {
"nombre": "Bodega Santa Ana",
"tipoDocumento": "36",
"numDocumento": "05110606161016",
"codActividad": "46510",
"descActividad": "Venta al por mayor de repuestos",
"bienTitulo": "03"
},
"items": [{ "descripcion": "Caja de repuestos", "cantidad": 2, "precioUni": 25, "tipoItem": 1 }]
}{
"tipoDte": "07",
"receptor": {
"nombre": "ZD, S.A DE C.V.", "tipoDocumento": "36", "numDocumento": "05110606161016",
"nrc": "2513113", "codActividad": "46510", "descActividad": "Venta al por mayor de equipo",
"direccion": { "departamento": "06", "municipio": "20", "distrito": "01", "complemento": "Colonia Centro, San Miguel" },
"correo": "proveedor@example.com"
},
"items": [{ "montoSujetoGrav": 250.5, "codigoRetencionMH": "C9", "ivaRetenido": 2.5, "descripcion": "Compra en papel" }]
}Cada campo, los códigos de retención, el grupo de referencia y los errores están en Nota de remisión (04) y comprobante de retención (07).
Líneas gravadas, exentas y no sujetas
Cada línea paga IVA por omisión (gravada). Si una línea no lo paga, usted lo dice con tipoVenta: "exenta" o "no_sujeta". Facta nunca lo deduce de la descripción ni del precio: una línea mal clasificada es un documento fiscal equivocado, y esa decisión es suya, con su contador.
gravada: la línea lleva IVA del 13 %. Es el valor por omisión.exenta: la operación entra en el campo del IVA, pero la ley la libera (Ley del IVA, arts. 45 y 46). Va aventaExentay no lleva IVA. Un caso frecuente son los intereses de un préstamo, que están exentos solo cuando los cobra un banco u otra institución supervisada por la Superintendencia del Sistema Financiero, o una cooperativa de ahorro y crédito (art. 46, letra f). Quien presta sin esa condición cobra IVA, y su línea esgravada.no_sujeta: la operación está fuera del hecho generador del impuesto. Va aventaNoSujy no lleva IVA.
El IVA se calcula solo sobre las líneas gravadas. En una factura (01) el precio ya lo incluye, así que una línea exenta o no sujeta se factura por su precio, sin IVA dentro. En un crédito fiscal (03) y en las notas el precio es neto y el 13 % se suma únicamente a lo gravado. Los totales salen separados (totalGravada, totalExenta, totalNoSuj) y montoTotalOperacion suma los tres más el IVA de lo gravado. Una factura con todas sus líneas exentas es válida y no lleva IVA.
El campo vale en 01, 03, 05 y 06. En una nota, use la clase que tenía la línea del documento que corrige. En una exportación (11), que es siempre de tasa cero, y en un sujeto excluido (14), que documenta una compra, el campo se rechaza con 422 validation_failed aunque diga gravada. Si manda productId, la clase del producto de su catálogo todavía no llega a la API: escriba tipoVenta en la línea.
{
"tipoDte": "01",
"items": [
{ "descripcion": "Equipo de oficina", "cantidad": 1, "precioUni": 113 },
{ "descripcion": "Intereses de préstamo", "cantidad": 1, "precioUni": 50, "tipoVenta": "exenta" },
{ "descripcion": "Reembolso de gastos", "cantidad": 1, "precioUni": 30, "tipoVenta": "no_sujeta" }
]
}Con esos precios el documento suma totalGravada 113.00 (13.00 de IVA ya incluido: 113 ÷ 1.13 = 100), totalExenta 50.00, totalNoSuj 30.00 y un total a pagar de 193.00.
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-POS-000418" \
-H "Content-Type: application/json" \
-d '{
"tipoDte": "01",
"items": [
{ "descripcion": "Equipo de oficina", "cantidad": 1, "precioUni": 113 },
{ "descripcion": "Intereses de préstamo", "cantidad": 1, "precioUni": 50, "tipoVenta": "exenta" }
]
}'El SDK de TypeScript declara tipoVenta desde la versión 0.6.0-next.3 (npm i @facta-dte/api@next) y el de PHP desde v0.2.0-rc.2; con una versión anterior, use la llamada HTTP directa para estas líneas.
Retención de renta en el sujeto excluido (14). aplicarReteRenta es opcional: si se omite o vale false, no se retiene; si vale true, la API calcula la retención vigente sobre todo el subtotal después de descuentos por línea. Los descuentos se restan antes: los de línea (montoDescu) y el global (descuentoGlobal, que en la FSE es resumen.descu). La retención no selecciona líneas según tipoItem. Si un servicio incluye bienes como insumos, esos materiales forman parte de la operación y quedan dentro de ese subtotal. Por ejemplo, materiales de $100 más mano de obra de $50 producen un subtotal de $150; al aplicar el 10 %, la retención es $15 y el total a pagar es $135.
La compra de bienes por sí sola no activa automáticamente la retención, y que una operación no lleve IVA no determina si corresponde. Para seleccionar líneas, use el modo explícito descrito a continuación cuando la API confirme que lo admite. No presente el artículo 156 como regla automática para toda compra a una persona natural. Si envía tipoVenta: "exenta" o "no_sujeta" junto con aplicarReteRenta: true, la API responde 422 retention_mixed_class_unsupported antes de reservar un correlativo; el tipo de venta no sirve para clasificar bienes frente a servicios.
Retención por línea (14)
Este modo requiere que GET /v1/status confirme capabilities.fseIncomeWithholdingPerLine: true. Si el campo falta o no vale true, no envíe el modo nuevo: una API anterior podría ignorar los campos que no conoce. Las solicitudes existentes con aplicarReteRenta conservan su comportamiento y no requieren esta capacidad.
En una API que lo admite, agregue este fragmento a su solicitud FSE, conservando los datos requeridos del receptor:
{
"incomeWithholding": { "mode": "per_line" },
"items": [
{ "descripcion": "Compra independiente de materiales", "tipoItem": 1, "cantidad": 1, "precioUni": 100, "applyIncomeWithholding": false },
{ "descripcion": "Servicio", "tipoItem": 2, "cantidad": 1, "precioUni": 50, "applyIncomeWithholding": true }
]
}Al 10 %, el subtotal es $150, la retención es $5 y el total a pagar es $145. Si marca ambas líneas, la retención es $15; si marca ninguna, es cero. El cálculo usa los importes después del descuento de cada línea y redondea la retención después de sumar la base seleccionada. tipoItem no selecciona la retención, tampoco en los tipos 3 y 4.
Todas las líneas deben llevar un booleano explícito. No combine este modo con aplicarReteRenta, aunque sea false; no envíe marcas por línea sin activar el modo; no envíe porcentajes ni montos de retención. La API rechaza esas combinaciones antes de reservar número. Una versión del SDK que implemente este contrato también puede detectarlas localmente antes de hacer una llamada HTTP; compruebe el soporte de su versión instalada. Actualizar el SDK no activa el modo nuevo en solicitudes anteriores.
Las marcas pertenecen a la solicitud de Facta. El DTE fiscal conserva la retención agregada en resumen.reteRenta; no se agregan marcas propias al cuerpoDocumento. Cambiar las selecciones con la misma Idempotency-Key produce conflicto, incluso si el monto retenido coincide.
Retención y percepción de IVA, solo si usted las pide. Son interruptores (true o false), no montos: usted indica si aplican y Facta calcula el monto con la tasa vigente. Las tres valen false si no las envía, porque quién retiene o percibe depende del comprador, algo que la API no puede ver.
aplicarRetencionIva (en el 01, 03, 05 y 06) es la retención de IVA del 1 % que le hace un cliente agente de retención (gran contribuyente), art. 162 del Código Tributario. Es el 1 % de la base neta gravada, no del IVA. No cambia el IVA del 13 %: lo que cambia es el total a pagar, que baja en ese 1 %. Por ejemplo, con una base neta de $420.00 el IVA es $54.60 y el total $474.60; con aplicarRetencionIva: true la retención es $4.20 y el total a pagar queda en $470.40. En una nota de crédito (05) o de débito (06) la API no lo infiere del CCF relacionado: quien llama lo declara. «Revisar y emitir» de Facta sí lo propone a partir del CCF relacionado.
aplicarPercepcionIva (solo en el 03) es la percepción del 1 % que cobra usted, como emisor agente de percepción (art. 163 CT), sobre las líneas de bienes (tipoItem 1) después de descuentos. A diferencia de la retención, se suma al total a pagar. En el crédito fiscal, el total a pagar es montoTotalOperacion + ivaPerci − ivaRete; la percepción no forma parte de montoTotalOperacion. Enviarlas en otro tipo es 400 validation_failed. El tipo de línea del SDK de TypeScript todavía no las declara: use la llamada HTTP directa.
| Campo del pedido | Tipos | Campo del DTE sellado | Qué hace con el total |
|---|---|---|---|
aplicarRetencionIva | 01, 03, 05, 06 | resumen.ivaRete | Lo baja: 1 % de la base neta gravada |
aplicarPercepcionIva | 03 | resumen.ivaPerci | Lo sube: 1 % de la base neta de los bienes |
aplicarReteRenta | 14 | resumen.reteRenta | Lo baja: 10 % de renta, con la tasa vigente |
Descuentos por línea
montoDescu es el descuento de una línea, en dinero y no en porcentaje, y va en la misma base de IVA que precioUni: en una factura (01) incluye el IVA; en un crédito fiscal (03), una nota o una exportación no lo incluye. Tiene que estar entre 0 y cantidad × precioUni. El servidor hace el resto: la línea sale con su venta ya descontada, el IVA se calcula sobre lo descontado y el resumen trae totalDescu.
{
"tipoDte": "01",
"items": [{ "descripcion": "Plan Pro", "cantidad": 1, "precioUni": 50, "montoDescu": 5 }]
}El nombre es exacto.
Cargos y abonos que no afectan la base imponible
Algunos valores viajan en el documento sin ser una venta: el abono a capital de un préstamo, un depósito, un saldo a favor del cliente. Hacienda los llama «Cargos/Abonos que no afectan la base imponible» (Manual Funcional del Sistema de Transmisión 2.0, §XII) y los recibe como una línea propia con noGravado:
{ "descripcion": "Capital", "noGravado": 50000, "tipoItem": 2, "codigo": "CAP" }noGravado: el monto, distinto de cero y con hasta 8 decimales. Positivo es un cargo que se suma al total a pagar; negativo, un abono que lo resta.tipoItem: obligatorio — 1 bien, 2 servicio o 3 ambos. Facta no lo adivina.codigo: opcional.
La línea va sola: Facta escribe la cantidad 1, el precio 0, la unidad 99 y las ventas en cero que pide Hacienda. Si la manda con cantidad, precioUni, montoDescu, tipoVenta o productId, la respuesta es 400 invalid_request con details.field; uniMedida, si va, tiene que ser 99.
El valor no toca nada más que el total a pagar: no lleva IVA y no entra en el subtotal, en montoTotalOperacion, en los descuentos (de línea o global) ni en la base de la retención o la percepción. La suma de estas líneas sale en documento.resumen.totalNoGravado y en totales.totalNoGravado; totalPagar, totalLetras y la suma de pagos[] ya la incluyen.
{
"tipoDte": "03",
"receptor": { "customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea" },
"items": [
{ "descripcion": "Interés exento", "cantidad": 1, "precioUni": 176.71, "tipoVenta": "exenta", "tipoItem": 2 },
{ "descripcion": "Capital", "noGravado": 50000, "tipoItem": 2, "codigo": "CAP" }
]
}Ese documento sale con montoTotalOperacion 176.71, totalNoGravado 50,000.00 y totalPagar 50,176.71 («CINCUENTA MIL CIENTO SETENTA Y SEIS 71/100 DOLARES»).
Vale en la factura (01), el crédito fiscal (03), las notas de crédito y de débito (05 y 06, con su numeroDocumento cuando corrigen más de un documento) y la exportación (11). Tres reglas, y ninguna gasta correlativo:
- El documento necesita al menos una línea de venta (gravada, exenta o no sujeta) mayor que $0.00; si no,
400 non_taxed_requires_sale_line. - En el sujeto excluido (14) el campo no existe:
400 non_taxed_not_supported. - Los abonos no pueden dejar el total a pagar por debajo de cero:
400 non_taxed_total_negative, condetails.totalPagarVentaydetails.totalNoGravado. Un total exactamente cero sí vale.
GET /v1/status lo anuncia con capabilities.noGravado: true. Los SDK todavía no declaran la línea: use la llamada HTTP directa.
Descuento global
descuentoGlobal es el descuento de toda la venta (01, 03, 11 y 14), el mismo que ofrece la pantalla de emisión de la app. Va en el cuerpo, no en una línea, y tiene dos claves, las dos obligatorias:
modo:"monto"(dólares) o"porcentaje"(10 es 10 %).valor: mayor que cero, con dos decimales como máximo; un porcentaje no pasa de 100. Un monto va en la misma base de IVA queprecioUni: con IVA en la factura (01), sin IVA en el crédito fiscal (03) y en la exportación (11).
{
"tipoDte": "03",
"receptor": { "customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea" },
"items": [{ "descripcion": "Integración de la API", "cantidad": 1, "precioUni": 125 }],
"descuentoGlobal": { "modo": "monto", "valor": 12.5 }
}curl -X POST "$FACTA_URL/v1/dte" \
-H "X-Facta-Key: $FACTA_KEY" \
-H "X-Facta-Sign-Key: $FACTA_SIGN_KEY" \
-H "Idempotency-Key: pedido-1042" \
-H "Content-Type: application/json" \
-d '{ "tipoDte": "01", "items": [{ "descripcion": "Café", "cantidad": 10, "precioUni": 2 }], "descuentoGlobal": { "modo": "porcentaje", "valor": 10 } }'Se aplica después de los descuentos por línea y Facta lo reparte con la misma regla que la app: un porcentaje cae sobre cada tipo de venta (gravada, exenta, no sujeta) y queda en resumen.porcentajeDescuento; un monto se reparte en proporción a cada tipo y la suma cuadra al centavo. En la exportación todo va a descuGravada; en el sujeto excluido, a resumen.descu. Lo que sigue se calcula ya descontado: el IVA, aplicarRetencionIva, aplicarPercepcionIva, aplicarReteRenta (también por línea), totalPagar y la suma que tiene que dar pagos[].
Un descuento mayor que el subtotal es 400 invalid_request con details.field: "descuentoGlobal" y details.subtotal; un modo que no es uno de los dos, un valor fuera de rango o cualquier otra clave dentro del objeto también es 400. En una nota de crédito (05) o de débito (06) es 400 global_discount_not_supported: sus montos salen del documento que corrigen. Nada de esto gasta correlativo. GET /v1/status confirma el soporte con capabilities.descuentoGlobal: true; una API sin esa marca ignora el campo y lo advierte como campo_desconocido. Los SDK todavía no lo declaran: use la llamada HTTP directa.
Forma de pago
El pago no se informa aparte: viaja en el mismo cuerpo de POST /v1/dte y Facta lo convierte en documento.resumen.pagos. No hay otro endpoint ni otro momento. Lo que mande depende de cómo se paga:
| Caso | Qué manda | Qué queda en resumen.pagos |
|---|---|---|
| Contado, un medio (01, 03, 11, 14) | formaPago; sin él, 01 (05 en la exportación) | una fila con montoPago igual al total a pagar |
| Contado, varios medios (01, 03, 11, 14) | pagos[], sin formaPago; la suma de montoPago es el total a pagar | sus filas, tal cual |
Crédito (condicionOperacion 2) | formaPago + plazo + periodo; nunca pagos | una fila con el total a pagar, plazo y periodo |
| Nota de crédito (05) y de débito (06) | nada: no liquidan y su esquema oficial no tiene resumen.pagos; formaPago se ignora y pagos es 400. La 06 puede llevar numPagoElectronico | el campo no existe |
montoPago es siempre el total a pagar del documento (resumen.totalPagar), es decir, ya con retenciones y percepción aplicadas.
formaPago lleva un código del catálogo CAT-017: 01 billetes y monedas, 02 tarjeta de débito, 03 tarjeta de crédito, 04 cheque, 05 transferencia o depósito bancario, 08 dinero electrónico, 09 monedero electrónico, 11 bitcoin, 12 otras criptomonedas, 13 cuentas por pagar del receptor, 14 giro bancario, 99 otros. Un código que no es del catálogo se rechaza con 422 validation_failed y la lista de códigos válidos, antes de gastar correlativo. Lo mismo vale para exportacion.recintoFiscal (CAT-027), exportacion.tipoRegimen (CAT-033) y exportacion.regimen (CAT-028).
Contado con un solo medio
{
"tipoDte": "01",
"formaPago": "05",
"items": [{ "descripcion": "Café", "cantidad": 1, "precioUni": 25 }]
}"pagos": [
{ "codigo": "05", "montoPago": 25, "referencia": null, "plazo": null, "periodo": null }
]Contado con varios medios
{
"tipoDte": "01",
"items": [{ "descripcion": "Café", "cantidad": 2, "precioUni": 50 }],
"pagos": [
{ "codigo": "01", "montoPago": 40 },
{ "codigo": "02", "montoPago": 60, "referencia": "VOUCHER-0042" }
]
}"pagos": [
{ "codigo": "01", "montoPago": 40, "referencia": null, "plazo": null, "periodo": null },
{ "codigo": "02", "montoPago": 60, "referencia": "VOUCHER-0042", "plazo": null, "periodo": null }
]La suma de montoPago tiene que ser igual al total a pagar, al centavo; si no, 422 validation_failed con details.totalPagar y details.sumaPagos, sin gastar correlativo.
Crédito
Una venta a crédito no usa pagos. Escriba condicionOperacion: 2, la formaPago pactada, el plazo (CAT-018: 01 días, 02 meses, 03 años) y el periodo (cuántos):
{
"tipoDte": "01",
"condicionOperacion": 2,
"formaPago": "05",
"plazo": "01",
"periodo": 30,
"items": [{ "descripcion": "Café", "cantidad": 1, "precioUni": 25 }]
}"pagos": [
{ "codigo": "05", "montoPago": 25, "referencia": null, "plazo": "01", "periodo": 30 }
]Si manda pagos en una venta a crédito la respuesta es 422 validation_failed antes de gastar correlativo: Hacienda no publica cómo se reparte un plazo entre varios medios, y Facta no lo adivina. Quite pagos y use el cuerpo de arriba. Con condicionOperacion 3 (otro) sí se admite pagos.
Exportación (11): lo que Hacienda exige
En una exportación de bienes (tipoItemExpor 1, que también se usa para bienes y servicios; Hacienda no admite el 3, así que Facta lo acepta como alias, lo envía como 1 y avisa con tipo_item_expor_mapped) Hacienda exige exportacion.tipoRegimen, exportacion.regimen y exportacion.recintoFiscal, aunque su esquema los marque opcionales: sin tipoRegimen Hacienda rechaza el documento, y sin los otros dos lo sella con una advertencia. Facta los exige: si falta alguno responde 400 invalid_request con details.field, antes de gastar correlativo. En servicios (tipoItemExpor 2) pueden omitirse.
recintoFiscales una aduana o zona franca concreta, un código de CAT-027, no un texto libre ni un país.tipoRegimen(CAT-033):EX-1exportación definitiva,EX-2exportación temporal,EX-3reexportación,TA-1tránsito aduanero.regimen(CAT-028): el código1000.000(exportación definitiva, régimen común) en bienes solo el código llano.EX-1solo es un tipo de régimen y se rechaza aquí.
| Código | Recinto fiscal | Código | Recinto fiscal |
|---|---|---|---|
| 01 | Terrestre San Bartolo | 28 | Z.F. Santa Tecla |
| 02 | Marítima de Acajutla | 29 | Z.F. Santa Ana |
| 03 | Aérea de Comalapa | 30 | Z.F. La Concordia |
| 04 | Terrestre Las Chinamas | 31 | Aérea Ilopango |
| 05 | Terrestre La Hachadura | 32 | Z.F. Pipil |
| 06 | Terrestre Santa Ana | 33 | Puerto Barillas |
| 07 | Terrestre San Cristóbal | 34 | Z.F. Calvo Conservas |
| 08 | Terrestre Anguiatú | 35 | Feria Internacional |
| 09 | Terrestre El Amatillo | 36 | Aduana El Papalón |
| 10 | Marítima La Unión | 37 | Z.F. Sam-Li |
| 11 | Terrestre El Poy | 38 | Z.F. San José |
| 12 | Terrestre Metalío | 39 | Z.F. Las Mercedes |
| 15 | Fardos Postales | 40 | Z.F. EMCO |
| 16 | Z.F. San Marcos | 41 | Z.F. Gigante |
| 17 | Z.F. El Pedregal | 42 | Z.F. NOVABES |
| 18 | Z.F. San Bartolo | 43 | Z.F. INHDELVA |
| 20 | Z.F. Exportsalva | 71 | Aldesa |
| 21 | Z.F. American Park | 72 | Agdosa Merliot |
| 23 | Z.F. Internacional | 73 | Bodesa |
| 24 | Z.F. Diez | 76 | Delegación DHL |
| 26 | Z.F. Miramar | 77 | Transauto |
| 27 | Z.F. Santo Tomás | 80 | Nejapa |
| 81 | Almaconsa | 83 | Agdosa Apopa |
| 85 | Gutiérrez Courier y Cargo | 99 | San Bartolo Envío Hn/Gt |
{
"tipoDte": "11",
"formaPago": "05",
"receptor": {
"nombre": "Acme Imports LLC",
"tipoDocumento": "37",
"numDocumento": "98-7654321",
"codPais": "US",
"nombrePais": "Estados Unidos",
"complemento": "100 Main St, Miami, FL",
"tipoPersona": 2,
"descActividad": "Importación de alimentos",
"correo": "compras@acme.example"
},
"exportacion": {
"tipoItemExpor": 1,
"incoterms": "09",
"recintoFiscal": "02",
"tipoRegimen": "EX-1",
"regimen": "1000.000",
"flete": 150,
"seguro": 20
},
"items": [{ "descripcion": "Café tostado, sacos de 69 kg", "cantidad": 10, "precioUni": 300 }]
}Retención de renta (14), tal como funciona hoy
aplicarReteRenta (solo en el comprobante de sujeto excluido) es opcional. Lo que debe saber:
- Si se omite o vale
false, no se retiene yreteRentaqueda en 0. Nunca es automática. - Si vale
true, se aplica la tasa vigente de renta sobre el subtotal completo después de los descuentos por línea, sin elegir líneas portipoItem: incluye los bienes usados como insumos de un servicio. - Se resta del total a pagar:
totalPagar = subTotal − reteRenta. - El monto se lee en
documento.resumen.reteRentay también entotales.reteRentade la respuesta. - Este contrato conserva el cálculo completo. Para elegir líneas, use
incomeWithholdingy compruebe primero el soporte del servidor, como se explica en la sección siguiente.
Observaciones
observaciones es un texto libre para lo que el cliente tiene que leer en el documento: una referencia, una instrucción de entrega, un número de pedido. Va en el cuerpo de la petición y viaja dentro del DTE firmado, en resumen.observaciones, en los tipos que emite la API (01, 03, 05, 06, 11 y 14, y también el 04 y el 07). La hoja lo imprime como «Observaciones:» en todas las plantillas carta; en ticket, solo si la plantilla trae ese bloque.
{
"tipoDte": "01",
"items": [{ "descripcion": "Café", "cantidad": 2, "precioUni": 1.5 }],
"observaciones": "Pedido 1042 · entregar en bodega 3, portón norte."
}Hasta 3000 caracteres. Si no hay nada que decir, omita el campo o mande null: un texto vacío no lo admiten los esquemas de 01, 03, 11 y 14. Para datos con nombre propio (orden de compra, vendedor) use apendice, que se imprime como «etiqueta: valor» debajo de las observaciones.
Si su sistema lee documentos de otros emisores, tenga en cuenta que un DTE de la versión 1.x de los esquemas trae este texto en extension.observaciones y no en resumen. Facta DTE busca en los dos lugares al dibujar un documento importado; lo que la API firma va siempre en resumen.
Campos que no existen
Un campo que Facta DTE no reconoce no rechaza la petición, pero no forma parte del documento. La respuesta lo dice en advertencias:
{
"advertencias": [
{
"codigo": "campo_desconocido",
"campo": "items[0].descuento",
"sugerencia": "items[0].montoDescu",
"mensaje": "Facta DTE no reconoce el campo «items[0].descuento»: se ignoró y no forma parte del documento. ¿Quiso decir «items[0].montoDescu»?"
}
]
}También llega la cabecera Facta-Warning: campo_desconocido; campos=1, y si la petición falla por otra razón las mismas advertencias vienen en error.details.advertencias. Revise la primera respuesta de su integración: un campo ignorado es un descuento, un pago o un régimen que el documento no lleva. Un reintento con la misma Idempotency-Key devuelve las mismas advertencias.
Los borradores avisan igual: POST /v1/drafts, PUT /v1/drafts/{id} y POST /v1/drafts/{id}/issue traen las mismas advertencias y la misma cabecera. En un borrador importa todavía más, porque Facta DTE guarda la solicitud ya resuelta: el campo ignorado no queda en el borrador. Corríjalo y guarde una versión nueva antes de emitirlo.
Una nota (05/06) que nombra un codigoGeneracion que no está en su índice (404) o que Hacienda nunca selló (400) se rechaza antes de reservar el correlativo: no gasta ningún número.
Qué puede contestar
Un 200 trae selloRecibido: es un documento fiscal. Un 202 significa que quedó firmado y Hacienda no respondió — no se emite otra vez: se lista lo pendiente y se reintenta, como cuenta también Contingencia y resultados inciertos. Lo mismo vale para un 503 o un corte de conexión: nunca use una llave nueva para la misma venta. 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
Nota de remisión (04) y retención (07)
Para qué sirve cada uno, quién puede emitirlos, cada campo con su razón, los códigos de retención, lo que se ignora y los errores que verá.
Leer →Preparar y firmar por separado
Por qué separar la reserva del correlativo de la firma, el prepareToken y sus 15 minutos, y qué pasa si el documento cambia entre las dos llamadas.
Leer →