Business Management APIs

Intermediação de empresas

A API de Intermediação de Empresas permite que um parceiro faça o seguinte:

  • Obtenha acesso para agir em nome do cliente.
  • Crie um usuário do sistema no Gerenciador de Negócios do cliente e busque o respectivo token de acesso.

Um usuário do sistema é definido como alguém que pode executar tarefas programáticas repetitivas, como atualizar um catálogo de produtos, enviar eventos entre servidores, atualizar públicos personalizados e assim por diante.

Neste cenário, o usuário do sistema tem acesso de funcionário e pode acessar apenas os ativos atribuídos (no momento da criação) usando o token de acesso de usuário administrador.

Há uma vantagem em utilizar um usuário do sistema em vez de um token de acesso do próprio usuário: os usuários podem encerrar um negócio sem que os tokens de acesso do usuário do sistema expirem. Na abordagem apresentada aqui, o cliente continua sendo o proprietário do negócio e concede ao parceiro acesso ao Gerenciador de Negócios e aos ativos por meio de um usuário do sistema. Um cliente pode acessar o Gerenciador de Negócios e excluir o usuário do sistema ou remover o acesso a determinados ativos de um parceiro de forma programática.

Introdução

Antes de começar, recomendamos que você leia os requisitos e as informações abaixo:

Gerenciador de Negócios do cliente

Quando o cliente cria uma conta comercial no Gerenciador de Comércio, ela é conectada ao respectivo Gerenciador de Negócios. Para encontrar o ID do Gerenciador de Negócios do cliente, siga estas instruções.

Caso o cliente não tenha um Gerenciador de Negócios, crie um antes de prosseguir. Para saber mais, consulte API do Gerenciador de Negócios.

Permissões do app

  • business_management

IDs

  • PARTNER_BM_ID: o ID do Gerenciador de Negócios do parceiro que deve ser o proprietário do app.
  • CLIENT_BM_ID: o ID do Gerenciador de Negócios do cliente que possui a Página do Facebook conectada à respectiva conta comercial.

Tokens de acesso

  • USERS_ACCESS_TOKEN: o token de acesso de um administrador do Gerenciador de Negócios do cliente, criado com permissões business_manage usando o app pertencente ao Gerenciador de Negócios do parceiro. Esse token é gerado por meio do Login do Facebook.
  • PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN: o token de acesso do usuário do sistema administrador no Gerenciador de Negócios do parceiro destinado ao app.
  • CLIENT_BM_SU_ACCESS_TOKEN: o token de acesso do usuário do sistema no Gerenciador de Negócios do cliente.
  • CLIENT_BM_SU_PAGE_ACCESS_TOKEN: o token de acesso à Página do usuário do sistema no Gerenciador de Negócios do cliente.

Etapas recomendadas

Etapa 1

Crie o relacionamento "Em nome de" entre o parceiro e o Gerenciador de Negócios do cliente.

Isso conectará os Gerenciadores de Negócios de ambas as partes e permitirá que o parceiro crie um usuário do sistema por meio da API na próxima etapa.

Token de acesso usado:USERS_ACCESS_TOKEN


curl -i -X POST \
 "https://graph.facebook.com/v19.0/<PARTNER_BM_ID>/managed_businesses?existing_client_business_id=<CLIENT_BM_ID>&access_token=<USERS_ACCESS_TOKEN>"

Etapa 2

Busque o token de acesso de usuário do sistema no Gerenciador de Negócios do cliente. Assim, será possível instalar o app no Gerenciador de Negócios do cliente e criar um usuário do sistema. Por padrão, o nome do usuário do sistema é "{Client_Business_Manager_Name} SYSTEM USER". O cliente poderá ver o app do parceiro no Gerenciador de Negócios como um ativo compartilhado, mas só terá acesso a ele se criar um usuário de teste.

No parâmetro scope, inclua as permissões que o usuário do sistema precisa ter para acessar os pontos de extremidade da API que sejam relevantes. Consulte as referências individuais da API para descobrir quais permissões de acesso são necessárias.

Token de acesso usado:PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN. Esse token exige a permissão business_management e todas as permissões incluídas nos parâmetros scope acima.


curl -i -X POST \
 "https://graph.facebook.com/v19.0/<CLIENT_BM_ID>/access_token?scope=ads_management,pages_read_engagement&app_id=<APP_ID>&access_token=<PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN>"

A resposta conterá o token para o usuário do sistema que está vinculado aos relacionamentos "Em nome de". Não é preciso criar nem utilizar qualquer outro usuário do sistema para fazer a integração comercial.

Etapa 3

Obtenha o número de identificação do usuário do sistema.

Token de acesso usado:CLIENT_BM_SU_ACCESS_TOKEN

curl -i -X GET \
 "https://graph.facebook.com/v19.0/me?access_token=<CLIENT_BM_SU_ACCESS_TOKEN>"

Etapa 4

Atribua ativos (Página e catálogo) ao usuário do sistema no Gerenciador de Negócios do cliente.

Token de acesso usado:USERS_ACCESS_TOKEN

curl -i -X POST \
 "https://graph.facebook.com/v19.0/<ASSET_ID>/assigned_users?user=<SYSTEM_USER_ID>&tasks=MANAGE&access_token=<USERS_ACCESS_TOKEN>"

Etapa 5

Armazene o CLIENT_BM_SU_ACCESS_TOKEN em um banco de dados seguro e use-o para acessar APIs que requerem um token de acesso do usuário, como a API de Gerenciamento de Catálogos.

Etapa 6

Gere um token de acesso à Página usando CLIENT_BM_SU_ACCESS_TOKEN com esta chamada:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/me/accounts?access_token=<CLIENT_BM_SU_ACCESS_TOKEN>"

A solicitação exibida listará todas as Páginas gerenciadas pelo usuário do sistema, incluindo o access_token correspondente. Exemplo de resposta:

{
  "data": [
    {
      "access_token": "<access token sanitized>",
      "category": "Retail Company",
      "category_list": [
        {
          "id": "2239",
          "name": "Retail Company"
        }
      ],
      "name": "Test_Shop_Page",
      "id": "<content sanitized>",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "<content sanitized>",
      "after": "<content sanitized>"
    }
  }
}

Copie o access_token da Página vinculada à conta comercial do cliente e armazene-o de forma segura. Ele será usado para acessar APIs que exigem um token de acesso à Página em nome da conta comercial, como a API de Gerenciamento de Pedidos e a API de Relatórios Financeiros.

Perguntas frequentes

Como posso excluir o relacionamento "Em Nome de" para remover o usuário do sistema que foi atribuído a mim no Gerenciador de Negócios do cliente?


curl -i -X DELETE \
 "https://graph.facebook.com/v19.0/<PARTNER_BM_ID>/managed_businesses?existing_client_business_id=<CLIENT_BM_ID>&access_token=<USERS_ACCESS_TOKEN>"

O cliente pode remover a conexão e o usuário do sistema do parceiro na visualização do app do Gerenciador de Negócios.