Resumen de la API
Referencia completa de la API REST de SouthGames.
La API REST de SouthGames permite integrar gamificacion y loyalty desde cualquier plataforma.
Base URL
https://southgames.ai/api/v1
Autenticacion
Todas las llamadas requieren:
Authorization: Bearer <api_key>
X-Org-Id: <org_slug>
Content-Type: application/json
Ver Autenticacion para mas detalles.
Formato de respuesta
Las respuestas exitosas devuelven los datos directamente con HTTP 200 (no hay un envoltorio data). Los endpoints de escritura incluyen ademas un campo success: true:
{ "success": true, "remainingUses": 9 }
Los endpoints de lectura devuelven el objeto o arreglo de datos tal cual:
{ "entries": [ ... ], "total": 120 }
Errores: HTTP 4xx/5xx con un cuerpo plano { error, code }:
{ "error": "Descripcion del error", "code": "ERROR_CODE" }
Endpoints
Clientes
| Metodo | Ruta | Descripcion |
|---|---|---|
| POST | /clients/register | Registrar o actualizar un cliente identificado |
| POST | /clients/register-device | Registrar un dispositivo anonimo |
| POST | /clients/heartbeat | Actualizar lastSeenAt e incrementar sesiones |
| GET | /clients/tier | Obtener tier y XP del cliente |
| POST | /clients/logout | Remover device token (cerrar sesion) |
Campanas y juegos
| Metodo | Ruta | Descripcion |
|---|---|---|
| GET | /campaigns | Listar campanas activas |
| POST | /games/play | Ejecutar una jugada |
Codigos
| Metodo | Ruta | Descripcion |
|---|---|---|
| POST | /codes/redeem | Canjear un codigo promocional |
Puntos
| Metodo | Ruta | Descripcion |
|---|---|---|
| GET | /points/balance | Consultar saldo de puntos |
| GET | /points/history | Historial de puntos |
| POST | /points/spend | Gastar puntos |
| POST | /points/earn | Ganar puntos manualmente |
Misiones
| Metodo | Ruta | Descripcion |
|---|---|---|
| GET | /missions | Listar misiones activas con progreso |
| POST | /missions/claim | Reclamar recompensa de mision completada |
Referidos
| Metodo | Ruta | Descripcion |
|---|---|---|
| GET | /referrals/code | Obtener o crear codigo de referido |
| POST | /referrals/apply | Aplicar un codigo de referido |
| GET | /referrals/status | Estado y lista de referidos |
Notificaciones
| Metodo | Ruta | Descripcion |
|---|---|---|
| GET | /notifications/in-app | Notificaciones in-app del cliente |
| POST | /notifications/in-app/events | Trackear eventos in-app (shown, dismissed, cta_click) |
| POST | /notifications/push/events | Trackear eventos push (click, dismiss) |
Eventos y journeys
| Metodo | Ruta | Descripcion |
|---|---|---|
| POST | /events/track | Trackear un evento custom |
| POST | /journeys/events | Enviar evento a journeys |
Metricas (solo lectura)
Para extraer metricas agregadas (campanas, push, codigos, puntos, ranking, tiers, journeys, marketplace) de forma programatica, ver la API de Metricas. Requiere una key con scope metrics:read.