Business Management APIs

Business On Behalf Of

L'API Business On Behalf Of consente a un partner di:

  • ottenere l'accesso per agire per conto del proprio cliente;
  • creare un utente di sistema con il proprio Business Manager e recuperarne il token d'accesso.

Un utente di sistema è definito come qualcuno che può eseguire attività programmatiche ripetitive, come l'aggiornamento di un catalogo prodotti, l'invio di eventi da server a server o l'aggiornamento del pubblico personalizzato e così via.

In questo scenario, l'utente di sistema dispone dell'accesso dipendente e può accedere solo alle risorse assegnate (al momento della creazione) utilizzando il token d'accesso dell'utente con diritti di amministratore.

Il vantaggio di utilizzare un token d'accesso dell'utente di sistema rispetto a un token d'accesso dell'utente è che gli utenti possono abbandonare un Business Manager, mentre i token d'accesso dell'utente di sistema non scadono. In questo approccio, il cliente, rimanendo proprietario del Business Manager, consente al partner di accedere al suo Business Manager e alle sue risorse tramite un utente di sistema. Il cliente ha la possibilità di accedere a quel Business Manager e rimuovere l'utente di sistema o revocare al partner l'accesso a specifiche risorse in modo programmatico.

Primi passi

Prima di iniziare, ti consigliamo di esaminare a questi requisiti e informazioni:

Business Manager per il cliente

Se il tuo cliente ha creato un account per le vendite attraverso il Gestore delle vendite, è già connesso al Business Manager. Puoi trovare l'ID del Business Manager seguendo queste istruzioni.

Se il cliente non ha un Business Manager, dovrai crearne uno prima di procedere. Per istruzioni, consulta il documento API Business Manager.

Autorizzazioni dell'app

  • business_management

ID

  • PARTNER_BM_ID: ID del Business Manager del partner che dovrebbe possedere l'app.
  • CLIENT_BM_ID: ID del Business Manager del cliente che possiede la Pagina Facebook collegata all'account per le vendite del cliente.

Token d'accesso

  • USERS_ACCESS_TOKEN: il token d'accesso di un amministratore del Business Manager del cliente, creato con autorizzazioni business_manage attraverso l'app di proprietà del Business Manager del partner. Questo token è generato tramite Facebook Login.
  • PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN: il token d'accesso dell'utente di sistema con diritti di amministratore nel Business Manager del partner per l'app.
  • CLIENT_BM_SU_ACCESS_TOKEN: il token d'accesso dell'utente di sistema associato al Business Manager del cliente.
  • CLIENT_BM_SU_PAGE_ACCESS_TOKEN: il token d'accesso della Pagina dell'utente di sistema associato al Business Manager del cliente.

Passaggi consigliati

Passaggio 1

Crea la relazione "Per conto di" tra il partner e il Business Manager del cliente.

Questo genera un segmento di relazione tra il Business Manager del partner e il Business Manager del cliente. In questo modo, il partner sarà in grado di creare un SU tramite l'API al passaggio successivo.

Token d'accesso utilizzato:USERS_ACCESS_TOKEN


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

Passaggio 2

Recupera il token d'accesso dell'utente di sistema associato al Business Manager del cliente. In questo modo l'app viene installata nel Business Manager del cliente e viene creato un utente di sistema. Per impostazione predefinita, il nome dell'utente di sistema è "{Client_Business_Manager_Name} SYSTEM USER". Il cliente potrà vedere l'app del partner nel proprio Business Manager come risorsa condivisa, ma non vi avrà accesso solo come utente test.

Nel parametro scope, devi includere tutte le autorizzazioni di cui l'utente di sistema deve disporre per poter accedere agli endpoint delle API pertinenti. Consulta i riferimenti per le singole API per sapere quali autorizzazioni sono necessarie per l'accesso.

Token d'accesso utilizzato:PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN. Questo token d'accesso deve avere l'autorizzazione business_management e tutte le autorizzazioni incluse nei parametri scope in alto.


curl -i -X POST \
 "https://graph.facebook.com/v21.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>"

La risposta contiene il token per l'utente di sistema collegato alle relazioni OBO. Non è necessario creare o utilizzare altri utenti di sistema per l'integrazione commerciale.

Passaggio 3

Ottieni l'ID dell'utente di sistema.

Token d'accesso utilizzato:CLIENT_BM_SU_ACCESS_TOKEN

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

Passaggio 4

Assegna risorse (Pagina e catalogo) all'utente di sistema nel Business Manager del cliente.

Token d'accesso utilizzato:USERS_ACCESS_TOKEN

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

Passaggio 5

Memorizza questo CLIENT_BM_SU_ACCESS_TOKEN in un database sicuro e usalo per accedere alle API che richiedono un token d'accesso dell'utente, come Catalog Management.

Passaggio 6

Genera un token d'accesso della Pagina con CLIENT_BM_SU_ACCESS_TOKEN chiamando:

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

Questa richiesta elencherà tutte le Pagine gestite dall'utente di sistema, incluso il access_token corrispondente. Esempio di risposta:

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

Copia il access_token corrispondente alla Pagina collegata con l'account per le vendite del cliente e memorizzalo in modo sicuro. Ti servierà per accedere alle API che richiedono un token d'accesso della Pagina per conto dell'account per le vendite, come Order Management e Finance Reporting.

FAQ

Come posso eliminare la relazione "Per conto di" per rimuovere l'utente di sistema associato al Business Manager del cliente assegnato a me?


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

Se il cliente vuole rimuovere il collegamento e l'utente di sistema del partner, può farlo nella vista App del Business Manager.