factadesarrolladores API 0.1.0-esqueleto

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.

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

jsoncuerpo · crédito fiscal
{
  "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.

typescriptSDK · crédito fiscal con receptor inline, sin ficha de cliente
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:

typescriptSDK · factura a consumidor final
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.

curlHTTP · CCF con receptor inline
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).

jsoncuerpo · nota de remisión mínima
{
  "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 }]
}
jsoncuerpo · comprobante de retención (compra en papel, retención declarada)
{
  "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 a ventaExenta y 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 es gravada.
  • no_sujeta: la operación está fuera del hecho generador del impuesto. Va a ventaNoSuj y 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.

jsoncuerpo · factura con tres clases de 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.

curlHTTP · factura con una línea exenta
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:

jsonfragmento · selección explícita de renta
{
  "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 pedidoTiposCampo del DTE selladoQué hace con el total
aplicarRetencionIva01, 03, 05, 06resumen.ivaReteLo baja: 1 % de la base neta gravada
aplicarPercepcionIva03resumen.ivaPerciLo sube: 1 % de la base neta de los bienes
aplicarReteRenta14resumen.reteRentaLo 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.

jsoncuerpo · factura con un descuento de $5 en una línea
{
  "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:

jsonlínea · cargo que no afecta la base imponible
{ "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.

jsoncuerpo · crédito fiscal con intereses exentos y abono a capital
{
  "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, con details.totalPagarVenta y details.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 que precioUni: con IVA en la factura (01), sin IVA en el crédito fiscal (03) y en la exportación (11).
jsoncuerpo · crédito fiscal con un descuento global de $12.50
{
  "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 }
}
bashcurl · factura con 10 % de descuento global
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:

CasoQué mandaQué 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 pagarsus filas, tal cual
Crédito (condicionOperacion 2)formaPago + plazo + periodo; nunca pagosuna 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 numPagoElectronicoel 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

jsoncuerpo · factura de $25.00 pagada con transferencia
{
  "tipoDte": "01",
  "formaPago": "05",
  "items": [{ "descripcion": "Café", "cantidad": 1, "precioUni": 25 }]
}
jsonrespuesta · documento.resumen.pagos
"pagos": [
  { "codigo": "05", "montoPago": 25, "referencia": null, "plazo": null, "periodo": null }
]

Contado con varios medios

jsoncuerpo · $100.00 mitad efectivo, mitad tarjeta
{
  "tipoDte": "01",
  "items": [{ "descripcion": "Café", "cantidad": 2, "precioUni": 50 }],
  "pagos": [
    { "codigo": "01", "montoPago": 40 },
    { "codigo": "02", "montoPago": 60, "referencia": "VOUCHER-0042" }
  ]
}
jsonrespuesta · documento.resumen.pagos
"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):

jsoncuerpo · factura de $25.00 a 30 días
{
  "tipoDte": "01",
  "condicionOperacion": 2,
  "formaPago": "05",
  "plazo": "01",
  "periodo": 30,
  "items": [{ "descripcion": "Café", "cantidad": 1, "precioUni": 25 }]
}
jsonrespuesta · documento.resumen.pagos
"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.

  • recintoFiscal es una aduana o zona franca concreta, un código de CAT-027, no un texto libre ni un país.
  • tipoRegimen (CAT-033): EX-1 exportación definitiva, EX-2 exportación temporal, EX-3 reexportación, TA-1 tránsito aduanero.
  • regimen (CAT-028): el código 1000.000 (exportación definitiva, régimen común) en bienes solo el código llano. EX-1 solo es un tipo de régimen y se rechaza aquí.
CódigoRecinto fiscalCódigoRecinto fiscal
01Terrestre San Bartolo28Z.F. Santa Tecla
02Marítima de Acajutla29Z.F. Santa Ana
03Aérea de Comalapa30Z.F. La Concordia
04Terrestre Las Chinamas31Aérea Ilopango
05Terrestre La Hachadura32Z.F. Pipil
06Terrestre Santa Ana33Puerto Barillas
07Terrestre San Cristóbal34Z.F. Calvo Conservas
08Terrestre Anguiatú35Feria Internacional
09Terrestre El Amatillo36Aduana El Papalón
10Marítima La Unión37Z.F. Sam-Li
11Terrestre El Poy38Z.F. San José
12Terrestre Metalío39Z.F. Las Mercedes
15Fardos Postales40Z.F. EMCO
16Z.F. San Marcos41Z.F. Gigante
17Z.F. El Pedregal42Z.F. NOVABES
18Z.F. San Bartolo43Z.F. INHDELVA
20Z.F. Exportsalva71Aldesa
21Z.F. American Park72Agdosa Merliot
23Z.F. Internacional73Bodesa
24Z.F. Diez76Delegación DHL
26Z.F. Miramar77Transauto
27Z.F. Santo Tomás80Nejapa
81Almaconsa83Agdosa Apopa
85Gutiérrez Courier y Cargo99San Bartolo Envío Hn/Gt
jsoncuerpo · exportación definitiva de bienes, por el puerto de Acajutla
{
  "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 y reteRenta queda 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 por tipoItem: 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.reteRenta y también en totales.reteRenta de la respuesta.
  • Este contrato conserva el cálculo completo. Para elegir líneas, use incomeWithholding y 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.

jsoncuerpo · factura con observaciones
{
  "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:

jsonrespuesta · parte de 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

Escriba para buscar Por ejemplo: idempotencia, contingencia, 422, emitir.

↑ ↓ moverse Enter abrir Esc cerrar