Posts
Seguir el estado de una publicación con la API
Publicar con Connect es asíncrono: POST /posts responde 202 y el post sigue a la red después. Para saber el resultado, consulta el post por uuid o lista los posts del cliente con filtros. La respuesta trae el status, el enlace del post publicado y el motivo de un fallo.
La llamada
GET /api/posts/<post uuid> Authorization: Bearer <merchant token> x-customer-token: <customer token>
Qué puedes hacer
- Consultar un post con GET /posts/{uuid} y ver status, permalink y el estado de la publicación.
- Listar los posts del cliente con GET /posts, filtrando por customer_integration, external_reference y status.
- Ver el estado de cada medio en el publishing de cada elemento de media.
- Obtener el enlace del post en la red en permalink y el id de la red en publishing.external_id, una vez publicado.
- Encontrar el post por el id de tu sistema, filtrando por external_reference.
Reglas y límites
- POST /posts responde 202 con el post en created. Consulta hasta que status sea published o failed.
- El status del post es created, publishing, published o failed. publishing.status detalla el avance e incluye partially_published.
- Cuando falla, publishing.error trae code y message. Decide por el code, nunca por el mensaje.
- GET /posts devuelve los posts del cliente, los más recientes primero, con per_page de 1 a 100 (por defecto 15). Exige el x-customer-token.
- Para ver los posts de todos los clientes a la vez, usa GET /merchants/posts, solo con el Bearer.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| uuid | string | No | El id del post en Connect, devuelto por POST /posts. |
| external_reference | string | No | El id del post en tu sistema. También filtra GET /posts. |
| status | string | No | created, publishing, published o failed. También filtra GET /posts. |
| permalink | string | No | El enlace del post en la red, una vez publicado. |
| publishing.status | string | No | El estado de la publicación: pending, processing, ready, publishing, published, partially_published o failed. Cada medio tiene su propio publishing. |
| publishing.error | object | No | Se completa cuando falló: code y message. Decide por el code, no por el mensaje. |
| publishing.external_id | string | No | El id que la red le dio al post. |
| customer_integration | string | No | Filtro de GET /posts: el uuid de la conexión. |
| per_page | integer | No | Elementos por página en GET /posts, de 1 a 100. Por defecto 15. |
Para quién
Panel de publicaciones
El producto muestra cada post como en cola, publicado o con fallo, y el permalink en cuanto existe.
Reprocesar fallos
Un job lista los posts con status failed, lee publishing.error y avisa al cliente o reintenta con otra external_reference.
Agente de IA que confirma la entrega
El agente publica, consulta el post hasta que status sea published y solo entonces entrega al usuario el enlace del post.
Funciona con
Instagram Business
Facebook
Threads
LinkedIn
Pinterest
YouTube
Preguntas frecuentes
¿Cómo sé que el post salió?
Consulta GET /posts/{uuid} hasta que status sea published o failed. Con published, permalink trae el enlace del post en la red.
¿Cómo encuentro un post por el id de mi sistema?
Usa GET /posts con external_reference, que es el id del post en tu sistema. También puedes filtrar por status y customer_integration.
¿Qué significa failed?
La publicación no se completó. publishing.error trae el code y el message del motivo.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
