Skip to main content
Un DTE (Documento Tributario Electrónico) se crea con una sola llamada POST /dte: un objeto JSON con el detalle de la venta. Fegora completa con valores por defecto de la cuenta todo lo que no se envíe explícitamente, calcula el IVA implícito en el precio, y certifica el documento ante la autoridad fiscal correspondiente (SAT, MH o DGII, según el país de la cuenta emisora). Esta página documenta la forma del cuerpo de la solicitud. La respuesta de POST /dte incluye estos mismos campos más los datos que agrega la certificación (serie, número, sellos, URIs de archivos); vea Objeto de respuesta al final de esta página.
Todos los ejemplos de esta página usan datos ficticios (NIT, nombres, montos). Reemplácelos por los de su operación real.

​
Objeto raíz (Dte)

receptor es opcional. Si se omite por completo, o si se omiten receptor.id/receptor.nombre dentro de él, Fegora completa un receptor de Consumidor Final (id: "CF", nombre: "CONSUMIDOR FINAL"). En una nota de crédito/débito sin receptor explícito, el receptor se hereda del documento original referenciado por idDteOriginal.
serie y numero no se envían en la solicitud — los asigna el certificador durante la certificación y sólo aparecen en la respuesta.
El flujo de referencia a documentos pre-migración (“FACE”) no está disponible en el API actual. Un ejemplo de 2019 (Postman “Nota de Crédito (FACE)”) mostraba una alternativa a idDteOriginal: un objeto dteOriginal ({ esRegimenAntiguo, fechaEmision, id, numero, serie, tipo }) para referenciar una factura emitida en un sistema anterior a Fegora, sin un id propio de Fegora. El comando actual (CreateDteCommand) no tiene ese campo — la única forma de referenciar un documento original hoy es idDteOriginal con el UUID de un DTE que ya exista en la base de datos de Fegora.
El validador actual no exige motivoExencionIva cuando esExentoIva: true (a diferencia de lo que documentaba la wiki de 2019). Si omite el motivo en un documento exento, la solicitud puede pasar la validación de Fegora y de todas formas ser rechazada por la autoridad fiscal al certificar, con un error de certificación (FEG_DTE_CERTIFICATION_ERROR) en lugar de un error de validación temprano. Se recomienda enviar siempre motivoExencionIva explícito cuando esExentoIva es true.
emisor: los campos nit, nombre, nombreComercial, direccion y correoElectronico de este objeto se validan si se envían, pero no tienen efecto — los datos fiscales del emisor siempre provienen de la configuración de la cuenta. Los únicos campos de emisor que el API realmente utiliza son codigoEstablecimiento (para sobreescribir el establecimiento por defecto de la cuenta) y codigoPuntoVenta (código de punto de venta, usado en El Salvador — por ejemplo "P002").

​
receptor

receptor.id recibe el NIT del receptor, el literal "CF" para Consumidor Final, o un identificador provisional para receptores extranjeros. Guatemala no usa receptor.tipoId — Fegora infiere el tipo de identificación a partir del valor y de receptor.direccion.pais. Detalle completo en Guatemala → Identificación del receptor.

​
direccion

El valor por defecto de pais en el objeto direccion es el nombre completo "GUATEMALA", no el código ISO "GT" — pero todos los ejemplos de este sitio (y prácticamente todos los payloads reales) envían "GT". La validación del formato de codigoPostal (5 dígitos) sólo se activa cuando el valor es exactamente el literal "GUATEMALA", por lo que en la práctica, con pais: "GT", esa validación no se ejecuta.

​
item

* Es obligatorio enviar precioUnitario o precio con un valor mayor que cero — al menos uno de los dos debe resolver un precio unitario positivo.
descripcion tiene un límite de 500 caracteres en el validador actual. La wiki de 2019 documentaba un límite de 10,000 caracteres para este campo — el código actual es más estricto. CODE WINS: use 500 como el límite real.
El valor "bienServicio" para item.tipo no está documentado en las fuentes de 2019 (que sólo mencionaban "bien"/"servicio") — es un valor aceptado por el código actual.

​
impuesto

Objeto usado dentro de item.impuestos[]. Puede enviarse completo (con montos ya calculados) o parcial — Fegora completa los montos faltantes automáticamente. El mecanismo de cálculo y las tasas vigentes se documentan en detalle en Impuestos.
Enviar sólo { "nombreCorto": "IVA" } (sin montos) es el patrón típico para dejar que Fegora calcule el IVA implícito a partir de precioUnitario. Lo mismo aplica a ITH, IFB, TDP e IDP: enviar sólo el nombreCorto (y, para IDB, además montoGravable + cantidadUnidadesGravables) activa el cálculo automático a la tasa vigente.

​
datoAdicional

Objeto usado en datosAdicionales[] a nivel de documento, de receptor o de ítem.
etiqueta y visible ya no son campos de entrada. La wiki y los ejemplos de Postman de 2019 mostraban datoAdicional con cuatro campos aceptados en la solicitud: nombre, valor, etiqueta y visible. El modelo de solicitud actual (DatoAdicionalDto) sólo tiene nombre y valor — si su integración envía etiqueta/visible, esos valores se ignoran silenciosamente (no producen error, pero tampoco tienen efecto). En la respuesta, Fegora deriva ambos automáticamente: etiqueta sale vacía para las frases SAT y leyendas internas (por ejemplo SAT-4-1, FACTESP-LEYENDA) y es igual al nombre para el resto; visible es true salvo para TIPO_PERSONERIA. CODE WINS sobre la documentación de 2019.

​
abonoPactado

Objeto usado en abonosPactados[].

​
datosExportacion

Objeto obligatorio cuando esExportacion es true o tipo es facturaExportacion.
incoterm ya no es obligatorio. La documentación de 2019 indicaba que nombreConsignatario, direccionConsignatario e incoterm eran los tres campos obligatorios de datosExportacion. El validador actual (DatosExportacionDtoValidator) sólo exige nombreConsignatario y direccionConsignatario como no nulos; incoterm es opcional y sólo se valida su formato si se envía. CODE WINS — pero se recomienda igual enviarlo cuando aplique, ya que el complemento de exportación de la SAT (Guatemala) exige un orden estricto de campos en el XML (nombreConsignatario → direccionConsignatario → incoterm).

​
Ejemplo completo anotado

Factura guatemalteca con descuento, un impuesto adicional (ITH), datos adicionales de documento e ítem, y receptor con dirección completa:
Notas sobre este ejemplo:
  • tipo, moneda y fechaEmision son opcionales — en un DTE mínimo se podrían omitir los tres. Se incluyen aquí explícitos sólo para mostrar el formato.
  • receptor.id lleva un NIT de ejemplo (contribuyente, no Consumidor Final); si fuera venta a público general bastaría con omitir receptor por completo.
  • items[0].precioUnitario (450.00) incluye IVA. Como no se envía un impuesto IVA explícito, Fegora sintetiza la línea de IVA automáticamente a partir de este precio.
  • items[0].descuento (50.00) es un monto fijo en quetzales, no un porcentaje — se resta del total de la línea antes de impuestos.
  • items[0].impuestos[0] sólo declara "nombreCorto": "ITH" sin montos: Fegora calcula el Impuesto de Hospedaje (10% en Guatemala) sobre la base gravable de la línea.
  • datosAdicionales a nivel de documento y de ítem son campos de libre uso (OrdenCompra, NumeroReserva) que Fegora almacena y devuelve tal cual, sin interpretarlos.

​
Objeto de respuesta

La respuesta de POST /dte (y de GET /dte/{id}) devuelve el documento con los mismos campos de la solicitud, más los datos que agrega la certificación: Para el detalle completo del esquema de respuesta (incluyendo campos específicos de anulación, notas de crédito/débito y exportación), vea la pestaña API Reference.