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.
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.
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": []
}'{
"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": []
}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.
| Campo | Tipo y valores |
|---|---|
type | Texto: announcement, notification, recommendation, video, image; por defecto announcement. |
emoji, subtitle, content, clean_content | Texto; por defecto cadena vacía. clean_content contiene la versión de texto sin formato. |
target_user_ids, orgchart_element_ids | Listas de texto: personas y elementos del organigrama. Ambas vacías significan toda la organización. |
message_count | Entero; por defecto 0. |
tenant_id | Texto 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.
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.
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"[
{
"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"
}
]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.
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"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.
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.
curl --fail-with-body -X GET "$CODY_API_URL/announcement/get/67206a7b8c9d0e1f234a5b6c?evaluate_audience=true" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"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.
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.
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."
}'{
"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": []
}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.
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.
curl --fail-with-body -X POST "$CODY_API_URL/announcement/67206a7b8c9d0e1f234a5b6c/read" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"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"
}
]
}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.
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.
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.
curl --fail-with-body -X DELETE "$CODY_API_URL/announcement/delete/67206a7b8c9d0e1f234a5b6c" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"{
"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.
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.
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 | Qué hacer |
|---|---|
| La solicitud responde 401 | Renueva el token siguiendo la guía de autenticación. Repite una vez la consulta que falló. |
| La solicitud responde 403 | Revisa 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). |
| La lista no trae registros individuales de lectura | Es correcto: AnnouncementListResponse no incluye acknowledgments. Consulta el detalle del anuncio. |
| El anuncio llegó a toda la organización | Revisa 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 administrador | La 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 asociado | La 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
acknowledgmentspara 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