Como postar no Instagram via API
O passo a passo real: conectar a conta, criar o container de mídia e publicar — com um exemplo de requisição completo.
Por André LugPostar no Instagram via API envolve três passos que não mudam, seja você um SaaS de agendamento ou um script interno: conectar a conta profissional, entregar a mídia e criar o post. A Graph API da Meta resolve isso internamente através de um container de mídia — um objeto intermediário que precisa ficar pronto antes da publicação sair do ar. O PostGate esconde essa etapa atrás de uma única chamada, mas entender o que acontece por baixo ajuda a debugar quando algo trava.
Este guia é o passo a passo técnico. Para uma visão geral da API do Instagram (requisitos, formatos suportados, sandbox), veja a landing da API para Instagram.
Conectar a conta profissional
A API de publicação do Instagram só funciona com contas Business ou Creator — contas pessoais não são suportadas pela Graph API da Meta, independente de qual produto você usa por cima dela. No PostGate, a conexão é hospedada: o cliente final autoriza pelo fluxo OAuth da própria Meta, e você recebe de volta um ID de perfil (pro_...) para usar em todas as chamadas seguintes. Você nunca precisa guardar, renovar ou rotacionar o token de acesso do Instagram manualmente.
O que acontece com o container de mídia
Ao criar um post com uma imagem ou vídeo, a Meta primeiro sobe a mídia para um container próprio, que passa por estados como processamento até ficar pronto para publicação. Isso é assíncrono — um vídeo maior pode levar mais tempo para ficar pronto do que uma foto. Se o container falhar a validação (por exemplo, um formato ou proporção não suportados), a publicação não sai, e o erro fica disponível no target daquele destino.
Você não precisa gerenciar esse container diretamente: basta passar a URL pública da mídia (ou um ID de mídia pré-enviado) no mesmo envelope da requisição de post, e o PostGate cuida da criação, validação e checagem de status do container do lado do Instagram.
Publicar com um único POST
Com a conta conectada, publicar é uma chamada só: o corpo do post, o array de perfis de destino e a mídia. O cabeçalho Idempotency-Key torna essa requisição segura para repetir — se sua aplicação tentar de novo depois de um timeout de rede, o PostGate devolve o resultado da primeira tentativa em vez de publicar duas vezes.
curl -X POST https://postgate.studio/api/posts \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-post-001" \
-d '{
"post": { "body": "Lançamento hoje 🚀" },
"profiles": ["pro_instagram123"],
"media": ["https://cdn.example.com/launch.jpg"]
}'Ler o resultado por destino, não só o status geral
A resposta da criação é aceitação, não prova de publicação — o post entra em processamento e o estado final chega por destino, dentro do array targets: status, tentativas, erro (se houver), ID retornado pela própria plataforma e o link permanente do post publicado. Um post pode terminar como partial se publicar em um destino e falhar em outro — trate isso como resultado terminal válido, não como erro genérico.
