Introducción a la API REST
Esta es la referencia técnica para desarrolladores. Si buscas la documentación de uso de la plataforma (módulos, configuración, guías), está en la documentación de usuario.
La API REST de DPOLab permite integrar los módulos de cumplimiento de privacidad en tus sistemas internos. Todos los endpoints siguen convenciones coherentes de autenticación, paginación y manejo de errores.
Esta API es para integración de tenants. No incluye endpoints de administración interna de la plataforma.
Base URL
https://api.dpolab.com/api/v1Todos los ejemplos de esta documentación usan esta URL base. En entornos de desarrollo local, reemplázala por http://localhost:3001/api/v1.
Autenticación
La API utiliza JWT Bearer Token para todos los endpoints autenticados. El token se envía en el encabezado Authorization:
Authorization: Bearer {token}El token JWT se obtiene al iniciar sesión mediante POST /auth/login. Tiene una vigencia limitada; cuando expira, el cliente debe renovarlo usando el refresh token (enviado automáticamente como cookie httpOnly).
El tenant se resuelve automáticamente desde el JWT. Nunca envíes el tenant como parámetro de URL ni en el cuerpo de la solicitud. Hacerlo no tendrá efecto — el sistema siempre usa el tenant del token.
Algunos endpoints admiten autenticación mediante API Key para integraciones server-to-server. En ese caso, envía la clave en el encabezado X-API-Key. Consulta la documentación de autenticación para más detalle.
Los endpoints públicos (formulario de consentimiento, portal ARSOP, cuestionarios compartidos) no requieren autenticación; se identifican con un token de acceso único en la URL.
Multi-tenancy
DPOLab es una plataforma multi-tenant. Cada organización opera en un tenant aislado. El aislamiento es automático: toda solicitud autenticada opera exclusivamente sobre los datos del tenant del token.
No existe forma de acceder a datos de otro tenant mediante la API de tenant. Los endpoints de administración de plataforma son independientes y no están documentados aquí.
Formato de respuesta
Todas las respuestas tienen la misma estructura:
Éxito:
{
"success": true,
"data": { ... }
}Error:
{
"success": false,
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Actividad no encontrada"
}
}El campo code es una constante en mayúsculas que puedes usar en tu código para manejar errores específicos. El campo message es un texto legible para humanos (en español).
Paginación
Los endpoints de listado usan paginación offset con los parámetros page y limit:
| Parámetro | Tipo | Default | Máximo | Descripción |
|---|---|---|---|---|
page | integer | 1 | — | Número de página |
limit | integer | 20 | 100 | Registros por página |
La respuesta incluye un objeto pagination:
{
"success": true,
"data": {
"items": [ ... ],
"pagination": {
"page": 1,
"limit": 20,
"total": 87,
"totalPages": 5
}
}
}Rate limiting
El límite de solicitudes depende de tu plan:
| Plan | Límite | Encabezado |
|---|---|---|
| Starter | 100 req/min | X-RateLimit-Remaining |
| Professional | 500 req/min | X-RateLimit-Remaining |
| Enterprise | 2.000 req/min | X-RateLimit-Remaining |
El plan Business tiene un límite intermedio, superior al de Professional. Cuando superas el límite, la API responde con HTTP 429 y el código RATE_LIMIT_EXCEEDED. El encabezado X-RateLimit-Remaining indica cuántas solicitudes te quedan en el período actual.
Códigos de error
| Código HTTP | Código de error | Descripción |
|---|---|---|
| 400 | VALIDATION_ERROR | Campos faltantes o con formato incorrecto |
| 401 | UNAUTHORIZED | Token ausente, inválido o expirado |
| 403 | FORBIDDEN | Sin permiso para realizar esta acción |
| 403 | FEATURE_DISABLED | Función no disponible en tu plan actual |
| 404 | RESOURCE_NOT_FOUND | El recurso solicitado no existe |
| 409 | CONFLICT | Estado incompatible con la operación (p. ej., recurso ya publicado) |
| 422 | VALIDATION_ERROR | Datos válidos en formato pero semánticamente incorrectos |
| 429 | RATE_LIMIT_EXCEEDED | Demasiadas solicitudes |
| 500 | INTERNAL_ERROR | Error interno del servidor |
Referencia completa
La Referencia Completa documenta todos los endpoints disponibles agrupados por módulo, incluyendo parámetros, cuerpos de solicitud y ejemplos de respuesta.