Gérer les revenus à l’aide de l’API du service de revenus

Cet article explique comment accéder aux données de revenus via les API Gains au lieu de l’interface utilisateur de l’Espace partenaires. Ces API fournissent un moyen programmatique de fournir la fonctionnalité Exporter les données dans l’Espace partenaires.

API disponibles

Consultez toutes les API disponibles sur les paiements partenaires.

Prerequisites

• Disposer d’un abonnement opérationnel dans le portail Azure.
• Accédez à un navigateur web.
• Être en mesure d’effectuer des appels d’API REST, par programmation ou par le biais de logiciels dédiés.

Inscrire une application sur la Plateforme d’identités Microsoft

1. Suivez les instructions pour créer un enregistrement d'application avec la plateforme d’identités Microsoft.

2. Donnez à l’application les autorisations déléguées appropriées.

   1. Dans l’inscription d’application nouvellement créée, accédez à Gérer les autorisations d’API →. Sélectionnez « Ajouter une autorisation ».
   2. Sélectionnez l’onglet « API que mon organisation utilise », puis recherchez l’AppId « 4990cffe-04e8-4e8b-808a-1175604b879f » ou par le nom « Centre de développement Microsoft ». Pour les autorisations, sélectionnez « user_impersonation ». Sélectionnez « Ajouter des autorisations ».
      • Résolution des problèmes : si la recherche de l’API du Centre de développement ne retourne aucun résultat, vous devrez peut-être créer les principaux de service requis pour accéder manuellement à ces API. Ils peuvent être créés avec AzCLI :

        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        

        Ensuite, les autorisations d’API doivent être disponibles pour effectuer une sélection dans la boîte de dialogue de recherche. Capture d’écran montrant l’autorisation user_impersonation.
   3. En outre, vérifiez que votre application dispose d’une autorisation « User.Read » dans Microsoft Graph. Si ce n’est pas le cas, ajoutez-le en sélectionnant Microsoft Graph sous l’onglet API Microsoft.
   4. Sélectionnez « Accorder le consentement administrateur » pour les trois autorisations que vous avez obtenues.
   5. Les autorisations de votre application doivent se présenter comme suit (notez la graduation verte en regard de chaque autorisation) :

3. Configurez un URI de redirection pour la plateforme web.

   1. Accédez à Gérer l’authentification →. Sélectionnez « Ajouter une plateforme ».
   2. Sélectionnez « Web ».
   3. Dans les URI de redirection, entrez l’URI que vous souhaitez utiliser pour votre application, par exemple https://localhost:3000. Notez cet URI pour plus tard. Appuyez sur « Configurer ».

4. Générez une clé secrète client à utiliser lors de l’obtention de jetons d’accès.

   1. Accédez à Gérer les certificats et secrets →. Accédez à l’onglet « Secrets clients », sélectionnez « Nouveau secret client ».
   2. Entrez le nom et la durée souhaités.
   3. Sélectionnez Ajouter un secret.
   4. Notez la valeur ailleurs. Veillez à le conserver dans un emplacement sécurisé, par exemple un coffre de clés. Vous utilisez ce secret lors de la demande d’AccessToken et d’RefreshToken.

Obtenir un jeton d’accès - Comptes compatibles MFA

Les API Gains nécessitent qu’un AccessToken soit fourni en tant que jeton du porteur d’autorisation dans la demande, avec le préfixe Bearer <access-token> dans l’en-tête Authorization. Vous pouvez obtenir ce jeton en vous connectant avec votre compte ; toutefois, les jetons d’accès sont de courte durée. La connexion à un compte compatible MFA pour générer un jeton chaque fois que vous devez appeler l’API n’est pas pratique pour les flux de travail impliquant l’automatisation. Ces étapes vous guident tout au long du processus pour générer un RefreshToken. Il a une durée de vie plus longue (environ 3 mois) et peut être utilisé pour obtenir AccessToken. En stockant un RefreshToken dans un emplacement sécurisé, vous pouvez l’utiliser pour obtenir par programme un AccessToken pour appeler l’API Gains. Remarque : RefreshToken ne peut être utilisé qu’une seule fois, après quoi il devient obsolète. Dans la réponse, un nouvel RefreshToken est retourné avec AccessToken. Veillez à remplacer l’ancienne valeur d’RefreshToken dans votre stockage sécurisé chaque fois que vous utilisez un RefreshToken.

1. Obtenir AuthCode via le navigateur. Actuellement, ce processus doit être effectué à l’aide de l’interface utilisateur d’un navigateur web et ne peut pas être effectué par programmation.

   1. Suivez le modèle ici pour générer une URL utilisée pour récupérer l’authentification.
      1. Utilisez l’ID de locataire et l’ID client pour l’application créée.
      2. Définir l’étendue sur https://api.partner.microsoft.com/.default.
      3. Définissez l’URL de redirection vers l’URL de redirection configurée précédemment. Le modèle d’URL est : https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
   2. Accédez à l’URL générée et connectez-vous à l’aide des informations d’identification d’un utilisateur autorisé.
   3. Une fois la connexion réussie, votre navigateur tente d’ouvrir une URL du format <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. Pour l’exemple d’URI de redirection à l’étape précédente, l’URL à laquelle vous êtes envoyé doit être https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Enregistrez l’authentification retournée quelque part en toute sécurité.
      • Étant donné qu’il n’existe généralement aucune application à l’écoute sur localhost :3000, le navigateur affiche un message d’erreur « impossible de se connecter ». Cette erreur est attendue, car nous devons simplement copier manuellement la valeur AuthCode à partir du code paramètre de requête d’URL indiqué précédemment.
      • Dans une solution prod, vous pouvez créer une application qui gère automatiquement cette partie du processus d’authentification. Par exemple, il peut s’agir d’un flux de travail dans lequel l’utilisateur accède à une application monopage (SPA). L’utilisateur sélectionne un bouton « se connecter » qui les amène à l’URL construite précédemment. Lors de la connexion, l'application SPA extrait la valeur du code d'autorisation et l'enregistre dans un coffre. L’application SPA utilise ensuite AuthCode pour obtenir RefreshToken et AccessToken, comme décrit dans les étapes suivantes.

2. Utilisez AuthCode pour obtenir RefreshToken et AccessToken initial. Remarque : RefreshToken expire tous les 3 mois et doit être reobtaché et stocké dans un coffre de clés.

   1. Générez une demande d’API POST en suivant le modèle fourni ici.
      1. Utilisez les mêmes valeurs pour l'ID locataire/client et l’URL de redirection.
      2. Définir le périmètre au https://api.partner.microsoft.com/.default offline_access.
      3. Définissez le code AuthCode obtenu à l'étape avant.
      4. Définissez client_secret sur le secret généré pour l’application créée. L’URL doit ensuite être structurée comme suit : https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. Plus tard, vous pouvez utiliser RefreshToken pour obtenir un nouvel AccessToken.

   1. Générez une demande d’API POST en suivant le modèle fourni ici.
      1. Utilisez les mêmes valeurs pour l’ID client/client et l’URL de redirection.
      2. Définir la portée sur https://api.partner.microsoft.com/.default
      3. Attribuez refresh_token à RefreshToken obtenu lors de l'étape précédente.
      4. Définissez client_secret sur le secret généré pour l’application créée.

Obtenir un jeton d’accès - Comptes non MFA

1. Obtenez AccessToken à l’aide des informations relatives à la nouvelle inscription d’application.
   1. Générez une demande d’API POST en suivant le modèle fourni ici.
      1. Utilisez les mêmes valeurs pour l’ID client/locataire
      2. Définir l’étendue sur https://api.partner.microsoft.com/.default
      3. Utilisez le nom d’utilisateur/mot de passe d’un utilisateur autorisé. L’URL doit ensuite être structurée comme suit : https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. La requête retourne AccessToken et un nouvel RefreshToken. Veillez à mettre à jour la valeur stockée pour RefreshToken, car vous ne pouvez plus utiliser l’ancienne valeur.

Revenus d'appels (anciennement "transactionhistory")/Paiements

• Utilisez le AccessToken obtenu précédemment dans l’en-tête d'autorisation avec le préfixe Bearer <access-token> pour créer de nouveaux rapports Revenus (anciennement transactionhistory) ou Paiements.

Contenu connexe

• Utiliser le portail pour créer une application Microsoft Entra et un principal de service qui peuvent accéder aux ressources
• Inscrire une application avec la plateforme d’identités Microsoft
• Configurer une application cliente pour accéder à une API web