---
title: Estructura y organigrama por API
section: Cody Academy / Public API
updated: 2026-11-03
source: https://docs.cody-tech.com/academy/public-api/estructura-y-organigrama
markdown: https://docs.cody-tech.com/academy/public-api/estructura-y-organigrama.md
---

# Sincroniza la estructura y el organigrama de tu empresa desde tu sistema

> **Guía de Cody Academy · Public API.** 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.
>
> Para equipos de integración y de recursos humanos · Necesitas una credencial y los identificadores de las personas en Cody.
>
> Versión web, con las capturas de pantalla: https://docs.cody-tech.com/academy/public-api/estructura-y-organigrama

## 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](https://docs.cody-tech.com/academy/ams/estructura-organizacional) 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](https://docs.cody-tech.com/academy/ams/credenciales-public-api) y sigue [Credencial y token](https://docs.cody-tech.com/academy/public-api/exportacion-de-datos#credenciales). 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.

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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"
}
```

### Paso 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

```bash
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"
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "name": "Tienda Monterrey Centro",
    "parent_id": "6720a1b2c3d4e5f607182931",
}
response = requests.request(
    "POST",
    f"{CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Tienda Monterrey Centro",
  "parent_id": "6720a1b2c3d4e5f607182931"
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "id": "6720a1b2c3d4e5f607182932",
  "name": "Tienda Monterrey Centro",
  "parent_id": "6720a1b2c3d4e5f607182931",
  "store_id": null,
  "created_at": "2026-11-03T15:00:00Z"
}
```

### Paso 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

```bash
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"
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "name": "Tienda Monterrey Macroplaza",
}
response = requests.request(
    "PUT",
    f"{CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Tienda Monterrey Macroplaza"
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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.

### Paso 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

```bash
curl --fail-with-body -X DELETE "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "DELETE",
    f"{CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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.

### Paso 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](https://docs.cody-tech.com/academy/ams/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

```bash
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"
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "store_id": "66c3d4e5f60718293a4b5c6d",
}
response = requests.request(
    "POST",
    f"{CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "store_id": "66c3d4e5f60718293a4b5c6d"
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "entity_id": "6720a1b2c3d4e5f607182933",
  "store_id": "66c3d4e5f60718293a4b5c6d",
  "orgchart_element_id": "6720b3c4d5e6f70819203a43",
  "user_ids": [
    "664f5f3c2f4f5e3b1c2a9d14"
  ]
}
```

### Paso 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.

### Paso 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

```bash
curl --fail-with-body -X DELETE "$CODY_API_URL/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "DELETE",
    f"{CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/business-structure/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182933/store`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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.

### Paso 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

```bash
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"
  }
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "entity_id": "6720a1b2c3d4e5f607182932",
    "name": "Encargado de tienda",
    "type": "Operación",
    "user_ids": [
        "664f5f3c2f4f5e3b1c2a9d11",
    ],
    "reports_to_element_id": "6720b3c4d5e6f70819203a41",
    "metadata": {
        "turno": "matutino",
    },
}
response = requests.request(
    "POST",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "entity_id": "6720a1b2c3d4e5f607182932",
  "name": "Encargado de tienda",
  "type": "Operación",
  "user_ids": [
    "664f5f3c2f4f5e3b1c2a9d11"
  ],
  "reports_to_element_id": "6720b3c4d5e6f70819203a41",
  "metadata": {
    "turno": "matutino"
  }
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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"
}
```

### Paso 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.

### Paso 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

```bash
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"
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "type": "Operación de tienda",
}
response = requests.request(
    "PUT",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "type": "Operación de tienda"
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

### Paso 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

```bash
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"
  ]
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "user_ids": [
        "664f5f3c2f4f5e3b1c2a9d16",
    ],
}
response = requests.request(
    "POST",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42/users",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42/users`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "user_ids": [
    "664f5f3c2f4f5e3b1c2a9d16"
  ]
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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

```bash
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"
  ]
}'
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
payload = {
    "user_ids": [
        "664f5f3c2f4f5e3b1c2a9d16",
    ],
}
response = requests.request(
    "DELETE",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42/users",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42/users`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "user_ids": [
    "664f5f3c2f4f5e3b1c2a9d16"
  ]
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

### Paso 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

```bash
curl --fail-with-body -X DELETE "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "DELETE",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/element/6720b3c4d5e6f70819203a42`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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.

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Línea de mando**

##### cURL

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/reporting-tree" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/reporting-tree",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/reporting-tree`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada de la línea de mando**

```json
{
  "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"
}
```

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
[
  {
    "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"
  }
]
```

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/tree" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/tree",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/tree`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
[
  {
    "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": []
        }
      ]
    }
  }
]
```

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932/users" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932/users",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182932/users`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
[
  {
    "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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182931/subtree" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182931/subtree",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/entity/6720a1b2c3d4e5f607182931/subtree`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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`.

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/reporting-scope" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/reporting-scope",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/reporting-scope`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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"
    ]
  }
}
```

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?tree_depth=2" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?tree_depth=2",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?tree_depth=2`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?selected_ids=6720a1b2c3d4e5f607182932" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?selected_ids=6720a1b2c3d4e5f607182932",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope?selected_ids=6720a1b2c3d4e5f607182932`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

### Paso 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

```bash
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"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope/subtree/6720a1b2c3d4e5f607182933?tree_depth=2",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d11/ranking-scope/subtree/6720a1b2c3d4e5f607182933?tree_depth=2`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "id": "6720a1b2c3d4e5f607182933",
  "name": "Tienda San Pedro",
  "type": null,
  "peopleCount": 1,
  "descendantCount": 0,
  "hasMoreChildren": false,
  "children": []
}
```

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/management-scope" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/management-scope",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/management-scope`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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"
  ]
}
```

### Paso 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

```bash
curl --fail-with-body -X GET "$CODY_API_URL/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/assignable-users" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
```

##### Python

```python
import os
import requests

CODY_API_URL = os.environ["CODY_API_URL"]
access_token = os.environ["CODY_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.request(
    "GET",
    f"{CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/assignable-users",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

##### JavaScript

```javascript
const accessToken = process.env.CODY_ACCESS_TOKEN
const response = await fetch(`${process.env.CODY_API_URL}/orgchart/66a1b2c3d4e5f60718293a4b/user/664f5f3c2f4f5e3b1c2a9d13/assignable-users`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

**Respuesta simulada**

```json
{
  "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](https://docs.cody-tech.com/academy/public-api/tareas), al dirigir [anuncios](https://docs.cody-tech.com/academy/public-api/anuncios) a puestos con `orgchart_element_ids` y al calcular [clasificaciones de misiones](https://docs.cody-tech.com/academy/public-api/misiones-y-resultados). 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](https://docs.cody-tech.com/academy/public-api/exportacion-de-datos#credenciales). 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 `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.
