Saltar al contenido
CodyCody
Cody Academy · Public API

Publica anuncios desde tu sistema y consulta su lectura

Usa la Public API de Cody para crear, consultar, actualizar y retirar comunicados. En Grupo Aurora, Carlos Méndez Luna prepara un aviso de inventario para Diego Ramírez Peña en Tienda Monterrey Centro y revisa su lectura. Los datos son simulados y siguen los campos del contrato de producción.

Lectura estimada: 14 minutos · Para equipos de integración y comunicación · Necesitas una credencial y la audiencia identificada 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

Del aviso operativo a la bandeja del equipo

El anuncio guarda el contenido; su lectura y el aviso al celular son pasos distintos.

Publicar el contenido

Crea el comunicado con título, contenido y destinatarios. La respuesta incluye su id, útil para consultar, actualizar o vincular una notificación.

Consultar la lectura

El detalle incluye is_read para quien consulta y acknowledgments, la lista de personas con fecha de lectura. La lista no incluye estos registros de lectura individuales.

Avisar al celular

Combina el anuncio con Push Notifications cuando necesitas llamar la atención del equipo. Crear el anuncio y enviar el aviso son operaciones distintas.

Administra el comunicado en Anuncios del AMS, la consola de administración. Diego lo abre en Inicio del Companion, la aplicación del equipo; los líderes trabajan en Comunicación. Revisa cómo se conecta todo para ubicar publicación, lectura y seguimiento.

2 · Antes de empezar

Define acceso y audiencia

Confirma si el aviso es personal, por área o para toda la organización.

Credencial y acceso vigente

Pide una credencial para la Public API y sigue Credencial y token. Un token es la clave temporal con la que tu proceso demuestra que tiene acceso. No repetimos aquí su obtención.

La persona y sus permisos

La credencial actúa en nombre de una persona. Confirma con un administrador que puede ver y modificar los datos del flujo; tener una credencial no amplía sus permisos.

Dirección base y ejemplos

Todas las rutas parten de https://api.public.cody-tech.com. Los ejemplos usan cURL, Python y JavaScript. Configura CODY_API_URL con esta dirección y CODY_ACCESS_TOKEN con tu token vigente; reemplaza los IDs ficticios por los tuyos. Ejecuta desde un proceso seguro de tu equipo.

Destinatarios reales

target_user_ids y orgchart_element_ids son listas de identificadores como texto. Si ambas quedan vacías, el anuncio es para toda la organización. Si tu filtro no encuentra destinatarios, detén la creación y muestra un estado vacío; no mandes listas vacías para representar «nadie».

3 · Crear un anuncio

Publica un aviso para Diego

El ejemplo crea un comunicado de inventario dirigido a una persona.

1

Envía el contenido y la audiencia

POST /announcement/create exige únicamente title como texto. El ejemplo especifica la audiencia para que la publicación no termine dirigida a toda la organización. Éxito documentado: 201, con un objeto AnnouncementResponse, sin envoltura data.

Solicitud
curl --fail-with-body -X POST "$CODY_API_URL/announcement/create" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "type": "announcement",
  "emoji": "📣",
  "title": "Grupo Aurora · Conteo de cierre",
  "subtitle": "Tienda Monterrey Centro",
  "content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
  "clean_content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
  "target_user_ids": [
    "664f5f3c2f4f5e3b1c2a9d11"
  ],
  "orgchart_element_ids": []
}'
Respuesta simulada
{
  "id": "67206a7b8c9d0e1f234a5b6c",
  "tenant_id": "66a1b2c3d4e5f60718293a4b",
  "type": "announcement",
  "emoji": "📣",
  "title": "Grupo Aurora · Conteo de cierre",
  "subtitle": "Tienda Monterrey Centro",
  "content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
  "clean_content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
  "target_user_ids": [
    "664f5f3c2f4f5e3b1c2a9d11"
  ],
  "orgchart_element_ids": [],
  "is_read": false,
  "message_count": 0,
  "created_at": "2026-10-27T16:00:00Z",
  "updated_at": "2026-10-27T16:00:00Z",
  "acknowledgments": []
}
2

Conserva el identificador devuelto

Guarda id para consultar, editar, eliminar, registrar lectura o usarlo como announcement_id al enviar una notificación. tenant_id es texto o null en la creación; para credenciales normales se usa su propia organización.

Campos opcionales de creación
CampoTipo y valores
typeTexto: announcement, notification, recommendation, video, image; por defecto announcement.
emoji, subtitle, content, clean_contentTexto; por defecto cadena vacía. clean_content contiene la versión de texto sin formato.
target_user_ids, orgchart_element_idsListas de texto: personas y elementos del organigrama. Ambas vacías significan toda la organización.
message_countEntero; por defecto 0.
tenant_idTexto o null; no permite a una credencial normal cambiar de organización.

El contrato no define campos image_url, video_url, scheduled_at ni send_push al crear el anuncio. No los agregues por analogía con otra pantalla; usa Push Notifications para el aviso al celular.

4 · Listar y filtrar

Elige bandeja o administración

La vista de lectura y la de administración cumplen propósitos distintos.

1

Consulta la bandeja de quien actúa

GET /announcement/list usa view=inbox por defecto y aplica la audiencia. type es opcional y acepta announcement, notification, recommendation, video o image. El ejemplo consulta anuncios de la bandeja. Éxito: 200.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/announcement/list?type=announcement&view=inbox&skip=0&limit=100" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
[
  {
    "id": "67206a7b8c9d0e1f234a5b6c",
    "tenant_id": "66a1b2c3d4e5f60718293a4b",
    "type": "announcement",
    "emoji": "📣",
    "title": "Grupo Aurora · Conteo de cierre",
    "subtitle": "Tienda Monterrey Centro",
    "content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
    "clean_content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
    "target_user_ids": [
      "664f5f3c2f4f5e3b1c2a9d11"
    ],
    "orgchart_element_ids": [],
    "is_read": false,
    "message_count": 0,
    "created_at": "2026-10-27T16:00:00Z",
    "updated_at": "2026-10-27T16:00:00Z"
  }
]
2

Consulta la vista de administración cuando tengas acceso

view=manage solicita todos los anuncios de la organización; no es un permiso por sí mismo. Usa una credencial autorizada para administrarlos. view está definido como texto, no como una lista cerrada, aunque el contrato describe inbox y manage.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/announcement/list?type=announcement&view=manage&skip=0&limit=100" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
3

Recorre todas las páginas

skip es entero desde 0 (por defecto 0); limit es entero de 1 a 1,000 (por defecto 100). La respuesta es un arreglo directo de AnnouncementListResponse, sin total, items ni acknowledgments. Aumenta skip por la cantidad solicitada y continúa hasta recibir un arreglo vacío. tenant_id es texto y solo se toma en cuenta para superadministradores.

5 · Consultar el detalle

Abre el anuncio y su seguimiento

Usa la ruta de detalle cuando necesites los registros individuales de lectura.

1

Consulta por announcement_id

GET /announcement/get/{announcement_id} acepta evaluate_audience como booleano, por defecto false; el ejemplo lo activa. Éxito: 200 con AnnouncementResponse, la misma estructura mostrada al crear. No uses desactivar esa evaluación como sustituto de permisos.

Solicitud
curl --fail-with-body -X GET "$CODY_API_URL/announcement/get/67206a7b8c9d0e1f234a5b6c?evaluate_audience=true" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
2

Lee los datos de seguimiento

El detalle exige id, tenant_id, type, emoji, title, message_count, created_at, updated_at y acknowledgments. Cada lectura contiene user_id como texto y acknowledged_at como fecha y hora. is_read es booleano y se refiere a quien consulta; no significa que todo el equipo ya lo leyó.

6 · Actualizar

Corrige el comunicado existente

Usa el identificador guardado para cambiar el contenido sin crear otro anuncio.

1

Envía los campos que vas a modificar

PUT /announcement/update/{announcement_id} es el método de actualización documentado. Todos los campos son opcionales: type, emoji, title, subtitle, content, clean_content admiten texto o null; type conserva las cinco opciones de creación. target_user_ids y orgchart_element_ids admiten lista de textos o null; message_count, entero o null. No recibe tenant_id. Éxito: 200 con AnnouncementResponse.

Solicitud
curl --fail-with-body -X PUT "$CODY_API_URL/announcement/update/67206a7b8c9d0e1f234a5b6c" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "subtitle": "Conteo hasta las 19:00",
  "content": "El conteo en Tienda Monterrey Centro termina a las 19:00.",
  "clean_content": "El conteo en Tienda Monterrey Centro termina a las 19:00."
}'
Respuesta simulada
{
  "id": "67206a7b8c9d0e1f234a5b6c",
  "tenant_id": "66a1b2c3d4e5f60718293a4b",
  "type": "announcement",
  "emoji": "📣",
  "title": "Grupo Aurora · Conteo de cierre",
  "subtitle": "Conteo hasta las 19:00",
  "content": "El conteo en Tienda Monterrey Centro termina a las 19:00.",
  "clean_content": "El conteo en Tienda Monterrey Centro termina a las 19:00.",
  "target_user_ids": [
    "664f5f3c2f4f5e3b1c2a9d11"
  ],
  "orgchart_element_ids": [],
  "is_read": false,
  "message_count": 0,
  "created_at": "2026-10-27T16:00:00Z",
  "updated_at": "2026-10-27T16:10:00Z",
  "acknowledgments": []
}
2

Revisa el contenido en las pantallas de Cody

Actualiza Anuncios del AMS y abre el aviso en Inicio del Companion. El ejemplo mantiene a Diego como destinatario porque no envía cambios de audiencia. Editar el anuncio no envía automáticamente otra notificación al celular.

7 · Marcar como leído

Registra la lectura de quien actúa

Esta operación corresponde a una lectura real de la persona representada por la credencial.

1

Registra la lectura, sin cuerpo

POST /announcement/{announcement_id}/read no recibe cuerpo ni user_id. Marca el anuncio para quien actúa con la credencial; no permite elegir otra persona en la solicitud. El ejemplo de respuesta supone una credencial que representa a Diego. Si la credencial representa a Carlos, la lectura corresponde a Carlos. Éxito: 200 con AnnouncementResponse.

Solicitud
curl --fail-with-body -X POST "$CODY_API_URL/announcement/67206a7b8c9d0e1f234a5b6c/read" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "id": "67206a7b8c9d0e1f234a5b6c",
  "tenant_id": "66a1b2c3d4e5f60718293a4b",
  "type": "announcement",
  "emoji": "📣",
  "title": "Grupo Aurora · Conteo de cierre",
  "subtitle": "Tienda Monterrey Centro",
  "content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
  "clean_content": "Diego Ramírez Peña: revisa el inventario de pantallas antes de las 18:00 y confirma con Carlos Méndez Luna.",
  "target_user_ids": [
    "664f5f3c2f4f5e3b1c2a9d11"
  ],
  "orgchart_element_ids": [],
  "is_read": true,
  "message_count": 0,
  "created_at": "2026-10-27T16:00:00Z",
  "updated_at": "2026-10-27T16:20:00Z",
  "acknowledgments": [
    {
      "user_id": "664f5f3c2f4f5e3b1c2a9d11",
      "acknowledged_at": "2026-10-27T16:20:00Z"
    }
  ]
}
2

Revisa la lectura en el detalle

El ejemplo muestra is_read: true y un registro de Diego en acknowledgments. Los administradores revisan lectores en Anuncios del AMS o Comunicación del Companion. No marques anuncios masivamente para simular que el equipo los leyó.

8 · Eliminar

Retira un anuncio que ya no corresponde

La eliminación del anuncio y el manejo de sus notificaciones son operaciones separadas.

1

Revisa primero los avisos al celular asociados

La descripción de DELETE /announcement/delete/{announcement_id} dice que no elimina las notificaciones asociadas. Indica usar DELETE /push-notification/{id} para cada una primero; revisa las condiciones de esa operación en Push Notifications. No copies a esta ruta las expectativas de eliminación de una pantalla.

2

Elimina el comunicado identificado

La ruta no recibe cuerpo. Éxito documentado: 200 con AnnouncementDeleteResponse, un objeto con message e id, ambos texto. La frase de message del ejemplo es simulada; el contrato no fija su redacción.

Solicitud
curl --fail-with-body -X DELETE "$CODY_API_URL/announcement/delete/67206a7b8c9d0e1f234a5b6c" \
  -H "Authorization: Bearer $CODY_ACCESS_TOKEN"
Respuesta simulada
{
  "message": "Anuncio eliminado",
  "id": "67206a7b8c9d0e1f234a5b6c"
}

9 · Combinar con avisos al celular

Envía una notificación cuando necesites llamar la atención

El anuncio permanece en la bandeja; la notificación ayuda a que la persona llegue a él.

1

Crea primero el anuncio

Conserva su id y úsalo como announcement_id en POST /push-notification/send. La guía de Push Notifications explica sus campos, envío y seguimiento; no hay un campo send_push en la creación del anuncio.

2

Coordina audiencia y momento de envío

Elige destinatarios coherentes con el anuncio y revisa que tengan la aplicación y puedan recibir avisos. Programar el aviso al celular no programa la publicación del anuncio: este ya fue creado. No registres una lectura solo porque se envió el aviso.

10 · Si algo falla

Revisa antes de repetir la solicitud

Usa el código de respuesta y el paso en que ocurrió el problema para decidir qué hacer.

Síntoma y qué hacer
SíntomaQué hacer
La solicitud responde 401Renueva el token siguiendo la guía de autenticación. Repite una vez la consulta que falló.
La solicitud responde 403Revisa los permisos de la persona representada por la credencial y la audiencia o alcance del recurso.
La solicitud responde 422Revisa nombres, tipos y campos obligatorios. El contrato describe detail como una lista de errores con loc (campo), msg (explicación) y type (clase de error).
La lista no trae registros individuales de lecturaEs correcto: AnnouncementListResponse no incluye acknowledgments. Consulta el detalle del anuncio.
El anuncio llegó a toda la organizaciónRevisa las dos listas de audiencia. Si ambas están vacías, ese es el alcance documentado; si querías «nadie», no debías crearlo.
La lectura aparece a nombre del administradorLa ruta de lectura actúa como la persona de la credencial. No acepta user_id para marcar a alguien más.
El anuncio se eliminó pero el aviso al celular sigue asociadoLa eliminación por API no elimina las notificaciones. Revisa su manejo por separado en la guía correspondiente.

11 · Preguntas frecuentes

Dudas sobre publicación y lectura

Confirma la audiencia y distingue el comunicado del aviso al celular.

¿Crear el anuncio envía una notificación al celular?
No es parte de la creación documentada. Combina el anuncio con Push Notifications usando su identificador.
¿Puedo marcarlo como leído para Diego desde la credencial de Carlos?
No mediante esta solicitud. No recibe un usuario destino: registra la lectura de quien actúa.
¿is_read significa que ya lo leyó todo el equipo?
No. Es el estado de lectura de quien consulta. El detalle contiene acknowledgments para revisar las lecturas individuales.
¿Por qué el borrado por API puede diferir de la pantalla del AMS?
La guía del AMS describe una acción de interfaz que también puede gestionar la notificación. El contrato público de eliminación dice expresamente que no elimina las notificaciones asociadas; tu integración debe tratarlas por separado.

¿Necesitas ayuda?

Si el anuncio no llega a la audiencia esperada, comparte con soporte su identificador, la ruta, la hora y el código de respuesta. No incluyas credenciales ni listas completas de datos personales.

El equipo de Cody