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

---