Business Management APIs

Funções entre empresas

Desde 8 de junho de 2021, o acesso a esses pontos de extremidade é limitado. Os apps que não tiverem acesso receberão um erro.

Solicitar o acesso aos ativos

Um Gerenciador de Negócios pode solicitar acesso a uma conta de anúncios ou Página de propriedade de outro Gerenciador de Negócios. Ele deve especificar as tarefas que deseja atribuir na solicitação.

Para atribuir uma empresa a uma Página, é preciso ter um token de página. Por exemplo:

curl 
  -F "business=<BUSINESS_ID>"
  -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']"   
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Para solicitar acesso AGENCY, é preciso fornecer permitted_tasks na solicitação. Você só pode enviar uma solicitação de acesso aos ativos para o Gerenciador de Negócios que pretende aprovar e que já conheça sua empresa.

Por exemplo, uma empresa que necessita de acesso ao adaccount_id e precisa atribuir seus funcionários como ['ADVERTISE', 'ANALYZE'], deverá fazer a seguinte chamada POST:

curl \
  -F "adaccount_id=act_<AD_ACCOUNT_ID>" \
  -F "permitted_tasks=['ADVERTISE','ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_ad_accounts?access_token=<ACCESS_TOKEN>"

Assim como para uma Página, se você desejar atribuir tarefas ['ADVERTISE', 'ANALYZE'] para uma Página da qual uma pessoa não é proprietária:

curl \
  -F "page_id=<PAGE_ID>" \
  -F "permitted_tasks=['ADVERTISE','ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_pages?access_token=<ACCESS_TOKEN>"

Essas chamadas enviam uma notificação para os respectivos administradores da conta de anúncios ou Página, pedindo para aceitar a solicitação de acesso. Os respectivos administradores verão a notificação no Gerenciador de Anúncios ou no Gerenciador de Páginas. Eles também podem aceitar a solicitação na interface do usuário. Caso queira ver as solicitações pendentes por meio da API, faça uma solicitação GET e marque PENDING para o campo access_status.

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

A resposta:

"data": [
 {
    "name": "Random Page", 
    "page_permissions": [
    {
    "id": "1900952844321", 
    "permitted_tasks": [
        'MANAGE',
        'CREATE_CONTENT', 
        'MODERATE',  
        'ADVERTISE', 
        'ANALYZE',
    ], 
    "access_status": "CLIENT_RESPONSE_PENDING", 
    "access_requested_time": "2014-01-07T23:26:09+0000", 
    "access_updated_time": "2014-01-07T23:26:09+0000"
    }
    ], 
    "id": "190137931178903"
 },

Conceder acesso aos ativos de outro Gerenciador de Negócios

Isso também é conhecido como adicionar uma agência ao seu objeto.

Para aceitar uma solicitação de acesso a um objeto que é seu de outro Gerenciador de Negócios, ou para conceder acesso a um dos seus objetos a outro Gerenciador de Negócios, é preciso especificar a empresa e a lista de tarefas às quais ele terá acesso.

Se o token de acesso usado para fazer a chamada da API pertencer a um usuário ou usuário do sistema que tenha acesso ao ativo solicitado por meio de uma empresa, o acesso ao ativo poderá ser concedido somente se essa empresa for a OWNER do ativo. Não é possível conceder acesso a ativos dos quais você é apenas uma AGENCY.

Por exemplo, para conceder a uma pessoa acesso a uma conta de anúncios usando as tarefas [ADVERTISE,ANALYZE], use esta solicitação POST:

curl \
  -F "business=<BUSINESS_ID>" \
  -F "permitted_tasks=['ADVERTISE', 'ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Para conceder a uma empresa acesso à sua página com [ADVERTISE], [MODERATE] e [ANALYZE]:

curl \
  -F "business=<BUSINESS_ID>" \
  -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

No caso de conceder acesso a uma conta de anúncios, ocasionalmente, uma análise de outro administrador de negócios é necessária como medida de segurança. Para aprovar essa análise, acesse https://business.facebook.com/settings/requests/admin_reviews. Nesse caso, a resposta terá um campo adicional indicando que a análise é necessária.

{
  "success": true,
  "requires_admin_approval": true
}

Os administradores de páginas também podem aceitar solicitações de acesso de uma agência nas abas Manage Admin Roles das configurações de uma página no site facebook.com.

Remover o acesso aos ativos

Isso também é chamado de remover uma agência da sua empresa. Para remover o acesso de um Gerenciador de Negócios da sua conta de anúncios:

curl \
  -X DELETE \
  -F "business=<BUSINESS_ID>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Da mesma forma, para remover o acesso de uma empresa da sua Página:

curl \
  -X DELETE \
  -F "business=<BUSINESS_ID>" \
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Visualizar acesso de agência

Para ver todas as empresas que têm acesso à sua conta de anúncios com uma chamada GET:

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

Para ver todas as empresas que têm acesso à sua página:

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

Para ver todas as empresas que têm acesso aos seus ativos de negócios:

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

Visualizar acesso do cliente

Para ver todas as empresas que concederam a você o acesso a uma ou mais das respectivas contas de anúncios ou páginas, use a seguinte chamada GET:

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

Managing Your Relationship as an Ad Agency Acting on Behalf of Another Business

These APIs allow you to manage the relationship between your Ad Accounts and the businesses for which you are acting on behalf of (OBO). Creating these relationships allows you to access custom audiences for the business and use of the audience overlap tool.

View OBO Request Details

To view the details of an OBO request, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<OBO_REQUEST_ID>?fields=id,receiving_business,requesting_business,status,business_owned_object"

The response contains the details of the OBO request and looks like this:

{
  "id": "1111111111",
  "receiving_business": {
    "id": "2222222222",
    "name": "Example Business Name"
  },
  "requesting_business": {
    "id": "3333333333",
    "name": "Example Business Name"
  },
  "status": "IN_PROGRESS",
  "business_owned_object": "1111111111"
}

Delete OBO Request

To cancel a pending request to act OBO another business, make this DELETE request:

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

The response, indicating success or failure, looks like this:

{
  "success": "true" 
}

View the Status of OBO Requests for an Ad Account

To view the status of requests to act OBO another business for an Ad account, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/onbehalf_requests?
    fields=id,status,receiving_business,requesting_business&status=<STATUS>"

The status parameter in the request must be APPROVE, DECLINE, or IN_PROGRESS.

The response contains an array with the OBO request objects for an Ad account matching the requested status.

Example response:

{
  "data": [
    {
      "id": "1111111111",
      "status": "IN_PROGRESS",
      "receiving_business": {
        "id": "2222222222",
        "name": "Example Business Name"
      },
      "requesting_business": {
        "id": "3333333333",
        "name": "Example Business Name"
      }
    }
  ]
}

View OBO Requests Received From Other Businesses

To view requests of IN_PROGRESS OBO requests sent to your business, make this GET request:

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

The response contains the IN_PROGRESS OBO request IDs and looks like this:

{
  "data": [
    {
      "id": "1111111111"
    },
    {
      "id": "2222222222"
    },
    {
      "id": "3333333333"
    }
  ]
}

View Pending OBO Requests Sent by Your Business

To view OBO requests that were sent by your business that are still in the IN_PROGRESS state, make this GET request:

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

The response contains the IN_PROGRESS OBO request IDs and looks like this:

{
  "data": [
    {
      "id": "1111111111"
    },
    {
      "id": "2222222222"
    },
    {
      "id": "3333333333"
    }
  ]
}

Saiba mais