Documentación de la API del Ministerio de Hacienda

Introducción

Aquí se describen los principales recursos y lineamientos para el uso de la API pública del Ministerio de Hacienda de Costa Rica. Su objetivo es facilitar la integración de aplicaciones desarrolladas por terceros, garantizando al mismo tiempo la disponibilidad, estabilidad y equidad en el acceso.

A lo largo de este documento se detallan los diferentes endpoints disponibles, los parámetros requeridos y los códigos de respuesta. También se incluyen ejemplos prácticos en cURL, lineamientos de validación, políticas de uso y límites de consumo, así como recomendaciones de buenas prácticas para evitar bloqueos y asegurar una integración eficiente.

La API pone a disposición información de contribuyentes, tipos de cambio, exoneraciones, registros agropecuarios y pesqueros, además del Catálogo de Bienes y Servicios (CABYS). Cada sección incorpora casos de prueba y orientaciones técnicas para ayudar a los desarrolladores a implementar soluciones robustas y responsables.

En caso de consultas adicionales, reportes de incidencias o solicitudes de apoyo técnico relacionadas con el uso de esta API, le invitamos a comunicarse directamente con el equipo de soporte a través del correo electrónico: facturati@hacienda.go.cr.

1. EndPoints

https://api.hacienda.go.cr/fe/ae

Permite obtener el nombre, el tipo de identificación, el régimen, la situación tributaria y las actividades económicas asociadas a un contribuyente.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/fe/ae?identificacion=2100042005"

https://api.hacienda.go.cr/indicadores/tc/dolar

Permite obtener el tipo de cambio del dólar (compra/venta). No requiere parámetros.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/indicadores/tc/dolar"

https://api.hacienda.go.cr/indicadores/tc/dolar/historico

Permite obtener el histórico del tipo de cambio diario del dólar. Requiere parámetros d (desde) y h (hasta).

Ejemplo cURL:

curl "https://api.hacienda.go.cr/indicadores/tc/dolar/historico?d=2019-12-01&h=2019-12-09"

https://api.hacienda.go.cr/indicadores/tc/euro

Permite obtener el tipo de cambio del euro en dólares y colones. No requiere parámetros.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/indicadores/tc/euro"

https://api.hacienda.go.cr/indicadores/tc

Permite obtener tipo de cambio del dólar y euro en un solo recurso.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/indicadores/tc"

https://api.hacienda.go.cr/fe/ex

Permite obtener información de exoneración. Requiere el parámetro autorizacion en formato AL-XXXXXXXX-XX.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/fe/ex?autorizacion=al-00460853-20"

https://api.hacienda.go.cr/fe/agropecuario

Permite obtener información de productores agropecuarios del MAG.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/fe/agropecuario?identificacion=2100042005"

https://api.hacienda.go.cr/fe/pesca

Permite obtener datos de productores agropecuarios, INCOPESCA y acuicultores vinculados a pesca.

Ejemplo cURL:

curl "https://api.hacienda.go.cr/fe/pesca?identificacion=2100042005"

https://api.hacienda.go.cr/fe/cabys

Permite obtener información del Catálogo de Bienes y Servicios (CABYS).

• Por descripción:

curl "https://api.hacienda.go.cr/fe/cabys?q=jugo%20de%20tomate&top=2"

• Por código:

curl "https://api.hacienda.go.cr/fe/cabys?codigo=2132100000100"

2. Políticas de uso y límites

Con el propósito de asegurar la continuidad del servicio y la igualdad de acceso, se aplican límites de consumo que permiten regular la cantidad de consultas realizadas por los usuarios.

3. Impacto de abusos y bloqueos

Las consultas excesivas o mal diseñadas pueden generar bloqueos automáticos, afectando tanto al consumidor de la API como a otros usuarios que comparten la misma red.

Causas comunes de bloqueos:

• Consultas repetitivas a un mismo registro.
• Búsquedas constantes sobre identificaciones inexistentes.
• Picos de tráfico generados por múltiples llamadas en ráfaga desde una sola acción.

Escenarios de riesgo:

• En Costa Rica, muchos usuarios comparten la misma dirección IP por temas de red de los proveedores (CGNAT). La suma de consultas puede activar los límites de protección aunque provengan de diferentes usuarios.
• En arquitecturas de nube, cientos de clientes pueden acceder desde un mismo servidor, concentrando el tráfico en una sola IP.

Recomendaciones para mitigar bloqueos:

• Usar caché local para evitar consultas innecesarias (ejemplo: el estado de un contribuyente no cambia en tiempo real).
• Espaciar las consultas y manejar los errores 429 con reintentos controlados.
• Optimizar la lógica de la aplicación para que una acción no genere múltiples solicitudes simultáneas.
• Coordinar con el ISP la posibilidad de usar IPv6 o solicitar un rango dedicado en caso de necesitar alto volumen sostenido.

4. Validación de parámetros

Cada endpoint exige parámetros específicos:

• /fe/ae → identificacion (9–12 dígitos, numérico)
• /fe/ex → autorizacion (formato AL-XXXXXXXX-XX)
• /fe/cabys → codigo (13 dígitos) o q (mínimo 3 caracteres)

Códigos de error diferenciados:

• 400 → parámetro faltante o inválido
• 404 → recurso inexistente
• 429 → límites de consumo superados

5. Casos de prueba

En los siguientes ejemplos se utiliza la opción -i de cURL, la cual permite visualizar los encabezados HTTP junto con la respuesta. Esto facilita la verificación del código de estado devuelto por la API y asegura que las solicitudes estén siendo procesadas correctamente.

6. Buenas prácticas de integración

Con el fin de garantizar la disponibilidad, estabilidad y equidad en el acceso a api.hacienda.go.cr, se han identificado patrones de consumo que exceden los límites razonables, especialmente en las consultas al estado de situación tributaria.

Si bien entendemos que algunos accesos provienen de entornos con IP compartidas (por CGNAT o arquitecturas en la nube), el principal factor de sobrecarga no está en la conectividad, sino en la lógica de integración implementada por cada desarrollador.

El monitoreo continuo realizado por el equipo técnico de la DTIC ha detectado consultas repetitivas en intervalos muy cortos que no responden a cambios reales en el estado tributario. En seguimiento al monitoreo constante del servicio, se recalcan las siguientes recomendaciones:

• Implemente caché local: el estado tributario no cambia en tiempo real. Evite consultas innecesarias.
• Espacie las consultas: distribuya las llamadas en el tiempo y maneje los errores 429 con reintentos controlados.
• Revise la lógica de su aplicación: evite que una sola acción genere múltiples llamadas en ráfaga.
• Considere alternativas de conectividad: si su aplicación requiere alto volumen sostenido, evalúe con su proveedor el uso de IPv6 o rangos dedicados.

7. Consideraciones de red

Entendemos que en escenarios donde múltiples clientes comparten un mismo servidor o dirección IP (como ocurre en entornos de nube o con CGNAT), la concurrencia de solicitudes puede ser elevada.

Se aclaran algunos puntos importantes:

• Los umbrales comunicados oficialmente y establecidos en este documento, son los que deben considerarse como referencia al diseñar e integrar aplicaciones con la API.
• El sistema cuenta con mecanismos automáticos de protección que bloquean temporalmente IPs cuando se exceden los límites, independientemente de si se trata de un solo usuario o de múltiples clientes detrás de la misma IP.
• Para evitar bloqueos, recomendamos implementar las buenas prácticas publicadas: uso de caché (para no repetir consultas a la misma identificación en intervalos cortos), distribución de las llamadas en el tiempo, y manejo adecuado de errores 429 con reintentos controlados.
• El estado de los contribuyentes no cambia en tiempo real, por lo que no es necesario realizar consultas repetitivas continuas.
• Si su aplicación atiende a múltiples clientes desde un mismo punto de salida, es fundamental regular el tráfico internamente para no superar los umbrales de la API.

Toda la información publicada en esta documentación se ofrece con el objetivo de facilitar la integración tecnológica y garantizar el acceso equitativo a los servicios. En caso de dudas, comentarios o incidencias técnicas, le invitamos a comunicarse directamente con nuestro equipo de soporte a través del correo electrónico: facturati@hacienda.go.cr.