Introdução

Para usar o Gerenciador de Negócios, uma empresa precisa ter pelo menos uma página, um administrador, um nome comercial e um endereço de email válido.

O nome comercial é usado apenas para sua empresa e qualquer outro negócio com o qual você escolha compartilhar objetos. Depois de criar a empresa, você poderá adicionar páginas, contas de anúncios, apps, objetos de rastreamento de conversão externos e outros ativos relacionados a anúncios que pertencem a um negócio.

Requisitos

• Seu app precisa ter o nível apropriado de acesso à API de Marketing para usar a API do Gerenciador de Negócios. Em alguns casos, o acesso avançado talvez seja necessário. Saiba mais sobre os diferentes níveis de acesso.
• Seu app também precisa da permissão business_management.

Criar um novo Gerenciador de Negócios

Crie um novo Gerenciador de Negócios para representar sua empresa. Faça isso apenas se estiver configurando um novo Gerenciador de Negócios para você ou seus clientes. Se precisar de outra conta de anúncios ou acesso a outra página, use seu Gerenciador de Negócios e suas permissões de ativos existentes. Não é permitido excluir um Gerenciador de Negócios.

Por exemplo, crie um novo Gerenciador de Negócios com uma solicitação POST:

curl \
  -F "name=Pomni Media" \
  -F "vertical=ADVERTISING" \
  -F "primary_page=<PAGE_ID>" \
  -F "timezone_id=1" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses"

Requisitos

Para criar um negócio, você precisará do seguinte:

• Um token de acesso
• Uma identificação da Página
• Um setor
• Um número de identificação do usuário no escopo do app

A identificação da Página fornecida deve ser a página principal do seu negócio. Essa página representa publicamente sua empresa no Facebook. A pessoa que cria o negócio é designada como gerenciador da página. Caso você não tenha uma página que represente sua empresa no Facebook, crie uma.

O setor pode ser uma das opções a seguir:

ADVERTISING , AUTOMOTIVE , CONSUMER_PACKAGED_GOODS , ECOMMERCE , EDUCATION , ENERGY_AND_UTILITIES , ENTERTAINMENT_AND_MEDIA , FINANCIAL_SERVICES , GAMING , GOVERNMENT_AND_POLITICS ,MARKETING , ORGANIZATIONS_AND_ASSOCIATIONS , PROFESSIONAL_SERVICES , RETAIL , TECHNOLOGY , TELECOM , TRAVEL , OTHER

Para ver propriedades de uma empresa, use a identificação dela:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>?access_token=<ACCESS_TOKEN>"

Também é possível ver uma lista dos Gerenciadores de Negócios que você pode acessar:

curl "https://graph.facebook.com/<API_VERSION>/me/businesses?access_token=<ACCESS_TOKEN>"

Confira os campos de resposta:

Atualizar os Gerenciadores de Negócios

Para atualizar os campos no Gerenciador de Negócios, faça uma solicitação POST para https://graph.facebook.com/{API_VERSION}/{BUSINESS_ID}. Por exemplo, altere o nome comercial:

curl \
-F "name=My Actual Business Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

Altere o setor do negócio fazendo a seguinte solicitação POST:

curl \
-F "vertical=RETAIL" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

As seguintes opções estão disponíveis:

Você pode atualizar a página principal fazendo a solicitação POST a seguir. Essa página precisa pertencer ao Gerenciador de Negócios.

curl \
  -F "primary_page=<PAGE_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

Você também pode atualizar todas as opções acima fazendo uma solicitação POST:

curl \
  -F "name=My Actual Business Name" \
  -F "vertical=RETAIL" \
  -F "primary_page=<PAGE_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

Gerenciar pessoas e funções

Existem dois tipos de funções no Gerenciador de Negócios:

Para mais informações sobre funções, veja Como atribuir permissões de catálogo no Gerenciador de Negócios da Meta.

Inicialmente, o criador do negócio é o único usuário e também um administrador.

Convidar pessoas

Para adicionar colegas de trabalho ao seu negócio, você precisa enviar a eles um convite. Para isso, forneça um endereço de email válido ao qual a pessoa a ser convidada tenha acesso. O envio de solicitações para adicionar funcionários a um Gerenciador de Negócios é limitado. Ao atingir esse limite, você receberá o código de erro 17 e deverá retomar o processo 24 horas depois.

Para convidar alguém como administrador, envie uma solicitação POST:

curl \
-F "email=some@email.com" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

Para convidar alguém como funcionário, envie uma solicitação POST:

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

O Facebook envia um convite para o endereço de email de trabalho especificado. A pessoa que foi convidada precisa conferir o email e seguir o processo de cadastro. Quando o fluxo for concluído, você verá o nome dela na lista de usuários.

Pessoas no Gerenciador de Negócios

A partir da versão 2.11, disponibilizamos pontos de extremidade específicos para obter usuários com base no status. Faça um solicitação GET para buscar cada grupo de usuários. Para obter todos os usuários do negócio (observação: é obrigatório ter acesso avançado):

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users?access_token=<ACCESS_TOKEN>"

Para obter usuários do sistema, com acesso no nível do sistema:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users?access_token=<ACCESS_TOKEN>"

Para obter usuários pendentes que foram convidados a acessar um negócio, mas ainda não aceitaram o convite:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_users?access_token=<ACCESS_TOKEN>"

Os pontos de extremidade retornam usuários ativos, pendentes ou do sistema para seu negócio. Por exemplo:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "name": "Alpha MK",
      "email": "some@email.com",
      "role": "EMPLOYEE",
    }
  ]
}

Estes são os resultados para usuários pendentes:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "email": "some@email.com",
      "role": "EMPLOYEE",
      "status": "PENDING",
      "owner": {
        "id": "USER_ID",
        "name": "Generic Emporium"
      }
    }
  ]
}

As definições para campos retornados são as seguintes:

Alterar funções

Para alterar a função de um usuário ativo no seu negócio, é preciso fornecer o número de identificação dele. Por exemplo, você pode atualizar um Funcionário para a função de Administrador, com esta solicitação POST:

curl \
  -F "role=ADMIN" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

Para trocar uma função de Administrador para Funcionário, faça uma solicitação POST:

curl \
  -F "role=EMPLOYEE" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

Você pode alterar a função de um usuário pendente com esta solicitação POST:

curl \
  -F "role=EMPLOYEE" \
    -F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

Remover usuários

Remova as permissões concedidas a alguém com base na associação aos seus Gerenciadores de Negócios. Também é possível limitar o acesso a contas de anúncios e páginas. Se o usuário tiver acesso a contas de anúncios ou páginas fora do seu Gerenciador de Negócios, essas permissões não serão alteradas. Por exemplo, alguém pode ter se adicionado ou ter recebido acesso por meio de outro Gerenciador de Negócios.

Para remover um usuário ativo do seu negócio, faça uma chamada DELETE:

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

Para cancelar um usuário pendente com uma solicitação DELETE:

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

Isso removerá os usuários e o acesso aos ativos de negócios.

Obter objetos de conexão

Os objetos de conexão são objetos do Facebook (por exemplo, Páginas, app e assim por diante) que são gerenciados por um administrador. Um administrador pode ser um usuário ou uma empresa, ou no caso de apps, um desenvolvedor ou um anunciante. Os tipos de objetos de conexão são os seguintes:

• Páginas e locais
• Eventos
• Apps
• Domínios

Veja exemplos de consultas e saiba mais em Connection Objects.

Faturas

A API do Gerenciador de Negócios permite visualizar e gerenciar fontes de crédito associadas a uma empresa. A API busca todas as faturas visíveis para um Gerenciador de Negócios. Isso significa que todas as faturas pelas quais esse Gerenciador de Negócios é responsável ficam visíveis via API, e não apenas as faturas pertencentes a uma identificação da empresa individual.

Linha de crédito normal de propriedade do Gerenciador de Negócios

Para os parceiros da API de Marketing que têm o faturamento habilitado, você pode aproveitar as vantagens da linha de crédito normal de propriedade do Gerenciador de Negócios.

Os Parceiros de Marketing do Facebook (FBMP, pelas iniciais em inglês) precisam entrar em contato com o representante de vendas para configurar o crédito do Gerenciador de Negócios. Não se esqueça de solicitar a linha de crédito normal de propriedade do Gerenciador de Negócios. Depois de configurado, você pode começar a usar a API de criação de conta de anúncios para começar a criar suas contas. As cobranças serão feitas com base na linha de crédito do seu Gerenciador de Negócios.

Para as contas de anúncios criadas por meio da API a seguir, distribuiremos o crédito dinamicamente entre as contas e atualizaremos os limites de crédito e gastos para evitar que eles sejam atingidos. Também será possível ver o crédito resumido e o valor disponível em cada conta de anúncios.

No momento, trabalhamos apenas com a responsabilidade normal, e não com a responsabilidade sequencial. O processo para essa configuração permanecerá inalterado.

Faturamento de fim do mês

Depois que sua linha de crédito for configurada para uma empresa e usada para veicular anúncios, geraremos faturas de final do mês para a conta empresarial. Para ver as faturas do negócio, você precisa ter uma função relacionada a finanças. Para o tipo padrão de administradores e funcionários de uma empresa, você pode atribuir permissões em People no Gerenciador de Negócios. Você também pode atribuir permissões relacionadas a finanças aos usuários do sistema usando o Gerenciador de Negócios.

Para buscar faturas de uma conta empresarial via API, envie uma solicitação GET:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?start_date=2017-01-01&end_date=2017-04-01"

Estes são os exemplos de resultados:

{
  "business_invoices": {
    "data": [
      {
        "id": "1659175694099710",
        "billing_period": "2017-03-01"
      },
      {
        "id": "1303851778395619",
        "billing_period": "2017-01-01"
      },
      {
        "id": "1415846861611329",
        "billing_period": "2017-02-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "249554531892085"
}

É possível obter detalhes da fatura no nível da campanha com esta solicitação:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?fields=billed_amount_details,billing_period,entity,id,invoice_id,payment_term,type,campaigns&start_date=2019-06-01&end_date=2019-07-01"

A resposta é semelhante a esta:

{
  "business_invoices": {
    "data": [
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "387.70",
          "tax_amount": "0.00",
          "total_amount": "387.70"
        },
        "billing_period": "2017-03-01",
        "entity": "FBUS",
        "id": "1659175694099710",
        "invoice_id": "22736800",
        "liability_type": "Normal",
        "invoice_type": "Invoice",
        "payment_term": "CUSTOMER",
        "type": "Invoice",
        "campaigns": {
          "data": [
            {
              "campaign_id": "6056967798500",
              "campaign_name": "Nhận ưu đãi",
              "tags": [
                "hello2"
              ],
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "207.62",
                "tax_amount": "0.00",
                "total_amount": "207.62"
              }
            },
            {
              "campaign_id": "6056958052500",
              "campaign_name": "Nhận ưu đãi",
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "180.08",
                "tax_amount": "0.00",
                "total_amount": "180.08"
              }
              "impressions": 100,
              "clicks": 50,
              "conversions": 30
            }
          ]
        }
      },
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "382.99",
          "tax_amount": "0.00",
          "total_amount": "382.99"
        },
        ......
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "1515766328651000"
}

Você também pode recuperar os campos de faturamento adicionais:

• invoice_date: data em que o Facebook gerou a fatura.
• due_date: data de vencimento da fatura.
• payment_status: mostra se a fatura está Paid, Unpaid ou Partially Paid.
• amount_due: o valor devido e pendente na fatura.
• download_uri: baixe um PDF da fatura neste URI.

API de Forma de Pagamento

Para buscar a forma de pagamento de crédito estendido associada a um Gerenciador de Negócios, envie esta solicitação GET:

curl "https://www.graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/extendedcredits"

Para configurar uma forma de pagamento para um empresa, acesse as configurações do seu negócio no Gerenciador de Negócios.

Alocação Dinâmica de Crédito

A Alocação Dinâmica de Crédito (DCAF, pelas iniciais em inglês) é nosso sistema de alocação de crédito que funciona para ajustar periodicamente o crédito disponível por conta de anúncios. Nosso script automatizado é executado aproximadamente a cada 30 minutos e usa seu crédito disponível e o distribui uniformemente por todas suas contas ativas habilitadas para a DCAF. O valor disponível inclui o crédito total aprovado menos o saldo devedor total. Isso ajuda a gerenciar os gastos no nível da conta de anúncios e a alocar fundos para cada conta.

Uma empresa também pode "inativar" uma conta de anúncios faturada e removê-la da lista de contas que precisam de crédito atribuído. As empresas não dependem mais do Facebook para gerenciar esse status.