Business Management APIs

Funzioni Business-to-Business

Dall'8 giugno 2021, l'accesso a questi endpoint è limitato. Le app non autorizzate all'accesso riceveranno un errore.

Richiesta di accesso alle risorse

Un Business Manager può richiedere l'accesso a un account pubblicitario o a una Pagina di proprietà di un altro Business Manager. Deve specificare le attività che desidera assegnare nella richiesta.

L'assegnazione di un'azienda a una Pagina richiede un token della Pagina; ad esempio:

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

Per richiedere accesso come AGENCY, devi fornire le permitted_tasks nella tua richiesta. Puoi inviare richieste solo per risorse di Business Manager che hai intenzione di approvare e tali Business Manager devono già conoscere la tua azienda.

Ad esempio, un'azienda che deve accedere a adaccount_id e deve poter assegnare i suoi dipendenti come ['ADVERTISE', 'ANALYZE'] farebbe questa chiamata 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>"

Analogamente, se desideri assegnare attività ['ADVERTISE', 'ANALYZE'] per una Pagina non di proprietà di qualcuno:

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>"

Queste chiamate inviano ai rispettivi amministratori dell'account pubblicitario o della Pagina una notifica in cui viene chiesto di accettare la richiesta di accesso. I rispettivi amministratori visualizzeranno la notifica in Gestione inserzioni o Gestore delle Pagine. Possono accettare la richiesta anche dall'interfaccia utente. Se desideri visualizzare le richieste in sospeso tramite l'API, fai una richiesta GET e seleziona PENDING per il campo access_status.

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

Risposta:

"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"
 },

Concessione dell'accesso a risorse per un altro Business Manager

Questa procedura è anche nota come aggiunta di un'agenzia all'oggetto.

Per accettare una richiesta di accesso a un oggetto di tua proprietà proveniente da un altro Business Manager o per concedere l'accesso a uno degli oggetti di tua proprietà a un altro Business Manager, devi specificare l'azienda e la lista di attività a cui dovrebbe avere accesso.

Se il token d'accesso usato per effettuare la chiamata API appartiene a un utente o utente del sistema che ha accesso alla risorsa richiesta tramite un'azienda, l'accesso alla risorsa può essere concesso solo se questa azienda è OWNER della risorsa. Non puoi concedere l'accesso alle risorse in cui operi solo come AGENCY.

Ad esempio, per consentire a qualcuno di accedere a un account pubblicitario utilizzando le attività [ADVERTISE,ANALYZE], usa questa richiesta 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>"

Per dare accesso alla tua Pagina a un'azienda con [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>"

Nel caso di concessione dell'accesso a un account pubblicitario, a volte è necessario un controllo da parte di un altro amministratore dell'azienda come misura di sicurezza. Per approvare questo controllo, occorre passare a https://business.facebook.com/settings/requests/admin_reviews. In questo caso, la risposta avrà un campo aggiuntivo, che indica che è necessario un ulteriore controllo.

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

Gli amministratori della Pagina possono inoltre accettare una richiesta di accesso di un'agenzia nelle tab Manage Admin Roles nelle impostazioni della Pagina su facebook.com.

Rimozione dell'accesso alle risorse

Questa procedura è anche nota come rimozione di un'agenzia dalla tua azienda. Per rimuovere l'accesso di un Business Manager dal tuo account pubblicitario:

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

Analogamente, per rimuovere l'accesso di un'azienda dalla tua Pagina:

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

Visualizzazione dell'accesso delle agenzie

Per visualizzare tutte le aziende che hanno accesso al tuo account pubblicitario con una chiamata GET:

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

Per visualizzare tutte le aziende che hanno accesso alla tua Pagina:

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

Per visualizzare tutte le aziende che hanno alle risorse della tua azienda:

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

Visualizzazione dell'accesso dei clienti

Per vedere tutte le aziende che ti hanno concesso l'accesso a uno o più dei loro account pubblicitari o delle loro pagine, usa questa chiamata 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"
    }
  ]
}

Per saperne di più