> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fegora.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Estructura del DTE
> Referencia completa de campos del documento JSON que se envía a POST /dte: objeto raíz, receptor, ítems, impuestos y datos adicionales.
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](#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](/dte/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](#receptor). | Consumidor Final (`id: "CF"`, `nombre: "CONSUMIDOR FINAL"`) |
| `items[]` | array\ | **Sí** | Detalle de productos/servicios. Debe incluir al menos un ítem. Ver [item](#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](/dte/impuestos#exención-de-iva)). | 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](/paises/guatemala#contingencia-y-verificación-en-línea). | — |
| `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](#datosexportacion). | — |
| `abonosPactados[]` | array\ | 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](#abonopactado). | — |
| `datosAdicionales[]` | array\ | No | Pares nombre/valor de libre uso, o campos país-específicos (por ejemplo `NUMERO_SECUENCIAL` en El Salvador). Ver [datoAdicional](#datoadicional) y [Datos adicionales](/dte/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
`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](/paises/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](/paises/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](/paises/republica-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](#direccion). | — |
| `datosAdicionales[]` | array\ | No | Campos país-específicos del receptor (por ejemplo `MH_NRC`, `MH_CODIGO_ACTIVIDAD` en El Salvador). Ver [datoAdicional](#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..` (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](/dte/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\ | No | Impuestos de la línea. Ver [impuesto](#impuesto) e [Impuestos](/dte/impuestos) para el mecanismo de cálculo automático. | IVA calculado automáticamente sobre `precioUnitario` |
| `datosAdicionales[]` | array\ | No | Datos adicionales propios del ítem. Ver [datoAdicional](#datoadicional). | — |
\* 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](/dte/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](/dte/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:
```json theme={null}
{
"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" }
]
}
]
}
```
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:
| 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). |
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**.