Saltar al contenido principal

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 API de Progreso del Jugador permite que su backend lea dónde está cada colaborador en la gamificación de su empresa: en qué nivel está, cuánto XP tiene, cuántas monedas puede gastar, cuál es su posición en el ranking y cuántos días seguidos lleva sumando puntos. Fue hecha para la franja superior de una pantalla de inicio — la que saluda a la persona y muestra cómo va.
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

  1. Usted recibe una API Key con el alcance progress:read
  2. Su backend consulta uno o varios colaboradores (por CPF o correo)
  3. SalesOS responde con la escalera una sola vez arriba, y luego el estado de cada persona

Autenticación


Referencia del endpoint

Una acción: 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

Respuesta (200):

Campos

La escalera (nivel superior)

La cantidad de niveles es de su empresa, no una constante. Construya la pantalla a partir del arreglo. Una escalera puede tener nueve peldaños donde otra tiene diez, y ambas son correctas.

Por colaborador


Cuánto falta para el siguiente nivel

Cada requisito de next_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 type y de event_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.requirements trae la misma medida para el nivel actual. Quien está en la cima no tiene next_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. El period solo 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_level puede venir con met: true en 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 en appearance. 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.
appearance puede venir null, y null no significa “sin color”. Significa que nadie ha configurado uno todavía. En ese caso use su propio fallback, pero no fije una paleta indexada por nombre de nivel: el día en que la empresa renombre un nivel o cambie los colores, la pantalla con paleta fija seguirá mostrando la anterior, sin ningún error.
Lea el color desde la respuesta incluso cuando hoy parezca constante. Es precisamente por eso que viaja en el payload en vez de vivir en su app.

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ó.
Un período desconocido se rechaza con 400, no se responde con ceros. Una respuesta en cero haría que su pantalla afirmara que la persona no tiene XP — una ausencia que no es cierta.
Un período que nunca se midió viene ausente, no como 0. En el ejemplo anterior falta weekly: esa persona no tiene fila de puntuación semanal. En cambio daily: 0 es distinto — se midió, y dio cero.Trate los dos casos por separado. Escribir “0 XP esta semana” para un período ausente le dice a la persona que no puntuó, cuando la verdad es que nadie calculó ese período para ella.

Ranking

Una posición solo significa algo junto a su universo, así que scope, period y total viajan siempre con ella.
total es contra cuántas personas se midió la posición. “#12 de 240” se lee muy distinto de “#12 de 13” — muéstrelo.

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.
Con at_risk: true, invite a la persona a actuar: “suma hoy para mantener tus 10 días”. expires_at da el plazo exacto — cuente las horas desde él, sin cálculos de zona horaria.
Hoy sin puntos no reinicia la racha. Solo vuelve a 0 después de un día entero sin puntos. Mostrar “racha perdida” al mediodía le diría a la persona que perdió algo que aún puede salvar.
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.
Cuerpo inválido, lote por encima de 500, CPF sin 11 dígitos, un elemento sin cpf ni email, o period / ranking_scope desconocido.
API Key válida, pero sin el alcance progress:read.
Una empresa sin escalera configurada no es un error. La respuesta llega con levels: [] y estado 200.

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