Documentación de Organizaciones
Requiere permisos de administrador global. Estos endpoints solo están disponibles para API Keys asociadas a usuarios con rol global_admin. Permiten dar de alta organizaciones (tenants) y activarles suscripciones sin pasar por la pantalla de administración.
GET /v1/organizations
Obtiene una lista de todas las organizaciones. Solo accesible por administradores globales.
/v1/organizationsHeaders
x-api-key: TU_API_KEY_ADMIN_GLOBALEjemplos de petición
curl -X GET https://api-docmind.devol.es/v1/organizations \
-H "x-api-key: TU_API_KEY_ADMIN_GLOBAL"Respuesta exitosa
{
"message": "Organizaciones obtenidas exitosamente",
"organizations": [
{
"id": "535676fd-e173-4a22-a499-59a3ae1e1c4a",
"name": "Eroski",
"logo_url": "https://ejemplo.com/logo-eroski.png",
"status": "inactivo"
},
{
"id": "e5102043-460f-43ce-88ed-46e0877ab183",
"name": "Codorniu",
"logo_url": "https://ejemplo.com/logo-codorniu.png",
"status": "activo"
}
]
}Devuelve una lista de organizaciones con sus detalles básicos. Solo accesible por usuarios con rol de administrador global.
Respuestas de error
401 UnauthorizedAPI Key inválida o no proporcionada.
{"error": "API key inválida"}403 ForbiddenEl usuario no tiene rol de administrador global.
{"message": "No tienes permisos para acceder a esta información"}404 Not FoundNo se encontraron organizaciones.
{"error": "No se encontraron organizaciones"}500 Internal Server ErrorError interno del servidor.
{"error": "Error interno del servidor"}POST /v1/organizations
Crea una organización (tenant). El schema del cliente y sus tablas los genera automáticamente la base de datos, así que queda lista para recibir habilidades y extracciones.
/v1/organizationsHeaders
x-api-key: TU_API_KEY_ADMIN_GLOBAL
Content-Type: application/jsonBody (JSON)
{
"name": "Acme S.L.",
"logo_url": "https://ejemplo.com/logo-acme.png"
}Ejemplos de petición
curl -X POST https://api-docmind.devol.es/v1/organizations \
-H "x-api-key: TU_API_KEY_ADMIN_GLOBAL" \
-H "Content-Type: application/json" \
-d '{"name": "Acme S.L."}'Respuesta exitosa
{
"message": "Organización creada correctamente",
"organization": {
"id": "9f1c2b7e-1f2a-4c3d-8e5f-0a1b2c3d4e5f",
"name": "Acme S.L.",
"logo_url": null,
"status": "inactivo",
"schema_name": "cliente_acme_sl"
}
}La organización nace en estado inactivo: se activa al asignarle una suscripción vigente.
Respuestas de error
400 Bad RequestFalta el nombre.
{"error": "Bad Request", "message": "'name' es obligatorio"}403 ForbiddenLa API Key no es de un global_admin.
{"error": "Forbidden", "message": "Se requiere una API Key de global_admin"}409 ConflictYa existe una organización con ese nombre.
{"error": "Conflict", "message": "Ya existe una organización llamada 'Acme S.L.'"}GET /v1/organizations/{organization_id}
Detalle de una organización, incluido su schema y estado actual.
/v1/organizations/{organization_id}Headers
x-api-key: TU_API_KEY_ADMIN_GLOBALEjemplos de petición
curl https://api-docmind.devol.es/v1/organizations/9f1c2b7e-1f2a-4c3d-8e5f-0a1b2c3d4e5f \
-H "x-api-key: TU_API_KEY_ADMIN_GLOBAL"Respuesta exitosa
{
"organization": {
"id": "9f1c2b7e-1f2a-4c3d-8e5f-0a1b2c3d4e5f",
"name": "Acme S.L.",
"logo_url": null,
"status": "activo",
"schema_name": "cliente_acme_sl"
}
}Datos básicos de la organización.
Respuestas de error
403 ForbiddenLa API Key no es de un global_admin.
{"error": "Forbidden"}404 Not FoundLa organización no existe.
{"error": "Not Found", "message": "Organización no encontrada"}POST /v1/organizations/{organization_id}/subscriptions
Activa una suscripción (licencia) para la organización: páginas contratadas y periodo de vigencia. Si el periodo ya ha empezado, la organización pasa a estado activo y puede procesar extracciones.
/v1/organizations/{organization_id}/subscriptionsHeaders
x-api-key: TU_API_KEY_ADMIN_GLOBAL
Content-Type: application/jsonBody (JSON)
{
"total_pages": 5000,
"start_date": "2026-09-01",
"end_date": "2027-08-31",
"active": true
}Ejemplos de petición
curl -X POST \
https://api-docmind.devol.es/v1/organizations/{organization_id}/subscriptions \
-H "x-api-key: TU_API_KEY_ADMIN_GLOBAL" \
-H "Content-Type: application/json" \
-d '{"total_pages": 5000, "start_date": "2026-09-01", "end_date": "2027-08-31"}'Respuesta exitosa
{
"message": "Suscripción creada correctamente",
"subscription": {
"id": "3a7d9e11-...",
"cliente_id": "9f1c2b7e-...",
"total_paginas": 5000,
"paginas_consumidas": 0,
"fecha_inicio": "2026-09-01T00:00:00+00:00",
"fecha_fin": "2027-08-31T23:59:59+00:00",
"activa": true
}
}Las fechas admiten AAAA-MM-DD (se completa la hora) o ISO 8601 completo.
Respuestas de error
400 Bad RequestFaltan campos o el número de páginas no es válido.
{"error": "Bad Request", "message": "Faltan campos obligatorios: total_pages"}403 ForbiddenLa API Key no es de un global_admin.
{"error": "Forbidden"}404 Not FoundLa organización no existe.
{"error": "Not Found"}GET /v1/organizations/{organization_id}/subscriptions
Lista las suscripciones de una organización y su consumo. Acepta el parámetro de query "status" con los valores: todas, activas, programadas o historicas.
/v1/organizations/{organization_id}/subscriptionsHeaders
x-api-key: TU_API_KEY_ADMIN_GLOBALEjemplos de petición
curl "https://api-docmind.devol.es/v1/organizations/{organization_id}/subscriptions?status=activas" \
-H "x-api-key: TU_API_KEY_ADMIN_GLOBAL"Respuesta exitosa
{
"subscriptions": [
{
"id": "3a7d9e11-...",
"total_paginas": 5000,
"paginas_consumidas": 128,
"fecha_inicio": "2026-09-01T00:00:00+00:00",
"fecha_fin": "2027-08-31T23:59:59+00:00",
"activa": true
}
]
}Útil para comprobar el consumo antes de enviar lotes grandes de documentos.
Respuestas de error
403 ForbiddenLa API Key no es de un global_admin.
{"error": "Forbidden"}404 Not FoundLa organización no existe.
{"error": "Not Found"}