API de rapprochement de facture facturée v2 (GA)

S’applique à : Espace partenaires (indisponible dans le cloud souverain)

Notre nouvelle API asynchrone offre un moyen plus rapide et plus efficace d’accéder à vos données de facturation et de rapprochement via des objets blob Azure. Au lieu de conserver une connexion ouverte pendant des heures ou de traiter des lots de 2000 éléments de ligne, vous pouvez maintenant simplifier votre flux de travail, réduire la charge du serveur et améliorer les temps de traitement de données.

La nouvelle API de rapprochement des factures facturées au commerce utilise des techniques avancées telles que la clé de valet et les modèles de demande-réponse asynchrones. Le modèle de clé de valet prend en charge l’accès sécurisé aux ressources sans partager les informations d’identification, tandis que le modèle de réponse aux demandes asynchrones permet une communication efficace entre les systèmes.

Cette API vous fournit un jeton de signature d’accès partagé (SAP) que vous pouvez utiliser pour accéder à tous les attributs ou à un sous-ensemble des données de rapprochement de facture facturées. Ce jeton améliore la sécurité en accordant un accès à temps limité et offre une flexibilité dans la gestion des autorisations d’accès aux données.

En adoptant nos API optimisées, vous pouvez obtenir des résultats plus rapides avec moins d’efforts, simplifier l’accès à vos données et améliorer l’efficacité globale. Adoptez ces outils pour simplifier votre flux de travail et gérer les autorisations plus efficacement.

Autoriser votre application à accéder en toute sécurité aux données de facturation des partenaires

Pour permettre à votre application d’accéder aux données de facturation des partenaires, suivez ce lien et familiarisez-vous avec les principes de base de l’authentification et de l’autorisation pour Microsoft Graph. Cette étape est cruciale, car elle garantit que votre application peut accéder en toute sécurité aux données nécessaires.

Enregistrez votre application et attribuez l’autorisation PartnerBilling.Read.All

Vous pouvez attribuer l’autorisation « PartnerBilling.Read.All » à l’aide du portail Azure ou du Centre d’administration Microsoft Entra. En effectuant ces étapes, vous vous assurez que votre application a l’accès requis aux données de facturation des partenaires. Voici comment procéder :

1. Inscrivez votre application sur la page d’accueil de Microsoft Entra sous la section Inscriptions d’applications.
2. Accordez l’autorisation nécessaire en accédant à la page de l’application Microsoft Entra. Dans la section Autorisations de l’API, sélectionnez Ajouter une autorisation et choisissez l’étendue PartnerBilling.Read.All.

En savoir plus sur les points de terminaison d’API clés

Pour vous aider à récupérer les nouveaux éléments de ligne de rapprochement de facture commerciale facturés de façon asynchrone, nous proposons deux points de terminaison d’API clés. Ces points de terminaison vous aident à gérer efficacement votre processus de rapprochement des factures. Suivez ce guide simplifié pour commencer rapidement.

Utiliser le point de terminaison de rapprochement de facture facturée

Tout d’abord, utilisez cette API pour récupérer les nouveaux éléments de ligne de rapprochement de facture facturés au commerce . Lorsque vous effectuez une requête, vous recevez un état HTTP 202 et un en-tête d’emplacement avec une URL. Interrogez régulièrement cette URL jusqu’à ce que vous obteniez un état de réussite et une URL de manifeste.

Utiliser le point de terminaison d’état de l’opération

Ensuite, continuez à vérifier l’état de l’opération en appelant cette API à intervalles réguliers. Si les données ne sont pas prêtes, la réponse inclut un en-tête Retry-After indiquant la durée d’attente avant de réessayer. Une fois l’opération terminée, vous recevez une ressource de manifeste avec un lien de dossier de stockage pour télécharger les données d’utilisation. La réponse segmente les fichiers pour améliorer le débit et permettre un parallélisme d’E/S.

Passer en revue le diagramme de séquence

Voici un diagramme de séquence qui montre les étapes de téléchargement des nouvelles données de rapprochement des factures commerciales.

Suivez la séquence d'actions de l'utilisateur pour récupérer les données de rapprochement de factures.

Voici la séquence d’actions de l’utilisateur pour récupérer les données de rapprochement des factures publiées :

• Envoyer une demande POST
• Vérifier l’état de la demande
• Télécharger les éléments de ligne de rapprochement de facture facturée à partir du Stockage Blob Azure

Envoyer une requête POST

Envoyez une requête POST au point de terminaison de l’API.

Obtenir les éléments de ligne de rapprochement de facture facturés

Obtenez les éléments de ligne de rapprochement de facture facturée.

Requête d’API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Paramètres de requête

S/O

Corps de la demande

En-têtes de requête

En-têtes de demande pour l’API à l’aide des étapes répertoriées dans les meilleures pratiques pour l’utilisation de Microsoft Graph. En suivant ces instructions, vous garantissez la fiabilité et la prise en charge de votre application. Votre attention aux détails de cette étape est essentielle à l’intégration transparente et aux performances optimales.

Réponse de l’API

HTTP/1.1 202 Accepted  
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

L’API répond généralement avec un état HTTP 202. Vous pouvez également rencontrer d’autres statuts en fonction de vos demandes. Ces états sont répertoriés dans la section États de réponse de l’API Standard.

Vérifier l’état de la requête

Pour suivre l’état d’une requête, vérifiez que vous recevez une réponse HTTP 200 qui est un code d’état standard indiquant « réussi » ou « échoué ». En cas de réussite, vous trouvez l’URL du manifeste dans l’attribut « resourceLocation ». Cet attribut fournit un point de terminaison pour accéder aux informations requises.

Obtenir l’état de l’opération

Récupère l’état d’une demande.

Requête d’API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Paramètres de la demande

En-tête de requête

En-têtes de demande pour l’API à l’aide des étapes répertoriées dans les meilleures pratiques pour l’utilisation de Microsoft Graph. En suivant ces instructions, vous garantissez la fiabilité et la prise en charge de votre application. Votre attention aux détails de cette étape est essentielle à l’intégration transparente et aux performances optimales.

Corps de la demande

N/A.

État de la réponse

Outre les états HTTP standard répertoriés dans les états de réponse de l’API Standard, l’API peut également retourner l’état HTTP suivant :

Charge utile de réponse

La charge utile de réponse de l’API inclut les attributs suivants :

Objet Resource Location

Requête d’API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Réponse de l’API

La réponse recommande d’attendre 10 secondes avant de réessayer lorsque vos données sont toujours traitées.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Requête d’API

(10 secondes après la demande précédente...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Réponse de l’API

L’API retourne l’état « réussi » et l’URI de « resourceLocation ».

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Télécharger les éléments de ligne de rapprochement de facture facturée à partir du Stockage Blob Azure

Tout d’abord, vous devez obtenir le jeton de signature d’accès partagé (SAP) et l’emplacement de stockage blob. Vous trouverez ces détails dans les propriétés sasToken et rootDirectory de la réponse de l’API de charge utile de manifeste. Ensuite, pour télécharger et décompresser le fichier blob, utilisez l’outil/SDK Stockage Azure. Il est au format JSONLines .

États de réponse de l’API standard

Vous pouvez obtenir les états HTTP suivants à partir de la réponse de l’API :

Attributs d’élément de ligne de rapprochement de facture facturés

Pour comparer les attributs retournés par l’API de rapprochement de facture facturée pour les ensembles d’attributs « full » ou « basic », reportez-vous à ce tableau. Pour en savoir plus sur ces attributs et leurs significations, consultez Utiliser le fichier de rapprochement.

Obtenir l’exemple de code d’API

Pour utiliser cette API, consultez le lien suivant, qui inclut l’exemple de code C#.

Exemples d’API pour obtenir des données de rapprochement de facturation à partir de l’Espace partenaires.

Contenu associé

• SDK/outil Stockage Azure
• Utiliser l’API Microsoft Graph pour exporter les données de facturation des partenaires