Como integrar a API do Instagram
Um guia prático de integração com a API do Instagram: autenticação, conexão de conta e primeira publicação.
Por André LugIntegrar com a API do Instagram direto significa lidar com OAuth da Meta, containers de mídia, App Review e um conjunto de códigos de erro que mudam de comportamento dependendo do estado da conta. O PostGate resolve essa camada uma vez: você autentica com a sua própria chave de API, conecta a conta do cliente através de uma URL hospedada e publica com um único endpoint — para Instagram e para as outras redes que o seu produto precisar depois.
Este guia cobre os três passos reais de uma integração: autenticação, conexão da conta e a primeira publicação.
1. Autenticação
Toda requisição para /api exige uma chave do PostGate no cabeçalho Authorization. Guarde a chave em um secret manager ou variável de ambiente — nunca em código que roda no navegador ou em um app mobile.
Use uma chave pg_test_ enquanto desenvolve: ela executa o ciclo completo — validação, jobs, targets, logs de entrega e webhooks — contra um adaptador de sandbox, sem chamar o Instagram de verdade. Troque para pg_live_ só quando for publicar em contas reais.
curl https://postgate.studio/api/profile-groups \
-H "Authorization: Bearer $POSTGATE_API_KEY"2. Conectar a conta do Instagram
O PostGate cria uma URL de conexão hospedada por trás da qual roda o fluxo OAuth da Meta inteiro. Antes disso, registre a origem do seu produto uma única vez em Dashboard → Chaves de API → Connect origins — o PostGate só redireciona de volta para uma origem que você autorizou.
Crie a URL no seu backend e redirecione o navegador do cliente para ela. Ela expira em 15 minutos. Do ponto de vista do cliente, o fluxo é nativo: ele sai do seu produto, autoriza a conta no Instagram e volta direto para o return_url que você informou.
curl -X POST https://postgate.studio/api/profiles/connect \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "instagram",
"profile_group_id": "grp_acme123",
"return_url": "https://app.example.com/settings/social"
}'3. Ler o resultado da conexão
Quando a Meta termina o fluxo, o PostGate redireciona o cliente de volta com connected (quantas contas foram anexadas) e connection_platform. Se o cliente cancelar ou o Instagram recusar, o retorno traz connection_error no lugar. Liste os perfis do grupo para confirmar o resultado completo.
4. Publicar o primeiro post
Com o perfil conectado, publicar é uma chamada só, passando o id do perfil e um cabeçalho Idempotency-Key estável — assim uma nova tentativa depois de um timeout nunca publica o mesmo conteúdo duas vezes.
curl -X POST "https://postgate.studio/api/posts?profile_group_id=grp_acme123" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-post-001" \
-d '{
"post": { "body": "Dia de lançamento. 🚀" },
"profiles": ["pro_instagram123"],
"media": ["https://cdn.example.com/launch.jpg"]
}'5. Próximos passos
A partir daqui, os pontos que costumam gerar dúvida são o token de acesso por trás da conexão, o fluxo OAuth em si e os códigos de erro que a Meta devolve durante a publicação — cada um tem um guia dedicado abaixo. Para o contrato completo da API, veja a documentação de autenticação e a documentação de perfis e conexões.
