Reporta el cumplimiento de misiones desde tu sistema y consulta resultados
Conecta tu ERP con las misiones de Cody mediante su Public API. Grupo Aurora verifica cuatro ventas cruzadas de Diego Ramírez Peña en Tienda Monterrey Centro, registra el cumplimiento y consulta resultados para su tablero. Todos los datos son simulados; registrar cumplimiento no equivale a cargar un detalle de ventas.
Lectura estimada: 20 minutos · Para equipos de integración y analistas · Necesitas una credencial, una misión y personas identificadas en Cody.
¿Prefieres tenerla a la mano?
Descarga esta guía en Markdown para consultarla sin conexión, compartirla con tu equipo o dársela a tu asistente de IA para que te acompañe paso a paso.
1 · Descripción
Distingue misión, ejecución y resultado
Separar estos conceptos evita cerrar el día equivocado o duplicar el cumplimiento.
Temporada y misión
La temporada agrupa misiones; la misión define la meta, audiencia y horario. Usa season_id y challenge_id para relacionarlas.
Ejecución programada
Una ocurrencia es una ejecución concreta de la misión para una persona y una fecha. Su occurrence_id permite completar esa ejecución exacta.
Resultado y reconocimiento
El resultado registra el avance o cumplimiento. Consulta resultados, clasificaciones y recompensas sin suponer que crear uno calcula todos los demás.
Configura y supervisa en Gamificación del AMS, la consola de administración. La persona encuentra sus misiones en Inicio y Misiones del Companion, la aplicación del equipo; los líderes revisan Misiones y ranking. La audiencia y el horario influyen en lo que ve cada persona. Revisa también cómo se conecta todo.
2 · Antes de empezar
Prepara acceso, personas y la misión
Define primero qué significa cumplir y cómo lo comprobará tu sistema.
Credencial y acceso vigente
Pide una credencial para la Public API y sigue Credencial y token. Un token es la clave temporal con la que tu proceso demuestra que tiene acceso. No repetimos aquí su obtención.
La persona y sus permisos
La credencial actúa en nombre de una persona. Confirma con un administrador que puede ver y modificar los datos del flujo; tener una credencial no amplía sus permisos.
Dirección base y ejemplos
Todas las rutas parten de https://api.public.cody-tech.com. Los ejemplos usan cURL, Python y JavaScript. Configura CODY_API_URL con esta dirección y CODY_ACCESS_TOKEN con tu token vigente; reemplaza los IDs ficticios por los tuyos. Ejecuta desde un proceso seguro de tu equipo.
Ventas verificadas y equivalencias
Relaciona a Diego con su identificador en Cody y acuerda que cuatro ventas cruzadas equivalen al cumplimiento de esta misión. La venta y su detalle se verifican en tu ERP; esta API no documenta campos de transacciones en el resultado.
3 · Temporadas
Ubica o prepara la temporada
Reutiliza la temporada vigente antes de crear una nueva.
Consulta las temporadas activas
GET /gamification-season/list acepta active como booleano, skip desde 0 y limit entre 1 y 1,000; sus valores por defecto son 0 y 100. tenant_id es texto y solo se toma en cuenta para superadministradores.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-season/list?active=true&skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Consulta una temporada existente
GET /gamification-season/get/{doc_id} recibe el identificador de la temporada en la ruta. El ejemplo representa «Grupo Aurora · Cierre de octubre». Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-season/get/6710e1b0a1b2c3d4e5f60718" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Crea una temporada solo si hace falta
POST /gamification-season/create exige name, start_date y end_date, todos texto; las fechas usan formato de fecha y hora. Opcionales: active (booleano, por defecto true), display_order (entero o null) y tenant_id (texto o null). El ejemplo incluye el desfase horario de Monterrey mediante fechas UTC. Éxito: 201.
curl --fail-with-body -X POST "$CODY_API_URL/gamification-season/create" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"name": "Grupo Aurora · Cierre de octubre",
"start_date": "2026-10-01T06:00:00Z",
"end_date": "2026-11-01T05:59:59Z",
"active": true
}'4 · Misiones
Encuentra la misión y verifica su disponibilidad
La misma misión puede tener muchas ejecuciones a lo largo de la temporada.
Filtra por temporada y estatus
GET /gamification-challenge/list acepta season_id como texto y status descrito como active, locked o completed. evaluate_schedule es booleano y por defecto true: considera el horario. evaluate_audience es booleano y por defecto false: el ejemplo lo activa para considerar la audiencia de quien consulta. También admite skip, limit y tenant_id, con los mismos tipos y límites de temporadas.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-challenge/list?season_id=6710e1b0a1b2c3d4e5f60718&status=active&evaluate_schedule=true&evaluate_audience=true&skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"id": "6710f3a2c4b5d6e7f8091a2b",
"season_id": "6710e1b0a1b2c3d4e5f60718",
"name": "Venta cruzada del día",
"goal": "4",
"description": "Grupo Aurora · Completa 4 ventas cruzadas en Tienda Monterrey Centro.",
"agent_id": null,
"agent_context_action": "",
"difficulty": "medium",
"status": "active",
"stored_status": "active",
"effective_status": "active",
"schedule_open": true,
"schedule": {
"type": "daily",
"timezone": "America/Monterrey",
"start_time": "09:00",
"end_time": "21:00",
"start_date": "2026-10-01",
"end_date": "2026-10-31",
"days_of_week": [],
"day_of_month": null,
"day_of_month_range_start": null,
"day_of_month_range_end": null
},
"display_order": 0,
"orgchart_element_ids": [
"66c0d1e2f3a4b5c6d7e8f901"
]
}
]Consulta el detalle de una misión
GET /gamification-challenge/get/{doc_id} usa el identificador de la misión. No confundas este valor con el de la temporada ni con el de una ejecución. Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-challenge/get/6710f3a2c4b5d6e7f8091a2b" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Crea la misión si tu proceso administra la campaña
POST /gamification-challenge/create solo exige season_id y name como texto. Este ejemplo añade descripción, meta goal como texto ("4", no número), unidad base_unit, audiencia orgchart_element_ids como lista de textos y schedule como objeto de horario. La programación diaria usa America/Monterrey para la zona horaria. Verifica la misión en el AMS antes de usarla con el equipo. Éxito: 201.
curl --fail-with-body -X POST "$CODY_API_URL/gamification-challenge/create" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"season_id": "6710e1b0a1b2c3d4e5f60718",
"name": "Venta cruzada del día",
"description": "Diego Ramírez Peña registra el cumplimiento de 4 ventas cruzadas en Tienda Monterrey Centro.",
"base_unit": "ventas",
"goal": "4",
"orgchart_element_ids": [
"66c0d1e2f3a4b5c6d7e8f901"
],
"schedule": {
"type": "daily",
"timezone": "America/Monterrey",
"start_time": "09:00",
"end_time": "21:00",
"start_date": "2026-10-01",
"end_date": "2026-10-31",
"days_of_week": []
}
}'| Campo | Tipo y valor por defecto |
|---|---|
description, base_unit, goal, agent_context_action, difficulty | Texto; por defecto cadena vacía. |
agent_id | Texto o null; identifica al agente que acompaña la misión. |
status | Texto; por defecto active. La solicitud de creación no define una lista cerrada de valores. |
display_order | Entero; por defecto 0. |
orgchart_element_ids | Lista de identificadores de elementos del organigrama. |
schedule | Objeto o null. Admite type, timezone, start_time, end_time, start_date, end_date como textos; days_of_week como lista de textos; day_of_month como entero, lista de enteros o null; y day_of_month_range_start / day_of_month_range_end como enteros o null. |
5 · Calendario por persona
Ubica la ejecución de Diego en la fecha correcta
El calendario te dice qué ejecución debes completar.
Consulta un rango de días
GET /gamification-calendar/user/{user_id} acepta from_date y to_date, opcionales, como fechas AAAA-MM-DD. El ejemplo consulta del 21 al 27 de octubre. El rango incluye ambos días en UTC y selecciona las ejecuciones cuya ventana se cruza con ese periodo. No conviertas estos parámetros en fechas con hora.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-calendar/user/664f5f3c2f4f5e3b1c2a9d11?from_date=2026-10-21&to_date=2026-10-27" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"data": [
{
"id": "67202a3b4c5d6e7f8091a2b3",
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"scheduled_date": "2026-10-27",
"schedule_window_start": "2026-10-27T15:00:00Z",
"schedule_window_end": "2026-10-28T03:00:00Z",
"status": "completed",
"is_override": false,
"result_id": "67203a4b5c6d7e8f901a2b3c",
"override_schedule": null,
"created_at": "2026-10-01T06:00:00Z",
"updated_at": "2026-10-27T23:00:00Z",
"awarded_xp": 50
}
],
"count": 1,
"from_date": "2026-10-21",
"to_date": "2026-10-27"
}Identifica la ejecución de la venta
El calendario devuelve data, count, from_date y to_date. En cada ejecución, id es el occurrence_id; challenge_id identifica la misión y scheduled_date su día. schedule_window_start y schedule_window_end delimitan la ventana. Usa status y result_id para revisar el cumplimiento, y awarded_xp para los puntos otorgados. Busca la misión y fecha que correspondan al dato validado por tu ERP.
6 · Completar una ejecución
Completa la ocurrencia que ya identificaste
Esta es la ruta preferida cuando conoces la ejecución programada.
Consulta la ejecución concreta
GET /gamification-occurrence/get/{doc_id} permite consultar la ejecución usando su identificador. Confirma la persona, misión y fecha a partir de la respuesta real antes de registrar el cumplimiento. Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-occurrence/get/67202a3b4c5d6e7f8091a2b3" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Completa esa ejecución, sin cuerpo
POST /gamification-occurrence/{doc_id}/complete marca la ejecución como completed y crea o actualiza su resultado en una sola operación. No lleva un cuerpo de venta, monto ni puntos. Úsala en lugar de crear otro resultado cuando ya tienes occurrence_id. Éxito: 200.
curl --fail-with-body -X POST "$CODY_API_URL/gamification-occurrence/67202a3b4c5d6e7f8091a2b3/complete" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Actualiza Misiones del Companion y revisa el calendario en Gamificación del AMS. Si reportas una venta de ayer, selecciona la ejecución de ayer: no cierres automáticamente la que corresponde al día de la consulta.
7 · Reportar desde el ERP
Registra el cumplimiento validado por tu sistema
Usa un resultado directo cuando no estás completando una ocurrencia identificada.
Traduce la regla de negocio al cumplimiento
El ERP valida las cuatro ventas cruzadas de Diego. POST /gamification-result/create exige únicamente user_id como texto; para asociarlo a esta misión envía además challenge_id y status: "completed". El contrato describe in_progress, completed y lost; el campo es texto o null y su valor por defecto es in_progress. Éxito: 201.
curl --fail-with-body -X POST "$CODY_API_URL/gamification-result/create" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"status": "completed"
}'No envíes campos de venta que la ruta no define
Opcionales: tenant_id, reward_id y challenge_id son texto o null; custom_rewards es objeto o null, con value y unit como texto (por defecto cadenas vacías). No hay sales, amount, transaction_id ni occurrence_id en este cuerpo. Para credenciales normales se usa su organización, y la misión y recompensa deben pertenecer a ella.
Corrige el resultado existente cuando corresponda
GET /gamification-result/get/{doc_id} consulta un resultado. PUT /gamification-result/update/{doc_id} permite enviar tenant_id, user_id, reward_id, challenge_id y status como texto o null, y custom_rewards como objeto o null, sin campos obligatorios. Usa el identificador real del resultado en vez de crear otro para corregir el mismo registro. Ambas rutas responden 200 al actualizar o consultar el resultado.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-result/get/67203a4b5c6d7e8f901a2b3c" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Actualiza el estatus del resultado identificado
Este ejemplo usa PUT con status: "completed". La creación directa no garantiza cerrar una ejecución del calendario; si conoces esa ejecución, utiliza la ruta de completar ocurrencia.
curl --fail-with-body -X PUT "$CODY_API_URL/gamification-result/update/67203a4b5c6d7e8f901a2b3c" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"status": "completed"
}'Evita duplicados y expectativas de cálculo
Crear un resultado no recibe una clave única de la transacción del ERP. Conserva la relación entre tu registro de origen y el recurso en Cody; ante una interrupción, verifica antes de repetir la creación. No prometemos que registrar puntos manuales actualice automáticamente el ranking o el nivel.
8 · Extraer cumplimiento
Consulta resultados con el alcance correcto
El filtro de misión no sustituye los permisos para consultar al equipo.
Consulta los resultados de quien actúa
GET /gamification-result/list usa scope=own por defecto: consulta los resultados de la persona representada por la credencial. Puedes filtrar por status (in_progress, completed, lost) y challenge_id.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-result/list?scope=own&status=completed&challenge_id=6710f3a2c4b5d6e7f8091a2b&skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"id": "67203a4b5c6d7e8f901a2b3c",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"user": null,
"reward_id": null,
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"status": "completed",
"custom_rewards": {
"value": "50",
"unit": "points"
},
"created_at": "2026-10-27T23:00:00Z"
}
]Consulta resultados de la organización con el acceso adecuado
scope=tenant solicita los resultados de la organización. Usa una credencial con permisos para ese alcance y verifica el acceso con un administrador; el parámetro no otorga permisos. skip es entero desde 0 y limit es entero de 1 a 1,000, con valores por defecto 0 y 100.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-result/list?scope=tenant&status=completed&challenge_id=6710f3a2c4b5d6e7f8091a2b&skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Filtra por persona solo cuando el tipo de acceso lo permite
OpenAPI dice que user_id y tenant_id, ambos texto, solo se toman en cuenta para superadministradores; se ignoran para los demás. Este ejemplo es exclusivo para ese acceso. Una credencial normal con scope=tenant no debe asumir que user_id reduce la respuesta a Diego.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-result/list?scope=tenant&tenant_id=66a1b2c3d4e5f60718293a4b&user_id=664f5f3c2f4f5e3b1c2a9d11&status=completed&challenge_id=6710f3a2c4b5d6e7f8091a2b&skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Antes de armar el tablero
Las listas de misiones y resultados son arreglos directos. Aumenta skip por el limit solicitado hasta recibir un arreglo vacío. Los resultados incluyen user_id; el campo user puede ser null, así que relaciona los nombres con tu catálogo de personas. No hay envoltura items ni total.
Para consultar las conversaciones asociadas, usa challenge_id en Exportación de datos. Resultados de cumplimiento y conversaciones responden preguntas distintas; no cuentes cada conversación como una misión completada.
9 · Rankings
Consulta o publica una clasificación
Consulta las posiciones del equipo o publica las que calcula tu integración.
Lista las clasificaciones disponibles
GET /gamification-ranking/list acepta skip (entero desde 0), limit (entero de 1 a 1,000) y tenant_id (texto, solo para superadministradores). Valores por defecto de paginación: 0 y 100. Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-ranking/list?skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Consulta una clasificación por su identificador
GET /gamification-ranking/get/{doc_id} consulta una clasificación existente. Devuelve id, tenant_id, entries, created_at y updated_at.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-ranking/get/67205a6b7c8d9e0f123a4b5c" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"id": "67205a6b7c8d9e0f123a4b5c",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"entries": [
{
"name": "Diego Ramírez Peña",
"score": "4"
},
{
"name": "Ana Torres Vega",
"score": "3"
}
],
"created_at": "2026-10-27T23:00:00Z",
"updated_at": "2026-10-27T23:00:00Z"
}Publica una clasificación calculada por tu sistema
POST /gamification-ranking/create acepta entries, una lista de objetos cuyos valores son todos texto, y tenant_id como texto o null; no define campos obligatorios. El ejemplo usa name y score, como el ejemplo de OpenAPI: incluso el puntaje va entre comillas. No asumas que esta carga reemplaza el cálculo que aparece en cada vista del Companion. Éxito: 201.
curl --fail-with-body -X POST "$CODY_API_URL/gamification-ranking/create" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"entries": [
{
"name": "Diego Ramírez Peña",
"score": "4"
},
{
"name": "Ana Torres Vega",
"score": "3"
}
]
}'Los líderes consultan las clasificaciones en Misiones y ranking. Verifica ahí la presentación de tus datos; la especificación pública no describe cómo se selecciona cada clasificación en esa pantalla.
10 · Recompensas
Consulta los reconocimientos disponibles
Distingue crear el catálogo de una recompensa de asignarla a una persona.
Lista las recompensas
GET /gamification-reward/list usa skip, limit y tenant_id, con los mismos tipos, límites y alcance que la lista de rankings. Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-reward/list?skip=0&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Consulta una recompensa por su identificador
GET /gamification-reward/get/{doc_id} consulta una recompensa existente. Su identificador puede usarse como reward_id al registrar un resultado. Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/gamification-reward/get/67204a5b6c7d8e9f012a3b4c" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Crea un reconocimiento cuando haga falta
POST /gamification-reward/create exige name como texto. Opcionales: tenant_id (texto o null), type, image_url, base_unit (texto, por defecto cadena vacía) y amount (número, por defecto 0). badge y points son valores del ejemplo de OpenAPI, no una lista cerrada de opciones. Crear una recompensa no se la asigna automáticamente a Diego. Éxito: 201.
curl --fail-with-body -X POST "$CODY_API_URL/gamification-reward/create" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"name": "Venta cruzada · Grupo Aurora",
"type": "badge",
"amount": 50,
"base_unit": "points"
}'11 · Si algo falla
Revisa antes de repetir la solicitud
Usa el código de respuesta y el paso en que ocurrió el problema para decidir qué hacer.
| Síntoma | Qué hacer |
|---|---|
| La solicitud responde 401 | Renueva el token siguiendo la guía de autenticación. Repite una vez la consulta que falló. |
| La solicitud responde 403 | Revisa los permisos de la persona representada por la credencial y la audiencia o alcance del recurso. |
| La solicitud responde 422 | Revisa nombres, tipos y campos obligatorios. El contrato describe detail como una lista de errores con loc (campo), msg (explicación) y type (clase de error). |
| La venta quedó reportada pero la ejecución sigue pendiente | Crear un resultado directo no asegura cerrar una ocurrencia. Si conoces occurrence_id, completa esa ejecución. |
| user_id no limita los resultados a Diego | Ese filtro solo se toma en cuenta para superadministradores. Revisa scope y el tipo de acceso. |
| La misión no aparece para una persona | Verifica audiencia, temporada y horario en el AMS; no confundas una misión bloqueada con una misión inexistente. |
| El tablero se corta en 100 resultados | 100 es el valor por defecto de limit. Revisa la paginación y la forma real de respuesta antes de calcular totales. |
12 · Preguntas frecuentes
Dudas sobre ventas y cumplimiento
Define con claridad qué escribe tu integración y qué muestra Cody.
- ¿Dónde mando el monto y el folio de cada venta?
gamification-resultno define esos campos. Valida las ventas en tu ERP y registra el cumplimiento; conserva allí el detalle de origen.- ¿Completo la ocurrencia y además creo un resultado?
- Cuando conoces la ocurrencia, usa su ruta de completar: crea o actualiza el resultado en la misma operación. No hagas una segunda creación para la misma ejecución.
- ¿El calendario incluye todo el día indicado en to_date?
- Sí. El rango se compara desde las 00:00:00 del primer día hasta el final de to_date en UTC. Incluye las ejecuciones cuya ventana se cruza con ese periodo; para cortes del negocio considera el desfase con tu zona horaria.
- ¿Puedo afirmar que crear una clasificación actualiza todos los rankings del Companion?
- No con esta especificación: no documenta esa relación. Verifica la vista y el criterio de la clasificación en Misiones y ranking.
- ¿Cómo se ve el cumplimiento en Cody?
- La persona revisa su misión en el Companion y los administradores consultan el calendario en el AMS. Las recompensas y la clasificación dependen de su configuración; no se promete que cualquier resultado manual cambie todas esas vistas.
¿Necesitas ayuda?
Si el resultado no coincide con la misión esperada, comparte con soporte la ruta, fecha de la ejecución, identificadores necesarios y código de respuesta. No compartas el token ni el detalle completo de tus ventas.
El equipo de Cody