NUC JSON V2.0.3 — Guatemala

1Funcionamiento

El objetivo principal de esta API es transformar una cadena con un esquema definido (NUC) en formato JSON a su factura electrónica correspondiente del país donde pertenezca.

Antes de iniciar con los detalles técnicos, es necesario que se tenga presente el siguiente concepto:

📄

NUC: archivo JSON que contiene la información necesaria para generar el XML de la factura electrónica del país que se indique. Se detalla el esquema completo en la sección 4.

El funcionamiento de la API va de la mano con las validaciones de la Factura Electrónica de Guatemala, creada por la Superintendencia de Administración Tributaria (SAT).

2Arquitectura

🖥️

Cliente

NUC en formato JSON →

← Factura electrónica equivalente

⚙️

API NUC to Native

Endpoint a consumir

Tabla 1 — Detalle del endpoint a consumir

URL	Tipo	Formato	Cuerpo / Body
`https://testnucgt.digifact.com/api/v2/transform/nuc_json`	`POST`	`JSON`	Ver sección 4 — Formato del NUC

Query Params

Key	Value
`TAXID`	NIT válido, sin guiones y completado con 0's hasta tener 12 caracteres. Ej: NIT `123456` → valor en URL `000000123456`
`FORMAT`	Formatos de respuesta para visualizar la factura: `XML`, `PDF` o `HTML`. Se pueden combinar con pipe: `XML\|HTML\|PDF`
`USERNAME`	Nombre de usuario quien realiza la consulta

3Convenciones utilizadas en el formato JSON

3.1 Columnas de las tablas de definición

Tabla 2 — Significado de cada columna en las tablas del NUC

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.

3.2 Tipos de dato en el archivo JSON

Tabla 3 — Tipos de dato

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" }

3.3 Tamaños de los campos

Tabla 4 — Formato de tamaños

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).

4Formato del NUC

4.1 Información que debe contener el NUC

Tabla 5 — Conjuntos de campos del NUC

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. Los nombres de los campos y datos que hagan referencia a información deben ingresarse respetando mayúsculas y minúsculas exactamente como se especifican.

4.2.1Schema NUCConjunto R

Campos raíz que identifican el documento NUC.

C	ID	Campo	Descripción	P	T	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 permitidos `GT` · Guatemala `PA` · Panamá

4.2.2Campos que contienen información general de la Factura ElectrónicaConjunto A

C	ID	Campo	Descripción	P	T	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 permitidos `FACT` · Factura `FACM` · Factura Cambiaria `FPEQ` · Factura Pequeño Contribuyente `FCAP` · Factura Cambiaria Pequeño Contribuyente `FESP` · Factura Especial Ver los 17 valores →
`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.3Catálogo de atributos Info en AdditionalIssueDocInfoConjunto A

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

C	ID	Campo	Descripción	P	T	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.3Campos que contienen información del EmisorConjunto B

C	ID	Campo	Descripción	P	T	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.1Catá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	P	T	Tam	Ocu	Observaciones
`B`	`BI01`	`AfiliacionIVA`	Régimen de IVA del emisor.	`B031`	A	`3`	1-1	Valores permitidos `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 permitidos `1674` · Intermediario bovino

4.3.2Frases 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	P	T	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.4Campos que contienen información del ReceptorConjunto C

C	ID	Campo	Descripción	P	T	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.1Catálogo DestinodelaVenta (TaxIDAdditionalInfo del receptor)Conjunto C

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

C	ID	Campo	Descripción	P	T	Tam	Ocu	Observaciones
`C`	`CI01`	`DestinodelaVenta`	Destino comercial de la venta.	`C071`	A	`—`	0-1	Valores permitidos `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.5Campos que describen los ÍtemsConjunto D

C	ID	Campo	Descripción	P	T	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 permitidos `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 permitidos `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.1Catá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	P	T	Tam	Ocu	Observaciones
`D`	`DI01`	`CodigoProducto`	Código de producto regulado.	`D031`	A	`1-20`	1-1	Valores permitidos `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.6Campos que describen los TotalesConjunto E

C	ID	Campo	Descripción	P	T	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.7Campos de Información Adicional del documento (Complementos y Adenda)Conjunto F

C	ID	Campo	Descripción	P	T	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 permitidos `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 permitidos `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.1Grupo Información Adicional Data ComplementosConjunto 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	P	T	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.2Grupo Información Adicional Info ComplementosConjunto 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	P	T	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.3Grupo Información Adicional Data AdendaConjunto 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	P	T	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.4Grupo Información Adicional Info AdendaConjunto F

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

C	ID	Campo	Descripción	P	T	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

5Respuesta de la API

Al enviar el contenido del NUC, se obtiene como respuesta un objeto JSON que tiene la siguiente estructura.

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 dentro de la Respuesta

Tabla 8 — Códigos de respuesta de la API

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 de Estado HTTP

Tabla 9 — Códigos de estado HTTP

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

1Funcionamiento

2Arquitectura

Endpoint a consumir

Query Params

3Convenciones utilizadas en el formato JSON

3.1 Columnas de las tablas de definición

3.2 Tipos de dato en el archivo JSON

3.3 Tamaños de los campos

4Formato del NUC

4.1 Información que debe contener el NUC

4.2.1Schema NUCConjunto R

4.2.2Campos que contienen información general de la Factura ElectrónicaConjunto A

4.2.3Catálogo de atributos Info en AdditionalIssueDocInfoConjunto A

4.3Campos que contienen información del EmisorConjunto B

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

4.3.2Frases tributarias (AdditionlInfo del emisor)Conjunto B

4.4Campos que contienen información del ReceptorConjunto C

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

4.5Campos que describen los ÍtemsConjunto D

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

4.6Campos que describen los TotalesConjunto E

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

4.7.1Grupo Información Adicional Data ComplementosConjunto F

4.7.2Grupo Información Adicional Info ComplementosConjunto F

4.7.3Grupo Información Adicional Data AdendaConjunto F

4.7.4Grupo Información Adicional Info AdendaConjunto F

5Respuesta de la API

Donde:

5.1 Códigos dentro de la Respuesta

5.2 Códigos de Estado HTTP