> ## 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.
# Datos adicionales
> Pares nombre/valor para adjuntar información extra a un DTE, su receptor o sus ítems — y las claves reservadas por país.
`datosAdicionales` es un mecanismo genérico para adjuntar información que no tiene un campo propio en la estructura del DTE. Aparece en tres niveles distintos, todos con la misma forma:
* **Documento**: `datosAdicionales[]` en la raíz del DTE.
* **Receptor**: `receptor.datosAdicionales[]`.
* **Ítem**: `items[].datosAdicionales[]`.
## Forma del dato adicional
```json theme={null}
{
"nombre": "OrdenDespacho",
"valor": "54654-65"
}
```
| Campo | Tipo | Obligatorio | Descripción |
| -------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------- |
| `nombre` | string | Sí | Identificador del dato. Libre para usos generales; reservado para las claves de país descritas más abajo. |
| `valor` | string | No | Valor asociado. |
El API sólo lee `nombre` y `valor` al recibir un `datoAdicional`. Cualquier otro campo enviado en el objeto (por ejemplo `etiqueta` o `visible`, presentes en documentación pública anterior de Fegora) se ignora silenciosamente — vea la sección siguiente.
## En la respuesta: `etiqueta` y `visible`
Al consultar un DTE (`GET /dte/{id}` o la respuesta de `POST /dte`), cada `datoAdicional` trae dos campos adicionales que el API calcula automáticamente, no que el cliente envía:
```json theme={null}
{
"nombre": "SAT-1-2",
"valor": "Sujeto a retención definitiva ISR",
"etiqueta": "",
"visible": true
}
```
| Campo | Descripción |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| `etiqueta` | Vacío (`""`) para las frases SAT (`SAT-*`) y leyendas internas (p. ej. `FACTESP-LEYENDA`); igual a `nombre` para el resto. |
| `visible` | `true` para todos los datos adicionales, salvo `TIPO_PERSONERIA`, que siempre viaja como `false`. |
## Usos generales comunes
Al no tener un campo dedicado, `datosAdicionales` suele usarse para:
* Condiciones de garantía o de crédito que deben imprimirse en el documento.
* Referencias internas: orden de despacho, código SAP, SKU, número de pedido.
* Cualquier otro dato de negocio que el receptor del documento no necesita procesar, pero que su empresa quiere conservar junto al DTE.
```json theme={null}
{
"receptor": { "id": "CF", "nombre": "CONSUMIDOR FINAL" },
"datosAdicionales": [
{ "nombre": "CondGarantia", "valor": "Garantía de 30 días a partir de la fecha de emisión." },
{ "nombre": "OrdenDespacho", "valor": "54654-65" }
],
"items": [
{
"descripcion": "Consultoría de instalación",
"precioUnitario": 300,
"datosAdicionales": [
{ "nombre": "CodigoSAP", "valor": "DKDU738" },
{ "nombre": "NotaInterna", "valor": "SKU 392821" }
]
}
]
}
```
## Datos adicionales que Fegora agrega automáticamente
Al crear un DTE, Fegora agrega por su cuenta ciertos `datosAdicionales` a nivel de documento (sin que el cliente los envíe), salvo que el cliente ya haya enviado un dato con ese mismo `nombre`:
* Campos configurados a nivel de la cuenta emisora (excluyendo credenciales internas del certificador, que nunca se exponen).
* **Guatemala**: las frases SAT correspondientes al documento, con `nombre` en el formato `SAT-{tipo}-{escenario}` (por ejemplo `SAT-1-2`) y `valor` con el texto literal de la frase — vea [Guatemala](/paises/guatemala).
* La leyenda de factura especial (`FACTESP-LEYENDA`), únicamente cuando `tipo: "facturaEspecial"`.
## Claves reservadas por país
Además del uso general, cada país usa `datosAdicionales` (a nivel de documento o de receptor) para transmitir campos que la autoridad fiscal exige y que no tienen un campo dedicado en el JSON del DTE.
Guatemala no requiere claves de `datosAdicionales` para emitir — las frases SAT se agregan automáticamente (vea arriba). El `datosAdicionales` de este país es de uso libre.
```json theme={null}
{
"nombre": "SAT-1-2",
"valor": "Sujeto a retención definitiva ISR",
"etiqueta": "",
"visible": true
}
```
Vea el detalle de frases y regímenes en [Guatemala](/paises/guatemala).
| Clave | Nivel | Obligatorio | Descripción |
| --------------------------------------------- | --------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NUMERO_SECUENCIAL` | Documento | Sí, si el receptor lleva `MH_NRC` o `MH_CODIGO_ACTIVIDAD` | Correlativo único por cuenta que exige el Ministerio de Hacienda. Debe incrementarse en cada documento — Digifact lo rechaza si está vacío o repetido. |
| `MH_NRC` | Receptor | Para CCF (crédito fiscal) | Número de Registro de Contribuyente del receptor. |
| `MH_CODIGO_ACTIVIDAD` | Receptor | Para CCF/FSE | Código de actividad económica del receptor. |
| `IVA_PERCIBIDO` (alias `MH_IVA_PERCIBIDO`) | Documento | No | IVA percibido — se suma al total del documento. |
| `IVA_RETENIDO` (alias `MH_IVA_RETENIDO`) | Documento | No | IVA retenido — se resta del total del documento. |
| `RETENCION_RENTA` (alias `MH_RENTA_RETENIDA`) | Documento | No | Retención de renta. Funciona de forma consistente sólo en `tipo: "facturaEspecial"` (FSE); en CCF el certificador puede rechazarla. |
```json theme={null}
{
"receptor": {
"id": "06141234567890",
"nombre": "Comercial Ejemplo, S.A. de C.V.",
"tipoId": "NIT",
"direccion": { "pais": "SV", "idMunicipio": "SV.SS.23", "direccion": "Colonia Escalón" },
"datosAdicionales": [
{ "nombre": "MH_NRC", "valor": "123456" },
{ "nombre": "MH_CODIGO_ACTIVIDAD", "valor": "01112" }
]
},
"datosAdicionales": [
{ "nombre": "NUMERO_SECUENCIAL", "valor": "2000015" }
]
}
```
Si el receptor lleva `MH_NRC` o `MH_CODIGO_ACTIVIDAD` y el documento no incluye `NUMERO_SECUENCIAL`, el API rechaza la solicitud con `400 FEG_VALIDATION_ERROR` — vea [Manejo de errores](/primeros-pasos/errores). Detalle completo en [El Salvador](/paises/el-salvador).
| Clave | Nivel | Obligatorio | Descripción |
| ------------------------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `NUMERO_SECUENCIAL` | Documento | Sí | Secuencial NCF asignado por la DGII a la cuenta (correlativo, por tipo de comprobante y establecimiento). |
| `VENCIMIENTO_NUMERO_SECUENCIAL` | Documento | Recomendado | Fecha de vencimiento del rango NCF asignado, formato `YYYY-MM-DD`. |
```json theme={null}
{
"emisor": { "codigoEstablecimiento": "1" },
"datosAdicionales": [
{ "nombre": "NUMERO_SECUENCIAL", "valor": "290091" },
{ "nombre": "VENCIMIENTO_NUMERO_SECUENCIAL", "valor": "2026-12-31" }
]
}
```
Vea el detalle de tipos de comprobante y rangos NCF en [República Dominicana](/paises/republica-dominicana).
## Páginas relacionadas
Referencia completa del documento JSON.
Catálogo de tipos de documento por país.