Documentação
Guia de configuração Meta
Conteúdo de docs/meta_setup.md.
# Meta (Facebook e Instagram) — guia de configuração
> Atualizado em 27/10/2026. Siga em ordem. Nenhuma credencial vai no código:
> elas ficam em `php_v2/config/*.local.php` (gravados pelo Assistente) ou no `.env`.
## Como a integração funciona hoje
| Rede | Como conecta | Como publica | Precisa de URL pública? |
|---|---|---|---|
| Facebook (Página) | Facebook Login (App Meta) | upload direto da foto (`/{page-id}/photos`) | Não — funciona em `localhost` |
| Instagram (conta profissional) | Instagram API com login do Instagram (app do Instagram) | a Meta baixa a imagem por URL e publica (`/media` + `/media_publish`) | **Sim, HTTPS** |
- Graph API: `v26.0` (configurável em `graph_version` / `FUBIZSOCIAL_META_GRAPH_VERSION`).
- Permissões do Facebook: `pages_show_list`, `pages_read_engagement`, `pages_manage_posts`.
- Permissões do Instagram (login do Instagram): `instagram_business_basic`,
`instagram_business_content_publish` (o assistente também pede comentários e mensagens).
- Tokens ficam criptografados (AES-256-GCM) no banco e no arquivo do assistente; nunca aparecem na tela nem no log.
- **Publicação é manual** (botão “Publicar no Facebook/Instagram” na tela da publicação).
“Agendado” registra data e hora no calendário; ainda não existe um publicador automático (cron).
- Suporte atual: **uma imagem por publicação** (a 1ª mídia). Facebook: JPG/PNG. Instagram: JPG.
Vídeo, Reels, Stories e carrossel ainda não são publicados pela API.
## Etapa 1 — App na Meta for Developers
1. Acesse https://developers.facebook.com, entre com o Facebook que administra a Página.
2. **Meus apps → Criar app** (tipo empresa/Business).
3. Adicione os casos de uso/produtos:
- **Facebook Login for Business** (Páginas);
- **Instagram → API do Instagram com login do Instagram**.
4. Anote:
- **App ID** e **Chave secreta do app** (Configurações → Básico) — usados no Facebook;
- **ID do app do Instagram** e **Chave secreta do app do Instagram** (tela “API do Instagram”) — usados no Instagram.
Nunca envie as chaves secretas por chat ou e-mail.
## Etapa 2 — URIs de redirecionamento (cadastrar exatamente)
Facebook Login → Configurações → **URIs de redirecionamento do OAuth válidos**:
```
http://localhost/FubizSocial/php_v2/public/meta_setup_live.php?oauth=facebook_callback
http://localhost/FubizSocial/php_v2/public/index.php?r=meta_callback
```
A primeira é usada pelo Assistente Meta; a segunda pelo botão “Conectar Facebook direto”
(Contas sociais). As duas aparecem prontas para copiar no próprio sistema.
API do Instagram → Configurar login comercial → **URL de redirecionamento**:
```
https://SEU-ENDERECO-PUBLICO/FubizSocial/php_v2/public/instagram_oauth_callback.php
```
O Instagram exige HTTPS. O assistente mostra a URL exata depois que você salva a URL pública (Etapa 4).
## Etapa 3 — Credenciais no sistema
Abra o assistente (só funciona no próprio computador):
```
http://localhost/FubizSocial/php_v2/public/meta_setup_live.php
```
- Etapa 7: App ID + Chave secreta do Facebook → grava `config/meta.local.php`.
- Etapa 8: ID + Chave secreta do app do Instagram → grava `config/instagram.local.php`.
Alternativa: variáveis no `php_v2/.env` (`FUBIZSOCIAL_META_APP_ID`, `FUBIZSOCIAL_META_APP_SECRET`,
`FUBIZSOCIAL_IG_APP_ID`, `FUBIZSOCIAL_IG_APP_SECRET`). Variáveis de ambiente têm prioridade sobre os arquivos.
## Etapa 4 — URL pública HTTPS (somente para Instagram)
A Meta precisa baixar a imagem do FubizSocial. Em ambiente local use um túnel, por exemplo
Cloudflare Tunnel (`cloudflared tunnel --url http://localhost:80`) ou ngrok, e informe na
etapa 8 do assistente a base que termina em `/FubizSocial/php_v2/public`, por exemplo:
```
https://exemplo.trycloudflare.com/FubizSocial/php_v2/public
```
- Túneis rápidos mudam de endereço a cada execução: atualize a URL no assistente e a URL de
redirecionamento do Instagram na Meta sempre que o endereço mudar.
- Pelo túnel, o FubizSocial só responde ao **callback do Instagram** e ao **arquivo de mídia**
(`index.php?r=media_file`). Todo o resto é bloqueado porque o sistema ainda não tem login
(veja `FUBIZSOCIAL_ACCESS` no README).
## Etapa 5 — Conectar e aplicar ao cliente
1. No assistente, etapa 7: **Continuar com Facebook** → autorize → escolha a Página.
2. Etapa 8: **Continuar com Instagram** → autorize a conta profissional.
3. No sistema, selecione o cliente no topo (Perfil) e abra **Contas sociais → Aplicar conexão ao perfil**.
4. Clique em **Testar conexão** em cada rede.
Alternativa só para Facebook: **Contas sociais → Conectar Facebook direto** (escolhe a Página e grava direto no cliente).
## Etapa 6 — Diagnóstico
**Configurações → Diagnóstico Meta**:
- “Verificação local”: App ID/Secret, redirect, cURL, OpenSSL, criptografia, sessão, URL pública.
- **Testar agora** (somente leitura): valida App ID + Secret na Meta, testa os tokens das contas do
perfil atual (validade, escopos, expiração) e verifica se a URL pública responde. Nada é publicado.
## Tokens
- Facebook (token de Página obtido de token de usuário de longa duração): normalmente não expira,
mas é invalidado se a senha mudar, a permissão for removida ou o app perder acesso.
- Instagram (login do Instagram): vale 60 dias. Use **Contas sociais → Renovar token** antes de vencer
(a renovação só funciona com o token ainda válido e com pelo menos 24 h de idade).
- **Desconectar** apaga o token do banco (posts e campanhas continuam).
## Modo de desenvolvimento x produção
- Com o app em **Desenvolvimento**, só usuários com função no app (administrador, desenvolvedor,
testador) conseguem autorizar e publicar.
- Para publicar em Páginas/contas de clientes sem função no app, a Meta exige **Revisão do app**
(Acesso Avançado) das permissões acima, verificação da empresa e, no modo ao vivo, HTTPS.
## O que depende da Meta / infraestrutura (não dá para resolver no código)
- Revisão do app e verificação de empresa para uso com clientes reais.
- Conta do Instagram profissional (Empresa ou Criador).
- URL pública HTTPS estável (domínio próprio ou túnel ativo) para publicar no Instagram.
- O usuário que autoriza precisa ter permissão de criar conteúdo na Página.
## Referências oficiais
- https://developers.facebook.com/docs/graph-api/overview
- https://developers.facebook.com/docs/graph-api/changelog/
- https://developers.facebook.com/docs/permissions/reference
- https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login