Sincroniza la estructura y el organigrama de tu empresa desde tu sistema
Usa la Public API de Cody para mantener al día las áreas de tu empresa, los puestos de cada una y quién los ocupa, y para consultar a quién puede asignar tareas, anunciar o comparar cada persona. En Grupo Aurora, la Región Norte de Carlos Méndez Luna incluye la Tienda Monterrey Centro, donde trabaja Diego Ramírez Peña. Los datos son simulados y siguen los campos del contrato de producción.
Lectura estimada: 18 minutos · Para equipos de integración y de recursos humanos · Necesitas una credencial y los identificadores de las personas 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
Dos árboles que describen la misma empresa
La estructura dice cómo se divide tu empresa; el organigrama dice quién ocupa cada puesto y a quién reporta.
Entidades: las áreas
Cada entidad es una parte de la empresa —dirección, región, tienda— con un parent_id que indica de qué área depende. Una entidad puede vincularse con una tienda (Store) de Cody.
Elementos: los puestos
Cada elemento del organigrama es un puesto dentro de una entidad: su name («Gerente Regional Norte»), su type («Gerencia») y las personas que lo ocupan en user_ids.
Reporta a
reports_to_element_id apunta al puesto que es el jefe directo. Puede estar en otra entidad. Con la estructura y esta línea, Cody resuelve equipos, rankings y a quién puede dirigirse cada persona.
El orden importa
Primero crea las entidades y después los puestos: un elemento siempre pertenece a una entidad existente. La guía Estructura organizacional del AMS explica los mismos conceptos desde la consola.
2 · Antes de empezar
Prepara acceso e identificadores
Todas las rutas usan la misma credencial y trabajan sobre tu organización.
Credencial y token 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.
tenant_id en la ruta
Todas las rutas empiezan con /business-structure/{tenant_id} u /orgchart/{tenant_id}. Con una credencial normal, Cody usa siempre la organización de tu token e ignora el valor de la ruta: no puedes leer ni modificar otra organización cambiándolo.
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.
Identificadores
Todos los IDs —entidades, elementos, personas (user_ids) y tiendas (store_id)— son ObjectId: texto de 24 caracteres hexadecimales, como 6720a1b2c3d4e5f607182931. Guarda cada ID que devuelve una creación para usarlo después.
Los cambios se aplican de inmediato
Mover una entidad o una persona cambia en ese momento quién ve las misiones de un área, quién recibe los anuncios dirigidos a un puesto y a quién se le pueden asignar tareas. Prueba primero con un área pequeña y revisa el resultado en el AMS.
3 · Estructura empresarial
Crea y mantén las áreas
Consulta la estructura completa, agrega áreas, renómbralas, muévelas o elimínalas.
Consulta la estructura actual
GET /business-structure/{tenant_id} devuelve todas las entidades en una lista plana, cada una con parent_id, store_id si está vinculada a una tienda y created_at. Si tu organización todavía no tiene áreas, entities llega vacía. Éxito: 200.
curl --fail-with-body -X GET "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"entities": [
{
"id": "6720a1b2c3d4e5f607182930",
"name": "Dirección Comercial",
"parent_id": null,
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
},
{
"id": "6720a1b2c3d4e5f607182931",
"name": "Región Norte",
"parent_id": "6720a1b2c3d4e5f607182930",
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
},
{
"id": "6720a1b2c3d4e5f607182932",
"name": "Tienda Monterrey Centro",
"parent_id": "6720a1b2c3d4e5f607182931",
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
},
{
"id": "6720a1b2c3d4e5f607182933",
"name": "Tienda San Pedro",
"parent_id": "6720a1b2c3d4e5f607182931",
"store_id": "66c3d4e5f60718293a4b5c6d",
"created_at": "2026-11-03T15:00:00Z"
}
],
"updated_at": "2026-11-03T16:30:00Z"
}Crea una entidad
POST /business-structure/{tenant_id}/entity exige name como texto. parent_id es opcional: sin él, el área queda en la raíz; si lo envías, debe existir o la respuesta es 404. Éxito: 201 con la entidad creada.
curl --fail-with-body -X POST "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"name": "Tienda Monterrey Centro",
"parent_id": "6720a1b2c3d4e5f607182931"
}'{
"id": "6720a1b2c3d4e5f607182932",
"name": "Tienda Monterrey Centro",
"parent_id": "6720a1b2c3d4e5f607182931",
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
}Renombra o mueve una entidad
PUT /business-structure/{tenant_id}/entity/{entity_id} acepta name y parent_id, ambos opcionales; lo que no envíes se conserva. Para mover el área, manda el parent_id de su nueva área superior; para llevarla a la raíz, manda parent_id como cadena vacía. Éxito: 200 con la entidad actualizada.
curl --fail-with-body -X PUT "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"name": "Tienda Monterrey Macroplaza"
}'{
"id": "6720a1b2c3d4e5f607182932",
"name": "Tienda Monterrey Macroplaza",
"parent_id": "6720a1b2c3d4e5f607182931",
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
}No muevas un área debajo de sí misma
Antes de cambiar parent_id, confirma que la nueva área superior no sea una de las áreas que dependen de la que mueves. Un ciclo así deja el árbol sin un camino claro hacia la raíz.
Elimina una entidad
DELETE /business-structure/{tenant_id}/entity/{entity_id} no recibe cuerpo. La respuesta es 400 si el área tiene otras áreas debajo o si está vinculada a una tienda: primero mueve o elimina sus áreas hijas y desvincula la tienda. Éxito: 200 con message e id; la frase de message no está fijada por el contrato.
curl --fail-with-body -X DELETE "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"message": "Entity deleted successfully",
"id": "6720a1b2c3d4e5f607182932"
}También se eliminan sus puestos
Al eliminar una entidad, Cody borra los elementos del organigrama que pertenecían a ella. Las personas siguen existiendo, pero dejan de ocupar esos puestos. Si solo quieres reorganizar, mueve los puestos a otra entidad antes de borrar.
4 · Vincular tiendas
Conecta un área con su tienda
Una entidad vinculada toma como personal a la gente de la tienda y lo mantiene al día.
Vincula la entidad con una tienda
POST /business-structure/{tenant_id}/entity/{entity_id}/store recibe store_id, el identificador de una tienda de tu organización (las tiendas se administran en Usuarios, roles y tiendas). Cody crea en esa entidad un puesto de tipo store con las personas de la tienda. Éxito: 200 con entity_id, store_id, orgchart_element_id (el puesto creado) y user_ids.
curl --fail-with-body -X POST "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"store_id": "66c3d4e5f60718293a4b5c6d"
}'{
"entity_id": "6720a1b2c3d4e5f607182933",
"store_id": "66c3d4e5f60718293a4b5c6d",
"orgchart_element_id": "6720b3c4d5e6f70819203a43",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d14"
]
}Administra al personal desde la tienda
Mientras la entidad esté vinculada, las personas de sus puestos siguen a la tienda: cuando cambian en la tienda, el puesto se actualiza solo. Por eso, en una entidad vinculada no puedes agregar ni quitar personas de sus puestos ni eliminarlos por API; la respuesta es 400. Cada vínculo es uno a uno: una tienda solo puede estar en una entidad y una entidad solo en una tienda.
Desvincula la tienda cuando ya no corresponda
DELETE /business-structure/{tenant_id}/entity/{entity_id}/store no recibe cuerpo. Quita el vínculo y el puesto de tipo store; no modifica las personas de la tienda. Responde 400 si la entidad no estaba vinculada. Éxito: 200 con message y entity_id.
curl --fail-with-body -X DELETE "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"message": "Entity unlinked from store",
"entity_id": "6720a1b2c3d4e5f607182933"
}5 · Puestos y personas
Arma el organigrama de cada área
Crea puestos, asigna personas, define a quién reportan y retira lo que ya no existe.
Crea un puesto
POST /orgchart/{tenant_id}/element exige entity_id y name. Las personas de user_ids deben existir y pertenecer a tu organización (404 o 400 si no). reports_to_element_id debe ser un puesto existente; related_element_id es el mismo campo con otro nombre. Éxito: 201 con el elemento.
curl --fail-with-body -X POST "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"entity_id": "6720a1b2c3d4e5f607182932",
"name": "Encargado de tienda",
"type": "Operación",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d11"
],
"reports_to_element_id": "6720b3c4d5e6f70819203a41",
"metadata": {
"turno": "matutino"
}
}'{
"id": "6720b3c4d5e6f70819203a42",
"entity_id": "6720a1b2c3d4e5f607182932",
"name": "Encargado de tienda",
"type": "Operación",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d11"
],
"related_element_id": "6720b3c4d5e6f70819203a41",
"reports_to_element_id": "6720b3c4d5e6f70819203a41",
"parent_id": null,
"metadata": {
"turno": "matutino",
"name": "Encargado de tienda",
"parent_line_1": "Gerente Regional Norte",
"parent_line_2": "Directora Comercial"
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
}Revisa los metadatos que completa Cody
metadata admite tus propias claves, como turno. Cody agrega y mantiene tres: name (el nombre del puesto), parent_line_1 (el puesto al que reporta) y parent_line_2 (el jefe de ese puesto); si envías valores propios en esas claves, se reemplazan. En puestos de áreas vinculadas a una tienda puede aparecer external_id, el código externo de la tienda.
Actualiza solo lo que cambió
PUT /orgchart/{tenant_id}/element/{element_id} cambia únicamente los campos que envías. Envía reports_to_element_id: null para quitar el «reporta a». Si envías user_ids, la lista reemplaza a las personas del puesto; si envías metadata, reemplaza tus claves propias. Éxito: 200 con el elemento actualizado.
curl --fail-with-body -X PUT "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"type": "Operación de tienda"
}'Agrega o quita personas sin reescribir la lista
POST /orgchart/{tenant_id}/element/{element_id}/users suma las personas de user_ids a las que ya ocupan el puesto; DELETE en la misma ruta, con el mismo cuerpo, las quita. Agregar a alguien que ya ocupa el puesto, o quitar a alguien que no lo ocupa, no causa error. Ambas responden 200 con el elemento.
curl --fail-with-body -X POST "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42/users" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d16"
]
}'{
"id": "6720b3c4d5e6f70819203a42",
"entity_id": "6720a1b2c3d4e5f607182932",
"name": "Encargado de tienda",
"type": "Operación",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d11",
"664f5f3c2f4f5e3b1c2a9d16"
],
"related_element_id": "6720b3c4d5e6f70819203a41",
"reports_to_element_id": "6720b3c4d5e6f70819203a41",
"parent_id": null,
"metadata": {
"turno": "matutino",
"name": "Encargado de tienda",
"parent_line_1": "Gerente Regional Norte",
"parent_line_2": "Directora Comercial"
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
}curl --fail-with-body -X DELETE "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42/users" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-raw '{
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d16"
]
}'Elimina un puesto
DELETE /orgchart/{tenant_id}/element/{element_id} no recibe cuerpo. Si otros puestos reportaban a este, revisa su reports_to_element_id después de borrarlo. Éxito: 200 con message e id.
curl --fail-with-body -X DELETE "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"message": "OrgChart element deleted successfully",
"id": "6720b3c4d5e6f70819203a42"
}6 · Consultar el organigrama
Lee el organigrama en la forma que necesitas
Elige entre la lista completa, la línea de mando o el árbol de un área con sus personas.
Descarga el organigrama completo o su línea de mando
GET /orgchart/{tenant_id} devuelve elements, la lista plana de puestos. GET /orgchart/{tenant_id}/reporting-tree devuelve los mismos puestos anidados en roots[].children, siguiendo el «reporta a»; si un puesto no lo tiene, se usa su parent_id, y si tampoco tiene, queda como raíz. Úsalo para dibujar la línea de mando sin reconstruirla.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/reporting-tree" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"roots": [
{
"id": "6720b3c4d5e6f70819203a40",
"entity_id": "6720a1b2c3d4e5f607182930",
"name": "Directora Comercial",
"type": "Dirección",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d15"
],
"related_element_id": null,
"reports_to_element_id": null,
"parent_id": null,
"metadata": {
"name": "Directora Comercial",
"parent_line_1": "",
"parent_line_2": ""
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z",
"children": [
{
"id": "6720b3c4d5e6f70819203a41",
"entity_id": "6720a1b2c3d4e5f607182931",
"name": "Gerente Regional Norte",
"type": "Gerencia",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d13"
],
"related_element_id": "6720b3c4d5e6f70819203a40",
"reports_to_element_id": "6720b3c4d5e6f70819203a40",
"parent_id": null,
"metadata": {
"name": "Gerente Regional Norte",
"parent_line_1": "Directora Comercial",
"parent_line_2": ""
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z",
"children": [
{
"id": "6720b3c4d5e6f70819203a42",
"entity_id": "6720a1b2c3d4e5f607182932",
"name": "Encargado de tienda",
"type": "Operación",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d11"
],
"related_element_id": "6720b3c4d5e6f70819203a41",
"reports_to_element_id": "6720b3c4d5e6f70819203a41",
"parent_id": null,
"metadata": {
"turno": "matutino",
"name": "Encargado de tienda",
"parent_line_1": "Gerente Regional Norte",
"parent_line_2": "Directora Comercial"
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z",
"children": []
}
]
}
]
},
{
"id": "6720b3c4d5e6f70819203a43",
"entity_id": "6720a1b2c3d4e5f607182933",
"name": "Store: Tienda San Pedro",
"type": "store",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d14"
],
"related_element_id": null,
"reports_to_element_id": null,
"parent_id": null,
"metadata": {
"name": "Store: Tienda San Pedro",
"parent_line_1": "",
"parent_line_2": ""
},
"store_id": "66c3d4e5f60718293a4b5c6d",
"created_at": "2026-11-03T15:00:00Z",
"children": []
}
],
"updated_at": "2026-11-03T16:30:00Z"
}Consulta los puestos de una persona
GET /orgchart/{tenant_id}/user/{user_id} devuelve los puestos donde aparece la persona; una misma persona puede ocupar varios. Una lista vacía significa que no está en el organigrama.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"id": "6720b3c4d5e6f70819203a42",
"entity_id": "6720a1b2c3d4e5f607182932",
"name": "Encargado de tienda",
"type": "Operación",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d11"
],
"related_element_id": "6720b3c4d5e6f70819203a41",
"reports_to_element_id": "6720b3c4d5e6f70819203a41",
"parent_id": null,
"metadata": {
"turno": "matutino",
"name": "Encargado de tienda",
"parent_line_1": "Gerente Regional Norte",
"parent_line_2": "Directora Comercial"
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
}
]Obtén el equipo completo debajo de una persona
GET /orgchart/{tenant_id}/user/{user_id}/tree devuelve, por cada puesto de la persona, subtree: su entidad y todas las entidades debajo, con las personas de cada nivel (name, email y position, el type de su puesto). Este árbol sigue la estructura de áreas, no el «reporta a».
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/tree" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"element_id": "6720b3c4d5e6f70819203a41",
"entity_id": "6720a1b2c3d4e5f607182931",
"position": "Gerencia",
"subtree": {
"entity_id": "6720a1b2c3d4e5f607182931",
"entity_name": "Región Norte",
"store_id": null,
"users": [
{
"element_id": "6720b3c4d5e6f70819203a41",
"user_id": "664f5f3c2f4f5e3b1c2a9d13",
"name": "Carlos Méndez Luna",
"email": "carlos.mendez@ejemplo.com",
"position": "Gerencia"
}
],
"children": [
{
"entity_id": "6720a1b2c3d4e5f607182932",
"entity_name": "Tienda Monterrey Centro",
"store_id": null,
"users": [
{
"element_id": "6720b3c4d5e6f70819203a42",
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"name": "Diego Ramírez Peña",
"email": "diego.ramirez@ejemplo.com",
"position": "Operación"
}
],
"children": []
},
{
"entity_id": "6720a1b2c3d4e5f607182933",
"entity_name": "Tienda San Pedro",
"store_id": "66c3d4e5f60718293a4b5c6d",
"users": [
{
"element_id": "6720b3c4d5e6f70819203a43",
"user_id": "664f5f3c2f4f5e3b1c2a9d14",
"name": "Laura Treviño Garza",
"email": "laura.trevino@ejemplo.com",
"position": "store"
}
],
"children": []
}
]
}
}
]Consulta un área: sus personas o todo lo que cuelga de ella
GET /orgchart/{tenant_id}/entity/{entity_id}/users devuelve solo las personas asignadas directamente a esa entidad; puede ser ninguna, una o varias. GET /orgchart/{tenant_id}/entity/{entity_id}/subtree devuelve el árbol recursivo desde esa entidad, con la misma forma que subtree; responde 404 si la entidad no existe.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932/users" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"element_id": "6720b3c4d5e6f70819203a42",
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"name": "Diego Ramírez Peña",
"email": "diego.ramirez@ejemplo.com",
"position": "Operación"
}
]curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182931/subtree" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"entity_id": "6720a1b2c3d4e5f607182931",
"entity_name": "Región Norte",
"store_id": null,
"users": [
{
"element_id": "6720b3c4d5e6f70819203a41",
"user_id": "664f5f3c2f4f5e3b1c2a9d13",
"name": "Carlos Méndez Luna",
"email": "carlos.mendez@ejemplo.com",
"position": "Gerencia"
}
],
"children": [
{
"entity_id": "6720a1b2c3d4e5f607182932",
"entity_name": "Tienda Monterrey Centro",
"store_id": null,
"users": [
{
"element_id": "6720b3c4d5e6f70819203a42",
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"name": "Diego Ramírez Peña",
"email": "diego.ramirez@ejemplo.com",
"position": "Operación"
}
],
"children": []
},
{
"entity_id": "6720a1b2c3d4e5f607182933",
"entity_name": "Tienda San Pedro",
"store_id": "66c3d4e5f60718293a4b5c6d",
"users": [
{
"element_id": "6720b3c4d5e6f70819203a43",
"user_id": "664f5f3c2f4f5e3b1c2a9d14",
"name": "Laura Treviño Garza",
"email": "laura.trevino@ejemplo.com",
"position": "store"
}
],
"children": []
}
]
}7 · Alcances por persona
Pregunta a Cody qué alcance tiene cada persona
En lugar de recorrer el árbol en tu sistema, consulta el alcance que Cody ya aplica en tareas, anuncios y rankings.
Cody resuelve el alcance con la estructura de áreas cuando tu organización la tiene y la persona está en ella; si no, usa el «reporta a» del organigrama. El campo mode te dice cuál se usó: entity (áreas) o element (puestos). Las respuestas de ranking-scope, management-scope y assignable-users usan nombres de campo en formato camelCase.
Compañeros con el mismo jefe
GET /orgchart/{tenant_id}/user/{user_id}/reporting-scope usa solo el «reporta a»: devuelve el puesto de la persona (own), los que le reportan (children), los que comparten su jefe (peers) y tres listas de personas: user_ids.own, team (ella y todo su equipo hacia abajo) y same_boss (ella y sus pares, sin los equipos de ellos). Esta respuesta usa nombres en snake_case.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/reporting-scope" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"own": {
"id": "6720b3c4d5e6f70819203a41",
"entity_id": "6720a1b2c3d4e5f607182931",
"name": "Gerente Regional Norte",
"type": "Gerencia",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d13"
],
"related_element_id": "6720b3c4d5e6f70819203a40",
"reports_to_element_id": "6720b3c4d5e6f70819203a40",
"parent_id": null,
"metadata": {
"name": "Gerente Regional Norte",
"parent_line_1": "Directora Comercial",
"parent_line_2": ""
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z"
},
"children": [
{
"id": "6720b3c4d5e6f70819203a42",
"entity_id": "6720a1b2c3d4e5f607182932",
"name": "Encargado de tienda",
"type": "Operación",
"user_ids": [
"664f5f3c2f4f5e3b1c2a9d11"
],
"related_element_id": "6720b3c4d5e6f70819203a41",
"reports_to_element_id": "6720b3c4d5e6f70819203a41",
"parent_id": null,
"metadata": {
"turno": "matutino",
"name": "Encargado de tienda",
"parent_line_1": "Gerente Regional Norte",
"parent_line_2": "Directora Comercial"
},
"store_id": null,
"created_at": "2026-11-03T15:00:00Z",
"children": []
}
],
"peers": [],
"user_ids": {
"own": [
"664f5f3c2f4f5e3b1c2a9d13"
],
"team": [
"664f5f3c2f4f5e3b1c2a9d13",
"664f5f3c2f4f5e3b1c2a9d11"
],
"same_boss": [
"664f5f3c2f4f5e3b1c2a9d13"
]
}
}Contra quién compite en un ranking
GET /orgchart/{tenant_id}/user/{user_id}/ranking-scope devuelve el universo de comparación: el grupo de la persona (own), el grupo superior desde el que se compara (root), todos los grupos debajo de él (subtreeIds) y sus personas (userIds). Si la persona no está en ningún árbol, mode y tree llegan como null y las listas vacías. tree es una vista para un selector, con peopleCount y descendantCount por grupo, limitada a tree_depth niveles (de 1 a 5; por defecto 2).
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?tree_depth=2" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"tenantId": "66a1b2c3d4e5f60718293a4b",
"mode": "entity",
"ownId": "6720a1b2c3d4e5f607182932",
"rootId": "6720a1b2c3d4e5f607182931",
"own": {
"id": "6720a1b2c3d4e5f607182932",
"name": "Tienda Monterrey Centro",
"type": null
},
"root": {
"id": "6720a1b2c3d4e5f607182931",
"name": "Región Norte",
"type": null
},
"subtreeIds": [
"6720a1b2c3d4e5f607182931",
"6720a1b2c3d4e5f607182932",
"6720a1b2c3d4e5f607182933"
],
"userIds": [
"664f5f3c2f4f5e3b1c2a9d13",
"664f5f3c2f4f5e3b1c2a9d11",
"664f5f3c2f4f5e3b1c2a9d14"
],
"tree": {
"id": "6720a1b2c3d4e5f607182931",
"name": "Región Norte",
"type": null,
"peopleCount": 3,
"descendantCount": 2,
"hasMoreChildren": false,
"children": [
{
"id": "6720a1b2c3d4e5f607182932",
"name": "Tienda Monterrey Centro",
"type": null,
"peopleCount": 1,
"descendantCount": 0,
"hasMoreChildren": false,
"children": []
},
{
"id": "6720a1b2c3d4e5f607182933",
"name": "Tienda San Pedro",
"type": null,
"peopleCount": 1,
"descendantCount": 0,
"hasMoreChildren": false,
"children": []
}
]
}
}Con selected_ids (IDs separados por coma) limitas userIds a las personas de esos grupos y de lo que cuelga de ellos. Los IDs fuera del universo de la persona se ignoran: el filtro solo reduce, nunca amplía.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?selected_ids=6720a1b2c3d4e5f607182932" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"Expande una rama del selector
Si un nodo de tree trae hasMoreChildren: true, pide esa rama con GET /orgchart/{tenant_id}/user/{user_id}/ranking-scope/subtree/{element_id}, donde element_id es el id del nodo, sea área o puesto. Acepta tree_depth. Responde 403 si el nodo está fuera del universo de la persona y 404 si no existe. Expandir no cambia userIds ni los conteos.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope/subtree/6720a1b2c3d4e5f607182933?tree_depth=2" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"id": "6720a1b2c3d4e5f607182933",
"name": "Tienda San Pedro",
"type": null,
"peopleCount": 1,
"descendantCount": 0,
"hasMoreChildren": false,
"children": []
}Qué equipo dirige y a quién reporta
GET /orgchart/{tenant_id}/user/{user_id}/management-scope usa la estructura de áreas. Devuelve el área de la persona (own), su área superior (parent), si dirige áreas debajo (hasChildren), las áreas de su equipo (teamIds), sus personas (teamUserIds) y quiénes ocupan el área superior (reportsToUserIds). Si tu organización arma su línea de mando solo con el «reporta a», llega scoped: false con listas vacías: usa entonces reporting-scope.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/management-scope" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"tenantId": "66a1b2c3d4e5f60718293a4b",
"mode": "entity",
"scoped": true,
"ownId": "6720a1b2c3d4e5f607182931",
"own": {
"id": "6720a1b2c3d4e5f607182931",
"name": "Región Norte",
"type": null
},
"parentId": "6720a1b2c3d4e5f607182930",
"parent": {
"id": "6720a1b2c3d4e5f607182930",
"name": "Dirección Comercial",
"type": null
},
"hasChildren": true,
"anchorId": "6720a1b2c3d4e5f607182931",
"anchor": {
"id": "6720a1b2c3d4e5f607182931",
"name": "Región Norte",
"type": null
},
"anchorSubtreeIds": [
"6720a1b2c3d4e5f607182931",
"6720a1b2c3d4e5f607182932",
"6720a1b2c3d4e5f607182933"
],
"teamIds": [
"6720a1b2c3d4e5f607182931",
"6720a1b2c3d4e5f607182932",
"6720a1b2c3d4e5f607182933"
],
"teamUserIds": [
"664f5f3c2f4f5e3b1c2a9d13",
"664f5f3c2f4f5e3b1c2a9d11",
"664f5f3c2f4f5e3b1c2a9d14"
],
"reportsToUserIds": [
"664f5f3c2f4f5e3b1c2a9d15"
]
}A quién puede asignar una tarea
GET /orgchart/{tenant_id}/user/{user_id}/assignable-users devuelve en userIds a quiénes puede asignar tareas, siempre incluida la propia persona, y en reportsToUserIds a sus jefes, para mostrarlos aparte. direction vale children si dirige un equipo, reports_to si no dirige a nadie y puede asignar hacia su grupo y su jefe, o none si no está en ningún árbol; en ese caso solo puede asignarse a sí misma.
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/assignable-users" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"tenantId": "66a1b2c3d4e5f60718293a4b",
"userId": "664f5f3c2f4f5e3b1c2a9d13",
"mode": "entity",
"scoped": true,
"direction": "children",
"userIds": [
"664f5f3c2f4f5e3b1c2a9d13",
"664f5f3c2f4f5e3b1c2a9d11",
"664f5f3c2f4f5e3b1c2a9d14",
"664f5f3c2f4f5e3b1c2a9d15"
],
"reportsToUserIds": [
"664f5f3c2f4f5e3b1c2a9d15"
]
}| Necesitas | Ruta | Ejemplo con Grupo Aurora |
|---|---|---|
| Comparar a una persona con grupos parecidos | ranking-scope | Diego, en Tienda Monterrey Centro, se compara con toda la Región Norte, incluida Tienda San Pedro. |
| Saber qué equipo dirige alguien | management-scope | Carlos dirige la Región Norte y sus dos tiendas; reporta a Dirección Comercial. |
| Llenar un selector de responsables de tarea | assignable-users | Carlos puede asignar a sí mismo, a Diego, a Laura y a su directora. |
| Agrupar por jefe directo | reporting-scope | Carlos ve a Diego como parte de su equipo por el «reporta a». |
Estos alcances son los mismos que Cody aplica al crear tareas, al dirigir anuncios a puestos con orgchart_element_ids y al calcular clasificaciones de misiones. Consultarlos no da permisos nuevos: sirven para que tu sistema muestre las mismas opciones que verá la persona en Cody.
8 · 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 que el token pertenezca a una organización. En ranking-scope/subtree, el nodo pedido está fuera del universo de la persona: usa un id de su tree. |
| La solicitud responde 404 | La entidad, el puesto, la entidad superior, el puesto de «reporta a», la tienda o una persona no existen en tu organización. Vuelve a consultar la estructura o el organigrama y usa IDs vigentes. |
| La solicitud responde 400 al eliminar una entidad | Tiene áreas debajo o está vinculada a una tienda. Mueve o elimina sus áreas hijas, o desvincula la tienda, y repite. |
| La solicitud responde 400 al cambiar personas o borrar un puesto | La entidad está vinculada a una tienda: sus personas se administran desde la tienda. Si el error menciona a una persona, esa persona no pertenece a tu organización. |
| La solicitud responde 400 al vincular una tienda | La entidad ya está vinculada a otra tienda, o la tienda ya está vinculada a otra entidad. Desvincula primero. |
| La solicitud responde 422 | Revisa nombres, tipos y campos obligatorios. detail es una lista de errores con loc (campo), msg (explicación) y type (clase de error). |
| Recibes datos de tu organización aunque pusiste otro tenant_id | Es lo esperado: con una credencial normal, Cody usa la organización del token e ignora la de la ruta. |
management-scope responde scoped: false | Tu organización arma la línea de mando con el «reporta a» o la persona no está en ninguna área. Usa reporting-scope o assignable-users. |
9 · Preguntas frecuentes
Dudas sobre estructura y organigrama
Lo que conviene saber antes de sincronizar desde tu sistema de recursos humanos.
- ¿Puedo cargar toda mi estructura en una sola solicitud?
- No. Crea las entidades de arriba hacia abajo, una por solicitud, guardando cada
idpara usarlo comoparent_idde las siguientes. Después crea los puestos. - ¿Una persona puede ocupar varios puestos?
- Sí, incluso en entidades distintas.
GET /orgchart/{tenant_id}/user/{user_id}los devuelve todos. - ¿Qué diferencia hay entre `reports_to_element_id` y `parent_id` en un puesto?
reports_to_element_ides el jefe directo y es el que Cody usa para la línea de mando.parent_idsolo se toma en cuenta cuando un puesto no tiene «reporta a». Para la mayoría de las integraciones basta conreports_to_element_id.- ¿Debo usar `user_ids` en el PUT o las rutas de personas?
- Usa las rutas
/userspara altas y bajas puntuales, porque no tocan a las demás personas del puesto. Usauser_idsen el PUT solo cuando tu sistema tenga la lista completa y quieras reemplazarla. - ¿Por qué no puedo cambiar a las personas de una tienda desde el organigrama?
- Porque esa área está vinculada a una tienda y sus personas siguen a la tienda automáticamente. Cámbialas en la tienda o desvincula el área.
¿Necesitas ayuda?
Si la estructura no se ve como esperas en el AMS, comparte con soporte la ruta, la hora, el código de respuesta y los IDs de las entidades o puestos involucrados. No incluyas credenciales ni listas completas de datos personales.
El equipo de Cody