Business Management APIs

Business On Behalf Of

Grâce à l’API Business On Behalf Of, un partenaire peut :

  • Obtenir l’accès pour agir au nom de son client ou de sa cliente
  • Créer un utilisateur système sous le Business Manager de son client ou de sa cliente et récupérer son token d’accès

Un utilisateur système est défini·e comme une personne qui peut effectuer des tâches programmatiques répétitives, telles que la mise à jour d’un catalogue produits, l’envoi d’évènements serveur à serveur, la mise à jour d’audiences personnalisées, etc.

Dans ce scénario, l’utilisateur système dispose d’un accès employé et ne peut accéder qu’aux éléments affectés (au moment de la création) en utilisant le token d’accès de l’utilisateur admin.

Avantage d’utiliser un utilisateur système plutôt qu’un token d’accès propre à l’utilisateur·ice : les utilisateur·ices peuvent quitter une entreprise, mais les tokens d’accès des utilisateurs système n’expirent pas. Dans cette approche, le client ou la cliente continue d’être propriétaire de son entreprise et permet au partenaire d’accéder à son Business Manager et à ses éléments via un utilisateur système. Un client ou une cliente a la possibilité d’accéder à son Business Manager et de révoquer l’utilisateur système ou de supprimer l’accès de certains actifs à un partenaire par programmation.

Premiers pas

Avant de commencer, nous vous recommandons d’examiner les exigences et informations suivantes :

Business Manager pour la clientèle

Si votre client a créé un compte marchand via le Gestionnaire des ventes, il est déjà connecté à son Business Manager. Vous pouvez trouver son ID Business Manager en suivant cette instruction.

S’il n’y a pas de Business Manager pour la clientèle, vous devez en créer un avant de continuer. Pour obtenir des instructions, voir API Business Manager.

Autorisations de l’application

  • business_management

ID

  • PARTNER_BM_ID : ID du Business Manager du partenaire qui doit être propriétaire de l’application.
  • CLIENT_BM_ID : ID du Business Manager du client propriétaire de la Page Facebook connectée au compte marchand du client.

Tokens d’accès

  • USERS_ACCESS_TOKEN : token d’accès d’un admin du Business Manager du client, créé avec les autorisations business_manage en utilisant l’application appartenant au Business Manager du partenaire. Ce token est généré via Facebook Login.
  • PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN : token d’accès de l’utilisateur système admin dans le Business Manager du partenaire pour l’application.
  • CLIENT_BM_SU_ACCESS_TOKEN : token d’accès de l’utilisateur système sous le Business Manager du client.
  • CLIENT_BM_SU_PAGE_ACCESS_TOKEN : token d’accès page de l’utilisateur système sous le Business Manager du client.

Étapes recommandées

Étape 1

Créez la relation On Behalf Of entre le partenaire et le Business Manager du client.

Cela crée un avantage relationnel entre le Business Manager du partenaire et celui du client. Cela permet au partenaire de créer un SU via l’API à l’étape suivante.

Token d’accès utilisé :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>"

Étape 2

Récupérez le token d’accès de l’utilisateur système sous le Business Manager du client. Cela installe l’application dans le Business Manager du client et crée un utilisateur système. Par défaut, le nom de l’utilisateur système est « {Client_Business_Manager_Name} SYSTEM USER ». Un client pourra voir l’application des partenaires dans son Business Manager en tant qu’élément partagé. (Il ou elle n’aura aucun accès à l’application, sauf en tant qu’utilisateur·ice test.)

Dans le paramètre scope, vous devez inclure toutes les autorisations dont vous avez besoin pour que l’utilisateur système ait accès aux points de terminaison de l’API pertinents. Consultez les références individuelles de l’API pour savoir quelles autorisations sont nécessaires pour y accéder.

Token d’accès utilisé :PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN. Ce token d’accès doit avoir l’autorisation business_management et toutes les autorisations incluses dans les paramètres scope ci-dessus.


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

Le paramètre appsecret_proof est obligatoire. Il s’agit d’un hachage sha256 du token d’accès utilisé dans l’appel, votre clé secrète d’application étant utilisée comme clé. Les appels vers ce point de terminaison sans appsecret_proof valide sont rejetés. Pour plus d’informations, consultez la section Générer la preuve.

La réponse contient le token pour l’utilisateur système qui est lié aux relations OBO. Vous n’avez pas besoin de créer ou d’utiliser un autre utilisateur système pour l’intégration commerciale.

Étape 3

Obtenez l’ID de l’utilisateur système.

Token d’accès utilisé :CLIENT_BM_SU_ACCESS_TOKEN

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

Étape 4

Affectez des éléments (page et catalogue) à l’utilisateur système dans le Business Manager du client.

Token d’accès utilisé :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>"

Étape 5

Stockez ce CLIENT_BM_SU_ACCESS_TOKEN dans une base de données sécurisée et utilisez-le pour accéder aux API qui nécessitent un token d’accès utilisateur·ice, comme Gestion du catalogue.

Étape 6

Générez un token d’accès de Page avec CLIENT_BM_SU_ACCESS_TOKEN en appelant :

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

Cette requête énumère toutes les Pages gérées par l’utilisateur système, y compris le access_token correspondant. Exemple de réponse :

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

Copiez le access_token correspondant à la page liée au compte marchand du client et stockez-le en toute sécurité. Vous l’utiliserez pour accéder aux API qui nécessitent un token d’accès de Page au nom du compte marchand, comme Gestion des commandes et Rapports financiers.

Questions/réponses

Comment puis-je annuler la relation On Behalf Of pour supprimer l’utilisateur système sous le Business Manager du client qui m’a été affecté ?


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

Si le client ou la cliente veut supprimer la relation et l’utilisateur système du partenaire, il ou elle peut le faire dans la vue de l’application du Business Manager.