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)
| Campo | Tipo | Obligatorio | Descripción | Valor por defecto |
|---|
tipo | string | No | Tipo de documento. Valores aceptados: factura, ticket, facturaCambiaria, facturaEspecial, facturaExportacion, notaCredito, notaDebito, notaAbono, recibo, reciboDonacion. No distingue mayúsculas/minúsculas. Vea Tipos de documento para el detalle de cada uno y qué países lo soportan. | "factura" |
moneda | string | No | Código ISO 4217 en mayúsculas. El API valida contra una lista fija: GTQ, USD, EUR, MXN, HNL, SVC, NIO, CRC, PAB, BZD. | moneda por defecto de la cuenta, o "GTQ" |
fechaEmision | string (fecha) | No | Formatos aceptados: yyyy-MM-dd, yyyy-MM-ddTHH:mm, yyyy-MM-ddTHH:mm:ss. No puede ser una fecha futura (con un margen de un día). | fecha y hora actual |
emisor | object | No | Datos del emisor. En la práctica sólo codigoEstablecimiento y codigoPuntoVenta (SV) tienen efecto — vea la nota debajo de la tabla. | datos fiscales de la cuenta |
receptor | object | No | Datos del receptor del documento. Ver receptor. | Consumidor Final (id: "CF", nombre: "CONSUMIDOR FINAL") |
items[] | array<object> | Sí | Detalle de productos/servicios. Debe incluir al menos un ítem. Ver item. | — |
esExentoIva | boolean | No | Marca el documento completo como exento de IVA. | configuración de exención de la cuenta |
motivoExencionIva | string | No | Motivo de exención — uno de los códigos reconocidos por Fegora (ver Impuestos). | motivo configurado en la cuenta, si aplica |
idDteOriginal | string (UUID) | Condicional | El id del documento al que hace referencia. Obligatorio junto con motivoAjuste cuando tipo es notaCredito o notaDebito. | — |
motivoAjuste | string | Condicional | Motivo del ajuste. Obligatorio cuando tipo es notaCredito o notaDebito. | — |
numeroTransaccion | string | No | Identificador de idempotencia propio de su sistema. Si ya existe un DTE certificado con el mismo valor para la cuenta, la solicitud se rechaza como duplicado (FEG_DTE_CREA_001). | — |
numeroAcceso | number (entero) | No | Número de acceso de contingencia (Guatemala). Ver Contingencia. | — |
esExportacion | boolean | No | Marca el documento como una exportación. Alternativa equivalente a tipo: "facturaExportacion". | false |
datosExportacion | object | Condicional | Obligatorio cuando esExportacion es true o tipo es facturaExportacion. Ver datosExportacion. | — |
abonosPactados[] | array<object> | No | Calendario de abonos. En Guatemala, su sola presencia convierte una factura/ticket en factura cambiaria; en El Salvador y República Dominicana describe formas de pago. Ver abonoPactado. | — |
datosAdicionales[] | array<object> | No | Pares nombre/valor de libre uso, o campos país-específicos (por ejemplo NUMERO_SECUENCIAL en El Salvador). Ver datoAdicional y Datos adicionales. | — |
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
🇬🇹 Guatemala
🇸🇻 El Salvador
🇩🇴 República Dominicana
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.receptor.id recibe el NIT (14 dígitos), DUI (9 dígitos), pasaporte o carné de residente del receptor, y receptor.tipoId declara explícitamente cuál de ellos es (NIT, DUI, PASAPORTE, CARNET_RESIDENTE, OTRO). Un Comprobante de Crédito Fiscal requiere además receptor.datosAdicionales con MH_NRC y MH_CODIGO_ACTIVIDAD. Detalle completo en El Salvador → Identificación del receptor.receptor.id recibe el RNC (9 dígitos, persona jurídica) o la cédula (11 dígitos, persona física) del receptor. Detalle completo en República Dominicana → Identificación del receptor.| Campo | Tipo | Obligatorio | Descripción | Valor por defecto |
|---|
id (alias nit) | string | No | Identificador fiscal del receptor. Máximo 20 caracteres. Ambos nombres (id, nit) son aceptados y equivalentes. | "CF" |
tipoId | string | No | Tipo de documento de identidad del receptor. Su uso y valores válidos varían por país — vea los tabs arriba. | — |
nombre | string | No | Nombre o razón social del receptor. Máximo 255 caracteres. | "CONSUMIDOR FINAL" |
nombreComercial | string | No | Nombre comercial del receptor. | — |
direccionCorreoElectronico (alias correoElectronico) | string | No | Correo del receptor. Admite múltiples direcciones separadas por coma — cada una se valida individualmente. | — |
afiliacionIva | string | No | Régimen de IVA del receptor. En República Dominicana, el valor REGIMEN_ESPECIAL activa el tipo de comprobante CERP. | — |
direccion | object | No | Dirección del receptor. Ver direccion. | — |
datosAdicionales[] | array<object> | No | Campos país-específicos del receptor (por ejemplo MH_NRC, MH_CODIGO_ACTIVIDAD en El Salvador). Ver datoAdicional. | — |
direccion
| Campo | Tipo | Obligatorio | Descripción | Valor por defecto |
|---|
direccion | string | No | Dirección específica (calle, zona/colonia). Máximo 500 caracteres. | — |
municipio | string | No | Nombre del municipio. | — |
departamento | string | No | Nombre del departamento/provincia. | — |
idMunicipio | string | No | Código de municipio del catálogo del país. En El Salvador usa el formato SV.<departamento>.<municipio> (por ejemplo SV.SS.23). | — |
idDepartamento | string | No | Código de departamento/provincia del catálogo del país. | — |
codigoPostal | string | No | Código postal. Debe tener exactamente 5 dígitos cuando pais es "GUATEMALA" (ver nota). | — |
pais | string | No | País de la dirección. | "GUATEMALA" |
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
| Campo | Tipo | Obligatorio | Descripción | Valor por defecto |
|---|
descripcion | string | Sí | Descripción del bien o servicio. Máximo 500 caracteres. | — |
tipo | string | No | "bien", "servicio" o "bienServicio". | "bien", o el configurado en la cuenta |
cantidad | number | No | Cantidad vendida. Se recomienda hasta 6 decimales. Un valor cero o negativo se trata como 1. | 1 |
unidadMedida | string | No | Unidad de medida. Se recomienda una de: UNI, MTS, MT2, MT3, KGS, LTS, PAR, CBZ, PZA, KWT, JGO, BAR. Máximo 10 caracteres. | unidad configurada en la cuenta, o "UNI" |
precioUnitario | number | Sí* | Precio del bien o servicio, con IVA incluido (salvo exenciones — ver Impuestos). Si incluye descuento, este precio no debe reflejar ya el descuento — Fegora aplica el cálculo. | — |
precio | number | No | Alternativa a precioUnitario: el total de la línea (con IVA incluido). Si se envía precio y precioUnitario es cero u omitido, Fegora deriva precioUnitario = precio / cantidad. | — |
descuento | number | No | Descuento discreto (monto fijo en la moneda del documento, no un porcentaje). Si necesita aplicar un porcentaje, calcúlelo en su sistema y envíe el monto resultante. | 0 |
impuestos[] | array<object> | No | Impuestos de la línea. Ver impuesto e Impuestos para el mecanismo de cálculo automático. | IVA calculado automáticamente sobre precioUnitario |
datosAdicionales[] | array<object> | No | Datos adicionales propios del ítem. Ver datoAdicional. | — |
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.
| Campo | Tipo | Obligatorio | Descripción | Valor por defecto |
|---|
nombreCorto | string | Sí | Código del impuesto. Valores aceptados por el validador actual: IVA, IDP, ITH, ITP, TDP, IFB, MUN, IDB. | — |
codigoUnidadGravable | string o number | Condicional | Código de unidad/tasa gravable. Obligatorio cuando nombreCorto es IVA explícito (por ejemplo 1 = gravado, 2 = exento en Guatemala — el significado exacto varía por impuesto y país, ver Impuestos). Acepta número o cadena. | — |
montoGravable | number | No | Base gravable de la línea. Si se omite (o es 0) y el impuesto tiene cálculo automático, Fegora la completa. | calculado |
montoImpuesto | number | No | Monto del impuesto. Si se omite (o es 0) y el impuesto tiene cálculo automático, Fegora lo completa. | calculado |
cantidadUnidadesGravables | number | Condicional | Cantidad de unidades gravables (por ejemplo litros de combustible, botellas). Informativo para algunos impuestos; obligatorio y usado en el cálculo para IDB. | 0 |
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.
| Campo | Tipo | Obligatorio | Descripción |
|---|
nombre | string | Sí | Nombre del dato adicional. Se usa para identificarlo (por ejemplo NUMERO_SECUENCIAL, MH_NRC, o un nombre propio como IdProductoSAP). |
valor | string | No | Valor del dato adicional. |
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[].
| Campo | Tipo | Obligatorio | Descripción | Valor por defecto |
|---|
fecha | string (fecha) | Sí | Fecha pactada del abono, formato yyyy-MM-dd. | — |
monto | number | Sí | Monto del abono. Debe ser mayor a cero. | — |
numero | number (entero) | No | Número de orden del abono. | calculado por Fegora según el orden de las fechas |
metodoPago | string | No | Método de pago del abono (usado en formas de pago de El Salvador/República Dominicana). | — |
duracion | string | No | Duración/plazo en formato ISO-8601 (por ejemplo P1M, P1Y6M). | — |
datosExportacion
Objeto obligatorio cuando esExportacion es true o tipo es facturaExportacion.
| Campo | Tipo | Obligatorio | Descripción |
|---|
nombreConsignatario | string | Sí | Nombre del consignatario. |
direccionConsignatario | string | Sí | Dirección del consignatario. |
incoterm | string | No | Código Incoterm. Si se envía, debe ser uno de: EXW, FCA, CPT, CIP, DAP, DPU, DDP, FAS, FOB, CFR, CIF. |
codigoConsignatario | string | No | Código/identificador del consignatario. |
nombreComprador | string | No | Nombre del comprador, si es distinto del consignatario. |
direccionComprador | string | No | Dirección del comprador. |
codigoComprador | string | No | Código/identificador del comprador. |
otraReferencia | string | No | Referencia adicional libre (por ejemplo número de orden). |
codigoExportador | string | No | Código del exportador. |
nombreExportador | string | No | Nombre del exportador, si es distinto del emisor. |
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:
{
"tipo": "factura",
"moneda": "GTQ",
"fechaEmision": "2026-07-10T09:30:00",
"numeroTransaccion": "PED-2026-000481",
"receptor": {
"id": "12345678",
"nombre": "Distribuidora Ejemplo, Sociedad Anónima",
"direccionCorreoElectronico": "facturacion@ejemplo.com",
"direccion": {
"direccion": "5a Avenida 10-25 Zona 4",
"municipio": "Guatemala",
"departamento": "Guatemala",
"codigoPostal": "01004",
"pais": "GT"
}
},
"datosAdicionales": [
{ "nombre": "OrdenCompra", "valor": "OC-98231" }
],
"items": [
{
"tipo": "servicio",
"descripcion": "Hospedaje 2 noches, habitación doble",
"cantidad": 2,
"unidadMedida": "UNI",
"precioUnitario": 450.00,
"descuento": 50.00,
"impuestos": [
{ "nombreCorto": "ITH" }
],
"datosAdicionales": [
{ "nombre": "NumeroReserva", "valor": "RES-4471" }
]
}
]
}
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:
| Campo | Descripción |
|---|
id | Identificador único del documento (UUID). En la mayoría de certificadores coincide con el número de autorización fiscal. |
serie, numero | Serie y número asignados por el certificador. |
estado | Certificado o Anulado. |
fechaCertificacion | Fecha y hora en que la autoridad fiscal certificó el documento. |
certificador | Datos del certificador que procesó el documento (id, nombre, nombreComercial). |
total | Total del documento. |
archivoXmlUri | URL del XML certificado. |
archivoPdfUri | URL del PDF — viene null en la respuesta de creación; se genera bajo demanda en la primera solicitud a GET /dte/{id}/pdf. |
archivoJsonUri | URL del JSON certificado (sólo cuando el certificador del país lo genera, por ejemplo El Salvador). |
dteUri | Enlace a la representación web del documento. |
selloEntidadFiscal | Sello/firma de la autoridad fiscal, cuando el certificador lo expone. |
verificacionCertificadorUri | URL para verificar el documento ante el certificador/autoridad. |
items[].impuestos[] | Las líneas de impuesto ya resueltas (con montoGravable/montoImpuesto calculados). |
datosAdicionales[] | Incluye, además de los enviados, los que Fegora agrega automáticamente (frases SAT en Guatemala, leyendas de tipo de documento, campos de la cuenta). |
