🗃️ API Reference
El backend de Rial expone una REST API documentada con OpenAPI / Swagger. Hay dos interfaces disponibles:
Interfaces de documentación
| Interfaz | URL Producción | URL Staging |
|---|---|---|
| Redoc (lectura) | api.rial-ai.com/api/v1/docs | https://rial-backend-staging-304072319206.southamerica-east1.run.app/api/v1/docs |
| Swagger UI (interactivo) | api.rial-ai.com/api/v1/swagger | https://rial-backend-staging-304072319206.southamerica-east1.run.app/api/v1/swagger |
Redoc organiza los endpoints en módulos en el panel izquierdo. Swagger UI permite probar los endpoints directamente desde el browser.
Autenticación
JWT Bearer (autenticación de usuarios)
La mayoría de los endpoints requieren un token JWT emitido por Supabase Auth.
Authorization: Bearer <supabase-jwt-token>El token se obtiene al hacer login con Supabase (supabase.auth.signInWithPassword) y se renueva automáticamente por el cliente del frontend. Los tokens expiran después de 1 hora por defecto.
API Key (autenticación de servicio)
Algunos endpoints de integración aceptan una API Key en el header:
x-api-key: <api-key>Las API Keys se crean desde el módulo api-keys y permiten acceso programático sin necesidad de login con usuario/contraseña.
Secret Headers (endpoints internos de workers)
Los endpoints del módulo Cache solo son accesibles por los workers con el header secreto correcto:
ADMIN_METRICS_BRANDS_REFRESH_SECRET: <secret-value>Versionado
Todos los endpoints están bajo el prefijo /api/v1/. La versión actual es v1.
Módulos de la API
| Módulo | Prefijo | Descripción |
|---|---|---|
| Auth | /auth | Login, registro, refresh token |
| Users | /users | Gestión de usuarios y permisos |
| Companies | /companies | Compañías cliente |
| Brands | /brands | Marcas de cada compañía |
| Brands Settings | /brands/settings | Configuración de poses y validaciones |
| Projects | /projects | Proyectos (BATCH, FACESWAP, PRODUCT) |
| Project Images | /projects/images | SKUs e imágenes individuales |
| Uploads | /uploads | Signed URLs para subida a GCS |
| Downloads | /downloads | Inicio y completado de descargas |
| Jobs | /jobs | Polling de tareas asíncronas |
| Chats | /chats | Hilos de chat por SKU |
| Cache | /cache | Escritura de métricas admin en Redis (solo workers) |
| Metrics | /metrics | Lectura de métricas desde Redis |
| Posts | /posts | Notificaciones y publicaciones en la plataforma |
/email | Envío de emails transaccionales | |
| API Keys | /api-keys | Gestión de API Keys de servicio |
| Excel | /excel | Descarga de plantillas y reportes Excel |
Ejemplos de uso con curl
Login
curl -X POST https://api.rial-ai.com/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@empresa.cl", "password": "tu-password"}'Obtener imágenes pendientes de aprobación
curl https://api.rial-ai.com/api/v1/projects/images?statuses=PENDING_APPROVAL&limit=20 \
-H "Authorization: Bearer <jwt-token>"Aprobar una imagen
curl -X PUT https://api.rial-ai.com/api/v1/projects/images/{id}/approve \
-H "Authorization: Bearer <jwt-token>"Iniciar descarga de imágenes
curl -X POST "https://api.rial-ai.com/api/v1/downloads/project-images?projectFolderId=uuid" \
-H "Authorization: Bearer <jwt-token>"Rate Limiting
La API no tiene rate limiting agresivo en este momento, pero Cloud Run tiene límites de concurrencia configurados por instancia. En producción, el backend escala automáticamente.