Contas e profiles

Uma conta conectada (integration) é uma conta do Instagram que autorizou a Postmatic a publicar por ela. Um profile é um rótulo opcional para agrupar contas, por exemplo um cliente da sua agência ou uma marca.

Requisitos da conta

• Conta do Instagram profissional: Business ou Creator. Uma conta pessoal é recusada na autorização com ACCOUNT_NOT_BUSINESS; o usuário converte a conta nas configurações do Instagram e tenta de novo.
• A conexão usa o Instagram Login da Meta. Não é preciso ter uma Página do Facebook vinculada.
• Permissões concedidas: perfil básico, publicação de conteúdo, métricas, comentários e mensagens diretas.

A conexão pede cinco permissões: publicação, leitura básica, métricas, comentários e mensagens. Uma conta conectada antes de métricas, comentários ou mensagens existirem precisa ser reconectada para usá-los; scopes na listagem mostra o que cada conta concedeu.

Conectar pela API

O fluxo tem três passos: pedir a URL, redirecionar o usuário, receber o retorno.

1. Peça a URL de autorização

curl "https://api.uat.postmatic.dev/v1/connect/instagram?redirectUri=https://app.exemplo.com/contas&profileId=prf_…" \
  -H "x-access-key: pm_live_…"

{ "url": "https://www.instagram.com/oauth/authorize?…" }

A URL vale por 10 minutos. Só a plataforma instagram está disponível; qualquer outra responde 403 PLATFORM_NOT_AVAILABLE.

2. Redirecione o usuário

Abra a url no navegador do usuário. Ele faz login no Instagram e autoriza. Não abra em iframe: a Meta bloqueia.

3. Receba o retorno

A Meta devolve o usuário à Postmatic, que troca o código por um token de longa duração, guarda o token cifrado e redireciona para o seu redirectUri com o resultado na query string.

Guarde o integrationId: é o accountId das publicações. Se a mesma conta do Instagram for conectada de novo no mesmo projeto, a Postmatic atualiza a conexão existente em vez de criar outra. É assim que se reconecta uma conta com token vencido.

Listar contas

curl "https://api.uat.postmatic.dev/v1/connect/integrations?profileId=prf_…&limit=50" \
  -H "x-access-key: pm_live_…"

{
  "success": true,
  "total": 1,
  "integrations": [
    {
      "id": "int_…",
      "platform": "instagram",
      "platformUserId": "17841400000000000",
      "displayName": "acme.brand",
      "imageUrl": "https://…",
      "profileId": "prf_…",
      "createdAt": "2026-09-01T12:00:00.000Z",
      "authStatus": "active",
      "status": "connected",
      "tokenExpiresAt": "2026-10-31T12:00:00.000Z",
      "lastHealthCheckAt": "2026-09-08T06:30:00.000Z",
      "healthError": null
    }
  ]
}

Os sete primeiros campos são o contrato básico da conta. Os demais são a saúde da conexão, que a Postmatic mantém sozinha:

Saúde de uma conta

Para verificar uma conta na hora, em vez de esperar a rotina:

curl "https://api.uat.postmatic.dev/v1/integrations/int_…/health?force=true" \
  -H "x-access-key: pm_live_…"

{
  "success": true,
  "health": {
    "integrationId": "int_…",
    "status": "connected",
    "authStatus": "active",
    "healthy": true,
    "tokenExpiresAt": "2026-10-31T12:00:00.000Z",
    "tokenRefreshedAt": "2026-09-01T12:00:00.000Z",
    "daysUntilExpiry": 53,
    "lastHealthCheckAt": "2026-09-08T14:02:11.000Z",
    "healthError": null,
    "scopes": ["instagram_business_basic", "instagram_business_content_publish"],
    "checkedLive": true
  }
}

A Postmatic só consulta a Meta se a última verificação tiver mais de 10 minutos; antes disso devolve o resultado guardado, com checkedLive: false. force=true consulta sempre. Cada consulta ao vivo conta na cota da conta na Meta, então não chame em loop.

Tokens e renovação

O token da Meta dura 60 dias. A Postmatic renova sozinha, a cada 6 horas, os tokens com mais de 7 dias desde a última renovação, e verifica a saúde de todas as contas na mesma frequência. Você só precisa agir quando authStatus virar reconnect_required: isso acontece se o usuário trocar a senha, remover o app no Instagram ou a conta for restringida.

Desconectar

curl -X DELETE https://api.uat.postmatic.dev/v1/connect/integrations/int_… \
  -H "x-access-key: pm_live_…"

O token é apagado e a conta some da listagem. Posts já publicados continuam no Instagram; agendamentos para essa conta vão falhar com TOKEN_INVALID.

Profiles

Use profiles quando você atende vários clientes com o mesmo projeto: crie um por cliente, passe o profileId na conexão e filtre contas e posts por ele.

curl -X POST https://api.uat.postmatic.dev/v1/profiles \
  -H "x-access-key: pm_live_…" \
  -H "content-type: application/json" \
  -d '{ "name": "Acme", "description": "Cliente desde 2026" }'

Nas listagens de contas e de posts, profileId="null" (a string) seleciona o que não tem profile.