# API Reference — Costa Rica (doc V1.3.0)

> Documentación técnica de la API REST para certificar, anular y consultar DTE en el régimen FEL ante Ministerio de Hacienda — Dirección General de Tributación (Ministerio de Hacienda).


## Ambientes

- **Test:** `https://testnuccr.digifact.com/api` — corriendo **V0.6.17-rc.1**
- **Producción:** `https://nuccr.digifact.com/api` — corriendo **V0.6.16**

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

## Soporte

- **Email:** soporte@digifact.com.cr
- **Teléfono:** undefined

---

## Endpoints

### POST · Obtención del TOKEN (Get Token)

El primer paso es la obtención del TOKEN, este se utilizará como forma de autenticación para las peticiones. Para obtener el Token deberá agregar en el Body/Cuerpo de la solicitud, los atributos: Username, y el Password, proporcionado en las credenciales, enviados en formato JSON. Donde Username será la concatenación siguiente, separada por punto (.): CR + "." + <identificador tributario> + "." + <Nombre de usuario>.

**URL Test:** `https://testnuccr.digifact.com/api/login/get_token`
**URL Prod:** `https://nuccr.digifact.com/api/login/get_token`

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `Username` | string | Sí | Concatenación separada por punto (.): CR + "." + <identificador tributario> + "." + <Nombre de usuario> | `CR.3102891411.USER_TEST` |
| `Password` | string | Sí | Password brindado en las credenciales TEST o Productivas según sea el caso | — |

#### Body de ejemplo (JSON)

```json
{
  "Username": "CR.3102891411.USER_TEST",
  "Password": "<password de las credenciales>"
}
```

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `Token` | string | Token generado. Tendrá una fecha de expiración que empieza a partir del momento que se solicita. |

#### Ejemplo de Respuesta

```http

```

#### Notas

- ℹ️ Solicitar credenciales TEST a través del correo de soporte soporte@digifact.com.cr brindando su nombre, nombre o razón social de la empresa que representa y un número de contacto, colocando como Asunto: "Solicitud de credenciales TEST".
- ⚠️ El token generado tendrá una fecha de expiración que empieza a partir del momento que se solicita. Una vez se haya vencido el token la API mostrará como respuesta a cualquier petición el mensaje con el código de error 401 o Unauthorized. Y será necesario generar un nuevo token para poder realizar consultas autorizadas a la API.
- ℹ️ El token se deberá agregar como encabezado en la petición, ingresando el nombre de Authorization y en su valor el Token vigente.

---

### POST · CERTIFICATE XML (Certificar XML)

Esta operación permitirá certificar un documento electrónico utilizando el formato NUC. La operación CERTIFICATE, hará todas las validaciones que la entidad tributaria ha normado tanto en su documentación técnica.

**URL Test:** `https://testnuccr.digifact.com/api/cert/xml`
**URL Prod:** `https://nuccr.digifact.com/api/cert/xml`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Content-type` | Sí | Según sea el caso, application/xml o application/json |
| `Authorization` | Sí | Token vigente |

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `TAXID` | — | Sí | NIT del usuario. | `3102891411` |
| `FORMAT` | — | Sí | Posibles valores: XML, PDF, HTML. Se deben ingresar separados por pipelines "\|" por ejemplo PDF\|HTML\|XML | — |
| `USERNAME` | — | Sí | Usuario asignado de Test o Productivo según sea el caso. | `TestUser` |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `BODY (raw)` | — | Sí | De acuerdo con la documentación proporcionada del NUC de Costa Rica, según el formato elegido, ya sea XML o JSON. | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `code` | string | contiene el código de la respuesta obtenida |
| `message` | string | contiene un mensaje informativo relacionado a la respuesta |
| `description` | string | descripción adicional del mensaje |
| `responseData1` | string | texto codificado en base64 del xml del documento enviado |
| `responseData2` | string | texto codificado en base64 que contiene la factura el formato HTML |
| `responseData3` | string | texto codificado en base64 que contiene la factura el formato PDF |
| `authNumber` | string | Identificador único del documento |
| `url` | string | Contiene el enlace para consultar el documento en el portal de hacienda |
| `infoDetails` | array | atributo tipo arreglo de objetos que, cuando la respuesta es un error, muestra el listado de errores que contiene el NUC. |
| `suggestedFileName` | string | nombre sugerido para nombrar y guardar el contenido de la información que contiene el responseData1, responseData2, responseData3 o algún otro documento relacionado con la información de la factura emitida. |
| `suggestedFileName2` | string | otro nombre sugerido |
| `batch` | string | atributo sin valor por el momento |
| `serial` | string | atributo sin valor por el momento |
| `issuedTimeStamp` | string | fecha de emisión de la factura electrónica |
| `taxID` | string | Identificador del contribuyente emisor del documento |
| `name` | string | nombre o razón social del emisor |
| `branchCode` | string | código de establecimiento o sucursal donde fue emitida la factura, atributo sin valor por el momento |
| `branchName` | string | nombre comercial, atributo sin valor por el momento |
| `receiverTaxID` | string | identificador del receptor/comprador, atributo sin valor por el momento |
| `receiverName` | string | nombre o razón social del receptor |
| `discounts` | string | indica el total de descuentos aplicados a la factura, atributo sin valor por el momento |
| `taxes` | string | indica el total de impuestos aplicados a la factura, atributo sin valor por el momento |
| `subtotal` | string | subtotal de la factura, atributo sin valor por el momento |
| `totalAmount` | string | monto total de la factura, atributo sin valor por el momento |
| `enrolledTimeStamp` | string | fecha y hora de certificación de la factura |
| `backprocessor` | string | servidor que realiza la consulta |
| `additionalInfo` | object | Atributo tipo objeto que contiene información adicional sobre la factura emitida. Sin valores por el momento. |

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Únicamente funciona con credenciales productivas cuando se da de alta a un NIT en nuestros sistemas.
- ℹ️ El contenido de la petición para el proceso de certificación es el mismo tanto si se utiliza formato NUC XML o JSON.
- ℹ️ Ejemplo de URL: https://testnuccr.digifact.com/api/cert/json?TAXID=3102891418&FORMAT=XML|HTML

---

### POST · CERTIFICATE JSON (Certificar JSON)

Esta operación permitirá certificar un documento electrónico utilizando el formato NUC en JSON. La operación CERTIFICATE, hará todas las validaciones que la entidad tributaria ha normado tanto en su documentación técnica. El contenido de la petición es el mismo tanto si se utiliza formato NUC XML o JSON.

**URL Test:** `https://testnuccr.digifact.com/api/cert/json`
**URL Prod:** `https://nuccr.digifact.com/api/cert/json`

#### Headers

| Nombre | Requerido | Descripción |
|---|---|---|
| `Content-type` | Sí | Según sea el caso, application/xml o application/json |
| `Authorization` | Sí | Token vigente |

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `TAXID` | — | Sí | NIT del usuario. | `3102891411` |
| `FORMAT` | — | Sí | Posibles valores: XML, PDF, HTML. Se deben ingresar separados por pipelines "\|" por ejemplo PDF\|HTML\|XML | — |
| `USERNAME` | — | Sí | Usuario asignado de Test o Productivo según sea el caso. | `TestUser` |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `BODY (raw)` | — | Sí | De acuerdo con la documentación proporcionada del NUC de Costa Rica, según el formato elegido, ya sea XML o JSON. Ver en sección Formato del NUC. | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `code` | string | contiene el código de la respuesta obtenida |
| `message` | string | contiene un mensaje informativo relacionado a la respuesta |
| `description` | string | descripción adicional del mensaje |
| `responseData1` | string | texto codificado en base64 del xml del documento enviado |
| `responseData2` | string | texto codificado en base64 que contiene la factura el formato HTML |
| `responseData3` | string | texto codificado en base64 que contiene la factura el formato PDF |
| `authNumber` | string | Identificador único del documento |
| `url` | string | Contiene el enlace para consultar el documento en el portal de hacienda |
| `infoDetails` | array | atributo tipo arreglo de objetos que, cuando la respuesta es un error, muestra el listado de errores que contiene el NUC. |

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Únicamente funciona con credenciales productivas cuando se da de alta a un NIT en nuestros sistemas.
- ℹ️ Query Params según la documentación NUC-JSON: TAXID (Identificador válido, ejemplo: 3102891418) y FORMAT (Formatos de respuesta para visualizar la factura: XML, PDF o HTML; se pueden ingresar separados por pipelines: XML|HTML|PDF).

---

### GET · GET DOCUMENT (Obtener documento)

Operación de tipo GET, permite obtener en formatos XML, HTML o PDF un documento específico por medio de su clave.

**URL Test:** `https://testnuccr.digifact.com/api/shared/getDocument`
**URL Prod:** `https://nuccr.digifact.com/api/shared/getDocument`

#### Headers

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

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `AUTHNUMBER` | — | Sí | Codigo único del documento electrónico. | `50603102400310289141800100001010000000042100000001` |
| `FORMAT` | — | Sí | Posibles valores: XML, PDF, HTML. Se deben ingresar separados por pipelines "\|" por ejemplo PDF\|HTML\|XML | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `respuesta` | int | Código de respuesta que indica si la operación fue exitosa o no. Valores esperados: 1 – exitoso; 0 – no se encontró información / recurso inexistente |
| `codigo` | Int | En caso de que la operación no sea exitosa, indica el código de error |
| `procesador` | String | Servidor que realiza la consulta |
| `mensaje` | String | Mensaje informativo relacionado a la respuesta, en el caso de ser fallida |
| `descripcion` | String | Descripción informativa relacionada a la respuesta, en el caso de ser fallida |
| `response` | Array | Este atributo contendrá en la primera y única posición de su arreglo, el siguiente objeto { "ResponseData1", "ResponseData2", "ResponseData3" }. Nota: ResponseData1 corresponde al documento en formato XML, ResponseData2 corresponde al documento en formato HTML y ResponseData3 corresponde al documento en formato PDF. Si algún dato que se requiere en los parámetros no existe, la respuesta será un arreglo vacío. Ej. "response": [ ] |

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Únicamente funciona con credenciales productivas cuando se da de alta a un NIT en nuestros sistemas.

---

### GET · OPERACIONES SHARED (Operaciones Shared)

Operaciones de tipo GET, permitirán obtener diferente información relacionada al contribuyente, como información fiscal, información sobre facturas emitidas, reportes, etc. Operaciones disponibles: SHARED_GETDTEINFO — Permite obtener la información de un documento enviando el número de identificación única del documento electrónico; los valores para ingresar en el parámetro DATA2 son: AUTHNUMBER (corresponde a la clave del documento que se desea consultar). SHARED_GETREPORTDAILYFELALL — Permite obtener la información resumida de los comprobantes electrónicos realizados en un día específico, permitiendo filtrar el reporte por fecha, código de establecimiento, clave y tipo de documento; los valores para ingresar en el parámetro DATA2 son: FECHA (obligatorio, indica la fecha para la cual se desea obtener el reporte de los comprobantes electrónicos emitidos en ese día), ESTABLECIMIENTO (opcional, filtra por el código de establecimiento; para no aplicar este filtro, se debe dejar el valor como cadena vacía), AUTHNUMBER (opcional, filtra por el número de clave; para no aplicar este filtro, se debe dejar el valor como cadena vacía), TIPO (opcional, filtra por el tipo de comprobante electrónico; valores permitidos: 1, 2, 3, 4, 8, 9 o 10). SHARED_GETDTEINFO_BY_CONSECUTIVO — Permite obtener la información de un documento enviando el número de consecutivo del documento electrónico; los valores para ingresar en el parámetro DATA2 son: BATCH (Obligatorio, corresponde al número consecutivo del documento que se desea consultar).

**URL Test:** `https://testnuccr.digifact.com/api/shared`
**URL Prod:** `https://nuccr.digifact.com/api/shared`

#### Headers

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

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `TAXID` | — | Sí | Número de identificación tributaria | `3102891418` |
| `DATA1` | — | Sí | Indica el nombre de la operación a realizar. Valores de las operaciones disponibles: SHARED_GETDTEINFO, SHARED_GETREPORTDAILYFELALL, SHARED_GETDTEINFO_BY_CONSECUTIVO | — |
| `DATA2` | — | Sí | Parámetros que acepta la operación indicada en el campo DATA1, se separan por pipelines "\|". | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Únicamente funciona con credenciales productivas cuando se da de alta a un NIT en nuestros sistemas.
- ℹ️ Ejemplo SHARED_GETDTEINFO: https://testnuccr.digifact.com/api/shared?TAXID=123456789&DATA1=SHARED_GETDTEINFO&DATA2=AUTHNUMBER|50605022500310289141800100001010000000370100000001
- ℹ️ Ejemplo SHARED_GETREPORTDAILYFELALL: https://testnuccr.digifact.com/api/shared?TAXID=3102891418&DATA1=SHARED_GETREPORTDAILYFELALL&DATA2=FECHA|2025-09-02|ESTABLECIMIENTO||AUTHNUMBER||TIPO| — Ejemplo filtrando por número de establecimiento: https://testnuccr.digifact.com/api/shared?TAXID=3102891418&DATA1=SHARED_GETREPORTDAILYFELALL&DATA2=FECHA|2025-09-02|ESTABLECIMIENTO|001|AUTHNUMBER||TIPO|
- ℹ️ Ejemplo SHARED_GETDTEINFO_BY_CONSECUTIVO: https://testnuccr.digifact.com/api/shared?TAXID=123456789&DATA1=SHARED_GETDTEINFO_BY_CONSECUTIVO&DATA2=BATCH|00100010040000010080

---

### GET · RECEPCIÓN GET DOCUMENT (Recepción: obtener documento)

Operación de tipo GET, permite obtener un comprobante en formato XML según el número de clave. Las operaciones de recepción son específicamente para la recepción de comprobantes electrónicos.

**URL Test:** `https://testnuccr.digifact.com/api/recepcion/getDocument`
**URL Prod:** `https://nuccr.digifact.com/api/recepcion/getDocument`

#### Headers

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

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `AUTHNUMBER` | — | Sí | Codigo único del documento electrónico. | `50603102400310289141800100001010000000042100000001` |
| `FORMAT` | — | Sí | Posibles valores: XML | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `respuesta` | int | Código de respuesta que indica si la operación fue exitosa o no. Valores esperados: 1 – exitoso; 0 – no se encontró información / recurso inexistente |
| `codigo` | Int | En caso de que la operación no sea exitosa, indica el código de error |
| `procesador` | String | Servidor que realiza la consulta |
| `mensaje` | String | Mensaje informativo relacionado a la respuesta, en el caso de ser fallida |
| `descripcion` | String | Descripción informativa relacionada a la respuesta, en el caso de ser fallida |
| `response` | Array | Este atributo contendrá en la primera y única posición de su arreglo, el siguiente objeto { "ResponseData1", "ResponseData2", "ResponseData3" }. Nota: ResponseData1 corresponde al documento en formato XML codificado en base64. Si algún dato que se requiere en los parámetros no existe, la respuesta será un arreglo vacío. Ej. "response": [ ] |

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Únicamente funciona con credenciales productivas cuando se da de alta a un NIT en nuestros sistemas.

---

### GET · RECEPCIÓN CONSULTA (Recepción: consulta de documentos)

Operación de tipo GET, permite obtener el detalle de los documentos electrónicos según los parámetros que se agreguen.

**URL Test:** `https://testnuccr.digifact.com/api/recepcion/consulta`
**URL Prod:** `https://nuccr.digifact.com/api/recepcion/consulta`

#### Headers

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

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `FECHAINICIAL` | — | Sí | *requerido. Corresponde a la fecha de inicio de los documentos a consultar | `2025-06-01 00:00:00` |
| `FECHAFINAL` | — | Sí | *requerido. Corresponde a la fecha final de los documentos a consultar | `2025-07-01 00:00:00` |
| `STAXID` | — | No | Filtro según el identificador tributario del emisor en el documento de compra | — |
| `TIPODOC` | — | No | Filtro según tipo el tipo de comprobante electrónico. Valores esperados: 1: Factura electrónica; 2: Nota de débito electrónica; 3: Nota de crédito electrónica; 4: Tiquete electrónico; 8: Factura electrónica de compras; 9: Factura electrónica de exportación; 10: Recibo electrónico de pago | — |
| `AUTHNUMBER` | — | No | Filtro por clave | `50603102400310289141800100001010000000042100000001` |
| `STATUSFILTER` | — | No | Filtro según estado de aceptación del documento. Valores esperados: ACEPTADO, RECHAZADO, ACEPTADO PARCIALMENTE | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Únicamente funciona con credenciales productivas cuando se da de alta a un NIT en nuestros sistemas.

---

### POST · RECEPCION XML (Recepción XML)

Operación POST que permite recibir y procesar un documento electrónico (XML) de un emisor externo, validar su estructura, firma digital y almacenarlo en el sistema de recepción. Este endpoint recibe el XML completo de un documento electrónico emitido por un tercero (proveedor) y dirigido al destinatario autenticado (comprador). El sistema realiza las siguientes validaciones y operaciones: 1. Validación de estructura XML (XML bien formado). 2. Identificación de namespace y detección del tipo de documento. 3. Validación de esquema XSD contra los esquemas oficiales de Costa Rica (v4.3 / v4.4). Tipos de Documento Soportados: Factura Electrónica (FE), Nota de Débito Electrónica (ND), Nota de Crédito Electrónica (NC), Tiquete Electrónico (TE), Factura Electrónica de Compra (FEC), Factura Electrónica de Exportación (FEE), Recibo Electrónico de Pago (RE).

**URL Test:** `https://testnuccr.digifact.com/api/recepcion/receive`
**URL Prod:** `https://nuccr.digifact.com/api/recepcion/receive`

#### Headers

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

#### Query Params

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `AUTO_ACCEPT` | — | No | Opcional: Genera automáticamente un recibo de aceptación/rechazo (Mensaje Receptor) para el documento recibido tras su almacenamiento correcto. Valores esperados: 0 = Aceptado, 1 = Rechazado, 2 = Aceptado parcialmente. Si se omite o está vacío, el documento se almacena sin generar recibo. Cualquier otro valor generará un error 400. | — |

#### Body

| Nombre | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
| `Content` | Raw XML | Sí | XML completo del documento electrónico tal como fue emitido por el proveedor, incluyendo la firma digital (ds:Signature). El XML debe cumplir con los esquemas XSD oficiales de Costa Rica (v4.3 o v4.4). | — |

#### Respuesta

| Campo | Tipo | Descripción |
|---|---|---|
| `code` | Int | Código de respuesta. 1 = exitoso, 0 = error |
| `message` | String | Mensaje informativo relacionado con la respuesta |
| `description` | String | Descripción adicional del resultado |
| `data` | Object | Contiene los detalles del resultado del procesamiento. Atributos del objeto data en respuesta exitosa: Clave (String, Clave única del documento procesado, 50 dígitos), DocumentGUID (String, GUID único asignado al documento en el sistema), S3Key (String, Ruta de almacenamiento en S3 donde se guardó el XML), TipoDocumento (String, Nombre legible del tipo de documento), Receptor (String, Número de identificación tributaria del receptor), Emisor (String, Número de identificación tributaria del emisor), Total (Decimal, Monto total del documento), FechaProcesamiento (DateTime, Marca de tiempo UTC de cuándo se procesó el documento). Atributos del objeto data en respuesta de error: TipoError (String, Categoría del error), Mensaje (String, Descripción del error legible para el usuario), Clave (String, Clave del documento si está disponible, null en caso contrario), Detalles adicionales (String, Detalles técnicos para depuración), Errores (Array, Lista de errores de validación XSD, solo para fallos de validación XSD). |

#### Ejemplo de Respuesta

```http

```

#### Notas

- ⚠️ Solicitar credenciales. Esto solo funciona con credenciales de producción cuando un NIT está registrado en nuestros sistemas.
- ℹ️ Ejemplos de solicitud (Reception Auto Accept): Solo se guarda el documento (sin recibo): POST https://testnuccr.digifact.com/api/recepcion/receive — Almacenar y aceptar automáticamente: POST https://testnuccr.digifact.com/api/recepcion/receive?AUTO_ACCEPT=0 — Almacenar y rechazar automáticamente: POST https://testnuccr.digifact.com/api/recepcion/receive?AUTO_ACCEPT=1 — Almacenar y aceptar parcialmente: POST https://testnuccr.digifact.com/api/recepcion/receive?AUTO_ACCEPT=2
- 🚫 Códigos de error (TipoError / Descripción / Causa): Validación XML / Estructura XML inválida / El contenido del body no es un XML bien formado. Tipo de documento no soportado / Tipo de documento no soportado / El namespace no coincide con ningún tipo de documento soportado, o es un mensaje de Hacienda. Configuración XSD / Archivo XSD no encontrado / El archivo XSD para el tipo de documento/versión no existe en el servidor. Validación XSD / Falló la validación del esquema XSD / El XML no cumple con el esquema XSD oficial; el array Errores contendrá los errores específicos de validación con línea y posición. Validación de firma / Firma digital ausente / El XML no contiene un elemento ds:Signature. Validación de NIT / NIT del receptor no encontrado / El NIT del receptor (de Receptor/Identificacion/Numero) no está registrado en Digifact. Documento duplicado / El documento ya existe / Un documento con la misma Clave ya fue procesado anteriormente para este receptor.

---