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 das Systemnutzer-Zugriffstoken abrufen

Ein Systemnutzer ist ein Nutzer, 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-Zugriffstokens auf zugewiesene Assets (zum Zeitpunkt der Erstellung) zugreifen.

Der Vorteil der Verwendung eines Systemnutzer- im Vergleich zu einem Nutzer-Zugriffstoken: Nutzer*innen können von einem Unternehmen abwandern, aber Systemnutzer-Zugriffstoken laufen nicht ab. 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.

Zugriffstoken

  • 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: Das Zugriffstoken des Admin-Systemnutzers im Business Manager des Partners für die App.
  • CLIENT_BM_SU_ACCESS_TOKEN: Das Zugriffstoken des Systemnutzers im Business Manager des*der Kund*in.
  • CLIENT_BM_SU_PAGE_ACCESS_TOKEN: Das Seiten-Zugriffstoken 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.

Verwendetes Zugriffstoken:USERS_ACCESS_TOKEN


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

Schritt 2

Rufe das Systemnutzer-Zugriffstoken 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 geteiltes 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.

Verwendetes Zugriffstoken:PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN. Dieses Zugriffstoken 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/v26.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>&appsecret_proof=<APPSECRET_PROOF>"

Der appsecret_proof-Parameter ist erforderlich. Dabei handelt es sich um einen sha256-Hash des Zugriffstokens, der im Aufruf verwendet wird. Der App-Geheimcode wird dabei als Schlüssel verwendet. Aufrufe an diesen Endpunkt ohne gültiges appsecret_proof werden abgelehnt. Weitere Informationen findest du unter Nachweis generieren.

Die Antwort enthält das Systemnutzer-Zugriffstoken, das 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.

Verwendetes Zugriffstoken:CLIENT_BM_SU_ACCESS_TOKEN

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

Verwendetes Zugriffstoken:USERS_ACCESS_TOKEN

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

Schritt 5

Speichere dieses CLIENT_BM_SU_ACCESS_TOKEN in einer sicheren Datenbank und verwende es für den Zugriff auf APIs, die ein Nutzer-Zugriffstoken erfordern, wie z. B. Catalog Management.

Schritt 6

Generiere ein Seiten-Zugriffstoken mit folgendem CLIENT_BM_SU_ACCESS_TOKEN-Aufruf:

curl -i -X GET \
 "https://graph.facebook.com/v26.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 das access_token der entsprechenden Seite, die mit dem Commerce-Konto des*der Kund*in verknüpft ist, und bewahre es sicher auf. Du wirst es verwenden, um auf APIs zuzugreifen, die im Namen des Commerce-Kontos ein Seiten-Zugriffstoken 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/v26.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.