API de Progreso del Jugador
Esta página presupone las reglas comunes en Convenciones de la API — autenticación, los dos formatos de error, lotes y resolución de identidad. Aquí queda solo lo específico del progreso.
La escalera de niveles la configura su empresa: cuántos niveles, los nombres, qué exige cada uno y cómo se ve cada uno. Esta API devuelve lo que esté configurado — no conoce ninguna escalera específica.
Cómo funciona
- Usted recibe una API Key con el alcance
progress:read - Su backend consulta uno o varios colaboradores (por CPF o correo)
- SalesOS responde con la escalera una sola vez arriba, y luego el estado de cada persona
Autenticación
Referencia del endpoint
progress_status.
Esquema de la solicitud
string
requerido
Debe ser
"progress_status"array
requerido
Lista de referencias de colaboradores (máximo 500)
string
Período del XP y del ranking:
daily, weekly, monthly o all_time. Ausente = all_time.string
Universo del ranking:
tenant (toda la empresa) u org_unit (la unidad de la propia persona). Ausente = tenant.Ejemplo
Campos
La escalera (nivel superior)
Por colaborador
Cuánto falta para el siguiente nivel
Cada requisito denext_level.requirements trae la regla y el progreso de la persona. Es lo que permite escribir “20 ventas, faltan 10” sin hacer cuentas de su lado:
- El número es el mismo que SalesOS usa para promover a la persona: la pantalla nunca discrepa del nivel.
- Un nivel puede tener más de un requisito. La persona sube cuando todos están con
met: true. - Los requisitos se configuran por empresa. Arme la pantalla a partir de
typey deevent_types, sin fijar “ventas” en su código. - Un tipo de requisito que la API todavía no mide viene solo con la regla, sin
current. Trátelo como “sin medida”, no como cero. level.requirementstrae la misma medida para el nivel actual. Quien está en la cima no tienenext_level, y es ahí donde el total sigue apareciendo.- El nivel es el peldaño actual de la persona en la escalera, el mismo de la app, y no depende del
period. Los conteos son siempre acumulados. Elperiodsolo cambia el XP y el ranking. - El nivel se recalcula cuando llega la próxima actividad de la persona. Por eso, por unos instantes,
next_levelpuede venir conmet: trueen todo antes de que la persona suba. - Un requisito configurado de forma que no se puede medir también viene solo con la regla, sin
current.
Apariencia del nivel
La identidad visual del nivel — el color, y lo que su empresa configure — viene enappearance.
appearance.image_url es el sello del nivel, con la dirección completa del ambiente que respondió (https://api.play2sell.com/storage/... en producción, https://api-staging.play2sell.com/storage/... en staging). Use la URL tal cual.
Períodos
El XP se guarda en cuatro períodos, y la pantalla suele mostrar uno de ellos. Como “200 XP” en un diseño no dice cuál, esta API devuelve los cuatro más el que usted pidió.Ranking
Una posición solo significa algo junto a su universo, así quescope, period y total viajan siempre con ella.
Racha de días seguidos
streak indica cuántos días seguidos la persona viene sumando puntos — el ”🔥 10 días” de una pantalla de inicio. Es el mismo número de la tarjeta Consistencia de la app: las dos lecturas salen de la misma regla.
Un día cuenta cuando la persona termina el día con saldo de puntos positivo. Cualquier punto acreditado vale (misión, quiz, puntos extra). Un punto revertido deshace el día; un día solo con penalización no cuenta. El día es el de la zona horaria de la empresa (timezone, arriba en la respuesta): un punto a las 21h del domingo en Brasilia cuenta para el domingo, aunque en UTC ya sea lunes.
Aquí el cero es una medición: quien nunca sumó tiene
current: 0 y longest: 0. Una persona no encontrada (found: false) no trae streak.Manejo de errores
Vea Convenciones de la API para los dos formatos y la tabla de códigos.400 — VALIDATION_ERROR
400 — VALIDATION_ERROR
Cuerpo inválido, lote por encima de 500, CPF sin 11 dígitos, un elemento sin
cpf ni email, o period / ranking_scope desconocido.403 — FORBIDDEN
403 — FORBIDDEN
API Key válida, pero sin el alcance
progress:read.Límites de uso
Próximos pasos
API de Misiones
El progreso que genera el XP mostrado aquí
API de Campañas
Donde se gastan las monedas

