Saltar al contenido
CodyCody
Cody Academy · Public API

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.

1

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-season/list?active=true&skip=0&limit=100" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
2

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-season/get/6710e1b0a1b2c3d4e5f60718" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
3

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.

Solicitud
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.

1

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.

Solicitud
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"
Respuesta simulada de Grupo Aurora
[
  {
    "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"
    ]
  }
]
2

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-challenge/get/6710f3a2c4b5d6e7f8091a2b" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
3

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.

Solicitud
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": []
  }
}'
Otros campos opcionales al crear una misión
CampoTipo y valor por defecto
description, base_unit, goal, agent_context_action, difficultyTexto; por defecto cadena vacía.
agent_idTexto o null; identifica al agente que acompaña la misión.
statusTexto; por defecto active. La solicitud de creación no define una lista cerrada de valores.
display_orderEntero; por defecto 0.
orgchart_element_idsLista de identificadores de elementos del organigrama.
scheduleObjeto 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.

1

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.

Solicitud
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"
Respuesta simulada de Grupo Aurora
{
  "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"
}
2

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.

1

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-occurrence/get/67202a3b4c5d6e7f8091a2b3" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
2

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.

Solicitud
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.

1

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.

Solicitud
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"
}'
2

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.

3

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-result/get/67203a4b5c6d7e8f901a2b3c" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
4

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.

Solicitud
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.

1

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.

Solicitud
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"
Respuesta simulada de Grupo Aurora
[
  {
    "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"
  }
]
2

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.

Solicitud
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"
3

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.

Solicitud
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.

1

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-ranking/list?skip=0&limit=100" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
2

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-ranking/get/67205a6b7c8d9e0f123a4b5c" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada de Grupo Aurora
{
  "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"
}
3

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.

Solicitud
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.

1

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-reward/list?skip=0&limit=100" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
2

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/gamification-reward/get/67204a5b6c7d8e9f012a3b4c" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
3

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.

Solicitud
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 y qué hacer
SíntomaQué hacer
La solicitud responde 401Renueva el token siguiendo la guía de autenticación. Repite una vez la consulta que falló.
La solicitud responde 403Revisa los permisos de la persona representada por la credencial y la audiencia o alcance del recurso.
La solicitud responde 422Revisa 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 pendienteCrear un resultado directo no asegura cerrar una ocurrencia. Si conoces occurrence_id, completa esa ejecución.
user_id no limita los resultados a DiegoEse filtro solo se toma en cuenta para superadministradores. Revisa scope y el tipo de acceso.
La misión no aparece para una personaVerifica audiencia, temporada y horario en el AMS; no confundas una misión bloqueada con una misión inexistente.
El tablero se corta en 100 resultados100 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-result no 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