# 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?**

- **Consultar servicios públicos en tiempo real**  
    Accede a información de los servicios que ofrecen las instituciones del Estado Dominicano.
- **Integrar con portales o aplicaciones**  
    Conecta datos del catálogo con portales ciudadanos, sistemas internos o aplicaciones móviles.
- **Optimizar procesos institucionales**  
    Permite a las instituciones reutilizar datos y automatizar tareas relacionadas con servicios y trámites.

---

## **¿Qué ofrece el API?**

- **Acceso a datos de servicios y trámites** (información general, estados, instituciones responsables).
- **Parámetros de búsqueda y filtrado avanzados** (por institución, tipo de servicio, estado, entre otros).
- **Formato estándar (JSON)** para fácil integración.
- **Documentación y herramientas interactivas** para desarrolladores.
- **Autenticación y control de acceso** para garantizar el uso seguro de la información.

---

## **¿Quiénes lo pueden usar?**

- **Instituciones del Estado** que necesiten integrar información del catálogo en sus portales o sistemas internos.
- **Desarrolladores** que trabajen en soluciones digitales para el sector público.
- **Sistemas ciudadanos** o portales que consulten datos oficiales del catálogo.

---

## **¿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**

> - El API es **RESTful** y devuelve datos en **formato JSON**.
> - Algunos endpoints son **públicos** y otros requieren autenticación.
> - El uso indebido o abusivo (consultas masivas sin autorización) puede generar restricciones según los **SLA (Acuerdos de Nivel de Servicio)**.

# 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:
    
    <div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="overflow-y-auto p-4" dir="ltr">`<span class="hljs-comment"><a href="https://catalogo-staging-1062351960128.us-east1.run.app/">https://catalogo-staging-1062351960128.us-east1.run.app/</a></span>`</div></div>
2. **Genera un token de acceso** (siguiendo la guía de [Autenticación](https://docs.digital.gob.do/books/manual-de-integracion-api/page/autenticacion)).  
    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**

> - **El entorno de pruebas y producción son separados**; asegúrate de usar las URLs correctas en cada fase.
> - **Los tokens expiran**; debes renovarlos periódicamente (ver [Actualizar token](https://docs.digital.gob.do/books/manual-de-integracion-api/page/autenticacion#bkmrk-recupere-nuevo-token)).
> - **El uso del API está regulado por los SLA**: evita consultas masivas sin autorización.
> - La información sobre autenticación avanzada (renovación de tokens, roles y permisos) está en el capítulo de **Autenticación**.

# 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](https://docs.digital.gob.do/books/manual-de-integracion-api/page/tokens-de-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
```

#### Método HTTP SEARCH

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](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body).

**Lectura útil**:

- [Método de búsqueda HTTP (IETF, 2021)](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body)
- [Definición de un nuevo método HTTP: HTTP SEARCH (Tim Perry, 2021)](https://httptoolkit.tech/blog/http-search-method)
- [HTTP GET con cuerpo de solicitud (StackOverflow, 2009 y en curso)](https://stackoverflow.com/questions/978061/http-get-with-request-body)
- [Uso del cuerpo de Elastic Search GET (elástico, s.f.)](https://www.elastic.co/guide/en/elasticsearch/guide/current/_empty_search.html)
- [Dropbox comienza a usar POST y por qué se trata de un diseño deficiente de la API. (Evert Pot, 2015)](https://evertpot.com/dropbox-post-api)

#### Códigos de error

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

<table id="bkmrk-c%C3%B3digo-de-error-esta"><thead><tr><th>Código de error</th><th>Estado</th><th>Descripción</th></tr></thead><tbody><tr><td>FAILED VALIDATION</td><td>400</td><td>Error en la validación de este elemento en particular</td></tr><tr><td>FORBIDDEN</td><td>403</td><td>No se le permite realizar la acción actual</td></tr><tr><td>INVALID\_TOKEN</td><td>403</td><td>El token proporcionado no es válido</td></tr><tr><td>TOKEN\_EXPIRED</td><td>401</td><td>El token proporcionado es válido, pero ha caducado</td></tr><tr><td>INVALID\_CREDENTIALS</td><td>401</td><td>El nombre de usuario/contraseña o el token de acceso son incorrectos</td></tr><tr><td>INVALID IP</td><td>401</td><td>Su dirección IP no está en la lista de permitidos para ser utilizada con este usuario</td></tr><tr><td>INVALID\_OTP</td><td>401</td><td>Se proporcionó una OTP incorrecta</td></tr><tr><td>INVALID\_PAYLOAD</td><td>400</td><td>La carga útil proporcionada no es válida</td></tr><tr><td>INVALID\_QUERY</td><td>400</td><td>No se pueden utilizar los parámetros de consulta solicitados</td></tr><tr><td>UNSUPPORTED\_MEDIA\_TYPE</td><td>415</td><td>El formato de carga útil o el encabezado proporcionados no son compatibles `Content-Type`</td></tr><tr><td>REQUESTS\_EXCEEDED</td><td>429</td><td>Alcanza el límite de velocidad</td></tr><tr><td>ROUTE\_NOT\_FOUND</td><td>404</td><td>El punto de conexión no existe</td></tr><tr><td>SERVICE\_UNAVAILABLE</td><td>503</td><td>No se pudo usar el servicio externo</td></tr><tr><td>UNPROCESSABLE\_CONTENT</td><td>422</td><td>Intentaste hacer algo ilegal</td></tr></tbody></table>

> **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](https://docs.digital.gob.do/books/manual-de-integracion-api/page/acceso-a-los-elementos), [consultas](https://docs.digital.gob.do/books/manual-de-integracion-api/page/parametros-de-consulta-global) y [filtrado](https://docs.digital.gob.do/books/manual-de-integracion-api/page/reglas-de-filtrado) en catalogo visita los enlaces correspondientes.