Business Management APIs

Business On Behalf Of

Die Business On Behalf Of API erlaubt einem Partner, folgende Handlungen auszuführen:

  • Zugriff erhalten, um im Namen seines*seiner Kund*in zu handeln
  • Einen Systemnutzer im Business Manager seines*seiner Kund*in erstellen und den Systemnutzer-Zugriffsschlüssel abzurufen

Ein Systemnutzer ist als jemand definiert, der sich wiederholende programmatische Aufgaben ausführen kann, z. B. das Aktualisieren eines Produktkatalogs, das Senden von Server-zu-Server- Events oder das Aktualisieren von Custom Audiences usw.

In diesem Szenario verfügt der Systemnutzer über Mitarbeitendenzugriff und kann nur mithilfe des Admin-Nutzer*innen-Zugriffsschlüssels auf zugewiesene Assets (zum Zeitpunkt der Erstellung) zugreifen.

Der Vorteil der Verwendung eines Systemnutzers im Vergleich zu einem Nutzer-Zugriffsschlüssels: Nutzer*innen können von einem Unternehmen abwandern, aber Systemnutzer-Zugriffsschlüssel verfallen nicht. Bei diesem Ansatz bleibt der*die Kund*in weiterhin Eigentümer*in seines*ihres Unternehmens und gewährt dem Partner über einen Systemnutzer Zugriff auf seinen*ihren Business Manager und seine*ihre Assets. Ein*e Kund*in hat die Möglichkeit, seinen*ihren Business Manager aufzurufen und den Systemnutzer zu widerrufen oder den Zugriff auf bestimmte Assets eines Partners programmgesteuert zu entfernen.

Erste Schritte

Bevor du beginnst, empfehlen wir dir, die folgenden Anforderungen und Informationen zu lesen:

Business Manager für Kund*innen

Wenn dein*e Kund*in über den Commerce Manager ein Commerce-Konto erstellt hat, ist dieses bereits mit seinem*ihrem Business Manager verbunden. Du kannst sein*ihre Business Manager-ID finden, indem du dieser Anleitung folgst.

Wenn für den*die Kund*in kein Business Manager vorhanden ist, musst du einen erstellen, bevor du fortfährst. Anweisungen findest du unter Business Manager API.

App-Berechtigungen

  • business_management

IDs

  • PARTNER_BM_ID: ID des Business Managers des Partners, der Eigentümer der App sein sollte.
  • CLIENT_BM_ID: ID des Business Managers des*der Kund*in, der*die Eigentümer*in der Facebook-Seite ist, die mit dem Commerce-Konto des*der Kund*in verbunden ist.

Zugriffsschlüssel

  • USERS_ACCESS_TOKEN: Das Zugriffstoken eines*einer Admin des Business Managers des*der Kund*in, erstellt mit business_manage-Berechtigungen unter Verwendung der App, die dem Business Manager des Partners gehört. Dieses Token wird über Facebook Login generiert.
  • PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN: Der Zugriffsschlüssel des Admin-Systemnutzers im Business Manager des Partners für die App.
  • CLIENT_BM_SU_ACCESS_TOKEN: Der Zugriffsschlüssel des Systemnutzers im Business Manager des*der Kund*in.
  • CLIENT_BM_SU_PAGE_ACCESS_TOKEN: Der Seitenzugriffsschlüssel des Systemnutzers im Business Manager des*der Kund*in.

Empfohlene Schritte

Schritt 1

Erstelle die „On Behalf Of“-Beziehung zwischen dem Partner und dem Business Manager des*der Kund*in.

Dadurch entsteht ein Beziehungs-Edge zwischen dem Business Manager des Partners und dem Business Manager des*der Kund*in. Dies ermöglicht dem Partner im nächsten Schritt die Erstellung eines Systemnutzers über die API.

Verwendeter Zugriffsschlüssel: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>"

Schritt 2

Rufe den Systemnutzer-Zugriffsschlüssel im Business Manager des*der Kund*in ab. Dadurch wird die App im Business Manager des*der Kund*in installiert und ein Systemnutzer erstellt. Standardmäßig lautet der Name des Systemnutzers „{Client_Business_Manager_Name} SYSTEM USER“. Ein*e Kund*in kann die Partner-App in seinem*ihrem Business Manager als geteilte Asset sehen. (Er*sie hat keinen Zugriff auf die App, höchstens als Testnutzer.)

In den scope-Parameter solltest du alle Berechtigungen einschließen, die der Systemnutzer für den Zugriff auf relevante API-Endpunkte haben muss. Welche Berechtigungen für den Zugriff erforderlich sind, erfährst du in den einzelnen API-Referenzen.

Verwendeter Zugriffsschlüssel:PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN. Dieser Zugriffsschlüssel muss über die business_management-Berechtigung und über alle in den oben genannten scope-Parametern enthaltenen Berechtigungen verfügen.


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

Die Antwort enthält den Systemnutzer-Zugriffsschlüssel, der mit den „On Behalf Of“-Beziehungen verknüpft ist. Für die Commerce-Integration musst du keinen weiteren Systemnutzer anlegen oder verwenden.

Schritt 3

Rufe die ID des Systemnutzers ab.

Verwendeter Zugriffsschlüssel:CLIENT_BM_SU_ACCESS_TOKEN

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

Schritt 4

Weise dem Systemnutzer im Business Manager des*der Kund*in Assets (Seite und Katalog) zu.

Verwendeter Zugriffsschlüssel: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>"

Schritt 5

Speichere diesen CLIENT_BM_SU_ACCESS_TOKEN in einer sicheren Datenbank und verwende ihn für den Zugriff auf APIs, die ein Nutzer-Zugriffsschlüssel erfordern, wie z. B. Catalog Management.

Schritt 6

Generiere ein Seitenzugriffsschlüssel mit folgendem CLIENT_BM_SU_ACCESS_TOKEN-Aufruf:

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

Diese Anfrage listet alle vom Systemnutzer verwalteten Seiten einschließlich Seiten mit übereinstimmendem access_token. Beispielantwort:

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

Kopiere den access_token der entsprechenden Seite, die mit dem Commerce-Konto des*der Kund*in verknüpft ist, und bewahre ihn sicher auf. Du wirst ihn verwenden, um auf APIs zuzugreifen, die im Namen des Commerce-Kontos einen Seitenzugriffsschlüssel erfordern, wie z. B. Order Management und Finance Reporting.

FAQ

Wie kann ich die „On Behalf Of“-Beziehung löschen, um den Systemnutzer aus dem mir zugewiesenen Business Manager des*der Kund*in zu entfernen?


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

Wenn der*die Kund*in die Verbindung und den Systemnutzer des Partners entfernen möchte, kann er*sie dies in der App-Ansicht des Business Managers tun.