Saltar al contenido
CodyCody
Cody Academy · Public API

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.

1

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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"
}
2

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.

Solicitud
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"
}'
Respuesta simulada
{
  "id": "6720a1b2c3d4e5f607182932",
  "name": "Tienda Monterrey Centro",
  "parent_id": "6720a1b2c3d4e5f607182931",
  "store_id": null,
  "created_at": "2026-11-03T15:00:00Z"
}
3

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.

Solicitud
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"
}'
Respuesta simulada
{
  "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.

4

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.

Solicitud
curl --fail-with-body -X DELETE "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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.

1

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.

Solicitud
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"
}'
Respuesta simulada
{
  "entity_id": "6720a1b2c3d4e5f607182933",
  "store_id": "66c3d4e5f60718293a4b5c6d",
  "orgchart_element_id": "6720b3c4d5e6f70819203a43",
  "user_ids": [
    "664f5f3c2f4f5e3b1c2a9d14"
  ]
}
2

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.

3

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.

Solicitud
curl --fail-with-body -X DELETE "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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.

1

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.

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

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.

3

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.

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

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.

Agregar personas
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"
  ]
}'
Respuesta simulada
{
  "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"
}
Quitar personas
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"
  ]
}'
5

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.

Solicitud
curl --fail-with-body -X DELETE "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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.

1

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.

Organigrama completo
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Línea de mando
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/reporting-tree" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada de la línea de mando
{
  "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"
}
2

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
[
  {
    "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"
  }
]
3

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

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/tree" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
[
  {
    "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": []
        }
      ]
    }
  }
]
4

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.

Personas de un área
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932/users" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
[
  {
    "element_id": "6720b3c4d5e6f70819203a42",
    "user_id": "664f5f3c2f4f5e3b1c2a9d11",
    "name": "Diego Ramírez Peña",
    "email": "diego.ramirez@ejemplo.com",
    "position": "Operación"
  }
]
Árbol de un área
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182931/subtree" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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.

1

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/reporting-scope" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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"
    ]
  }
}
2

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

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?tree_depth=2" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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.

Solo la Tienda Monterrey Centro
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?selected_ids=6720a1b2c3d4e5f607182932" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
3

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.

Solicitud
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"
Respuesta simulada
{
  "id": "6720a1b2c3d4e5f607182933",
  "name": "Tienda San Pedro",
  "type": null,
  "peopleCount": 1,
  "descendantCount": 0,
  "hasMoreChildren": false,
  "children": []
}
4

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/management-scope" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "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"
  ]
}
5

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.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/assignable-users" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "tenantId": "66a1b2c3d4e5f60718293a4b",
  "userId": "664f5f3c2f4f5e3b1c2a9d13",
  "mode": "entity",
  "scoped": true,
  "direction": "children",
  "userIds": [
    "664f5f3c2f4f5e3b1c2a9d13",
    "664f5f3c2f4f5e3b1c2a9d11",
    "664f5f3c2f4f5e3b1c2a9d14",
    "664f5f3c2f4f5e3b1c2a9d15"
  ],
  "reportsToUserIds": [
    "664f5f3c2f4f5e3b1c2a9d15"
  ]
}
Qué ruta usar
NecesitasRutaEjemplo con Grupo Aurora
Comparar a una persona con grupos parecidosranking-scopeDiego, en Tienda Monterrey Centro, se compara con toda la Región Norte, incluida Tienda San Pedro.
Saber qué equipo dirige alguienmanagement-scopeCarlos dirige la Región Norte y sus dos tiendas; reporta a Dirección Comercial.
Llenar un selector de responsables de tareaassignable-usersCarlos puede asignar a sí mismo, a Diego, a Laura y a su directora.
Agrupar por jefe directoreporting-scopeCarlos 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 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 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 404La 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 entidadTiene á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 puestoLa 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 tiendaLa entidad ya está vinculada a otra tienda, o la tienda ya está vinculada a otra entidad. Desvincula primero.
La solicitud responde 422Revisa 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_idEs lo esperado: con una credencial normal, Cody usa la organización del token e ignora la de la ruta.
management-scope responde scoped: falseTu 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 id para usarlo como parent_id de 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_id es el jefe directo y es el que Cody usa para la línea de mando. parent_id solo se toma en cuenta cuando un puesto no tiene «reporta a». Para la mayoría de las integraciones basta con reports_to_element_id.
¿Debo usar `user_ids` en el PUT o las rutas de personas?
Usa las rutas /users para altas y bajas puntuales, porque no tocan a las demás personas del puesto. Usa user_ids en 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