---
title: Tareas por API
section: Cody Academy / Public API
updated: 2026-10-27
source: https://docs.cody-tech.com/academy/public-api/tareas
markdown: https://docs.cody-tech.com/academy/public-api/tareas.md
---

# Crea tareas desde tu ERP y sigue su avance en tu tablero

> **Guía de Cody Academy · Public API.** Conecta tu ERP con la Public API de Cody. En Grupo Aurora, una diferencia de inventario genera una tarea para Diego Ramírez Peña; Carlos Méndez Luna sigue su avance en Cody y tu proceso consulta el estatus para actualizar un tablero propio. Los datos son simulados.
>
> Para equipos de integración y operaciones · Necesitas una credencial y los identificadores del responsable y de tu organización.
>
> Versión web, con las capturas de pantalla: https://docs.cody-tech.com/academy/public-api/tareas

## 1. Descripción: Del pendiente en tu sistema a una tarea en Cody

Crea, consulta y administra el mismo pendiente que tu equipo atiende en el Companion.

- **Crear y asignar.** Envía título, responsable y organización a `POST /task/create`. Puedes incluir descripción y fecha límite.
- **Extraer para tu tablero.** Consulta `GET /task/list` con `status` y `ownerId`. No tiene parámetros de paginación documentados; no le agregues `skip` ni `limit`.
- **Mantener el avance al día.** Consulta el detalle, actualiza el estatus con `PATCH` y elimina únicamente cuando corresponda.

La tarea se consulta en [Tareas del AMS](https://docs.cody-tech.com/academy/ams/tareas), la consola de administración; Diego la atiende en [Tareas del Companion](https://docs.cody-tech.com/academy/companion/tareas) y Carlos le da seguimiento en [Tareas del equipo](https://docs.cody-tech.com/academy/companion/tareas-del-equipo). Revisa [cómo se conecta todo](https://docs.cody-tech.com/academy/companion/como-se-conecta-todo) para ubicar cada pantalla.

## 2. Antes de empezar: Prepara el acceso y las equivalencias

Relaciona la persona y la organización de Cody con los registros de tu sistema.

- **Credencial y acceso 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. No repetimos aquí su obtención.
- **La persona y sus permisos.** La credencial actúa en nombre de una persona. Confirma con un administrador que puede ver y modificar los datos del flujo; tener una credencial no amplía sus permisos.
- **Dirección base y ejemplos.** Todas las rutas parten de `https://api.public.cody-tech.com`. Los ejemplos usan cURL, Python y JavaScript. Configura `CODY_API_URL` con esta dirección y `CODY_ACCESS_TOKEN` con tu token vigente; reemplaza los IDs ficticios por los tuyos. Ejecuta desde un proceso seguro de tu equipo.
- **Responsable real.** El `ownerId` del ejemplo representa a Diego Ramírez Peña, de Tienda Monterrey Centro. No envíes el nombre ni la clave del empleado de tu ERP en su lugar. Puedes obtener identificadores con [la guía de exportación](https://docs.cody-tech.com/academy/public-api/exportacion-de-datos#ids).

## 3. Listar para el tablero: Extrae pendientes por estatus y responsable

Empieza por las tareas abiertas de Diego y ajusta los filtros al reporte.

### Paso 1. Pide las tareas que necesitas

Usa `GET /task/list`. `status` acepta `open` (por hacer), `in_progress` (en curso) o `closed` (hecha); `ownerId` es texto. Ambos son opcionales. Omitirlos quita esos filtros, pero no amplía tus permisos.

**Solicitud**

##### cURL

```bash
curl --fail-with-body -X GET "$CODY_API_URL/task/list?status=open&ownerId=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}/task/list?status=open&ownerId=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}/task/list?status=open&ownerId=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)
```

### Paso 2. Lee las tareas de la respuesta

La respuesta 200 contiene `ok`, `data` con el arreglo de tareas y `count` con la cantidad devuelta. Usa `_id` para relacionar cada tarea con tu tablero; no hay un campo `items`.

**Respuesta simulada de Grupo Aurora**

```json
{
  "ok": true,
  "data": [
    {
      "_id": "67201a2b3c4d5e6f708192a3",
      "title": "Revisar diferencia de inventario ERP AUR-1042",
      "status": "open",
      "comments": [],
      "createdAt": "2026-10-27T16:00:00+00:00",
      "updatedAt": "2026-10-27T16:00:00+00:00",
      "tenant_id": "66a1b2c3d4e5f60718293a4b",
      "description": "Grupo Aurora · Validar 3 pantallas en Tienda Monterrey Centro.",
      "ownerId": "664f5f3c2f4f5e3b1c2a9d11",
      "ownerName": "Diego Ramírez Peña",
      "createdById": "664f5f3c2f4f5e3b1c2a9d13",
      "createdByName": "Carlos Méndez Luna",
      "dueDate": "2026-10-30T00:00:00"
    }
  ],
  "count": 1
}
```

| Parámetro | Tipo y alcance |
| --- | --- |
| `status` | Texto: `open`, `in_progress`, `closed`. |
| `ownerId` | Texto: identificador de la persona responsable. |
| `tenant_id` | Texto: solo se toma en cuenta para superadministradores, y ellos deben enviarlo. Para las demás credenciales se usa su propia organización. |

## 4. Consultar una tarea: Abre un pendiente específico

Usa el identificador de una tarea existente para revisar su detalle.

### Paso 1. Consulta por task_id

`GET /task/{task_id}` recibe el identificador en la ruta, sin cuerpo. El identificador simulado representa el pendiente AUR-1042. Éxito: 200 con `ok` y `data`; aquí `data` es un objeto de tarea y su identificador se llama `_id`.

**Solicitud**

##### cURL

```bash
curl --fail-with-body -X GET "$CODY_API_URL/task/67201a2b3c4d5e6f708192a3" \
  -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}/task/67201a2b3c4d5e6f708192a3",
    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}/task/67201a2b3c4d5e6f708192a3`, {
  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 Grupo Aurora**

```json
{
  "ok": true,
  "data": {
    "_id": "67201a2b3c4d5e6f708192a3",
    "title": "Revisar diferencia de inventario ERP AUR-1042",
    "status": "open",
    "comments": [],
    "createdAt": "2026-10-27T16:00:00+00:00",
    "updatedAt": "2026-10-27T16:00:00+00:00",
    "tenant_id": "66a1b2c3d4e5f60718293a4b",
    "description": "Grupo Aurora · Validar 3 pantallas en Tienda Monterrey Centro.",
    "ownerId": "664f5f3c2f4f5e3b1c2a9d11",
    "ownerName": "Diego Ramírez Peña",
    "createdById": "664f5f3c2f4f5e3b1c2a9d13",
    "createdByName": "Carlos Méndez Luna",
    "dueDate": "2026-10-30T00:00:00"
  }
}
```

## 5. Crear desde tu sistema: Convierte una diferencia de inventario en tarea

Grupo Aurora detecta tres pantallas por validar y asigna el conteo a Diego.

### Paso 1. Construye los campos obligatorios

`POST /task/create` exige `title` y `ownerId` como texto y `tenant_id` como texto o entero. Aunque una credencial normal usa su propia organización y reemplaza ese último valor, el campo sigue siendo obligatorio en la solicitud.

**Solicitud**

##### cURL

```bash
curl --fail-with-body -X POST "$CODY_API_URL/task/create" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "title": "Revisar diferencia de inventario ERP AUR-1042",
  "description": "Diego Ramírez Peña: validar 3 pantallas en Tienda Monterrey Centro y avisar a Carlos Méndez Luna.",
  "dueDate": "2026-10-30",
  "ownerId": "664f5f3c2f4f5e3b1c2a9d11",
  "tenant_id": "66a1b2c3d4e5f60718293a4b"
}'
```

##### 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 = {
    "title": "Revisar diferencia de inventario ERP AUR-1042",
    "description": "Diego Ramírez Peña: validar 3 pantallas en Tienda Monterrey Centro y avisar a Carlos Méndez Luna.",
    "dueDate": "2026-10-30",
    "ownerId": "664f5f3c2f4f5e3b1c2a9d11",
    "tenant_id": "66a1b2c3d4e5f60718293a4b",
}
response = requests.request(
    "POST",
    f"{CODY_API_URL}/task/create",
    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}/task/create`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "title": "Revisar diferencia de inventario ERP AUR-1042",
  "description": "Diego Ramírez Peña: validar 3 pantallas en Tienda Monterrey Centro y avisar a Carlos Méndez Luna.",
  "dueDate": "2026-10-30",
  "ownerId": "664f5f3c2f4f5e3b1c2a9d11",
  "tenant_id": "66a1b2c3d4e5f60718293a4b"
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

### Paso 2. Relaciona la tarea con tu registro de origen

`description` y `dueDate` son opcionales y aceptan texto o `null`. El ejemplo usa `AAAA-MM-DD` para la fecha, como el ejemplo de la especificación, que no impone un formato. El contrato no define `external_id`: el folio AUR-1042 va en el título y la descripción. Guarda en tu sistema la relación con la tarea creada, usando el `_id` de `data`.

> **Evita duplicar pendientes.** Crear responde 201 con `ok` y el objeto de tarea en `data`. No supongas que repetir la creación evita duplicados: ante una interrupción, verifica primero si la tarea ya existe.

Después de crearla, revisa el tablero de [Tareas del AMS](https://docs.cody-tech.com/academy/ams/tareas) y la vista de Diego en el [Companion](https://docs.cody-tech.com/academy/companion/tareas). Si no se ve de inmediato, actualiza la pantalla y revisa el responsable y los permisos.

## 6. Actualizar el estatus: Mueve la tarea cuando avance el trabajo

Cambia solo lo necesario y deja un comentario que explique el avance.

### Paso 1. Envía el nuevo estatus

`PATCH /task/update/{task_id}` cambia únicamente los campos enviados. `status` acepta `open`, `in_progress`, `closed` o `null`. El ejemplo la mueve a `in_progress` y agrega un comentario. Éxito: 200.

**Solicitud**

##### cURL

```bash
curl --fail-with-body -X PATCH "$CODY_API_URL/task/update/67201a2b3c4d5e6f708192a3" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "status": "in_progress",
  "comment": "Diego inició el conteo contra el reporte AUR-1042."
}'
```

##### 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 = {
    "status": "in_progress",
    "comment": "Diego inició el conteo contra el reporte AUR-1042.",
}
response = requests.request(
    "PATCH",
    f"{CODY_API_URL}/task/update/67201a2b3c4d5e6f708192a3",
    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}/task/update/67201a2b3c4d5e6f708192a3`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "status": "in_progress",
  "comment": "Diego inició el conteo contra el reporte AUR-1042."
}),
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

### Paso 2. Distingue cambiar la tarea de comentar

También admite `title`, `description`, `dueDate`, `ownerId` y `comment`, todos como texto o `null`, sin campos obligatorios. La línea de mando solo puede agregar `comment`, según la especificación; no des por hecho que Carlos puede cambiar el estatus por ser líder. Confirma el permiso de la persona que actúa.

## 7. Eliminar: Retira una tarea que ya no corresponde

Eliminar se reserva para pendientes creados por error; cerrar conserva el seguimiento.

### Paso 1. Verifica el identificador y elimina

`DELETE /task/delete/{task_id}` no recibe cuerpo. La especificación permite esta acción a quien creó la tarea y a superadministradores. Responde 200 con `ok: true` y `message: "Tarea eliminada"`. Confirma el resultado consultando tus pendientes y actualizando el tablero.

**Solicitud**

##### cURL

```bash
curl --fail-with-body -X DELETE "$CODY_API_URL/task/delete/67201a2b3c4d5e6f708192a3" \
  -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}/task/delete/67201a2b3c4d5e6f708192a3",
    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}/task/delete/67201a2b3c4d5e6f708192a3`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
})
const text = await response.text()
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`)
console.log(text)
```

## 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 los permisos de la persona representada por la credencial y la audiencia o alcance del recurso. |
| La solicitud responde 422 | Revisa nombres, tipos y campos obligatorios. El contrato describe `detail` como una lista de errores con `loc` (campo), `msg` (explicación) y `type` (clase de error). |
| No aparece la tarea en el tablero | Revisa `ownerId`, organización y permisos; actualiza el AMS o el Companion. |
| Un líder puede comentar pero no cambiar el estatus | La especificación limita a la línea de mando a agregar `comment`. Usa una persona con permiso para modificar. |
| Tu lector de datos busca `items` y falla | Lee el arreglo en `data` y la cantidad en `count`. En el detalle, `data` contiene un solo objeto. |

## 9. Preguntas frecuentes: Dudas al conectar tu sistema

Decisiones prácticas para operar sin duplicar ni perder pendientes.

### ¿Puedo crear la tarea a nombre de un empleado de mi ERP?

Sí, después de obtener su `ownerId` real en Cody. Un nombre o folio de empleado no sustituye el identificador.

### ¿Cerrar y eliminar son lo mismo?

No. `closed` mantiene la tarea como hecha. Eliminar retira el recurso y tiene permisos distintos.

### ¿Puedo descargar todas las tareas página por página?

`/task/list` no documenta paginación ni un total. No copies los parámetros de exportación de conversaciones a esta ruta.

### ¿Las pantallas y mi tablero se actualizan solos al mismo tiempo?

Son distintas vistas de las tareas. Vuelve a consultar la API para tu tablero y actualiza las pantallas de Cody; esta guía no promete un tiempo de sincronización.

## ¿Necesitas ayuda?

Si no logras crear o consultar una tarea, comparte con soporte la ruta, el código de respuesta y el momento de la solicitud. Omite credenciales y datos personales innecesarios.
