# Digifact Developer Portal

> Portal técnico unificado de Digifact para facturación electrónica (FEL/NUC) en Costa Rica, Rep. Dominicana, Guatemala, Panamá, El Salvador.

Digifact es un certificador autorizado en cada país donde opera. Esta documentación cubre el formato NUC (Norma de Uso del Comprobante) y la API para emisión de documentos tributarios electrónicos.

## Costa Rica

- [API Reference V1.3.0](http://localhost:3001/cr/api.md): endpoints REST para certificar, anular y consultar documentos ante Ministerio de Hacienda
- [NUC Overview](http://localhost:3001/cr/nuc.md): tipos de documento y complementos
- [NUC XML V4.4.0](http://localhost:3001/cr/nuc/xml.md): estructura completa en formato XML, con catálogos y respuesta API
- [NUC JSON V4.4.0](http://localhost:3001/cr/nuc/json.md): estructura completa en formato JSON, con catálogos y respuesta API
- [Esquemas](http://localhost:3001/cr/nuc/esquemas.md): NUCSchema.xsd y NUCSchema.json
- [Ejemplos](http://localhost:3001/cr/nuc/ejemplos.md): 15 ejemplos reales XML/JSON listos para descargar
- [Conceptos fiscales](http://localhost:3001/cr/conceptos.md): glosario de términos del régimen fiscal

## Rep. Dominicana

- [API Reference V1.0.4](http://localhost:3001/do/api.md): endpoints REST para certificar, anular y consultar documentos ante DGII
- [NUC Overview](http://localhost:3001/do/nuc.md): tipos de documento y complementos
- [NUC XML V1.0.7](http://localhost:3001/do/nuc/xml.md): estructura completa en formato XML, con catálogos y respuesta API
- [NUC JSON V1.0.7](http://localhost:3001/do/nuc/json.md): estructura completa en formato JSON, con catálogos y respuesta API
- [Esquemas](http://localhost:3001/do/nuc/esquemas.md): NUCSchema.xsd y NUCSchema.json
- [Ejemplos](http://localhost:3001/do/nuc/ejemplos.md): 20 ejemplos reales XML/JSON listos para descargar
- [Conceptos fiscales](http://localhost:3001/do/conceptos.md): glosario de términos del régimen fiscal

## Guatemala

- [API Reference V2.0.6](http://localhost:3001/gt/api.md): endpoints REST para certificar, anular y consultar documentos ante SAT
- [NUC Overview](http://localhost:3001/gt/nuc.md): tipos de documento y complementos
- [NUC XML V2.0.3](http://localhost:3001/gt/nuc/xml.md): estructura completa en formato XML, con catálogos y respuesta API
- [NUC JSON V2.0.3](http://localhost:3001/gt/nuc/json.md): estructura completa en formato JSON, con catálogos y respuesta API
- [Esquemas](http://localhost:3001/gt/nuc/esquemas.md): NUCSchema.xsd y NUCSchema.json
- [Ejemplos](http://localhost:3001/gt/nuc/ejemplos.md): 46 ejemplos reales XML/JSON listos para descargar
- [Conceptos fiscales](http://localhost:3001/gt/conceptos.md): glosario de términos del régimen fiscal

## Panamá

- [API Reference V2.0.5](http://localhost:3001/pa/api.md): endpoints REST para certificar, anular y consultar documentos ante DGI
- [NUC Overview](http://localhost:3001/pa/nuc.md): tipos de documento y complementos
- [NUC XML V2.0.8](http://localhost:3001/pa/nuc/xml.md): estructura completa en formato XML, con catálogos y respuesta API
- [NUC JSON V2.0.8](http://localhost:3001/pa/nuc/json.md): estructura completa en formato JSON, con catálogos y respuesta API
- [Esquemas](http://localhost:3001/pa/nuc/esquemas.md): NUCSchema.xsd y NUCSchema.json
- [Ejemplos](http://localhost:3001/pa/nuc/ejemplos.md): 59 ejemplos reales XML/JSON listos para descargar
- [Conceptos fiscales](http://localhost:3001/pa/conceptos.md): glosario de términos del régimen fiscal

## El Salvador

- [API Reference V1.1.0](http://localhost:3001/sv/api.md): endpoints REST para certificar, anular y consultar documentos ante Ministerio de Hacienda
- [NUC Overview](http://localhost:3001/sv/nuc.md): tipos de documento y complementos
- [NUC XML V2.0.0](http://localhost:3001/sv/nuc/xml.md): estructura completa en formato XML, con catálogos y respuesta API
- [NUC JSON V2.0.0](http://localhost:3001/sv/nuc/json.md): estructura completa en formato JSON, con catálogos y respuesta API
- [Esquemas](http://localhost:3001/sv/nuc/esquemas.md): NUCSchema.xsd y NUCSchema.json
- [Ejemplos](http://localhost:3001/sv/nuc/ejemplos.md): 57 ejemplos reales XML/JSON listos para descargar
- [Conceptos fiscales](http://localhost:3001/sv/conceptos.md): glosario de términos del régimen fiscal

### Versiones del NUC de El Salvador

Los links de arriba sirven **V2.0.0** (la versión por defecto). Las secciones y campos cambian entre versiones; endpoints, catálogos, tipos de documento, conceptos y ejemplos NO.

- **V2.0.0** (VIGENTE, por defecto) — en vigencia desde 20/11/2025 hasta 01/11/2026: [XML](http://localhost:3001/sv/nuc/xml.md) · [JSON](http://localhost:3001/sv/nuc/json.md)
- **V2.2.0** (PRÓXIMA — todavía no vigente) — en vigencia desde 01/07/2026: [XML](http://localhost:3001/sv/nuc/xml.md?v=2-2-0) · [JSON](http://localhost:3001/sv/nuc/json.md?v=2-2-0)

## Global

- [MCP Server](http://localhost:3001/global/mcp.md): conexión de asistentes de IA vía Model Context Protocol

## Contenido completo concatenado

- [llms-full.txt](http://localhost:3001/llms-full.txt): toda la documentación en un único archivo Markdown


---

# API Reference — Guatemala (doc V2.0.6)

> Documentación técnica de la API REST para certificar, anular y consultar DTE en el régimen FEL ante Superintendencia de Administración Tributaria (SAT).


## Ambientes

- **Test:** `https://testnucgt.digifact.com/api/` — corriendo **V2.2.29**
- **Producción:** `https://nucgt.digifact.com/gt.com.apinuc/api/` — corriendo **V2.4.8**

> La versión de este documento (V2.0.6) y la versión del servicio son números independientes. Para saber qué está corriendo, consultá la raíz del ambiente (`GET https://testnucgt.digifact.com/api/`), que responde con el número actual.

## Soporte

- **Email:** soporte@digifact.com.gt
- **Teléfono:** +502 2319-1921

---

## Endpoints

### POST · Obtener Token

Autenticación JWT. El token obtenido debe enviarse como header Authorization en todas las operaciones.

**URL Test:** `https://testnucgt.digifact.com/api/login/get_token`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/login/get_token`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Content-Type` | Sí | application/json |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `Username` | string | Sí | GT + "." + NIT (12 dígitos rellenos con ceros) + "." + usuario. | `GT.000000123456.USER_TEST` |
| `Password` | string | Sí | Contraseña proporcionada en las credenciales TEST o productivas. | `********` |

#### Body de ejemplo (JSON)

```json
{"Username":"GT.000000123456.USER_TEST","Password":"********"}
```

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `token` | string | JWT Bearer token. Tiene fecha de expiración. Al vencer la API responde 401 Unauthorized. |

#### Ejemplo de Respuesta

```http
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Notas

- ⚠️ El NIT debe complementarse con ceros a la izquierda hasta tener exactamente 12 caracteres. Ej: NIT 123456 → 000000123456.

---

### POST · Certificar DTE (CERTIFICATE_FE_XML_TOSIGN V2)

Certifica un Documento Tributario Electrónico ante la SAT. Acepta el NUC en formato XML o JSON — son DOS URLs distintos según el formato enviado. Devuelve el DTE certificado en base64 (XML/HTML/PDF).

**URL Test:** `https://testnucgt.digifact.com/api/v2/transform/nuc_json   (JSON · Content-Type: application/json) / https://testnucgt.digifact.com/api/v2/transform/nuc        (XML  · Content-Type: application/xml)`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/v2/transform/nuc_json   (JSON · Content-Type: application/json) / https://nucgt.digifact.com/gt.com.apinuc/api/v2/transform/nuc        (XML  · Content-Type: application/xml)`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Content-Type` | Sí | application/json para enviar JSON al endpoint /nuc_json · application/xml para enviar XML al endpoint /nuc. Enviar Content-Type que no coincida con la URL devuelve 415 Unsupported Media Type. |
| `Authorization` | Sí | Token JWT obtenido en GET TOKEN. |

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `TAXID` | string | Sí | NIT del emisor (12 dígitos con ceros). | `000000123456` |
| `FORMAT` | string | Sí | Formatos de respuesta separados por pipe. | `PDF|HTML|XML` |
| `USERNAME` | string | Sí | Usuario asignado (Test o Productivo). | `USER_TEST` |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `body (raw)` | XML|JSON | Sí | Documento NUC. El formato debe coincidir con la URL utilizada: JSON al endpoint /nuc_json, XML al endpoint /nuc. | — |

#### Body de ejemplo (JSON)

```json
{"Header":{"Issuer":{"TaxID":"000000123456"},"Receiver":{"TaxID":"CF","Name":"Consumidor Final"}},"Items":[{"Description":"Producto demo","Qty":1,"Price":100}]}
```

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `code` | string | Código de respuesta de la operación. |
| `message` | string | Mensaje informativo relacionado al código. |
| `authNumber` | string | Número de autorización del DTE (UUID). |
| `responseData1` | string | DTE en formato XML (base64). |
| `responseData2` | string | DTE en formato HTML (base64). |
| `responseData3` | string | DTE en formato PDF (base64). |
| `batch` | string | Número de serie del documento. |
| `serial` | string | Número correlativo del documento. |
| `enrolledTimeStamp` | string | Fecha y hora de certificación ante SAT. |
| `additionalInfo` | object | Información adicional: acuseReciboSAT y codigosSAT. |

#### Ejemplo de Respuesta

```http
{
  "code": "1",
  "message": "Procesado Correctamente",
  "authNumber": "BDE0DEC2-5ABE-468E-A6F1-0AB3637F2764",
  "batch": "A001",
  "serial": "1",
  "enrolledTimeStamp": "2026-02-05T10:30:05",
  "responseData1": "PD94bWwgdmVyc2lvbj0i...",
  "responseData2": "PCFET0NUWVBFIGh0bWw+...",
  "responseData3": "JVBERi0xLjQK..."
}
```

#### Notas

- ⚠️ El URL del endpoint cambia según el formato del body: usar /api/v2/transform/nuc_json para JSON o /api/v2/transform/nuc para XML. Enviar el Content-Type que no coincide con la URL devuelve 415 Unsupported Media Type.
- ℹ️ En productivo se requiere la firma electrónica del emisor (obtenida en la agencia virtual de SAT). En TEST no es necesaria.
- 🚫 La operación V1 (CERTIFICATE_FE_XML_TOSIGN V1) está OBSOLETA. Migrar a V2.

---

### POST · Anular DTE (CANCEL FEL)

Anula un Documento Tributario Electrónico previamente certificado ante la SAT.

**URL Test:** `https://testnucgt.digifact.com/api/CancelFelGT`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/CancelFelGT`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | Token JWT. |
| `Content-Type` | Sí | application/json |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `Taxid` | string | Sí | NIT del emisor. | `123456` |
| `Autorizacion` | string | Sí | UUID del DTE a anular. | `5B5BA194-22C5-4377-99D4-B8F86820533D` |
| `IdReceptor` | string | Sí | NIT del receptor. "CF" si es Consumidor Final. | `CF` |
| `FechaEmisionDocumentoAnular` | string | Sí | Fecha y hora de emisión del DTE. | `2022-10-04T10:25:09` |
| `MotivoAnulacion` | string | Sí | Motivo por el cual se anula. | `Error en datos del receptor` |
| `Username` | string | Sí | Usuario que realiza la anulación. | `USER_TEST` |

#### Body de ejemplo (JSON)

```json
{"Taxid":"123456","Autorizacion":"5B5BA194-22C5-4377-99D4-B8F86820533D","IdReceptor":"CF","FechaEmisionDocumentoAnular":"2022-10-04T10:25:09","MotivoAnulacion":"Error en datos","Username":"USER_TEST"}
```

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `Codigo` | string | Código de respuesta. |
| `Mensaje` | string | Descripción del resultado. |
| `Autorizacion` | string | UUID del DTE anulado. |
| `ResponseDATA1` | string | DTE de anulación en XML (base64). |
| `ResponseDATA2` | string | DTE de anulación en HTML (base64). |
| `ResponseDATA3` | string | DTE de anulación en PDF (base64). |

#### Ejemplo de Respuesta

```http
{
  "Codigo": "1",
  "Mensaje": "Anulación Exitosa",
  "Autorizacion": "5B5BA194-22C5-4377-99D4-B8F86820533D",
  "Serie": "A001",
  "Numero": "1"
}
```

---

### GET · Consultar DTE (SHARED_GETDTEINFO)

Obtiene información completa de un DTE certificado a partir de su número de autorización.

**URL Test:** `https://testnucgt.digifact.com/api/Shared`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/Shared`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | Token JWT. |

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `COUNTRY` | string | Sí | Código de país. | `GT` |
| `TAXID` | string | Sí | NIT del emisor. | `000044653948` |
| `DATA1` | string | Sí | Tipo de operación. | `SHARED_GETDTEINFO` |
| `DATA2` | string | Sí | Número de autorización. | `AUTHNUMBER|BDE0DEC2-5ABE-468E-A6F1-0AB3637F2764` |
| `USERNAME` | string | Sí | Usuario. | `USER_TEST` |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `TIPO_DTE` | string | Tipo de documento. |
| `GUID` | string | UUID del DTE. |
| `SERIE` | string | Número de serie. |
| `NUMERO` | string | Correlativo. |
| `FECHA_DE_EMISION` | string | Fecha de emisión. |
| `NIT_COMPRADOR` | string | NIT del receptor. |
| `TOTAL` | decimal | Total del DTE. |
| `DTE` | string | XML del DTE en base64. |

#### Ejemplo de Respuesta

```http
{
  "REQUEST_DATA": [{ "Codigo": "1", "Mensaje": "Procesado" }],
  "RESPONSE": [{
    "TIPO_DTE": "FACT",
    "GUID": "BDE0DEC2-5ABE-468E-A6F1-0AB3637F2764",
    "SERIE": "A001",
    "NUMERO": "5",
    "TOTAL": 100.00,
    "DTE": "PD94bWwgdmVyc2lvbj0i..."
  }]
}
```

---

### GET · Consultar NIT (GET INFONITcom)

Obtiene el nombre o razón social de un contribuyente a partir de su NIT.

**URL Test:** `https://testnucgt.digifact.com/api/Shared`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/Shared`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | Token JWT. |

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `COUNTRY` | string | Sí | Código de país. | `GT` |
| `TAXID` | string | Sí | NIT del usuario autenticado. | `000044653948` |
| `DATA1` | string | Sí | Tipo de operación. | `SHARED_GETINFONITcom` |
| `DATA2` | string | Sí | NIT a consultar. | `NIT|44653948` |
| `USERNAME` | string | Sí | Usuario. | `USER_TEST` |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `NIT` | string | NIT consultado. |
| `NOMBRE` | string | Razón social en SAT. |

#### Ejemplo de Respuesta

```http
{
  "RESPONSE": [{ "NIT": "44653948", "NOMBRE": "Empresa Ejemplo S.A." }]
}
```

---

### GET · Obtener Documento (GET DOCUMENT)

Descarga un DTE certificado en los formatos solicitados (XML, HTML, PDF, JSON).

**URL Test:** `https://testnucgt.digifact.com/api/GetDocument`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/GetDocument`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | Token JWT. |

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `AUTHNUMBER` | string | Sí | UUID del DTE. | `4D19A6D5-05B6-4D96-9EA4-7D75620B48CE` |
| `TAXID` | string | Sí | NIT del emisor. | `000000123456` |
| `FORMAT` | string | Sí | Formatos separados por pipe: XML, HTML, PDF, JSON. | `HTML|PDF` |
| `USERNAME` | string | Sí | Usuario. | `USER_TEST` |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `RESPONSE[0].ResponseData1` | string | XML en base64. |
| `RESPONSE[0].ResponseData2` | string | HTML en base64. |
| `RESPONSE[0].ResponseData3` | string | PDF en base64. |

#### Ejemplo de Respuesta

```http
{
  "RESPONSE": [{
    "ResponseData1": "",
    "ResponseData2": "PCFET0NUWVBFIGh0bWw+...",
    "ResponseData3": "JVBERi0xLjQK..."
  }]
}
```

#### Notas

- ℹ️ Si el documento no existe, RESPONSE retorna [].

---

### POST · Nota de Crédito Total (CERTIFICATE NCRED)

Genera una nota de crédito total a partir del número de autorización del documento referenciado. No requiere enviar el NUC completo.

**URL Test:** `https://testnucgt.digifact.com/api/cert/ncredtotal`
**URL Prod:** `https://nucgt.digifact.com/gt.com.apinuc/api/cert/ncredtotal`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | Token JWT. |
| `Content-Type` | Sí | application/json |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `Staxid` | string | Sí | NIT del emisor del documento referenciado. | `123456` |
| `Authnumber` | string | Sí | UUID del documento referenciado. | `5B5BA194-22C5-4377-99D4-B8F86820533D` |
| `FechaEmision` | string | Sí | Fecha de emisión de la NC. | `2025-08-21 13:24:00` |
| `MotivoAjuste` | string | Sí | Motivo del ajuste. | `Devolución total` |
| `Formatos` | string | Sí | Formatos de respuesta. | `xml|html|pdf` |
| `Username` | string | Sí | Usuario. | `USER_TEST` |
| `ReferenciaInterna` | string | No | Referencia interna. | `NC-001` |
| `NumeroAcceso` | string | No | Número de acceso para contingencia. | — |

#### Body de ejemplo (JSON)

```json
{"Staxid":"123456","Authnumber":"5B5BA194-22C5-4377-99D4-B8F86820533D","FechaEmision":"2025-08-21 13:24:00","MotivoAjuste":"Devolución total","Formatos":"xml|html|pdf","Username":"USER_TEST"}
```

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `—` | — | Mismo esquema de respuesta que Certificar DTE. |

#### Ejemplo de Respuesta

```http
// Idéntico a la respuesta de Certificar DTE
```

#### Notas

- ℹ️ NumeroAcceso es requerido únicamente en escenarios de contingencia.

---


---

# Documento NUC — Guatemala

> Norma de Uso del Comprobante V2.0.3. Formato unificado de Digifact que se transforma en el DTE oficial requerido por SAT bajo el régimen FEL.


> ℹ️ V2.0.3 es la versión vigente desde el 17/03/2026.

## Versión del documento

- **Versión:** V2.0.3 (VIGENTE)
- **Clave para `?v=`:** `v2-0-3`
- **En vigencia desde:** 17/03/2026
- **Es la versión por defecto:** sí
- **Ficha de la versión actualizada el:** 17/08/2026
- **URL de esta versión:** `/gt/nuc.md`

## Datos del país

- **Autoridad:** SAT
- **Esquema XML:** [NUCSchema.xsd](/schemas/gt/NUCSchema.xsd) (uno por país — no versionado)
- **Esquema JSON:** [NUCSchema.json](/schemas/gt/NUCSchema.json) (uno por país — no versionado)

## Tipos de documento

### Facturas

| Código | Nombre | Descripción |
|---|---|---|
| `FACT` | Factura | Documento estándar de venta gravada con IVA. |
| `FCAM` | Factura Cambiaria | Factura con efecto cambiario para crédito. |
| `FPEQ` | Factura Pequeño Contrib. | Para contribuyentes del régimen de Pequeño Contribuyente. |
| `FPEC` | Factura Pequeño C. Esp. | Régimen especial de pequeño contribuyente. |
| `FCPC` | Factura Contrib. Agro. | Régimen de contribuyente agropecuario. |
| `FESP` | Factura Especial | Cuando el receptor exige el documento al pequeño contribuyente. |
| `FEPE` | Factura Esp. Pesca | Régimen específico para sector pesca. |

### Notas

| Código | Nombre | Descripción |
|---|---|---|
| `NDEB` | Nota de Débito | Documento que aumenta el monto facturado al receptor. |
| `NCRE` | Nota de Crédito | Documento que disminuye el monto facturado al receptor. |
| `NABN` | Nota de Abono | Documento de abono sobre un saldo pendiente. |

### Recibos

| Código | Nombre | Descripción |
|---|---|---|
| `RECI` | Recibo | Comprobante de pago de servicios (no factura). |
| `RDON` | Recibo de Donación | Comprobante para registrar donaciones recibidas. |

### Especials

| Código | Nombre | Descripción |
|---|---|---|
| `FARP` | Factura Anu. Reten. PC | Anulación de retención sobre pequeño contribuyente. |
| `FCRP` | Factura Cobro Reten. PC | Cobro de retención sobre pequeño contribuyente. |

## Adendas y Complementos

| Código | Nombre | Categoría | Descripción |
|---|---|---|---|
| `ADENDA-EXP` | Adenda Exportación | adenda | Información adicional para operaciones de exportación. |
| `ADENDA-RETAIL` | Adenda Retail | adenda | Datos adicionales del sector retail. |
| `ADENDA-ARMAS` | Adenda Armas | adenda | Información obligatoria para venta de armas y municiones. |
| `ADENDA-CARGA` | Adenda Carga Aérea | adenda | Datos requeridos para transporte de carga aérea. |
| `ADENDA-DON-PP` | Adenda Donación PP | adenda | Información especial para donaciones a partidos políticos. |
| `COMP-CCA` | Complemento CCA | complemento | Complemento Cambiario obligatorio para FCAM. |
| `COMP-ESPEC` | Complemento Espectáculo | complemento | Datos requeridos para eventos y espectáculos. |
| `DET-ADIC-ITEM` | Detalle Adicional Item | complemento | Atributos extra a nivel de ítem (lote, vencimiento, etc.). |


---

# Documentación Técnica NUC-XML Guatemala V2.0.3

> Especificación oficial del formato NUC en XML. Misma estructura que la versión JSON — cambia solo la serialización.


> ℹ️ V2.0.3 es la versión vigente desde el 17/03/2026.

## Versión del documento

- **Versión:** V2.0.3 (VIGENTE)
- **Clave para `?v=`:** `v2-0-3`
- **En vigencia desde:** 17/03/2026
- **Es la versión por defecto:** sí
- **Ficha de la versión actualizada el:** 17/08/2026
- **URL de esta versión:** `/gt/nuc/xml.md`

## 1. Funcionamiento

Esta API transforma una cadena con un esquema definido (NUC) en formato XML a su factura electrónica correspondiente del país donde pertenezca.

**NUC:** archivo XML que contiene la información necesaria para generar el XML de la factura electrónica.

## 2. Arquitectura

**Endpoint:** `POST https://testnucgt.digifact.com/api/v2/transform/nuc`
**Content-Type:** `application/xml`

**Query Params:** `TAXID`, `FORMAT`, `USERNAME`

## 3. Convenciones

## Convenciones de las tablas

### Columnas de las tablas (Tabla 2)

| Título | Descripción |
|---|---|
| `C` | Conjunto de campos. |
| `ID` | Identificador del campo, para fines de referencia. |
| `Campo` | Nombre del campo. |
| `Descripción` | Descripción del campo y su significado. |
| `P` | Referencia al ID del campo del grupo que contiene este campo específico (padre). |
| `T` | Tipo de dato (ver tabla de tipos). |
| `Tam` | Tamaño del campo (ver tabla de tamaños). |
| `Ocu` | Ocurrencias en formato m-n. Si m=1 es obligatorio. Si m=0 es opcional. |
| `Observaciones` | Observaciones importantes sobre el elemento, incluyendo valores permitidos, validaciones, etc. |

### Tipos de dato en XML (Tabla 3)

| Tipo | Descripción |
|---|---|
| `XML` | Documento XML descrito en un schema (XSD) contenido en esta ficha técnica. |
| `G` | Grupo de elementos (equivale a objeto en JSON). |
| `A` | Alfanumérico. |
| `N` | Numérico. |
| `F` | Fecha: formato UTC AAAA-MM-DDThh:mm:ssTZH. |
| `I` | Información Adicional: elemento <Info Name="" Data="" Value="" />. |

### Formato de tamaños (Tabla 4)

| Formato | Descripción |
|---|---|
| `x` | Tamaño exacto del campo. Ejemplo: 5 |
| `x-y` | Tamaño mínimo de x, máximo de y. Ejemplo: 0-10 (admite vacío, hasta 10 chars). |
| `xpn` | Tamaño de x enteros, y con "n" casillas decimales. Ejemplo: 5p3 → 54321.103 |
| `xpn-m` | Tamaño de x enteros con mínimo n y máximo m decimales. Ejemplo: 11p0-6 |
| `x-ypn-m` | Mínimo x enteros, máximo y enteros, con mínimo n y máximo m decimales. Ej: 1-11p0-6 (parte decimal opcional). |

## 4. Formato del NUC

### 4.1 Conjuntos de campos (Tabla 5)

| Conjunto | Descripción |
|---|---|
| **R** | Campos que contienen información para la generación de la factura electrónica. |
| **A** | Campos que contienen información general de la Factura Electrónica. |
| **B** | Campos que contienen la información del emisor de la transacción documentada. |
| **C** | Campos que contienen la información del receptor de la transacción documentada. |
| **D** | Campos que describen cada ítem de la transacción documentada. |
| **E** | Campos que describen los subtotales y totales de la transacción documentada. |
| **F** | Campos que describen información adicional sobre la transacción documentada. |

> ⚠️ La API es **case-sensitive**. Respetar mayúsculas y minúsculas exactamente.

### 4.2.1 — Schema NUC (Conjunto R)

Campos raíz que identifican el documento NUC.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| R | `R01` | `NUC` | NUC (raíz). | — | G | `—` | `1-1` | Raíz del documento. En XML se representa como grupo (G); en JSON como documento JSON. |
| R | `R02` | `Version` | Versión del formato de la factura electrónica. | R01 | A | `1-pP2` | `1-1` | Control de versiones. Valor a ingresar: 1.00 |
| R | `R03` | `CountryCode` | Código del país donde pertenece la factura electrónica. | R01 | A | `2` | `1-1` | Valores: `GT`=Guatemala; `PA`=Panamá |

### 4.2.2 — Campos que contienen información general de la Factura Electrónica (Conjunto A)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| A | `A01` | `Header` | Información general de la factura electrónica. | R01 | G | `—` | `1-1` |  |
| A | `A02` | `DocType` | Tipo de DTE. | A01 | A | `4` | `1-1` | Valor obligatorio. Si no se ingresa uno de los valores permitidos, no se podrá generar la Factura Electrónica. CAIS está marcado como "no aceptado por el momento". — Valores: `FACT`=Factura; `FACM`=Factura Cambiaria; `FPEQ`=Factura Pequeño Contribuyente; `FCAP`=Factura Cambiaria Pequeño Contribuyente; `FESP`=Factura Especial … y 12 más de 17 — catálogo completo en `/gt/catalogos.md?key=doctype` |
| A | `A03` | `IssuedDateTime` | Fecha y hora de emisión del DTE (UTC). | A01 | F | `25` | `1-1` | Formato AAAA-MM-DDThh:mm:ssTZH. Ej: 2022-04-17T14:23:00-06:00 |
| A | `A04` | `Currency` | Moneda utilizada en la operación. | A01 | A | `3` | `1-1` | Código ISO 4217. Ej: GTQ, USD, EUR. Nota: el PDF lo lista como tipo "S" — es errata, debe tratarse como Alfanumérico (A). |
| A | `A05` | `AdditionalIssueDocInfo` | Información adicional general del documento. | A01 | G | `—` | `0-1` |  |
| A | `A051` | `Info` | Elementos clave/valor de información adicional. | A05 | I | `—` | `1-25` | Ver en sección "Grupo AdditionalIssueDocInfo". Agregar el nombre de la información en "Name" y el valor en "Value".  Ejemplo si el DTE es para exportación: { "Name": "Exp", "Data": null, "Value": "Si" } |

### 4.2.3 — Catálogo de atributos Info en AdditionalIssueDocInfo (Conjunto A)

Valores admitidos en el atributo "Name" de los elementos Info dentro de AdditionalIssueDocInfo (A051).

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| A | `AI01` | `Exp` | Exportación. | A051 | A | `2` | `0-1` | Indica si el DTE servirá para una exportación. Si el DTE no será para exportación, no es necesario agregar este elemento. Si se agrega, deberá agregarse el complemento de exportación (EXP).  Ejemplo: { "Name": "Exp", "Data": null, "Value": "Si" } |
| A | `AI02` | `Espectaculo` | Espectáculos públicos. | A051 | A | `2` | `0-1` | Indica si el DTE servirá para Manejo de Espectáculos Públicos. Si se agrega este elemento, deberá agregarse el complemento ESPECT.  Ejemplo: { "Name": "Espectaculo", "Data": null, "Value": "Si" } |
| A | `AI03` | `NumeroAcceso` | Número de acceso. | A051 | A | `9` | `0-1` | Número generado por el emisor en caso de contingencia, que va desde 100000000 hasta 999999999. |
| A | `AI04` | `TipoPersoneria` | Tipo de personería. | A051 | A | `3-4` | `0-1` | Indica el código o tipo de personería que está emitiendo. Requerido obligatoriamente para personerías que pueden emitir recibos de donación. |

### 4.3 — Campos que contienen información del Emisor (Conjunto B)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `B01` | `Seller` | Contenedor del emisor. | R01 | G | `—` | `1-1` |  |
| B | `B02` | `TaxID` | Identificador tributario o NIT del emisor. | B01 | A | `12` | `1-1` | NIT válido del emisor, sin guiones. |
| B | `B03` | `TaxIDAdditionalInfo` | Contenedor de info tributaria adicional del emisor. | B01 | G | `25` | `1-1` |  |
| B | `B031` | `Info` | Items clave/valor. | B03 | I | `—` | `1-25` |  |
| B | `B04` | `Name` | Razón social o Nombre de Persona Natural. | B01 | A | `2-100` | `1-1` |  |
| B | `B05` | `Contact` | Información de contacto. | B01 | G | `—` | `0-1` |  |
| B | `B051` | `EmailList` | Lista de emails (si Contact se incluye). | B05 | G | `—` | `1-1` |  |
| B | `B0511` | `Email` | Correo electrónico. | B051 | A | `50` | `1-1` | Correo válido del emisor. |
| B | `B06` | `AdditionlInfo` | Frases tributarias del emisor. | B01 | G | `—` | `0-1` | Nombre del elemento sin "a" (AdditionlInfo, sic). Usar literalmente — la API es case-sensitive. |
| B | `B061` | `Info` | Items que componen frases (agrupar por Data). | B06 | I | `—` | `1-30` |  |
| B | `B07` | `BranchInfo` | Establecimiento del emisor. | B01 | G | `—` | `1-1` |  |
| B | `B071` | `Code` | Código del establecimiento. | B07 | N | `1-9999` | `1-1` |  |
| B | `B072` | `AddressInfo` | Dirección del establecimiento. | B07 | G | `—` | `1-1` |  |
| B | `B0721` | `Address` | Dirección. | B072 | A | `100` | `1-1` |  |
| B | `B0722` | `City` | Código postal de la ubicación. | B072 | A | `50` | `1-1` | Debe corresponder a un código válido. |
| B | `B0723` | `District` | Municipio. | B072 | A | `50` | `1-1` |  |
| B | `B0724` | `State` | Departamento. | B072 | A | `50` | `1-1` |  |
| B | `B0725` | `Country` | País. | B072 | A | `50` | `1-1` | Valor: GT |

### 4.3.1 — Catálogo AfiliacionIVA (TaxIDAdditionalInfo del emisor) (Conjunto B)

Atributo "Name" obligatorio en B031 que indica el régimen de IVA del emisor.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `BI01` | `AfiliacionIVA` | Régimen de IVA del emisor. | B031 | A | `3` | `1-1` | Valores: `GEN`=General; `PEQ`=Pequeño Contribuyente; `PEE`=Pequeño Contribuyente Electrónico Agropecuario; `EXE`=Exento / No aplica; `PRI`=Contribuyente Régimen Primario; `PEC`=Contribuyente Régimen Pecuario |
| B | `BI02` | `ClasificacionEmisor` | Clasificación adicional del emisor. | B031 | N | `4` | `0-1` | Valores: `1674`=Intermediario bovino |

### 4.3.2 — Frases tributarias (AdditionlInfo del emisor) (Conjunto B)

Cada frase se forma agrupando varios Info por el atributo Data (entero positivo identificador). El catálogo completo de TipoFrase/CodigoEscenario está en el documento Reglas-y-Validaciones-FEL.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `BI02` | `TipoFrase` | Tipo de frase. | B061 | N | `1-9` | `1-1` | Identifica un determinado catálogo de leyendas. |
| B | `BI03` | `CodigoEscenario` | Código de escenario. | B061 | N | `1-99` | `1-1` | Indica un determinado Escenario dentro del catálogo de leyendas. |
| B | `BI04` | `NumeroResolucion` | Número de resolución. | B061 | A | `4-50` | `0-1` | Número de resolución relacionada a la frase. Uso opcional de acuerdo a reglas y validaciones. |
| B | `BI05` | `FechaResolucion` | Fecha de resolución. | B061 | A | `10` | `0-1` | Fecha de resolución relacionada a la frase. Uso opcional de acuerdo a reglas y validaciones. En formato YYYY-MM-DD. |

### 4.4 — Campos que contienen información del Receptor (Conjunto C)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| C | `C01` | `Buyer` | Contenedor del receptor. | R01 | G | `—` | `1-1` |  |
| C | `C02` | `TaxID` | Identificador tributario, CUI o NIT del receptor. | C01 | A | `1-13` | `1-1` | En caso de agregar el CUI, informar en el elemento C03 (TaxIDType="CUI"). Si es Consumidor Final, agregar "CF". |
| C | `C03` | `TaxIDType` | Tipo especial de identificación. | C01 | A | `3` | `0-1` | Agregar este elemento cuando se desee informar el CUI del receptor, ingresando la palabra "CUI". Indica que el elemento C02 no incluye un NIT, sino un CUI. |
| C | `C07` | `TaxIDAdditionalInfo` | Info tributaria adicional del receptor. | C01 | G | `5` | `0-1` |  |
| C | `C071` | `Info` | Items clave/valor. | C07 | I | `—` | `1-5` |  |
| C | `C04` | `Name` | Razón social o Nombre y Apellido del receptor. | C01 | A | `2-100` | `1-1` | Si el elemento C02 contiene un NIT válido, el nombre indicado debe corresponder a los registros tributarios. Caso contrario el contenido puede ser cualquiera que solicite el RECEPTOR. |
| C | `C05` | `Contact` | Contacto del receptor. | C01 | G | `—` | `0-1` |  |
| C | `C052` | `PhoneList` | Lista de teléfonos. | C05 | G | `—` | `0-1` |  |
| C | `C0521` | `Phone` | Teléfono válido. | C052 | A | `8-15` | `1-1` |  |
| C | `C051` | `EmailList` | Lista de emails. | C05 | G | `—` | `1-1` |  |
| C | `C0511` | `Email` | Email válido. | C051 | A | `50` | `1-1` |  |
| C | `C06` | `AddressInfo` | Dirección del receptor. | C01 | G | `—` | `0-1` |  |
| C | `C061` | `Address` | Dirección. | C06 | A | `100` | `1-1` |  |
| C | `C062` | `City` | Código postal de la ubicación. | C06 | A | `50` | `1-1` | Debe corresponder a un código válido. |
| C | `C063` | `District` | Municipio. | C06 | A | `50` | `1-1` |  |
| C | `C064` | `State` | Departamento. | C06 | A | `50` | `1-1` |  |
| C | `C065` | `Country` | País. | C06 | A | `50` | `1-1` |  |

### 4.4.1 — Catálogo DestinodelaVenta (TaxIDAdditionalInfo del receptor) (Conjunto C)

Atributo "Name" en C071 que indica el destino comercial de la venta.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| C | `CI01` | `DestinodelaVenta` | Destino comercial de la venta. | C071 | A | `—` | `0-1` | Valores: `Supermercado`=Supermercado; `Mercado cantonal`=Mercado cantonal; `Mercado municipal`=Mercado municipal; `Centro de acopio`=Centro de acopio; `Exportación`=Exportación; `Exportación en pie`=Exportación en pie; `Intermediación de productos bovinos`=Intermediación de productos bovinos; `Restaurante`=Restaurante; `Organización de Padres de Familia`=Organización de Padres de Familia |

### 4.5 — Campos que describen los Ítems (Conjunto D)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| D | `D01` | `Items` | Lista de ítems. | R01 | G | `—` | `1-1` |  |
| D | `D02` | `Item` | Cada ítem de la transacción. | D01 | G | `—` | `1-1000` |  |
| D | `D03` | `Codes` | Códigos asociados al ítem. | D02 | G | `—` | `0-1` |  |
| D | `D031` | `Code` | Items de código. | D03 | I | `—` | `1-2` |  |
| D | `D04` | `Type` | Tipo o clasificación del ítem. | D02 | A | `1-8` | `1-1` | Indica si el ítem es un bien o servicio. Los valores aceptados son: - B o BIEN: para indicar que es un Bien - S o SERVICIO: para indicar que es un Servicio — Valores: `B`=Bien (sinónimo: BIEN); `BIEN`=Bien; `S`=Servicio (sinónimo: SERVICIO); `SERVICIO`=Servicio |
| D | `D05` | `Description` | Descripción del producto o servicio. | D02 | A | `2-500` | `1-1` |  |
| D | `D06` | `Qty` | Cantidad de unidades del producto o servicio. | D02 | N | `1-11p2-6` | `1-1` |  |
| D | `D07` | `UnitOfMeasure` | Unidad de medida. | D02 | A | `1-20` | `0-1` | Indica la unidad de medida en que está expresado el elemento D05 (Description). |
| D | `D08` | `Price` | Precio unitario. | D02 | N | `1-9p2-6` | `1-1` | Precio de cada unidad del ítem en la moneda en que se emite el DTE (quetzales, dólares, euros, etc.). |
| D | `D09` | `Discounts` | Información relacionada a descuentos del ítem. | D02 | G | `—` | `0-1` | Descuento para aplicar sobre el total del ítem. |
| D | `D091` | `Discount` | Descuento aplicado. | D09 | G | `—` | `1-1` |  |
| D | `D0911` | `Amount` | Monto de descuento. | D091 | N | `1-9p2-6` | `1-1` |  |
| D | `D10` | `Taxes` | Contenedor de impuestos. | D02 | G | `—` | `1-1` |  |
| D | `D101` | `Tax` | Lista de impuestos aplicados. | D10 | G | `—` | `1-15` |  |
| D | `D1011` | `Code` | Código de unidad gravable. | D101 | N | `1-13` | `1-1` |  |
| D | `D1012` | `Description` | Nombre corto del impuesto. | D101 | A | `3-20` | `1-1` | Valores: `IVA`=Impuesto al Valor Agregado; `BEBIDAS ALCOHOLICAS`=Bebidas alcohólicas; `BEBIDAS NO ALCOHOLICAS`=Bebidas no alcohólicas; `PETROLEO`=Distribución de petróleo; `TURISMO HOSPEDAJE`=Turismo — hospedaje; `TURISMO PASAJES`=Turismo — pasajes; `TIMBRE DE PRENSA`=Timbre de prensa; `BOMBEROS`=Timbre bomberos; `TASA MUNICIPAL`=Tasa municipal; `TABACO`=Tabaco; `CEMENTO`=Cemento; `TARIFA PORTUARIA`=Tarifa portuaria |
| D | `D1013` | `TaxableAmount` | Monto gravable. | D101 | N | `1-11p2-6` | `0-1` | Monto sobre el cual se aplica el impuesto. |
| D | `D1014` | `ChargableAmount` | Cantidad de unidades gravables. | D101 | N | `1-11p2-6` | `0-1` |  |
| D | `D1015` | `Rate` | Tasa aplicable. | D101 | N | `1-11p2-6` | `0-1` | Para tasas municipales. |
| D | `D1016` | `Amount` | Monto del impuesto. | D101 | N | `1-9p2-6` | `1-1` |  |
| D | `D11` | `Totals` | Totales del ítem. | D02 | G | `—` | `1-1` |  |
| D | `D112` | `TotalItem` | Precio total del ítem. | D11 | N | `1-11p2-6` | `1-1` | Es el resultado de: (Precio Unitario × Cantidad) − Descuento + (la sumatoria de las casillas "Amount" de los impuestos que sean sumables al DTE). |

### 4.5.1 — Catálogo CodigoProducto (Codes del ítem) (Conjunto D)

Catálogo decretos 15-2021 y 20-2022 — usado en el atributo "Name" de los Info dentro de Codes (D031).

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| D | `DI01` | `CodigoProducto` | Código de producto regulado. | D031 | A | `1-20` | `1-1` | Valores: `CGP10LBS`=Cilindro Gas Propano 10 lbs; `CGP20LBS`=Cilindro Gas Propano 20 lbs; `CGP25LBS`=Cilindro Gas Propano 25 lbs; `CGP35LBS`=Cilindro Gas Propano 35 lbs; `GALDIESEL`=Galón Diesel; `GALREGULAR`=Galón Gasolina Regular; `GALSUPER`=Galón Gasolina Súper |

### 4.6 — Campos que describen los Totales (Conjunto E)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| E | `E01` | `Totals` | Contenedor de totales. | R01 | G | `—` | `1-1` |  |
| E | `E02` | `TotalTaxes` | Impuestos totalizados. | E01 | G | `—` | `0-1` |  |
| E | `E021` | `TotalTax` | Cada impuesto totalizado. | E02 | G | `—` | `1-20` |  |
| E | `E0211` | `Description` | Nombre corto del impuesto. | E021 | A | `6-7` | `1-1` | Valores a ingresar: - FACTURA: si se desea agregar un cargo por acarreo, indicar este nombre en la descripción. - SEGURO: si se desea agregar el precio por seguro cobrado en el precio total. |
| E | `E0212` | `Amount` | Total monto impuesto. | E021 | N | `1-11p2` | `1-1` | Sumatoria del monto de cada uno de los ítems con el mismo impuesto. Ejemplo: Si el elemento impuesto es IVA, este atributo deberá contener la sumatoria de los montos de IVA incluidos en todos los ítems del documento. |
| E | `E03` | `GrandTotal` | Total final del documento. | E01 | G | `—` | `1-1` |  |
| E | `E031` | `InvoiceTotal` | Precio total de la factura. | E03 | N | `1-11p2` | `1-1` | Sumatoria de los elementos D112 (TotalItem) de cada uno de los ítems. |

### 4.7 — Campos de Información Adicional del documento (Complementos y Adenda) (Conjunto F)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `F01` | `AdditionalDocumentInfo` | Contenedor de complementos y adenda. | R01 | G | `—` | `1-1` | OBLIGATORIO SIEMPRE. Confirmado en pruebas reales: la API rechaza el NUC sin esta sección con "Error al transformar, No se encuentra el elemento AdditionalDocumentInfo". Si no hay complementos ni adenda real del cliente, incluir un AdditionalInfo mínimo con Type=ADENDA y Code=<GUID generado de 36 chars>. Esta regla NO está en el PDF V2.0.3 pero es exigida por la API. |
| F | `F02` | `AdditionalInfo` | Grupo que contiene información adicional. | F01 | G | `—` | `0-20` | Elemento que contiene información sobre Complementos y la Adenda.  Si se desea agregar información sobre un Complemento, únicamente se agregarán los datos necesarios para ese complemento. Y si se desea agregar información sobre la Adenda, es necesario crear otro elemento AdditionalInfo y únicamente se deben agregar los datos necesarios para la Adenda.  Se debe agregar un elemento AdditionalInfo para cada Complemento, y la Adenda debe estar solo una vez. |
| F | `F03` | `Code` | Código de clasificación. | F02 | A | `1-100` | `1-1` | Para Complementos: indicar el código del complemento que se agregará (EXP, FCAMB, FESP, NDEB, NCRE, CCA, ESPECT, REFCONST, FEPE). Para Adenda: ingresar la referencia interna como GUID válido (36 chars, formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Datatype TREFERENCIAINTERNA en el schema XML tiene MinLength=36, así que strings cortos como "1" o "ref" fallan validación. — Valores: `EXP`=Exportaciones (Requerido cuando AdditionalInfo.Exp=Si.); `FCAMB`=Factura Cambiaria (Para FACM, FCAP, FCRP, FCPC.); `FESP`=Factura Especial (Para FESP (retenciones ISR/IVA).); `NDEB`=Nota de Débito (Para NDEB.); `NCRE`=Nota de Crédito (Para NCRE.); `CCA`=Cobro por Cuenta Ajena; `ESPECT`=Espectáculos Públicos (Requerido cuando AdditionalInfo.Espectaculo=Si.); `REFCONST`=Referencias de Constancia (Para CIVA y similares.); `FEPE`=Factura Específica (Para FEPE (retención ICT).) |
| F | `F04` | `Type` | Tipo de información a agregar. | F02 | A | `6-12` | `1-1` | Tipo de información, puede ser: - ADENDA - COMPLEMENTO — Valores: `ADENDA`=Adenda — datos NO fiscales; `COMPLEMENTO`=Complemento — datos fiscales obligatorios según operación |
| F | `F05` | `AditionalData` | Grupo que contiene datos adicionales. | F02 | G | `—` | `0-1` | Nombre con typo "Aditional" (sic). Usar literalmente.  Para Complemento: ver sección "Información Adicional Data Complementos" (4.7.1). Para Adenda: ver sección "Información Adicional Data Adenda" (4.7.3). |
| F | `F051` | `Data` | Elemento que contiene datos adicionales. | F05 | G | `—` | `1-50` | Este elemento contiene dos atributos, Name e Id, que serán únicamente utilizados al momento de agregar información sobre la Adenda.  Los valores que puede tomar el atributo Name son: - INFORMACION_AGENCIA_DE_VIAJES: información sobre viajes - INFORMACIÓN_ADICIONAL: información adicional libre - DetallesAux_Detalle: detalles auxiliares por ítem |
| F | `F0511` | `Info` | Items clave/valor. | F051 | I | `—` | `1-25` |  |
| F | `F06` | `AditionalInfo` | Grupo que contiene información adicional. | F02 | G | `—` | `0-1` | Nombre con typo "Aditional" (sic). Usar literalmente.  Para Complemento: ver sección "Información Adicional Info Complementos" (4.7.2). Para Adenda: ver sección "Información Adicional Info Adenda" (4.7.4). |
| F | `F061` | `Info` | Items clave/valor. | F06 | I | `—` | `1-25` |  |

### 4.7.1 — Grupo Información Adicional Data Complementos (Conjunto F)

Campos que viajan dentro de F05 AditionalData. Cada fila aplica al complemento indicado en la observación "Válido para X".

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FI01` | `NumeroAbono` | Número de abono. | F0511 | N | `3` | `1-1` | Válido para FCAMB |
| F | `FI02` | `FechaVencimiento` | Fecha de vencimiento. | F0511 | A | `10` | `1-1` | Válido para FCAMB. En formato YYYY-MM-DD. |
| F | `FI03` | `MontoAbono` | Monto de abono. | F0511 | N | `1-9p2-6` | `1-1` | Válido para FCAMB |
| F | `FI04` | `NITtercero` | NIT del tercero. | F0511 | A | `12` | `0-1` | Válido para CCA. El NIT del contribuyente para quien se está realizando el cobro (sin guión). |
| F | `FI05` | `NumeroDocumento` | Número de documento. | F0511 | A | `22` | `0-1` | Válido para CCA. El número del documento relacionado con la transacción. |
| F | `FI06` | `FechaDocumento` | Fecha del documento. | F0511 | A | `10` | `0-1` | Válido para CCA. La fecha del documento relacionado con la transacción. En formato YYYY-MM-DD. |
| F | `FI07` | `Descripcion` | Descripción. | F0511 | A | `1-50` | `1-1` | Válido para CCA. Indica la descripción del ítem. |
| F | `FI08` | `BaseImponible` | Base imponible. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El monto sobre el cual se cobró el concepto de IVA. Si no aplica consignar cero (0.00). |
| F | `FI09` | `MontoCobroDAI` | Monto cobro DAI. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El monto cobrado por concepto de Derechos Arancelarios a la Importación. Si no aplica consignar cero (0.00). |
| F | `FI10` | `MontoCobroIVA` | Monto cobro IVA. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El Monto cobrado por concepto de Impuesto al Valor Agregado sobre el valor de Base Imponible. Si no aplica consignar cero (0.00). |
| F | `FI11` | `MontoCobroOtros` | Monto cobro otros. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El Monto cobrado por cualquier otro concepto, si no aplica consignar cero (0.00). |
| F | `FI12` | `MontoCobroTotal` | Monto total. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El valor de la suma de las casillas: MontoCobroDAI, MontoCobroIVA, MontoCobroOtros. |

### 4.7.2 — Grupo Información Adicional Info Complementos (Conjunto F)

Campos que viajan dentro de F06 AditionalInfo. Cada fila aplica al complemento indicado en la observación "Válido para X".

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FI13` | `NombreConsignatarioODestinatario` | Nombre del consignatario o destinatario. | F061 | A | `1-50` | `1-1` | Válido para EXP |
| F | `FI14` | `DireccionConsignatarioODestinatario` | Dirección del consignatario o destinatario. | F061 | A | `1-50` | `1-1` | Válido para EXP |
| F | `FI15` | `INCOTERM` | INCOTERM. | F061 | A | `5-50` | `1-1` | Válido para EXP. Agregar un INCOTERM válido. |
| F | `FI16` | `RetencionISR` | Retención ISR. | F061 | N | `1-9p2-6` | `1-1` | Válido para FESP |
| F | `FI17` | `RetencionIVA` | Retención del IVA. | F061 | N | `1-9p2-6` | `0-1` | Válido para FESP |
| F | `FI18` | `TotalMenosRetenciones` | Monto del total menos las retenciones. | F061 | N | `1-9p2-6` | `1-1` | Válido para FESP |
| F | `FI19` | `RegimenAntiguo` | Régimen antiguo. | F061 | A | `1-12` | `0-1` | Válido para NDEB y NCRE. Debe incluirse solamente cuando el documento original corresponde al régimen de papel o FACE1. |
| F | `FI20` | `NumeroAutorizacionDocumentoOrigen` | Número de autorización. | F061 | A | `1-50` | `1-1` | Válido para NDEB y NCRE. Indica el número de Autorización del régimen FEL cuando el atributo RegimenAntiguo no se coloca en el complemento, de lo contrario se utiliza para indicar el Número de Resolución de Autorización del régimen de papel o FACE1. |
| F | `FI21` | `FechaEmisionDocumentoOrigen` | Fecha de emisión del documento de origen. | F061 | A | `10` | `1-1` | Válido para NDEB y NCRE. En formato YYYY-MM-DD. |
| F | `FI22` | `MotivoAjuste` | Motivo de ajuste. | F061 | A | `1-50` | `0-1` | Válido para NDEB y NCRE. Descripción de la causa por la cual se realiza el Ajuste. |
| F | `FI23` | `SerieDocumentoOrigen` | Número de serie. | F061 | A | `1-20` | `1-1` | Válido para NDEB y NCRE. Número de serie correspondiente al régimen de papel o FACE1. |
| F | `FI24` | `NumeroDocumentoOrigen` | Número de documento. | F061 | A | `1-20` | `1-1` | Válido para NDEB y NCRE. Número de documento correspondiente al régimen de papel o FACE1. |
| F | `FI25` | `CodigoEvento` | Código del evento. | F061 | A | `1-50` | `1-1` | Válido para ESPECT. Código asignado al evento. |
| F | `FI26` | `NombreEvento` | Nombre del evento. | F061 | A | `1-50` | `1-1` | Válido para ESPECT. Nombre con el que se identifica el evento. |
| F | `FI27` | `NombreLocalidad` | Nombre de la localidad. | F061 | A | `1-50` | `1-1` | Válido para ESPECT. Lugar donde se realiza el evento. |
| F | `FI28` | `PrecioAdmision` | Precio de admisión. | F061 | N | `—` | `1-1` | Válido para ESPECT. Precio del boleto de admisión. |
| F | `FI29` | `NumeroBoleto` | Número de boleto. | F061 | N | `6` | `1-1` | Válido para ESPECT. Número correlativo del boleto vendido. |
| F | `FI30` | `RegimenAntiguo` | Régimen antiguo. | F061 | A | `5-20` | `0-1` | Válido para REFCONST. Indica si la constancia se aplica a un DTE del Régimen FEL (no se incluye la casilla) o bien a uno antiguo (facturas de papel). Para los antiguos se incluye la casilla con el valor "Antiguo". |
| F | `FI31` | `NumeroAutorizacionDocumentoOrigen` | Número de autorización. | F061 | A | `1-50` | `1-1` | Válido para REFCONST. Describe el número de autorización del documento original al que se le aplica la constancia que se está emitiendo. |
| F | `FI32` | `FechaEmisionDocumentoOrigen` | Fecha de emisión. | F061 | A | `10` | `1-1` | Válido para REFCONST. Fecha de emisión del documento al cual se le está aplicando la constancia. En formato YYYY-MM-DD. |
| F | `FI33` | `SerieDocumentoOrigen` | Serie documento de origen. | F061 | A | `5-20` | `0-1` | Válido para REFCONST. Serie del documento al cual se le emite la constancia, cuando corresponde a un documento antiguo. *Se incluye la casilla, sólo si se hace referencia a un documento del Régimen Antiguo. |
| F | `FI34` | `NumeroDocumentoOrigen` | Número de documento de origen. | F061 | A | `5-20` | `0-1` | Válido para REFCONST. Número del documento al cual se le emite la constancia, cuando corresponde a un documento antiguo. *Se incluye la casilla, sólo si se hace referencia a un documento del Régimen Antiguo. |
| F | `FI35` | `MontoIVAExento` | Monto total del IVA. | F061 | N | `1-9p2-6` | `0-1` | Válido para REFCONST. El monto total del IVA que ampara el documento, cuando el complemento corresponde a una Constancia de Exención del IVA (CIVA). Dicho monto debe ser igual al total de IVA del DTE al que se hace referencia. |
| F | `FI36` | `RetencionICT` | Monto de retención ICT. | F061 | N | `1-9p2-6` | `0-1` | Válido para FEPE |
| F | `FI37` | `TotalMenosRetenciones` | Total menos retenciones. | F061 | N | `1-9p2-6` | `0-1` | Válido para FEPE |

### 4.7.3 — Grupo Información Adicional Data Adenda (Conjunto F)

Campos que viajan dentro de F05 AditionalData de la Adenda. El atributo "Name" indica a qué subgrupo pertenece (INFORMACION_AGENCIA_DE_VIAJES, INFORMACIÓN_ADICIONAL, DetallesAux_Detalle).

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FA01` | `**Cualquier nombre**` | Información sobre agencia de viajes. | F0511 | A | `1-50` | `0-1` | Válido para INFORMACION_AGENCIA_DE_VIAJES |
| F | `FA02` | `**Cualquier nombre**` | Información adicional. | F0511 | A | `1-50` | `0-1` | Válido para INFORMACION_ADICIONAL |
| F | `FA03` | `NumeroLinea` | Número de línea donde se encuentra el ítem referenciado. | F0511 | N | `3` | `0-1` | Válido para DetallesAux_Detalle |
| F | `FA04` | `Descripcion_Adicional` | Descripción adicional del ítem. | F0511 | A | `1-50` | `0-1` | Válido para DetallesAux_Detalle. Si se desea agregar una descripción adicional al ítem que se hace referencia. |
| F | `FA05` | `CodigoEAN` | Código del ítem. | F0511 | A | `1-20` | `0-1` | Válido para DetallesAux_Detalle. Si se desea el código del ítem. |
| F | `FA06` | `CategoriaAdicional` | Categoría adicional. | F0511 | A | `1-50` | `0-1` | Válido para DetallesAux_Detalle |
| F | `FA07` | `Textos` | Textos adicionales. | F0511 | A | `1-50` | `0-20` | Válido para DetallesAux_Detalle |

### 4.7.4 — Grupo Información Adicional Info Adenda (Conjunto F)

Campos que viajan dentro de F06 AditionalInfo de la Adenda — datos no fiscales requeridos por el cliente.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FA08` | `VALIDAR_REFERENCIA_INTERNA` | Validación de referencia interna. | F061 | A | `1-10` | `1-1` | Indicar si se desea validar la referencia interna de la Adenda. Valores permitidos: VALIDAR NO_VALIDAR |
| F | `FA09` | `CAJERO` | Nombre o información del cajero. | F061 | A | `1-50` | `0-1` |  |
| F | `FA10` | `VENDEDOR` | Nombre o información del vendedor. | F061 | A | `5-50` | `0-1` |  |
| F | `FA11` | `Subtotal` | Subtotal de la factura. | F061 | N | `1-9p2-6` | `0-1` |  |
| F | `FA12` | `Fuente` | Fuente. | F061 | A | `1-60` | `0-1` |  |
| F | `FA13` | `Tipo` | Indica un tipo al ingresar un RECIBO. | F061 | A | `1-20` | `1-1` | Valores permitidos: Universidad Colegio Inmobiliaria |
| F | `FA14` | `NombreAlumno` | Nombre del alumno. | F061 | A | `1-12` | `0-1` |  |
| F | `FA15` | `Carne` | Carné / número del estudiante. | F061 | A | `1-50` | `0-1` |  |
| F | `FA16` | `UnidadAcademica` | Unidad académica. | F061 | A | `1-50` | `0-1` |  |
| F | `FA17` | `Grado` | Grado. | F061 | A | `1-50` | `0-1` |  |
| F | `FA18` | `Seccion` | Sección. | F061 | A | `1-50` | `0-1` |  |
| F | `FA19` | `Jornada` | Tipo de jornada. | F061 | A | `1-50` | `0-1` |  |
| F | `FA20` | `TipoDePago` | Tipo de pago. | F061 | A | `1-50` | `0-1` |  |
| F | `FA21` | `NoReferencia` | Número de referencia. | F061 | A | `1-50` | `0-1` |  |
| F | `FA22` | `Banco` | Banco. | F061 | A | `1-50` | `0-1` |  |
| F | `FA23` | `Total` | Total. | F061 | A | `1-50` | `0-1` |  |
| F | `FA24` | `Observaciones` | Observaciones. | F061 | A | `1-70` | `0-1` |  |
| F | `FA25` | `MZ` | Manzana. | F061 | A | `1-50` | `0-1` |  |
| F | `FA26` | `APTO` | Apartamento. | F061 | A | `1-50` | `0-1` |  |
| F | `FA27` | `TipoPago` | Tipo de pago. | F061 | A | `1-50` | `0-1` |  |


## Respuesta de la API

### Ejemplo de Respuesta

```json
{
    "code": 0,
    "message": "",
    "description": "",
    "responseData1": "",
    "responseData2": "",
    "responseData3": "",
    "authNumber": "",
    "url": "",
    "infoDetails": [],
    "suggestedFileName": "",
    "suggestedFileName2": "",
    "batch": "",
    "serial": "",
    "issuedTimeStamp": "",
    "taxID": "",
    "name": "",
    "branchCode": "",
    "branchName": "",
    "receiverTaxID": "",
    "receiverName": "",
    "discounts": "",
    "taxes": "",
    "subTotal": "",
    "totalAmount": "",
    "enrolledTimeStamp": "",
    "backprocessor": "",
    "additionalInfo": {
        "anyAttribute": ""
    }
}
```

### Donde

| Atributo | Descripción |
|---|---|
| `code` | Muestra el código de la respuesta obtenida. Ver detalle en "Códigos dentro de la Respuesta". |
| `message` | Mensaje informativo relacionado a la respuesta. |
| `description` | Descripción adicional del mensaje. |
| `responseData1` | Texto codificado en base64 que contiene la factura en formato XML. |
| `responseData2` | Texto codificado en base64 que contiene la factura en formato HTML. |
| `responseData3` | Texto codificado en base64 que contiene la factura en formato PDF. |
| `authNumber` | Número de autorización de la factura electrónica (UUID). |
| `url` | Atributo sin valor por el momento. |
| `infoDetails` | Detalles adicionales. Atributo sin valor por el momento. |
| `suggestedFileName` | Nombre de archivo sugerido. Atributo sin valor por el momento. |
| `suggestedFileName2` | Nombre de archivo sugerido (alterno). Atributo sin valor por el momento. |
| `batch` | Número de serie de la factura. |
| `serial` | Número secuencial o correlativo de la factura. |
| `issuedTimeStamp` | Fecha de emisión de la factura electrónica. |
| `taxID` | NIT del contribuyente emisor de la factura. |
| `name` | Nombre o razón social del emisor. |
| `branchCode` | Código de sucursal emisora. Atributo sin valor por el momento. |
| `branchName` | Nombre comercial. Atributo sin valor por el momento. |
| `receiverTaxID` | NIT del receptor / comprador. |
| `receiverName` | Nombre o razón social del receptor. |
| `discounts` | Descuentos aplicados sobre el total de la factura. Atributo sin valor por el momento. |
| `taxes` | Impuestos aplicados. Atributo sin valor por el momento. |
| `subTotal` | Subtotal de la factura. Atributo sin valor por el momento. |
| `totalAmount` | Monto total de la factura. Atributo sin valor por el momento. |
| `enrolledTimeStamp` | Fecha y hora de certificación de la factura. |
| `backprocessor` | Servidor que realiza la consulta. |
| `additionalInfo` | Atributo tipo objeto con información adicional. Puede contener acuseReciboSAT (acuse de recibido SAT) y codigosSAT (códigos devueltos por SAT). |

### 5.1 Códigos de respuesta (Tabla 8)

| Código | Descripción |
|---|---|
| `1` | Consulta realizada correctamente. Documento certificado. |
| `401` | Unauthorized. Verificar token de autorización. |
| `500` | Internal Server Error. |
| `Otro` | Error en contenido del XML, verificar datos. |

### 5.2 Códigos HTTP (Tabla 9)

| Código | Descripción |
|---|---|
| `200` | Ok |
| `400` | Bad Request |
| `406` | Not Acceptable. Verificar contenido del XML NUC. |
| `401` | Unauthorized. Verificar token de autorización. |
| `500` | Internal Server Error. |


---

# Documentación Técnica NUC-JSON Guatemala V2.0.3

> Especificación oficial del formato NUC en JSON. Misma estructura que la versión XML — cambia solo la serialización.


> ℹ️ V2.0.3 es la versión vigente desde el 17/03/2026.

## Versión del documento

- **Versión:** V2.0.3 (VIGENTE)
- **Clave para `?v=`:** `v2-0-3`
- **En vigencia desde:** 17/03/2026
- **Es la versión por defecto:** sí
- **Ficha de la versión actualizada el:** 17/08/2026
- **URL de esta versión:** `/gt/nuc/json.md`

## 1. Funcionamiento

Esta API transforma una cadena con un esquema definido (NUC) en formato JSON a su factura electrónica correspondiente del país donde pertenezca.

**NUC:** archivo JSON que contiene la información necesaria para generar el XML de la factura electrónica.

## 2. Arquitectura

**Endpoint:** `POST https://testnucgt.digifact.com/api/v2/transform/nuc_json`
**Content-Type:** `application/json`

**Query Params:** `TAXID`, `FORMAT`, `USERNAME`

## 3. Convenciones

## Convenciones de las tablas

### Columnas de las tablas (Tabla 2)

| Título | Descripción |
|---|---|
| `C` | Conjunto de campos. |
| `ID` | Identificador del campo, para fines de referencia. |
| `Campo` | Nombre del campo. |
| `Descripción` | Descripción del campo y su significado. |
| `P` | Referencia al ID del campo del grupo que contiene este campo específico (padre). |
| `T` | Tipo de dato (ver tabla de tipos). |
| `Tam` | Tamaño del campo (ver tabla de tamaños). |
| `Ocu` | Ocurrencias en formato m-n. Si m=1 es obligatorio. Si m=0 es opcional. |
| `Observaciones` | Observaciones importantes sobre el elemento, incluyendo valores permitidos, validaciones, etc. |

### Tipos de dato en JSON (Tabla 3)

| Tipo | Descripción |
|---|---|
| `JSON` | Documento JSON, descrito en un schema contenido en esta ficha técnica. |
| `O` | Objeto JSON y/o grupos de elementos. |
| `A` | Alfanumérico. |
| `N` | Numérico (ver formatos en la tabla de tamaños). |
| `F` | Fecha: formato UTC AAAA-MM-DDThh:mm:ssTZH. Ej: 2022-04-17T14:23:00-06:00 |
| `L` | Arreglo o Lista: atributo de tipo arreglo que puede contener "n" objetos o datos. |
| `I` | Información Adicional: objeto con atributos Name / Data / Value para describir información extra. Ejemplo: { "Name": "AfiliacionIVA", "Data": null, "Value": "GEN" } |

### Formato de tamaños (Tabla 4)

| Formato | Descripción |
|---|---|
| `x` | Tamaño exacto del campo. Ejemplo: 5 |
| `x-y` | Tamaño mínimo de x, máximo de y. Ejemplo: 0-10 (admite vacío, hasta 10 chars). |
| `xpn` | Tamaño de x enteros, y con "n" casillas decimales. Ejemplo: 5p3 → 54321.103 |
| `xpn-m` | Tamaño de x enteros con mínimo n y máximo m decimales. Ejemplo: 11p0-6 |
| `x-ypn-m` | Mínimo x enteros, máximo y enteros, con mínimo n y máximo m decimales. Ej: 1-11p0-6 (parte decimal opcional). |

## 4. Formato del NUC

### 4.1 Conjuntos de campos (Tabla 5)

| Conjunto | Descripción |
|---|---|
| **R** | Campos que contienen información para la generación de la factura electrónica. |
| **A** | Campos que contienen información general de la Factura Electrónica. |
| **B** | Campos que contienen la información del emisor de la transacción documentada. |
| **C** | Campos que contienen la información del receptor de la transacción documentada. |
| **D** | Campos que describen cada ítem de la transacción documentada. |
| **E** | Campos que describen los subtotales y totales de la transacción documentada. |
| **F** | Campos que describen información adicional sobre la transacción documentada. |

> ⚠️ La API es **case-sensitive**. Respetar mayúsculas y minúsculas exactamente.

### 4.2.1 — Schema NUC (Conjunto R)

Campos raíz que identifican el documento NUC.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| R | `R01` | `NUC` | NUC (raíz). | — | JSON | `—` | `1-1` | Raíz del documento. En XML se representa como grupo (G); en JSON como documento JSON. |
| R | `R02` | `Version` | Versión del formato de la factura electrónica. | R01 | A | `1-pP2` | `1-1` | Control de versiones. Valor a ingresar: 1.00 |
| R | `R03` | `CountryCode` | Código del país donde pertenece la factura electrónica. | R01 | A | `2` | `1-1` | Valores: `GT`=Guatemala; `PA`=Panamá |

### 4.2.2 — Campos que contienen información general de la Factura Electrónica (Conjunto A)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| A | `A01` | `Header` | Información general de la factura electrónica. | R01 | O | `—` | `1-1` |  |
| A | `A02` | `DocType` | Tipo de DTE. | A01 | A | `4` | `1-1` | Valor obligatorio. Si no se ingresa uno de los valores permitidos, no se podrá generar la Factura Electrónica. CAIS está marcado como "no aceptado por el momento". — Valores: `FACT`=Factura; `FACM`=Factura Cambiaria; `FPEQ`=Factura Pequeño Contribuyente; `FCAP`=Factura Cambiaria Pequeño Contribuyente; `FESP`=Factura Especial … y 12 más de 17 — catálogo completo en `/gt/catalogos.md?key=doctype` |
| A | `A03` | `IssuedDateTime` | Fecha y hora de emisión del DTE (UTC). | A01 | F | `25` | `1-1` | Formato AAAA-MM-DDThh:mm:ssTZH. Ej: 2022-04-17T14:23:00-06:00 |
| A | `A04` | `Currency` | Moneda utilizada en la operación. | A01 | A | `3` | `1-1` | Código ISO 4217. Ej: GTQ, USD, EUR. Nota: el PDF lo lista como tipo "S" — es errata, debe tratarse como Alfanumérico (A). |
| A | `A05` | `AdditionalIssueDocInfo` | Información adicional general del documento. | A01 | L | `—` | `0-1` |  |
| A | `A051` | `Info` | Elementos clave/valor de información adicional. | A05 | I | `—` | `1-25` | Ver en sección "Grupo AdditionalIssueDocInfo". Agregar el nombre de la información en "Name" y el valor en "Value".  Ejemplo si el DTE es para exportación: { "Name": "Exp", "Data": null, "Value": "Si" } |

### 4.2.3 — Catálogo de atributos Info en AdditionalIssueDocInfo (Conjunto A)

Valores admitidos en el atributo "Name" de los elementos Info dentro de AdditionalIssueDocInfo (A051).

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| A | `AI01` | `Exp` | Exportación. | A051 | A | `2` | `0-1` | Indica si el DTE servirá para una exportación. Si el DTE no será para exportación, no es necesario agregar este elemento. Si se agrega, deberá agregarse el complemento de exportación (EXP).  Ejemplo: { "Name": "Exp", "Data": null, "Value": "Si" } |
| A | `AI02` | `Espectaculo` | Espectáculos públicos. | A051 | A | `2` | `0-1` | Indica si el DTE servirá para Manejo de Espectáculos Públicos. Si se agrega este elemento, deberá agregarse el complemento ESPECT.  Ejemplo: { "Name": "Espectaculo", "Data": null, "Value": "Si" } |
| A | `AI03` | `NumeroAcceso` | Número de acceso. | A051 | A | `9` | `0-1` | Número generado por el emisor en caso de contingencia, que va desde 100000000 hasta 999999999. |
| A | `AI04` | `TipoPersoneria` | Tipo de personería. | A051 | A | `3-4` | `0-1` | Indica el código o tipo de personería que está emitiendo. Requerido obligatoriamente para personerías que pueden emitir recibos de donación. |

### 4.3 — Campos que contienen información del Emisor (Conjunto B)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `B01` | `Seller` | Contenedor del emisor. | R01 | O | `—` | `1-1` |  |
| B | `B02` | `TaxID` | Identificador tributario o NIT del emisor. | B01 | A | `12` | `1-1` | NIT válido del emisor, sin guiones. |
| B | `B03` | `TaxIDAdditionalInfo` | Contenedor de info tributaria adicional del emisor. | B01 | L | `25` | `1-1` |  |
| B | `B031` | `Info` | Items clave/valor. | B03 | I | `—` | `1-25` |  |
| B | `B04` | `Name` | Razón social o Nombre de Persona Natural. | B01 | A | `2-100` | `1-1` |  |
| B | `B05` | `Contact` | Información de contacto. | B01 | O | `—` | `0-1` |  |
| B | `B051` | `EmailList` | Lista de emails (si Contact se incluye). | B05 | O | `—` | `1-1` |  |
| B | `B0511` | `Email` | Correo electrónico. | B051 | L | `50` | `1-1` | Correo válido del emisor. |
| B | `B06` | `AdditionlInfo` | Frases tributarias del emisor. | B01 | L | `—` | `0-1` | Nombre del elemento sin "a" (AdditionlInfo, sic). Usar literalmente — la API es case-sensitive. |
| B | `B061` | `Info` | Items que componen frases (agrupar por Data). | B06 | I | `—` | `1-30` |  |
| B | `B07` | `BranchInfo` | Establecimiento del emisor. | B01 | O | `—` | `1-1` |  |
| B | `B071` | `Code` | Código del establecimiento. | B07 | N | `1-9999` | `1-1` |  |
| B | `B072` | `AddressInfo` | Dirección del establecimiento. | B07 | O | `—` | `1-1` |  |
| B | `B0721` | `Address` | Dirección. | B072 | A | `100` | `1-1` |  |
| B | `B0722` | `City` | Código postal de la ubicación. | B072 | A | `50` | `1-1` | Debe corresponder a un código válido. |
| B | `B0723` | `District` | Municipio. | B072 | A | `50` | `1-1` |  |
| B | `B0724` | `State` | Departamento. | B072 | A | `50` | `1-1` |  |
| B | `B0725` | `Country` | País. | B072 | A | `50` | `1-1` | Valor: GT |

### 4.3.1 — Catálogo AfiliacionIVA (TaxIDAdditionalInfo del emisor) (Conjunto B)

Atributo "Name" obligatorio en B031 que indica el régimen de IVA del emisor.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `BI01` | `AfiliacionIVA` | Régimen de IVA del emisor. | B031 | A | `3` | `1-1` | Valores: `GEN`=General; `PEQ`=Pequeño Contribuyente; `PEE`=Pequeño Contribuyente Electrónico Agropecuario; `EXE`=Exento / No aplica; `PRI`=Contribuyente Régimen Primario; `PEC`=Contribuyente Régimen Pecuario |
| B | `BI02` | `ClasificacionEmisor` | Clasificación adicional del emisor. | B031 | N | `4` | `0-1` | Valores: `1674`=Intermediario bovino |

### 4.3.2 — Frases tributarias (AdditionlInfo del emisor) (Conjunto B)

Cada frase se forma agrupando varios Info por el atributo Data (entero positivo identificador). El catálogo completo de TipoFrase/CodigoEscenario está en el documento Reglas-y-Validaciones-FEL.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| B | `BI02` | `TipoFrase` | Tipo de frase. | B061 | N | `1-9` | `1-1` | Identifica un determinado catálogo de leyendas. |
| B | `BI03` | `CodigoEscenario` | Código de escenario. | B061 | N | `1-99` | `1-1` | Indica un determinado Escenario dentro del catálogo de leyendas. |
| B | `BI04` | `NumeroResolucion` | Número de resolución. | B061 | A | `4-50` | `0-1` | Número de resolución relacionada a la frase. Uso opcional de acuerdo a reglas y validaciones. |
| B | `BI05` | `FechaResolucion` | Fecha de resolución. | B061 | A | `10` | `0-1` | Fecha de resolución relacionada a la frase. Uso opcional de acuerdo a reglas y validaciones. En formato YYYY-MM-DD. |

### 4.4 — Campos que contienen información del Receptor (Conjunto C)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| C | `C01` | `Buyer` | Contenedor del receptor. | R01 | O | `—` | `1-1` |  |
| C | `C02` | `TaxID` | Identificador tributario, CUI o NIT del receptor. | C01 | A | `1-13` | `1-1` | En caso de agregar el CUI, informar en el elemento C03 (TaxIDType="CUI"). Si es Consumidor Final, agregar "CF". |
| C | `C03` | `TaxIDType` | Tipo especial de identificación. | C01 | A | `3` | `0-1` | Agregar este elemento cuando se desee informar el CUI del receptor, ingresando la palabra "CUI". Indica que el elemento C02 no incluye un NIT, sino un CUI. |
| C | `C07` | `TaxIDAdditionalInfo` | Info tributaria adicional del receptor. | C01 | L | `5` | `0-1` |  |
| C | `C071` | `Info` | Items clave/valor. | C07 | I | `—` | `1-5` |  |
| C | `C04` | `Name` | Razón social o Nombre y Apellido del receptor. | C01 | A | `2-100` | `1-1` | Si el elemento C02 contiene un NIT válido, el nombre indicado debe corresponder a los registros tributarios. Caso contrario el contenido puede ser cualquiera que solicite el RECEPTOR. |
| C | `C05` | `Contact` | Contacto del receptor. | C01 | O | `—` | `0-1` |  |
| C | `C052` | `PhoneList` | Lista de teléfonos. | C05 | O | `—` | `0-1` |  |
| C | `C0521` | `Phone` | Teléfono válido. | C052 | L | `8-15` | `1-1` |  |
| C | `C051` | `EmailList` | Lista de emails. | C05 | O | `—` | `1-1` |  |
| C | `C0511` | `Email` | Email válido. | C051 | L | `50` | `1-1` |  |
| C | `C06` | `AddressInfo` | Dirección del receptor. | C01 | O | `—` | `0-1` |  |
| C | `C061` | `Address` | Dirección. | C06 | A | `100` | `1-1` |  |
| C | `C062` | `City` | Código postal de la ubicación. | C06 | A | `50` | `1-1` | Debe corresponder a un código válido. |
| C | `C063` | `District` | Municipio. | C06 | A | `50` | `1-1` |  |
| C | `C064` | `State` | Departamento. | C06 | A | `50` | `1-1` |  |
| C | `C065` | `Country` | País. | C06 | A | `50` | `1-1` |  |

### 4.4.1 — Catálogo DestinodelaVenta (TaxIDAdditionalInfo del receptor) (Conjunto C)

Atributo "Name" en C071 que indica el destino comercial de la venta.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| C | `CI01` | `DestinodelaVenta` | Destino comercial de la venta. | C071 | A | `—` | `0-1` | Valores: `Supermercado`=Supermercado; `Mercado cantonal`=Mercado cantonal; `Mercado municipal`=Mercado municipal; `Centro de acopio`=Centro de acopio; `Exportación`=Exportación; `Exportación en pie`=Exportación en pie; `Intermediación de productos bovinos`=Intermediación de productos bovinos; `Restaurante`=Restaurante; `Organización de Padres de Familia`=Organización de Padres de Familia |

### 4.5 — Campos que describen los Ítems (Conjunto D)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| D | `D01` | `Items` | Lista de ítems. | R01 | L | `—` | `1-1` |  |
| D | `D02` | `Item` | Cada ítem de la transacción. | D01 | O | `—` | `1-1000` |  |
| D | `D03` | `Codes` | Códigos asociados al ítem. | D02 | L | `—` | `0-1` |  |
| D | `D031` | `Code` | Items de código. | D03 | I | `—` | `1-2` |  |
| D | `D04` | `Type` | Tipo o clasificación del ítem. | D02 | A | `1-8` | `1-1` | Indica si el ítem es un bien o servicio. Los valores aceptados son: - B o BIEN: para indicar que es un Bien - S o SERVICIO: para indicar que es un Servicio — Valores: `B`=Bien (sinónimo: BIEN); `BIEN`=Bien; `S`=Servicio (sinónimo: SERVICIO); `SERVICIO`=Servicio |
| D | `D05` | `Description` | Descripción del producto o servicio. | D02 | A | `2-500` | `1-1` |  |
| D | `D06` | `Qty` | Cantidad de unidades del producto o servicio. | D02 | N | `1-11p2-6` | `1-1` |  |
| D | `D07` | `UnitOfMeasure` | Unidad de medida. | D02 | A | `1-20` | `0-1` | Indica la unidad de medida en que está expresado el elemento D05 (Description). |
| D | `D08` | `Price` | Precio unitario. | D02 | N | `1-9p2-6` | `1-1` | Precio de cada unidad del ítem en la moneda en que se emite el DTE (quetzales, dólares, euros, etc.). |
| D | `D09` | `Discounts` | Información relacionada a descuentos del ítem. | D02 | O | `—` | `0-1` | Descuento para aplicar sobre el total del ítem. |
| D | `D091` | `Discount` | Descuento aplicado. | D09 | L | `—` | `1-1` |  |
| D | `D0911` | `Amount` | Monto de descuento. | D091 | N | `1-9p2-6` | `1-1` |  |
| D | `D10` | `Taxes` | Contenedor de impuestos. | D02 | O | `—` | `1-1` |  |
| D | `D101` | `Tax` | Lista de impuestos aplicados. | D10 | L | `—` | `1-15` |  |
| D | `D1011` | `Code` | Código de unidad gravable. | D101 | N | `1-13` | `1-1` |  |
| D | `D1012` | `Description` | Nombre corto del impuesto. | D101 | A | `3-20` | `1-1` | Valores: `IVA`=Impuesto al Valor Agregado; `BEBIDAS ALCOHOLICAS`=Bebidas alcohólicas; `BEBIDAS NO ALCOHOLICAS`=Bebidas no alcohólicas; `PETROLEO`=Distribución de petróleo; `TURISMO HOSPEDAJE`=Turismo — hospedaje; `TURISMO PASAJES`=Turismo — pasajes; `TIMBRE DE PRENSA`=Timbre de prensa; `BOMBEROS`=Timbre bomberos; `TASA MUNICIPAL`=Tasa municipal; `TABACO`=Tabaco; `CEMENTO`=Cemento; `TARIFA PORTUARIA`=Tarifa portuaria |
| D | `D1013` | `TaxableAmount` | Monto gravable. | D101 | N | `1-11p2-6` | `0-1` | Monto sobre el cual se aplica el impuesto. |
| D | `D1014` | `ChargableAmount` | Cantidad de unidades gravables. | D101 | N | `1-11p2-6` | `0-1` |  |
| D | `D1015` | `Rate` | Tasa aplicable. | D101 | N | `1-11p2-6` | `0-1` | Para tasas municipales. |
| D | `D1016` | `Amount` | Monto del impuesto. | D101 | N | `1-9p2-6` | `1-1` |  |
| D | `D11` | `Totals` | Totales del ítem. | D02 | O | `—` | `1-1` |  |
| D | `D112` | `TotalItem` | Precio total del ítem. | D11 | N | `1-11p2-6` | `1-1` | Es el resultado de: (Precio Unitario × Cantidad) − Descuento + (la sumatoria de las casillas "Amount" de los impuestos que sean sumables al DTE). |

### 4.5.1 — Catálogo CodigoProducto (Codes del ítem) (Conjunto D)

Catálogo decretos 15-2021 y 20-2022 — usado en el atributo "Name" de los Info dentro de Codes (D031).

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| D | `DI01` | `CodigoProducto` | Código de producto regulado. | D031 | A | `1-20` | `1-1` | Valores: `CGP10LBS`=Cilindro Gas Propano 10 lbs; `CGP20LBS`=Cilindro Gas Propano 20 lbs; `CGP25LBS`=Cilindro Gas Propano 25 lbs; `CGP35LBS`=Cilindro Gas Propano 35 lbs; `GALDIESEL`=Galón Diesel; `GALREGULAR`=Galón Gasolina Regular; `GALSUPER`=Galón Gasolina Súper |

### 4.6 — Campos que describen los Totales (Conjunto E)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| E | `E01` | `Totals` | Contenedor de totales. | R01 | O | `—` | `1-1` |  |
| E | `E02` | `TotalTaxes` | Impuestos totalizados. | E01 | O | `—` | `0-1` |  |
| E | `E021` | `TotalTax` | Cada impuesto totalizado. | E02 | L | `—` | `1-20` |  |
| E | `E0211` | `Description` | Nombre corto del impuesto. | E021 | A | `6-7` | `1-1` | Valores a ingresar: - FACTURA: si se desea agregar un cargo por acarreo, indicar este nombre en la descripción. - SEGURO: si se desea agregar el precio por seguro cobrado en el precio total. |
| E | `E0212` | `Amount` | Total monto impuesto. | E021 | N | `1-11p2` | `1-1` | Sumatoria del monto de cada uno de los ítems con el mismo impuesto. Ejemplo: Si el elemento impuesto es IVA, este atributo deberá contener la sumatoria de los montos de IVA incluidos en todos los ítems del documento. |
| E | `E03` | `GrandTotal` | Total final del documento. | E01 | O | `—` | `1-1` |  |
| E | `E031` | `InvoiceTotal` | Precio total de la factura. | E03 | N | `1-11p2` | `1-1` | Sumatoria de los elementos D112 (TotalItem) de cada uno de los ítems. |

### 4.7 — Campos de Información Adicional del documento (Complementos y Adenda) (Conjunto F)

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `F01` | `AdditionalDocumentInfo` | Contenedor de complementos y adenda. | R01 | O | `—` | `1-1` | OBLIGATORIO SIEMPRE. Confirmado en pruebas reales: la API rechaza el NUC sin esta sección con "Error al transformar, No se encuentra el elemento AdditionalDocumentInfo". Si no hay complementos ni adenda real del cliente, incluir un AdditionalInfo mínimo con Type=ADENDA y Code=<GUID generado de 36 chars>. Esta regla NO está en el PDF V2.0.3 pero es exigida por la API. |
| F | `F02` | `AdditionalInfo` | Grupo que contiene información adicional. | F01 | L | `—` | `0-20` | Elemento que contiene información sobre Complementos y la Adenda.  Si se desea agregar información sobre un Complemento, únicamente se agregarán los datos necesarios para ese complemento. Y si se desea agregar información sobre la Adenda, es necesario crear otro elemento AdditionalInfo y únicamente se deben agregar los datos necesarios para la Adenda.  Se debe agregar un elemento AdditionalInfo para cada Complemento, y la Adenda debe estar solo una vez. |
| F | `F03` | `Code` | Código de clasificación. | F02 | A | `1-100` | `1-1` | Para Complementos: indicar el código del complemento que se agregará (EXP, FCAMB, FESP, NDEB, NCRE, CCA, ESPECT, REFCONST, FEPE). Para Adenda: ingresar la referencia interna como GUID válido (36 chars, formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Datatype TREFERENCIAINTERNA en el schema XML tiene MinLength=36, así que strings cortos como "1" o "ref" fallan validación. — Valores: `EXP`=Exportaciones (Requerido cuando AdditionalInfo.Exp=Si.); `FCAMB`=Factura Cambiaria (Para FACM, FCAP, FCRP, FCPC.); `FESP`=Factura Especial (Para FESP (retenciones ISR/IVA).); `NDEB`=Nota de Débito (Para NDEB.); `NCRE`=Nota de Crédito (Para NCRE.); `CCA`=Cobro por Cuenta Ajena; `ESPECT`=Espectáculos Públicos (Requerido cuando AdditionalInfo.Espectaculo=Si.); `REFCONST`=Referencias de Constancia (Para CIVA y similares.); `FEPE`=Factura Específica (Para FEPE (retención ICT).) |
| F | `F04` | `Type` | Tipo de información a agregar. | F02 | A | `6-12` | `1-1` | Tipo de información, puede ser: - ADENDA - COMPLEMENTO — Valores: `ADENDA`=Adenda — datos NO fiscales; `COMPLEMENTO`=Complemento — datos fiscales obligatorios según operación |
| F | `F05` | `AditionalData` | Grupo que contiene datos adicionales. | F02 | O | `—` | `0-1` | Nombre con typo "Aditional" (sic). Usar literalmente.  Para Complemento: ver sección "Información Adicional Data Complementos" (4.7.1). Para Adenda: ver sección "Información Adicional Data Adenda" (4.7.3). |
| F | `F051` | `Data` | Elemento que contiene datos adicionales. | F05 | L | `—` | `1-50` | Este elemento contiene dos atributos, Name e Id, que serán únicamente utilizados al momento de agregar información sobre la Adenda.  Los valores que puede tomar el atributo Name son: - INFORMACION_AGENCIA_DE_VIAJES: información sobre viajes - INFORMACIÓN_ADICIONAL: información adicional libre - DetallesAux_Detalle: detalles auxiliares por ítem |
| F | `F0511` | `Info` | Items clave/valor. | F051 | I | `—` | `1-25` |  |
| F | `F06` | `AditionalInfo` | Grupo que contiene información adicional. | F02 | L | `—` | `0-1` | Nombre con typo "Aditional" (sic). Usar literalmente.  Para Complemento: ver sección "Información Adicional Info Complementos" (4.7.2). Para Adenda: ver sección "Información Adicional Info Adenda" (4.7.4). |
| F | `F061` | `Info` | Items clave/valor. | F06 | I | `—` | `1-25` |  |

### 4.7.1 — Grupo Información Adicional Data Complementos (Conjunto F)

Campos que viajan dentro de F05 AditionalData. Cada fila aplica al complemento indicado en la observación "Válido para X".

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FI01` | `NumeroAbono` | Número de abono. | F0511 | N | `3` | `1-1` | Válido para FCAMB |
| F | `FI02` | `FechaVencimiento` | Fecha de vencimiento. | F0511 | A | `10` | `1-1` | Válido para FCAMB. En formato YYYY-MM-DD. |
| F | `FI03` | `MontoAbono` | Monto de abono. | F0511 | N | `1-9p2-6` | `1-1` | Válido para FCAMB |
| F | `FI04` | `NITtercero` | NIT del tercero. | F0511 | A | `12` | `0-1` | Válido para CCA. El NIT del contribuyente para quien se está realizando el cobro (sin guión). |
| F | `FI05` | `NumeroDocumento` | Número de documento. | F0511 | A | `22` | `0-1` | Válido para CCA. El número del documento relacionado con la transacción. |
| F | `FI06` | `FechaDocumento` | Fecha del documento. | F0511 | A | `10` | `0-1` | Válido para CCA. La fecha del documento relacionado con la transacción. En formato YYYY-MM-DD. |
| F | `FI07` | `Descripcion` | Descripción. | F0511 | A | `1-50` | `1-1` | Válido para CCA. Indica la descripción del ítem. |
| F | `FI08` | `BaseImponible` | Base imponible. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El monto sobre el cual se cobró el concepto de IVA. Si no aplica consignar cero (0.00). |
| F | `FI09` | `MontoCobroDAI` | Monto cobro DAI. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El monto cobrado por concepto de Derechos Arancelarios a la Importación. Si no aplica consignar cero (0.00). |
| F | `FI10` | `MontoCobroIVA` | Monto cobro IVA. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El Monto cobrado por concepto de Impuesto al Valor Agregado sobre el valor de Base Imponible. Si no aplica consignar cero (0.00). |
| F | `FI11` | `MontoCobroOtros` | Monto cobro otros. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El Monto cobrado por cualquier otro concepto, si no aplica consignar cero (0.00). |
| F | `FI12` | `MontoCobroTotal` | Monto total. | F0511 | N | `1-9p2-6` | `0-1` | Válido para CCA. El valor de la suma de las casillas: MontoCobroDAI, MontoCobroIVA, MontoCobroOtros. |

### 4.7.2 — Grupo Información Adicional Info Complementos (Conjunto F)

Campos que viajan dentro de F06 AditionalInfo. Cada fila aplica al complemento indicado en la observación "Válido para X".

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FI13` | `NombreConsignatarioODestinatario` | Nombre del consignatario o destinatario. | F061 | A | `1-50` | `1-1` | Válido para EXP |
| F | `FI14` | `DireccionConsignatarioODestinatario` | Dirección del consignatario o destinatario. | F061 | A | `1-50` | `1-1` | Válido para EXP |
| F | `FI15` | `INCOTERM` | INCOTERM. | F061 | A | `5-50` | `1-1` | Válido para EXP. Agregar un INCOTERM válido. |
| F | `FI16` | `RetencionISR` | Retención ISR. | F061 | N | `1-9p2-6` | `1-1` | Válido para FESP |
| F | `FI17` | `RetencionIVA` | Retención del IVA. | F061 | N | `1-9p2-6` | `0-1` | Válido para FESP |
| F | `FI18` | `TotalMenosRetenciones` | Monto del total menos las retenciones. | F061 | N | `1-9p2-6` | `1-1` | Válido para FESP |
| F | `FI19` | `RegimenAntiguo` | Régimen antiguo. | F061 | A | `1-12` | `0-1` | Válido para NDEB y NCRE. Debe incluirse solamente cuando el documento original corresponde al régimen de papel o FACE1. |
| F | `FI20` | `NumeroAutorizacionDocumentoOrigen` | Número de autorización. | F061 | A | `1-50` | `1-1` | Válido para NDEB y NCRE. Indica el número de Autorización del régimen FEL cuando el atributo RegimenAntiguo no se coloca en el complemento, de lo contrario se utiliza para indicar el Número de Resolución de Autorización del régimen de papel o FACE1. |
| F | `FI21` | `FechaEmisionDocumentoOrigen` | Fecha de emisión del documento de origen. | F061 | A | `10` | `1-1` | Válido para NDEB y NCRE. En formato YYYY-MM-DD. |
| F | `FI22` | `MotivoAjuste` | Motivo de ajuste. | F061 | A | `1-50` | `0-1` | Válido para NDEB y NCRE. Descripción de la causa por la cual se realiza el Ajuste. |
| F | `FI23` | `SerieDocumentoOrigen` | Número de serie. | F061 | A | `1-20` | `1-1` | Válido para NDEB y NCRE. Número de serie correspondiente al régimen de papel o FACE1. |
| F | `FI24` | `NumeroDocumentoOrigen` | Número de documento. | F061 | A | `1-20` | `1-1` | Válido para NDEB y NCRE. Número de documento correspondiente al régimen de papel o FACE1. |
| F | `FI25` | `CodigoEvento` | Código del evento. | F061 | A | `1-50` | `1-1` | Válido para ESPECT. Código asignado al evento. |
| F | `FI26` | `NombreEvento` | Nombre del evento. | F061 | A | `1-50` | `1-1` | Válido para ESPECT. Nombre con el que se identifica el evento. |
| F | `FI27` | `NombreLocalidad` | Nombre de la localidad. | F061 | A | `1-50` | `1-1` | Válido para ESPECT. Lugar donde se realiza el evento. |
| F | `FI28` | `PrecioAdmision` | Precio de admisión. | F061 | N | `—` | `1-1` | Válido para ESPECT. Precio del boleto de admisión. |
| F | `FI29` | `NumeroBoleto` | Número de boleto. | F061 | N | `6` | `1-1` | Válido para ESPECT. Número correlativo del boleto vendido. |
| F | `FI30` | `RegimenAntiguo` | Régimen antiguo. | F061 | A | `5-20` | `0-1` | Válido para REFCONST. Indica si la constancia se aplica a un DTE del Régimen FEL (no se incluye la casilla) o bien a uno antiguo (facturas de papel). Para los antiguos se incluye la casilla con el valor "Antiguo". |
| F | `FI31` | `NumeroAutorizacionDocumentoOrigen` | Número de autorización. | F061 | A | `1-50` | `1-1` | Válido para REFCONST. Describe el número de autorización del documento original al que se le aplica la constancia que se está emitiendo. |
| F | `FI32` | `FechaEmisionDocumentoOrigen` | Fecha de emisión. | F061 | A | `10` | `1-1` | Válido para REFCONST. Fecha de emisión del documento al cual se le está aplicando la constancia. En formato YYYY-MM-DD. |
| F | `FI33` | `SerieDocumentoOrigen` | Serie documento de origen. | F061 | A | `5-20` | `0-1` | Válido para REFCONST. Serie del documento al cual se le emite la constancia, cuando corresponde a un documento antiguo. *Se incluye la casilla, sólo si se hace referencia a un documento del Régimen Antiguo. |
| F | `FI34` | `NumeroDocumentoOrigen` | Número de documento de origen. | F061 | A | `5-20` | `0-1` | Válido para REFCONST. Número del documento al cual se le emite la constancia, cuando corresponde a un documento antiguo. *Se incluye la casilla, sólo si se hace referencia a un documento del Régimen Antiguo. |
| F | `FI35` | `MontoIVAExento` | Monto total del IVA. | F061 | N | `1-9p2-6` | `0-1` | Válido para REFCONST. El monto total del IVA que ampara el documento, cuando el complemento corresponde a una Constancia de Exención del IVA (CIVA). Dicho monto debe ser igual al total de IVA del DTE al que se hace referencia. |
| F | `FI36` | `RetencionICT` | Monto de retención ICT. | F061 | N | `1-9p2-6` | `0-1` | Válido para FEPE |
| F | `FI37` | `TotalMenosRetenciones` | Total menos retenciones. | F061 | N | `1-9p2-6` | `0-1` | Válido para FEPE |

### 4.7.3 — Grupo Información Adicional Data Adenda (Conjunto F)

Campos que viajan dentro de F05 AditionalData de la Adenda. El atributo "Name" indica a qué subgrupo pertenece (INFORMACION_AGENCIA_DE_VIAJES, INFORMACIÓN_ADICIONAL, DetallesAux_Detalle).

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FA01` | `**Cualquier nombre**` | Información sobre agencia de viajes. | F0511 | A | `1-50` | `0-1` | Válido para INFORMACION_AGENCIA_DE_VIAJES |
| F | `FA02` | `**Cualquier nombre**` | Información adicional. | F0511 | A | `1-50` | `0-1` | Válido para INFORMACION_ADICIONAL |
| F | `FA03` | `NumeroLinea` | Número de línea donde se encuentra el ítem referenciado. | F0511 | N | `3` | `0-1` | Válido para DetallesAux_Detalle |
| F | `FA04` | `Descripcion_Adicional` | Descripción adicional del ítem. | F0511 | A | `1-50` | `0-1` | Válido para DetallesAux_Detalle. Si se desea agregar una descripción adicional al ítem que se hace referencia. |
| F | `FA05` | `CodigoEAN` | Código del ítem. | F0511 | A | `1-20` | `0-1` | Válido para DetallesAux_Detalle. Si se desea el código del ítem. |
| F | `FA06` | `CategoriaAdicional` | Categoría adicional. | F0511 | A | `1-50` | `0-1` | Válido para DetallesAux_Detalle |
| F | `FA07` | `Textos` | Textos adicionales. | F0511 | A | `1-50` | `0-20` | Válido para DetallesAux_Detalle |

### 4.7.4 — Grupo Información Adicional Info Adenda (Conjunto F)

Campos que viajan dentro de F06 AditionalInfo de la Adenda — datos no fiscales requeridos por el cliente.

| C | ID | Campo | Descripción | Padre | Tipo | Tam | Ocu | Observaciones |
|---|---|---|---|---|---|---|---|---|
| F | `FA08` | `VALIDAR_REFERENCIA_INTERNA` | Validación de referencia interna. | F061 | A | `1-10` | `1-1` | Indicar si se desea validar la referencia interna de la Adenda. Valores permitidos: VALIDAR NO_VALIDAR |
| F | `FA09` | `CAJERO` | Nombre o información del cajero. | F061 | A | `1-50` | `0-1` |  |
| F | `FA10` | `VENDEDOR` | Nombre o información del vendedor. | F061 | A | `5-50` | `0-1` |  |
| F | `FA11` | `Subtotal` | Subtotal de la factura. | F061 | N | `1-9p2-6` | `0-1` |  |
| F | `FA12` | `Fuente` | Fuente. | F061 | A | `1-60` | `0-1` |  |
| F | `FA13` | `Tipo` | Indica un tipo al ingresar un RECIBO. | F061 | A | `1-20` | `1-1` | Valores permitidos: Universidad Colegio Inmobiliaria |
| F | `FA14` | `NombreAlumno` | Nombre del alumno. | F061 | A | `1-12` | `0-1` |  |
| F | `FA15` | `Carne` | Carné / número del estudiante. | F061 | A | `1-50` | `0-1` |  |
| F | `FA16` | `UnidadAcademica` | Unidad académica. | F061 | A | `1-50` | `0-1` |  |
| F | `FA17` | `Grado` | Grado. | F061 | A | `1-50` | `0-1` |  |
| F | `FA18` | `Seccion` | Sección. | F061 | A | `1-50` | `0-1` |  |
| F | `FA19` | `Jornada` | Tipo de jornada. | F061 | A | `1-50` | `0-1` |  |
| F | `FA20` | `TipoDePago` | Tipo de pago. | F061 | A | `1-50` | `0-1` |  |
| F | `FA21` | `NoReferencia` | Número de referencia. | F061 | A | `1-50` | `0-1` |  |
| F | `FA22` | `Banco` | Banco. | F061 | A | `1-50` | `0-1` |  |
| F | `FA23` | `Total` | Total. | F061 | A | `1-50` | `0-1` |  |
| F | `FA24` | `Observaciones` | Observaciones. | F061 | A | `1-70` | `0-1` |  |
| F | `FA25` | `MZ` | Manzana. | F061 | A | `1-50` | `0-1` |  |
| F | `FA26` | `APTO` | Apartamento. | F061 | A | `1-50` | `0-1` |  |
| F | `FA27` | `TipoPago` | Tipo de pago. | F061 | A | `1-50` | `0-1` |  |


## Respuesta de la API

### Ejemplo de Respuesta

```json
{
    "code": 0,
    "message": "",
    "description": "",
    "responseData1": "",
    "responseData2": "",
    "responseData3": "",
    "authNumber": "",
    "url": "",
    "infoDetails": [],
    "suggestedFileName": "",
    "suggestedFileName2": "",
    "batch": "",
    "serial": "",
    "issuedTimeStamp": "",
    "taxID": "",
    "name": "",
    "branchCode": "",
    "branchName": "",
    "receiverTaxID": "",
    "receiverName": "",
    "discounts": "",
    "taxes": "",
    "subTotal": "",
    "totalAmount": "",
    "enrolledTimeStamp": "",
    "backprocessor": "",
    "additionalInfo": {
        "anyAttribute": ""
    }
}
```

### Donde

| Atributo | Descripción |
|---|---|
| `code` | Muestra el código de la respuesta obtenida. Ver detalle en "Códigos dentro de la Respuesta". |
| `message` | Mensaje informativo relacionado a la respuesta. |
| `description` | Descripción adicional del mensaje. |
| `responseData1` | Texto codificado en base64 que contiene la factura en formato XML. |
| `responseData2` | Texto codificado en base64 que contiene la factura en formato HTML. |
| `responseData3` | Texto codificado en base64 que contiene la factura en formato PDF. |
| `authNumber` | Número de autorización de la factura electrónica (UUID). |
| `url` | Atributo sin valor por el momento. |
| `infoDetails` | Detalles adicionales. Atributo sin valor por el momento. |
| `suggestedFileName` | Nombre de archivo sugerido. Atributo sin valor por el momento. |
| `suggestedFileName2` | Nombre de archivo sugerido (alterno). Atributo sin valor por el momento. |
| `batch` | Número de serie de la factura. |
| `serial` | Número secuencial o correlativo de la factura. |
| `issuedTimeStamp` | Fecha de emisión de la factura electrónica. |
| `taxID` | NIT del contribuyente emisor de la factura. |
| `name` | Nombre o razón social del emisor. |
| `branchCode` | Código de sucursal emisora. Atributo sin valor por el momento. |
| `branchName` | Nombre comercial. Atributo sin valor por el momento. |
| `receiverTaxID` | NIT del receptor / comprador. |
| `receiverName` | Nombre o razón social del receptor. |
| `discounts` | Descuentos aplicados sobre el total de la factura. Atributo sin valor por el momento. |
| `taxes` | Impuestos aplicados. Atributo sin valor por el momento. |
| `subTotal` | Subtotal de la factura. Atributo sin valor por el momento. |
| `totalAmount` | Monto total de la factura. Atributo sin valor por el momento. |
| `enrolledTimeStamp` | Fecha y hora de certificación de la factura. |
| `backprocessor` | Servidor que realiza la consulta. |
| `additionalInfo` | Atributo tipo objeto con información adicional. Puede contener acuseReciboSAT (acuse de recibido SAT) y codigosSAT (códigos devueltos por SAT). |

### 5.1 Códigos de respuesta (Tabla 8)

| Código | Descripción |
|---|---|
| `1` | Consulta realizada correctamente. Documento certificado. |
| `401` | Unauthorized. Verificar token de autorización. |
| `500` | Internal Server Error. |
| `Otro` | Error en contenido del XML, verificar datos. |

### 5.2 Códigos HTTP (Tabla 9)

| Código | Descripción |
|---|---|
| `200` | Ok |
| `400` | Bad Request |
| `406` | Not Acceptable. Verificar contenido del XML NUC. |
| `401` | Unauthorized. Verificar token de autorización. |
| `500` | Internal Server Error. |


---

# Esquemas del NUC — Guatemala

> Definiciones oficiales del NUC para validación local: XSD para XML, JSON Schema para JSON.


## NUCSchema.xsd (XML)

- **Descarga:** [NUCSchema.xsd](/schemas/gt/NUCSchema.xsd)
- **Tipo:** XML Schema Definition
- **Uso típico:**
  - `xmllint --schema NUCSchema.xsd documento.xml --noout`
  - .NET: `XmlSchemaSet.Add("", "NUCSchema.xsd")`
  - Java: `SchemaFactory.newSchema(new File("NUCSchema.xsd"))`
  - Python: `etree.XMLSchema(etree.parse("NUCSchema.xsd"))`

## NUCSchema.json (JSON Schema draft-04)

- **Descarga:** [NUCSchema.json](/schemas/gt/NUCSchema.json)
- **Tipo:** JSON Schema draft-04
- **Uso típico:**
  - ajv (JS): `new Ajv().compile(require("./NUCSchema.json"))`
  - Python: `jsonschema.validate(data, schema)`
  - .NET: `JSchema.Parse(File.ReadAllText("NUCSchema.json"))`
  - CLI: `ajv validate -s NUCSchema.json -d documento.json`

> ⚠️ Validar contra el schema es necesario pero no suficiente. La API también valida reglas de negocio FEL (NIT existente, frases válidas, totales coherentes).


---

# Ejemplos NUC — GT

> Galería de 46 ejemplos reales del documento NUC. 36 en XML y 10 en JSON.


| Filename | DocType | Variante | Formato | Título | Descripción | Descargar |
|---|---|---|---|---|---|---|
| `NUC 1 - FACT.xml` | `FACT` | — | XML | Factura básica | Factura estándar mínima con un ítem. | [Descargar](/examples/gt/xml/NUC 1 - FACT.xml) |
| `NUC 1 - FACT CF.xml` | `FACT` | CF | XML | Factura a Consumidor Final | Receptor identificado como Consumidor Final. | [Descargar](/examples/gt/xml/NUC 1 - FACT CF.xml) |
| `NUC 1 - FACT CF 2 exp.xml` | `FACT` | CF/exp | XML | Factura CF para exportación | Consumidor final con datos de exportación. | [Descargar](/examples/gt/xml/NUC 1 - FACT CF 2 exp.xml) |
| `NUC 1 - FACT CUI.xml` | `FACT` | CUI | XML | Factura con identificación CUI | Cliente identificado por DPI (CUI) en vez de NIT. | [Descargar](/examples/gt/xml/NUC 1 - FACT CUI.xml) |
| `NUC 1 - FACT mas 1 item.xml` | `FACT` | — | XML | Factura con múltiples ítems | Factura con varios productos detallados. | [Descargar](/examples/gt/xml/NUC 1 - FACT mas 1 item.xml) |
| `NUC 1 - FACT CF.json` | `FACT` | CF | JSON | Factura CF (JSON) | Misma estructura que XML pero en formato JSON. | [Descargar](/examples/gt/json/NUC 1 - FACT CF.json) |
| `NUC 1 - FACT CUI.json` | `FACT` | CUI | JSON | Factura CUI (JSON) | Factura con CUI en formato JSON. | [Descargar](/examples/gt/json/NUC 1 - FACT CUI.json) |
| `NUC 2 - FCAM.xml` | `FCAM` | — | XML | Factura Cambiaria | Factura con compromiso de pago futuro. | [Descargar](/examples/gt/xml/NUC 2 - FCAM.xml) |
| `NUC 2 - FCAM CF.xml` | `FCAM` | CF | XML | Cambiaria a Consumidor Final | FCAM emitida a Consumidor Final. | [Descargar](/examples/gt/xml/NUC 2 - FCAM CF.xml) |
| `NUC 2 - FCAM 2.xml` | `FCAM` | v2 | XML | Cambiaria con detalle de abonos | FCAM con plan de abonos completo. | [Descargar](/examples/gt/xml/NUC 2 - FCAM 2.xml) |
| `NUC 2 - FCAM exp.xml` | `FCAM` | exp | XML | Cambiaria de Exportación | FCAM para una operación de exportación. | [Descargar](/examples/gt/xml/NUC 2 - FCAM exp.xml) |
| `NUC 2 - FCAM.json` | `FCAM` | — | JSON | Cambiaria (JSON) | FCAM en formato JSON. | [Descargar](/examples/gt/json/NUC 2 - FCAM.json) |
| `NUC 3 - NDEB.xml` | `NDEB` | — | XML | Nota de Débito | Cargo adicional sobre factura previa. | [Descargar](/examples/gt/xml/NUC 3 - NDEB.xml) |
| `NUC 3 - NDEB CF.xml` | `NDEB` | CF | XML | Nota de Débito a CF | NDEB emitida a Consumidor Final. | [Descargar](/examples/gt/xml/NUC 3 - NDEB CF.xml) |
| `NUC 3 - NDEB exp.xml` | `NDEB` | exp | XML | Nota de Débito Exportación | NDEB para operación de exportación. | [Descargar](/examples/gt/xml/NUC 3 - NDEB exp.xml) |
| `NUC 3 - NDEB.json` | `NDEB` | — | JSON | Nota de Débito (JSON) | NDEB en formato JSON. | [Descargar](/examples/gt/json/NUC 3 - NDEB.json) |
| `NUC 4 - NCRE.xml` | `NCRE` | — | XML | Nota de Crédito | Disminución sobre factura previa. | [Descargar](/examples/gt/xml/NUC 4 - NCRE.xml) |
| `NUC 4 - NCRE CF.xml` | `NCRE` | CF | XML | Nota de Crédito a CF | NCRE emitida a Consumidor Final. | [Descargar](/examples/gt/xml/NUC 4 - NCRE CF.xml) |
| `NUC 4 - NCRE exp.xml` | `NCRE` | exp | XML | Nota de Crédito Exportación | NCRE de exportación. | [Descargar](/examples/gt/xml/NUC 4 - NCRE exp.xml) |
| `NUC 4 - NCRE.json` | `NCRE` | — | JSON | Nota de Crédito (JSON) | NCRE en formato JSON. | [Descargar](/examples/gt/json/NUC 4 - NCRE.json) |
| `NUC 5 - NABN.xml` | `NABN` | — | XML | Nota de Abono | Abono sobre saldo pendiente.  Las notas de abono llevan la frase especial 9 y escenario 16 o 17 según sea su giro de negocio. Escenario 16: Vendedor intermediario de productos agropecuarios, artesanales y productos reciclados. Escenario 17: Documento de rebaja de inventarios.  Los escenarios deberán utilizarse según corresponda al giro comercial y operación realizada por cada contribuyente. | [Descargar](/examples/gt/xml/NUC 5 - NABN.xml) |
| `NUC 5 - NABN CF.xml` | `NABN` | CF | XML | Nota de Abono a CF | NABN a Consumidor Final. Las notas de abono llevan la frase especial 9 y escenario 16 o 17 según sea su giro de negocio. Escenario 16: Vendedor intermediario de productos agropecuarios, artesanales y productos reciclados. Escenario 17: Documento de rebaja de inventarios.  Los escenarios deberán utilizarse según corresponda al giro comercial y operación realizada por cada contribuyente. | [Descargar](/examples/gt/xml/NUC 5 - NABN CF.xml) |
| `NUC 5 - NABN.json` | `NABN` | — | JSON | Nota de Abono (JSON) | NABN en formato JSON. Las notas de abono llevan la frase especial 9 y escenario 16 o 17 según sea su giro de negocio. Escenario 16: Vendedor intermediario de productos agropecuarios, artesanales y productos reciclados. Escenario 17: Documento de rebaja de inventarios.  Los escenarios deberán utilizarse según corresponda al giro comercial y operación realizada por cada contribuyente. | [Descargar](/examples/gt/json/NUC 5 - NABN.json) |
| `NUC 6 - FESP.xml` | `FESP` | — | XML | Factura Especial | Factura emitida en condiciones especiales reguladas. | [Descargar](/examples/gt/xml/NUC 6 - FESP.xml) |
| `NUC 6 - FESP.json` | `FESP` | — | JSON | Factura Especial (JSON) | FESP en formato JSON. | [Descargar](/examples/gt/json/NUC 6 - FESP.json) |
| `NUC 7 - RECI.xml` | `RECI` | — | XML | Recibo (genérico) | Recibo estándar por servicios. | [Descargar](/examples/gt/xml/NUC 7 - RECI.xml) |
| `NUC 7 - RECI Univ.xml` | `RECI` | Univ | XML | Recibo Universitario | Recibo de universidad por colegiatura. | [Descargar](/examples/gt/xml/NUC 7 - RECI Univ.xml) |
| `NUC 7 - RECI Colegio.xml` | `RECI` | Col | XML | Recibo Colegio | Recibo de colegio por cuota mensual. | [Descargar](/examples/gt/xml/NUC 7 - RECI Colegio.xml) |
| `NUC 7 - RECI Inmobiliaria.xml` | `RECI` | Inmo | XML | Recibo Inmobiliaria | Recibo de inmobiliaria por arrendamiento. | [Descargar](/examples/gt/xml/NUC 7 - RECI Inmobiliaria.xml) |
| `NUC 8 - RDON.xml` | `RDON` | — | XML | Recibo de Donación | Comprobante de donación recibida. | [Descargar](/examples/gt/xml/NUC 8 - RDON.xml) |
| `NUC 8 - RDON.json` | `RDON` | — | JSON | Recibo de Donación (JSON) | RDON en formato JSON. | [Descargar](/examples/gt/json/NUC 8 - RDON.json) |
| `NUC 11 - FEPE.xml` | `FEPE` | — | XML | Factura Especial Pesca | Régimen especial del sector pesca. | [Descargar](/examples/gt/xml/NUC 11 - FEPE.xml) |
| `NUC 12 - FPEC.xml` | `FPEC` | — | XML | Factura Pequeño Contrib. Esp. | Variante especial del régimen PC. | [Descargar](/examples/gt/xml/NUC 12 - FPEC.xml) |
| `NUC 13 - FCPC.xml` | `FCPC` | — | XML | Factura Contrib. Agropecuario | Régimen agropecuario. | [Descargar](/examples/gt/xml/NUC 13 - FCPC.xml) |
| `NUC 14 - FARP.xml` | `FARP` | — | XML | Factura Anulación Retención PC | Anulación de retención sobre PC. | [Descargar](/examples/gt/xml/NUC 14 - FARP.xml) |
| `NUC 15 - FCRP.xml` | `FCRP` | — | XML | Factura Cobro Retención PC | Cobro de retención sobre PC. | [Descargar](/examples/gt/xml/NUC 15 - FCRP.xml) |
| `NUC - FPEQ.json` | `FPEQ` | — | JSON | Factura Pequeño Contrib. (JSON) | FPEQ en formato JSON. | [Descargar](/examples/gt/json/NUC - FPEQ.json) |
| `NUC 9 - Adenda Armas.xml` | `FACT` | Adenda Armas | XML | Adenda Armas | Factura con datos obligatorios para venta de armas. | [Descargar](/examples/gt/xml/NUC 9 - Adenda Armas.xml) |
| `NUC 9 - Adenda Carga Aerea.xml` | `FACT` | Adenda Carga Aérea | XML | Adenda Carga Aérea | Datos requeridos para carga aérea. | [Descargar](/examples/gt/xml/NUC 9 - Adenda Carga Aerea.xml) |
| `NUC 9 - Adenda Donacion PP.xml` | `RDON` | Adenda PP | XML | Adenda Donación Partido Político | Donación a partido político. | [Descargar](/examples/gt/xml/NUC 9 - Adenda Donacion PP.xml) |
| `NUC 9 - Adenda Exportacion.xml` | `FACT` | Adenda Exportación | XML | Adenda Exportación | Factura con datos completos de exportación. | [Descargar](/examples/gt/xml/NUC 9 - Adenda Exportacion.xml) |
| `NUC 9 - Adenda Retail.xml` | `FACT` | Adenda Retail | XML | Adenda Retail | Datos del sector retail. | [Descargar](/examples/gt/xml/NUC 9 - Adenda Retail.xml) |
| `NUC 9 - Complemento CCA.xml` | `FCAM` | Complemento CCA | XML | Complemento CCA | Complemento Cambiario obligatorio en FCAM. | [Descargar](/examples/gt/xml/NUC 9 - Complemento CCA.xml) |
| `NUC 9 - Complemento CCA.json` | `FCAM` | Complemento CCA | JSON | Complemento CCA (JSON) | CCA en formato JSON. | [Descargar](/examples/gt/json/NUC 9 - Complemento CCA.json) |
| `NUC 9 - Complemento Espectaculo.xml` | `FACT` | Complemento Espectáculo | XML | Complemento Espectáculo | Datos requeridos para eventos. | [Descargar](/examples/gt/xml/NUC 9 - Complemento Espectaculo.xml) |
| `NUC 9 - Det Adicional Item.xml` | `FACT` | Det. Adicional Item | XML | Detalle Adicional de Item | Atributos extra a nivel de ítem (lote, vencimiento). | [Descargar](/examples/gt/xml/NUC 9 - Det Adicional Item.xml) |


---

# Conceptos fiscales — GT

> Glosario de términos del régimen FEL.


## NIT

**Aliases:** `Número de Identificación Tributaria`

Identificador único asignado por la SAT a contribuyentes en Guatemala. Hasta 12 dígitos. Para emisores y receptores con actividad comercial.

**Ejemplos:** `123456`, `44653948`

**Aparece en:** `seller.taxId`, `buyer.taxId`

---

## CUI / DPI

**Aliases:** `CUI`, `DPI`, `Código Único de Identificación`

Documento Personal de Identificación, 13 dígitos. Usado cuando el receptor es una persona natural que no cuenta con NIT.

**Aparece en:** `buyer.taxId`, `buyer.taxIdType`

---

## CF

**Aliases:** `Consumidor Final`

Se usa cuando el receptor no proporciona NIT o CUI. Valor literal "CF" en el campo TaxID del Buyer. Caso de uso más común en retail.

**Aparece en:** `buyer.taxId`

---

## DTE

**Aliases:** `Documento Tributario Electrónico`

Documento Tributario Electrónico. Término genérico para cualquier factura electrónica, nota de crédito, débito, abono, recibo o factura especial certificado bajo el régimen FEL.

---

## FEL

**Aliases:** `Factura Electrónica en Línea`

Régimen de Factura Electrónica en Línea establecido por la SAT vía Acuerdo de Directorio 13-2018. Contempla emisión, transmisión, certificación y conservación electrónica de documentos tributarios.

---

## CAE

**Aliases:** `authNumber`, `Número de Autorización`, `Autorización SAT`

Código de Autorización Electrónica. UUID único que la SAT asigna al certificar un documento. Identifica al DTE para anulaciones y referencias futuras.

**Aparece en:** `header.reference.code`

---

## Frases

**Aliases:** `Frase tributaria`

Códigos definidos por SAT para indicar que el documento aplica a regímenes especiales (exportación, exento, ley de turismo, maquila, etc.).

---

## Adenda

**Aliases:** `Adendas`

Sección opcional con información extra que el cliente necesita pero que no exige la SAT. Ej: número de orden de compra, centro de costo, transportista. Va dentro de AdditionalDocumentInfo.

---

## Complemento

**Aliases:** `Complementos`

Anexo fiscal obligatorio en ciertos tipos de documento. CCA es obligatorio en FCAM. Espectáculo en eventos masivos. Exportación cuando aplique.

---

## Tipo de Documento

**Aliases:** `DocType`, `Tipo Documento`

Catálogo oficial SAT de tipos de documento electrónico: FACT (factura), FCAM (cambiaria), NDEB (nota débito), NCRE (nota crédito), NABN (abono), FESP (especial), RECI (recibo), RDON (donación), FEPE (especial pesca), FPEC/FCPC/FPEQ (regímenes PC y agro), FARP/FCRP (retenciones PC).

---


---

# MCP Server — Digifact

> Servidor MCP (Model Context Protocol) que expone la documentación Digifact a asistentes de IA. Compatible con cualquier cliente que implemente MCP.


## URL del servidor

- **Público:** `https://documentacion.digifact.com/mcp/sse`

## Configuración por cliente

### Claude Desktop / Cursor / Windsurf / Kiro

```json
{
  "mcpServers": {
    "digifact": {
      "url": "https://documentacion.digifact.com/mcp/sse"
    }
  }
}
```

## Autenticación (2 pasos, credenciales TEST)

Las consultas de contenido requieren un `access_token` POR PAÍS, obtenido con el tool `country_login` usando las credenciales de PRUEBA (TEST) del país — las mismas Username/Password del ambiente de pruebas de la API que Digifact entrega a todo cliente.

1. `country_login { country, username, password }` → devuelve `access_token` con el mismo vencimiento que el token del API del país (el password no se almacena).
2. Pasá ese `access_token` en el parámetro `access_token` de cada tool de contenido. El token solo autoriza consultas de SU país.

El login NO invalida los tokens que ya tengas en uso: el API permite tokens simultáneos, así que tu integración de pruebas sigue certificando normalmente.

Quedan abiertos sin token: `list_countries` y `get_country_info`.

## Tools disponibles

### Vitrina (sin token)
- `list_countries` — lista de países disponibles
- `get_country_info` — info general del país

### Autenticación
- `country_login` — login por país con credenciales TEST → access_token (hereda el vencimiento del API)

### API y país (requieren access_token)
- `list_endpoints` — endpoints API por país
- `get_endpoint` — doc completa de un endpoint
- `search_docs` — búsqueda full-text (limitada al país del token)

### Generación de NUC (requieren access_token)
- `generate_nuc_template` — esqueleto de NUC por DocType (con reglas y preguntas obligatorias)
- `get_required_fields` — campos obligatorios por DocType
- `get_complement_for_doctype` — complementos requeridos
- `get_nuc_schema` — XSD o JSON Schema oficial

### Exploración del NUC (requieren access_token)
- `get_nuc_field` — detalle de un campo por ID (R01, A02, B051, etc.)
- `list_nuc_fields_by_section` — campos por conjunto (R/A/B/C/D/E/F)
- `get_doctypes` — catálogo de DocTypes
- `get_catalog` — catálogos cerrados (AfiliacionIVA, Impuestos, etc.)

### Ejemplos (requieren access_token)
- `list_examples` — 46 ejemplos NUC con filtros
- `get_example` — contenido completo de un ejemplo