Quick Start (Inicio rápido)

¿Qué es el API del Catálogo?

El API del Catálogo de Servicios del Estado Dominicano es una interfaz que permite a instituciones y desarrolladores consultar, integrar y utilizar la información de los servicios públicos registrados en el Catálogo.

Su objetivo es facilitar la interoperabilidad entre plataformas del Estado y sistemas externos, permitiendo que los datos del catálogo estén disponibles de forma segura, estructurada y actualizada.

¿Para qué sirve?

¿Qué ofrece el API?

¿Quiénes lo pueden usar?

¿Qué necesitas para empezar?

  1. Credenciales de acceso (API Keys u otro método, según el caso).

  2. Revisar la Guía de Inicio Rápido (Quick Start) para probar tu primera consulta.

  3. Acceder a Rapidocus para explorar y probar los endpoints de forma interactiva.

  4. Consultar la Referencia Técnica (OpenAPI) para ver todos los endpoints disponibles.

Notas importantes

Cómo obtener acceso (credenciales, entorno)

Para poder utilizar el API del Catálogo de Servicios del Estado Dominicano, es necesario solicitar credenciales y configurar tu entorno de acceso.

De forma predeterminada, todos los datos del catálogo están protegidos y solo algunos endpoints básicos son públicos.

1. Solicitar un usuario y credenciales

Antes de poder autenticarte en el API, debes solicitar un usuario institucional:

  1. Enviar una solicitud a la División de Arquitectura de OGTIC

    • Especifica el proyecto o sistema que consumirá el API.

    • Indica el responsable técnico de la integración.

    • Proporciona un correo de contacto institucional.

  2. Recibirás credenciales de acceso que incluyen:

    • Usuario y contraseña inicial.

    • Instrucciones para generar tu primer token de acceso.

    • Enlace al entorno de pruebas y, posteriormente, al entorno de producción.

2. Configurar tu entorno de desarrollo

Una vez recibidas tus credenciales:

  1. Accede al entorno de pruebas (sandbox) para validar tus integraciones.
    La dirección base (base URL) será indicada en el correo de la OGTIC.


    Ejemplo:

    https://catalogo-staging-1062351960128.us-east1.run.app/

     

  2. Genera un token de acceso (siguiendo la guía de Autenticación).
    Este token será necesario para consumir cualquier endpoint protegido.

  3. Usa herramientas como Postman o cURL para probar tus primeras solicitudes antes de integrar en tu sistema.

3. Pasar a producción

Cuando tus pruebas en sandbox estén aprobadas:

  1. Solicita a OGTIC la habilitación de tu usuario para producción.

  2. Recibirás:

    • Nueva URL base para producción.

    • Límites y parámetros de consumo (según los SLA vigentes).

    • Credenciales actualizadas si es necesario.

Notas importantes

Tu primera consulta (ejemplos prácticos)

En este paso realizarás tu primera consulta exitosa al API del Catálogo para obtener la lista de servicios. Aquí tienes ejemplos.

🔐 Requisitos previos

  1. Ya tienes un token de acceso válido (consulta Obtener acceso)  
  2. Estás usando correctamente el entorno sandbox o producción, según corresponda

REST API y los Datos relacionales

De forma predeterminada, Catalogo solo recupera el valor de referencia de un campo relacional en los elementos. Para recuperar también datos anidados de un campo relacional, se puede utilizar el parámetro fields en REST. Esto le permite recuperar datos referenciados de un servicio.

Para definir el ámbito de los campos que se devuelven por tipo de colección, puede usar la sintaxis <field>:<scope> del parámetro fields de la siguiente manera:

GET /items/services
	?fields[]=name
	&fields[]=description
	&fields[]=legal_framework_ids.description
	&fields[]=services_electronic_gov_type_ids.electronic_gov_type_id.type

Otra alternativa seria:

GET /items/services
	?fields[]=name,description,legal_framework_ids.description,services_electronic_gov_type_ids.electronic_gov_type_id.type

Al usar la API de REST para leer varios elementos mediante filtros (muy) avanzados, es posible que se encuentre con el problema de que la dirección URL simplemente no puede contener suficientes datos para incluir la estructura de consulta completa. En esos casos, puede usar el método HTTP SEARCH como reemplazo directo de GET, donde se le permite colocar la consulta en el cuerpo de la solicitud de la siguiente manera:

Antes:

GET /items/services?filter[name][_eq]=Hello World

Después:

SEARCH /items/services

{
	"query": {
		"filter": {
			"name": {
				"_eq": "Hello World"
			}
		}
	}
}

Hay mucha discusión sobre si se debe o no poner un cuerpo en una solicitud GET, usar POST para crear consultas de búsqueda o confiar en un método completamente diferente. A partir de ahora, hemos optado por alinearnos con la especificación del método HTTP SEARCH de IETF.

Lectura útil:

Códigos de error

A continuación, se muestran los códigos de error globales utilizados en Catalogo y lo que significan.

Código de error Estado Descripción
FAILED VALIDATION 400 Error en la validación de este elemento en particular
FORBIDDEN 403 No se le permite realizar la acción actual
INVALID_TOKEN 403 El token proporcionado no es válido
TOKEN_EXPIRED 401 El token proporcionado es válido, pero ha caducado
INVALID_CREDENTIALS 401 El nombre de usuario/contraseña o el token de acceso son incorrectos
INVALID IP 401 Su dirección IP no está en la lista de permitidos para ser utilizada con este usuario
INVALID_OTP 401 Se proporcionó una OTP incorrecta
INVALID_PAYLOAD 400 La carga útil proporcionada no es válida
INVALID_QUERY 400 No se pueden utilizar los parámetros de consulta solicitados
UNSUPPORTED_MEDIA_TYPE 415 El formato de carga útil o el encabezado proporcionados no son compatibles Content-Type
REQUESTS_EXCEEDED 429 Alcanza el límite de velocidad
ROUTE_NOT_FOUND 404 El punto de conexión no existe
SERVICE_UNAVAILABLE 503 No se pudo usar el servicio externo
UNPROCESSABLE_CONTENT 422 Intentaste hacer algo ilegal

Seguridad

Para evitar que se filtren los elementos existentes, todas las acciones de los elementos no existentes devolverán un error FORBIDDEN.

Para conocer más sobre los items, consultas y filtrado en catalogo visita los enlaces correspondientes.