Posts
Acompanhar o status de uma publicação pela API
Publicar com o Connect é assíncrono: o POST /posts responde 202 e o post segue para a rede depois. Para saber o resultado, consulte o post pelo uuid ou liste os posts do cliente com filtros. A resposta traz o status, o link do post publicado e o motivo de uma falha.
A chamada
GET /api/posts/<post uuid> Authorization: Bearer <merchant token> x-customer-token: <customer token>
O que dá para fazer
- Consultar um post com GET /posts/{uuid} e ver status, permalink e o estado da publicação.
- Listar os posts do cliente com GET /posts, filtrando por customer_integration, external_reference e status.
- Ver o estado de cada mídia no publishing de cada item de media.
- Pegar o link do post na rede em permalink e o id da rede em publishing.external_id, depois de publicado.
- Achar o post pelo id do seu sistema, filtrando por external_reference.
Regras e limites
- O POST /posts responde 202 com o post em created. Consulte até o status ser published ou failed.
- O status do post é created, publishing, published ou failed. O publishing.status detalha o andamento e inclui partially_published.
- Quando falha, publishing.error traz code e message. Decida pelo code, nunca pela mensagem.
- O GET /posts devolve os posts do cliente mais recentes primeiro, com per_page de 1 a 100 (padrão 15). Exige o x-customer-token.
- Para ver os posts de todos os clientes de uma vez, use GET /merchants/posts, só com o Bearer.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| uuid | string | Não | O id do post no Connect, devolvido pelo POST /posts. |
| external_reference | string | Não | O id do post no seu sistema. Também filtra o GET /posts. |
| status | string | Não | created, publishing, published ou failed. Também filtra o GET /posts. |
| permalink | string | Não | O link do post na rede, depois de publicado. |
| publishing.status | string | Não | O estado da publicação: pending, processing, ready, publishing, published, partially_published ou failed. Cada item de media tem o seu publishing. |
| publishing.error | object | Não | Preenchido quando falhou: code e message. Decida pelo code, não pela mensagem. |
| publishing.external_id | string | Não | O id que a rede deu ao post. |
| customer_integration | string | Não | Filtro do GET /posts: o uuid da conexão. |
| per_page | integer | Não | Itens por página no GET /posts, de 1 a 100. Padrão 15. |
Para quem
Painel de publicações
O produto mostra cada post como na fila, publicado ou com falha, e o permalink assim que ele existe.
Reprocessar falhas
Um job lista os posts com status failed, lê publishing.error e avisa o cliente ou tenta de novo com outra external_reference.
Agente de IA que confirma a entrega
O agente publica, consulta o post até o status ser published e só então devolve ao usuário o link do post.
Funciona com
Instagram Business
Facebook
Threads
LinkedIn
Pinterest
YouTube
Perguntas frequentes
Como sei que o post foi publicado?
Consulte GET /posts/{uuid} até o status ser published ou failed. Com published, o permalink traz o link do post na rede.
Como acho um post pelo id do meu sistema?
Use GET /posts com external_reference, que é o id do post no seu sistema. Também dá para filtrar por status e customer_integration.
O que significa failed?
A publicação não foi concluída. O publishing.error traz o code e a message do motivo.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
