Resumen de la API

La API de Solução42 Console es una API RESTful que te permite gestionar compañías, usuarios, grupos y permisos de forma programática.

URL Base

Entorno	URL
Producción	https://api.console.solucao42.com.br

Todos los endpoints tienen el prefijo /v1/ para versionado.

Autenticación

Todas las solicitudes a la API (excepto login y endpoints públicos) requieren autenticación usando un token JWT:

curl https://api.console.solucao42.com.br/v1/users \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Consulta Autenticación para detalles sobre cómo obtener tokens.

Formato de Solicitud

Headers

Header	Requerido	Descripción
Authorization	Sí*	Bearer token para autenticación
Content-Type	Para POST/PUT	Siempre application/json

*No requerido para login y endpoints públicos.

Cuerpo de Solicitud

Todos los cuerpos de solicitud deben ser JSON válido:

{
  "name": "Example",
  "email": "[email protected]"
}

Formato de Respuesta

Respuestas Exitosas

Recurso individual:

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Example Resource",
  "created_at": "2024-03-01T10:30:00.000Z"
}

Lista de recursos:

{
  "total": 100,
  "quantity": 20,
  "records": [
    { "_id": "...", "name": "Resource 1" },
    { "_id": "...", "name": "Resource 2" }
  ]
}

Campo	Descripción
total	Número total de registros que coinciden con tu consulta
quantity	Número de registros en esta respuesta
records	Array de objetos de recurso

Respuestas de Error

Error de validación (422):

{
  "errors": [
    {
      "instancePath": "/email",
      "message": "must be a valid email"
    }
  ]
}

Error de lógica de negocio (400):

{
  "error": "User with this email already exists",
  "error_code": "USER_EMAIL_DUPLICATE"
}

Códigos de Estado HTTP

Código	Descripción
200	Éxito
201	Creado exitosamente
204	Éxito sin contenido (ej. eliminar)
400	Solicitud incorrecta - revisa el mensaje de error
401	No autorizado - token inválido o faltante
403	Prohibido - permisos insuficientes
404	Recurso no encontrado
422	Error de validación - revisa el array errors
429	Límite de tasa excedido
500	Error interno del servidor

Paginación

Los endpoints de lista soportan paginación:

GET /v1/users?page=2&per_page=50

Parámetro	Por defecto	Máximo	Descripción
page	1	-	Número de página (empieza en 1)
per_page	20	100	Elementos por página

Limitación de Tasa

Para proteger la API, se aplican límites de tasa:

Endpoints Disponibles

Autenticación

Método	Endpoint	Descripción
GET	/v1/auth/validate-company	Verificar si la compañía existe
POST	/v1/auth/login	Iniciar sesión con email/contraseña
POST	/v1/auth/google	Iniciar sesión con Google OAuth
POST	/v1/auth/passwordless/request	Solicitar código de inicio de sesión
POST	/v1/auth/passwordless/verify	Verificar código de inicio de sesión
POST	/v1/auth/2fa/login	Verificar token 2FA
GET	/v1/auth/sso/:slug/start	Iniciar flujo SSO
GET	/v1/auth/me	Obtener usuario actual
POST	/v1/auth/logout	Cerrar sesión

Ver API de Autenticación →

Usuarios

Método	Endpoint	Descripción
GET	/v1/users	Listar todos los usuarios
GET	/v1/users/:id	Obtener usuario por ID
POST	/v1/users/invite	Invitar nuevo usuario
POST	/v1/users/accept-invitation	Aceptar invitación
POST	/v1/users/reset-password/request	Solicitar restablecimiento de contraseña
POST	/v1/users/:id/activate	Activar usuario
POST	/v1/users/:id/deactivate	Desactivar usuario
POST	/v1/users/:id/groups	Agregar grupos al usuario
PUT	/v1/users/:id/groups	Reemplazar grupos del usuario
DELETE	/v1/users/:id/groups	Eliminar grupos del usuario

Ver API de Usuarios →

Grupos

Método	Endpoint	Descripción
GET	/v1/groups	Listar todos los grupos
GET	/v1/groups/:id	Obtener grupo por ID
POST	/v1/groups	Crear grupo
PUT	/v1/groups/:id	Actualizar grupo
DELETE	/v1/groups/:id	Eliminar grupo
POST	/v1/groups/:id/permissions	Agregar permisos
PUT	/v1/groups/:id/permissions	Reemplazar permisos
DELETE	/v1/groups/:id/permissions	Eliminar permisos

Ver API de Grupos →

Permisos

Método	Endpoint	Descripción
GET	/v1/permissions	Listar todos los permisos
GET	/v1/permissions/:id	Obtener permiso por ID
POST	/v1/permissions	Crear permiso
PUT	/v1/permissions/:id	Actualizar permiso
DELETE	/v1/permissions/:id	Eliminar permiso

Ver API de Permisos →

Códigos de Error

Códigos de error comunes que puedes encontrar:

Código de Error	Descripción
INVALID_CREDENTIALS	Email, contraseña o compañía incorrectos
UNAUTHORIZED	Token faltante o expirado
FORBIDDEN	Permisos insuficientes
VALIDATION_ERROR	Validación de solicitud fallida
NOT_FOUND	El recurso no existe
USER_EMAIL_DUPLICATE	Email ya en uso
COMPANY_NOT_FOUND	Slug de compañía no encontrado
CANNOT_DEACTIVATE_SELF	No puedes desactivar tu propia cuenta de usuario

SDKs y Bibliotecas

Aunque aún no tenemos SDKs oficiales, aquí hay recursos de la comunidad:

• Cliente JavaScript de ejemplo en nuestra guía de Primeros Pasos
• Especificación OpenAPI disponible bajo solicitud

¿Necesitas Ayuda?

• 📧 Email: [email protected]
• 📚 Guías: Consulta nuestras guías conceptuales
• 🐛 Problemas: Reporta bugs por email