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

CampoTipoObrigatórioDescrição
uuidstringNãoO id do post no Connect, devolvido pelo POST /posts.
external_referencestringNãoO id do post no seu sistema. Também filtra o GET /posts.
statusstringNãocreated, publishing, published ou failed. Também filtra o GET /posts.
permalinkstringNãoO link do post na rede, depois de publicado.
publishing.statusstringNãoO estado da publicação: pending, processing, ready, publishing, published, partially_published ou failed. Cada item de media tem o seu publishing.
publishing.errorobjectNãoPreenchido quando falhou: code e message. Decida pelo code, não pela mensagem.
publishing.external_idstringNãoO id que a rede deu ao post.
customer_integrationstringNãoFiltro do GET /posts: o uuid da conexão.
per_pageintegerNãoItens 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.

Relacionadas

Ver tudo que dá para fazer em Posts

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.