API Reference — Costa Rica | Digifact Developer Portal

🧪 Test

https://testnuccr.digifact.com/api

🚀 Producción

https://nuccr.digifact.com/api

ℹ️

Todas las operaciones requieren un token JWT obtenido en GET TOKEN. El token expira automáticamente — al recibir un error 401, solicitar un nuevo token.

POSTObtención del TOKENGet 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>.

TESThttps://testnuccr.digifact.com/api/login/get_token

PRODhttps://nuccr.digifact.com/api/login/get_token

Body

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

Respuesta

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

ℹ️

Solicitar credenciales TEST a través del correo de soporte [email protected] 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.

Ejemplo de Request

curl -X POST "https://testnuccr.digifact.com/api/login/get_token" \
  -d '{
  "Username": "CR.3102891411.USER_TEST",
  "Password": "<password de las credenciales>"
}'

Ejemplo de Response

json

POSTCERTIFICATE XMLCertificar 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.

TESThttps://testnuccr.digifact.com/api/cert/xml

PRODhttps://nuccr.digifact.com/api/cert/xml

Headers

Nombre	Req.	Descripción
Content-type	Req	Según sea el caso, application/xml o application/json
Authorization	Req	Token vigente

Query Params

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

Body

Nombre	Req.	Descripción
BODY (raw)	Req	De acuerdo con la documentación proporcionada del NUC de Costa Rica, según el formato elegido, ya sea XML o JSON.

Respuesta

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

⚠️

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

Ejemplo de Request

curl -X POST "https://testnuccr.digifact.com/api/cert/xml?TAXID=3102891411&FORMAT=%3CFORMAT%3E&USERNAME=TestUser" \
  -H "Content-type: <valor>" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

POSTCERTIFICATE JSONCertificar 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.

TESThttps://testnuccr.digifact.com/api/cert/json

PRODhttps://nuccr.digifact.com/api/cert/json

Headers

Nombre	Req.	Descripción
Content-type	Req	Según sea el caso, application/xml o application/json
Authorization	Req	Token vigente

Query Params

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

Body

Nombre	Req.	Descripción
BODY (raw)	Req	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

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

⚠️

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

Ejemplo de Request

curl -X POST "https://testnuccr.digifact.com/api/cert/json?TAXID=3102891411&FORMAT=%3CFORMAT%3E&USERNAME=TestUser" \
  -H "Content-type: <valor>" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

GETGET DOCUMENTObtener documento

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

TESThttps://testnuccr.digifact.com/api/shared/getDocument

PRODhttps://nuccr.digifact.com/api/shared/getDocument

Headers

Nombre	Req.	Descripción
Authorization	Req	Token vigente

Query Params

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

Respuesta

Nombre	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": [ ]

⚠️

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

Ejemplo de Request

curl -X GET "https://testnuccr.digifact.com/api/shared/getDocument?AUTHNUMBER=50603102400310289141800100001010000000042100000001&FORMAT=%3CFORMAT%3E" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

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

TESThttps://testnuccr.digifact.com/api/shared

PRODhttps://nuccr.digifact.com/api/shared

Headers

Nombre	Req.	Descripción
Authorization	Req	Token vigente

Query Params

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

Respuesta

⚠️

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

Ejemplo de Request

curl -X GET "https://testnuccr.digifact.com/api/shared?TAXID=3102891418&DATA1=%3CDATA1%3E&DATA2=%3CDATA2%3E" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

GETRECEPCIÓN GET DOCUMENTRecepció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.

TESThttps://testnuccr.digifact.com/api/recepcion/getDocument

PRODhttps://nuccr.digifact.com/api/recepcion/getDocument

Headers

Nombre	Req.	Descripción
Authorization	Req	Token vigente

Query Params

Nombre	Req.	Descripción	Ejemplo
AUTHNUMBER	Req	Codigo único del documento electrónico.	50603102400310289141800100001010000000042100000001
FORMAT	Req	Posibles valores: XML

Respuesta

Nombre	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": [ ]

⚠️

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

Ejemplo de Request

curl -X GET "https://testnuccr.digifact.com/api/recepcion/getDocument?AUTHNUMBER=50603102400310289141800100001010000000042100000001&FORMAT=%3CFORMAT%3E" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

GETRECEPCIÓN CONSULTARecepció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.

TESThttps://testnuccr.digifact.com/api/recepcion/consulta

PRODhttps://nuccr.digifact.com/api/recepcion/consulta

Headers

Nombre	Req.	Descripción
Authorization	Req	Token vigente

Query Params

Nombre	Req.	Descripción	Ejemplo
FECHAINICIAL	Req	*requerido. Corresponde a la fecha de inicio de los documentos a consultar	2025-06-01 00:00:00
FECHAFINAL	Req	*requerido. Corresponde a la fecha final de los documentos a consultar	2025-07-01 00:00:00
STAXID	Opt	Filtro según el identificador tributario del emisor en el documento de compra
TIPODOC	Opt	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	Opt	Filtro por clave	50603102400310289141800100001010000000042100000001
STATUSFILTER	Opt	Filtro según estado de aceptación del documento. Valores esperados: ACEPTADO, RECHAZADO, ACEPTADO PARCIALMENTE

Respuesta

⚠️

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

Ejemplo de Request

curl -X GET "https://testnuccr.digifact.com/api/recepcion/consulta?FECHAINICIAL=2025-06-01%2000%3A00%3A00&FECHAFINAL=2025-07-01%2000%3A00%3A00&STAXID=%3CSTAXID%3E&TIPODOC=%3CTIPODOC%3E&AUTHNUMBER=50603102400310289141800100001010000000042100000001&STATUSFILTER=%3CSTATUSFILTER%3E" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

POSTRECEPCION XMLRecepció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).

TESThttps://testnuccr.digifact.com/api/recepcion/receive

PRODhttps://nuccr.digifact.com/api/recepcion/receive

Headers

Nombre	Req.	Descripción
Authorization	Req	Token vigente

Query Params

Nombre	Req.	Descripción
AUTO_ACCEPT	Opt	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	Req.	Descripción
Content	Raw XML	Req	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

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

⚠️

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.

Ejemplo de Request

curl -X POST "https://testnuccr.digifact.com/api/recepcion/receive?AUTO_ACCEPT=%3CAUTO_ACCEPT%3E" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de Response

json

Soporte Técnico

Disponible en horario hábil para dudas durante implementación, pruebas y producción.

[email protected]

Teléfono

— opción 2

Subject recomendado: [NIT] Tipo_REST · [NIT] Tipo_GENERAL

API Reference — Costa Rica 🇨🇷

Soporte Técnico