Conectar Páginas do Facebook

Crie um link de conexão do Facebook, associe Páginas do proprietário aos seus locais, confirme ou escolha vínculos e desconecte a conta se o cliente sair.

Uma conta do Facebook conectada permite publicar e gerar relatórios para um local no Facebook. Depois que uma Página é vinculada, as publicações podem usar FACEBOOK como destino em postSites, o endpoint de análise do Facebook retorna métricas da Página em vez de null, a Página é adicionada como fonte de avaliações para que suas avaliações cheguem junto com as demais, e a linha do Facebook nas listagens premium do local sai de REQUIRING_ACTION.

O fluxo é o mesmo do Google: crie um link, deixe o proprietário dar consentimento, busque correspondências e confirme. Quando um valor é diferente para o Facebook, essa diferença é indicada.

A Página do Facebook já deve ter horários de funcionamento definidos no Facebook. O Facebook rejeita uma atualização do ListingsAPI para uma Página sem horários, mesmo quando o local tem businessHours. Nesse caso, a listagem do Facebook permanece em IN_PROGRESS com um syncIssue sobre a ausência de horários. Para corrigir isso, adicione os horários de funcionamento à Página no Facebook e, em seguida, envie uma atualização do local.

1. Crie o link de conexão e redirecione o proprietário

O corpo contém apenas suas duas URLs de redirecionamento. O link se limita à conta à qual a chave pertence e é válido por 24 horas.

Connect link

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/facebook/success",    "errorUrl": "https://app.example.com/connect/facebook/error"  }}'

JSON

{  "data": {    "bulkConnectLinkForFacebook": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

O url acima é um valor de exemplo. Direcione o proprietário para o url retornado na sua própria resposta.

Redirecione o proprietário para url. Ele aceita os termos do Facebook, concede as permissões da Página e é direcionado para seu successUrl.

2. Liste as contas conectadas após o retorno do OAuth

Filtre por publisher=FacebookAccount. Esta é uma página com paginação por offset: records[] mais pageInfo.totalRecords, paginada com page e perPage.

List accounts

curl "https://listingsapi.com/api/v4/connected-accounts?publisher=FacebookAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",          "connectedAccountType": "FacebookAccount",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

Guarde o connectedAccountId. status é CONNECTED, MATCH_IN_PROGRESS ou CONNECTIVITY_ISSUE; qualquer valor diferente de CONNECTED significa que o proprietário precisa autorizar novamente para que as próximas etapas funcionem.

3. Inicie a busca de correspondências e aguarde sua conclusão

A busca de correspondências recupera as Páginas às quais a conta tem acesso e associa cada uma a um dos seus locais. Ela é executada em segundo plano, então consulte periodicamente os detalhes da conta até que requestMatchesStatus seja MATCH_COMPLETED. Consultar as sugestões antes disso retorna um array records vazio, que parece indicar "nenhuma correspondência".

Trigger and poll

curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["d2397854-52c2-41d7-95f1-b90cba16498d"] } }' # then, every 15 seconds until requestMatchesStatus is MATCH_COMPLETEDcurl https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/details \-H "Authorization: API $LISTINGSAPI_KEY"

O registro de detalhes é retornado em data.connectedAccountDetails.details. MATCH_COMPLETED significa que a busca de correspondências terminou; nada é vinculado até você confirmar, então connectedLocationsCount permanece em 0 por enquanto.

4. Revise e confirme as sugestões

Cada registro associa seu local (locationInfo, locationId) a uma Página (suggestedLocationInfo). Para uma conta do Facebook, accountType é FB em vez de GMB, e isso altera o id que você envia para confirmar.

Suggestions

curl "https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

Uma sugestão não tem id. Crie um codificando <MatchRecordType>:<matchedDataDatabaseId> em base64 e escolhendo o tipo a partir de accountType. A referência mostra apenas um exemplo do Google, que, ao ser decodificado, resulta em GmbLocationMatchedData:...; o tipo varia conforme a plataforma de publicação. Para o Facebook, ele é FbLocationMatchedData, então FB com 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc é codificado como RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==.

`accountType`	Tipo de registro de correspondência
`GMB`	`GmbLocationMatchedData`
`FB`	`FbLocationMatchedData`
`APPLE`	`AppleLocationMatchedData`

Confirm matches

# base64 of FbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw=="] } }'

A resposta é data.confirmConnectMatches com success e failedIds, os ids decodificados do banco de dados que não puderam ser confirmados. Um id criado com o tipo errado retorna 200 com success: false e sem failedIds, então sempre verifique success.

5. Vincule uma Página a um local manualmente

Quando a busca de correspondências não chega a um resultado seguro, ou quando uma Página foi criada após a execução da busca, liste as Páginas que a conta consegue visualizar e vincule uma diretamente. connectedAccountId deve ser incluído no corpo JSON da chamada de listagens; como parâmetro de consulta, ele é ignorado, e você recebe as listagens da primeira conta conectada.

Pick and link

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d", "locationInfo": "Lincoln" }' curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",    "connectedAccountListingId": "<id from the listings response>"  }}'

Cada registro de listagem contém id, locationName, address e liveLink. Seu id é o connectedAccountListingId que connect-listing recebe; o campo não se chama listingId. Uma tentativa de vínculo malsucedida retorna success: false com um message, como Listing record not found.

6. Desconecte a conta quando um cliente sair

A desconexão é tudo ou nada: todas as Páginas vinculadas pela conta deixam de sincronizar e as interações do Facebook deixam de chegar. Para desvincular um único local mantendo a conta, use disconnect-listing.

Disconnect

curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'

A resposta é data.fbBulkDisconnect com success. Ela é true mesmo para um connectedAccountId desconhecido, portanto significa "processado", e não "uma conexão ativa foi removida". Liste as contas conectadas novamente se precisar de certeza.

7. O que acontece em seguida

Um evento connection.location_connected com data.platform: "facebook" é disparado para cada local vinculado, e connection.location_disconnected é disparado quando você desfaz o vínculo. Se o Facebook invalidar a autorização, você receberá connection.reauth_required: crie um novo link (etapa 1) e peça ao proprietário que dê seu consentimento novamente com todas as permissões. Após a vinculação, a linha do Facebook nas listagens premium do local passa para SYNCED, postSites: ["FACEBOOK"] se torna um destino válido e o endpoint de análise do Facebook começa a retornar dados.

Próximas etapas

Publicar posts: envie um anúncio para o Google e o Facebook ao mesmo tempo.
Obter dados de análise do perfil: consulte as métricas da Página que chegam após a conexão.
Conectar o Google e importar locais: o passo a passo mais completo do mesmo fluxo.
Referências dos SDKs: contas conectadas em Python e contas conectadas em Node.
Referência: Conectar uma conta do Facebook, Confirmar correspondências de conexão, Conectar uma listagem a um local, Desconectar uma conta do Facebook.