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 2 000 éléments de ligne, vous pouvez maintenant simplifier votre flux de travail.
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. 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.
Notre API utilise des techniques optimisées pour améliorer votre efficacité, ce qui vous permet d’obtenir des résultats plus rapides avec moins d’efforts. Adoptez cette API pour simplifier l’accès aux données et améliorer votre efficacité globale.
Remarque
La nouvelle API n’est pas hébergée sur l’hôte d’API de l’Espace partenaires. Au lieu de cela, vous pouvez le trouver sur MS Graph à l’aide de l’API Microsoft Graph pour exporter les données de facturation des partenaires - Microsoft Graph v1.0. Pour accéder à cette API, reportez-vous aux détails suivants.
Important
Pour autoriser l’accès à votre application 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.
Vous pouvez attribuer l’autorisation « PartnerBilling.Read.All » à l’aide du Portail Azure ou du Centre d’administration Entra. Voici comment procéder :
- Inscrivez votre application sur la page d’accueil de Microsoft Entra sous la section Inscriptions d’applications.
- Pour accorder l’autorisation nécessaire, accédez à la page Microsoft Entra App sous la section Autorisations de l’API. Sélectionnez « Ajouter une autorisation » et choisissez l’étendue « PartnerBilling.Read.All ».
En effectuant ces étapes, vous vérifiez que votre application dispose de l’accès requis aux données de facturation des partenaires.
Présentation de l’API
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. Voici un guide simplifié pour vous aider à démarrer :
Point de terminaison de rapprochement de facture facturé
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.
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.
En suivant ces étapes, vous pouvez gérer efficacement votre processus de rapprochement de facture.
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.
Séquence d’actions utilisateur
Pour récupérer les données de rapprochement des factures facturées, procédez comme suit :
Étape 1 : Envoyer une demande
Envoyez une requête POST au point de terminaison de l’API.
Obtenir les éléments de ligne de rapprochement de facture facturés
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
| Attribut | Obligatoire | Type | Description |
|---|---|---|---|
| attributeSet | False | Chaîne | Choisissez « full » pour tous les attributs ou « de base » pour un ensemble limité. S’il n’est pas spécifié, « full » est la valeur par défaut. Consultez la liste des attributs de cette section. Facultatif. |
| invoiceId | True | Chaîne | Identificateur unique pour chaque facture. Obligatoire. |
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 états en fonction de vos demandes. Ces états sont répertoriés dans la section États de réponse de l’API Standard.
| Code | Description |
|---|---|
| 202 – Accepté | Votre demande a été acceptée. Pour vérifier l’état de votre demande, interrogez l’URL fournie dans l’en-tête d’emplacement. |
Étape 2 : Vérifier l’état de la demande
Pour suivre l’état d’une demande, veillez à recevoir une réponse HTTP 200 indiquant « réussi » ou « échoué ». Si elle réussit, 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
| Nom | Inclure dans | Requis | Type | Description |
|---|---|---|---|---|
| operationId | URI de demande | True | Chaîne | ID unique pour vérifier l’état de la demande. Obligatoire. |
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 :
| Code | Description |
|---|---|
| 410 - Disparu | Le lien manifeste expire après une heure définie. Pour obtenir à nouveau le lien manifeste, envoyez une nouvelle requête. |
Charge utile de réponse
La charge utile de réponse de l’API inclut les attributs suivants :
| Attribut | Obligatoire | Description |
|---|---|---|
| id | True | Identificateur unique pour chaque réponse Obligatoire. |
| statut | True | Valeurs et actions : Obligatoire. notstarted : attendez l’heure spécifiée dans l’en-tête « Réessayer-After », puis effectuez un autre appel pour vérifier l’état. en cours d’exécution : attendez l’heure spécifiée dans l’en-tête « Réessayer-After », puis effectuez un autre appel pour vérifier l’état. réussite : les données sont prêtes. Récupérez la charge utile du manifeste à l’aide de l’URI spécifié dans resourceLocation. échec : l’opération a échoué définitivement. Redémarrez-le. |
| createdDateTime | True | Heure à laquelle la demande a été faite. Obligatoire. |
| lastActionDateTime | True | La dernière fois que l’état a changé. Obligatoire. |
| resourceLocation | False | URI de la charge utile du manifeste. Facultatif. |
| error | False | Détails sur les erreurs fournies au format JSON. Facultatif. Attributs inclus : message : Description de l’erreur. code : type d’erreur. |
Objet Resource Location
| Attribut | Description |
|---|---|
| id | Identificateur unique du manifeste. |
| schemaVersion | Version du schéma de manifeste. |
| dataFormat | Format du fichier de données de facturation. compresséJSON : format de données où chaque objet blob est un fichier compressé qui contient des données au format de lignes JSON . Pour récupérer les données de chaque objet blob, décompressez-les. |
| createdDateTime | Date et heure de création du fichier manifeste. |
| eTag | Version des données du manifeste. Une nouvelle valeur est générée chaque fois qu’il existe une modification des informations de facturation. |
| partnerTenantId | ID Microsoft Entra du locataire du partenaire. |
| rootDirectory | Répertoire racine du fichier. |
| sasToken | Jeton SAP (signature d’accès partagé) qui vous permet de lire tous les fichiers sous le répertoire. |
| partitionType | Divise les données en plusieurs objets blob en fonction de l’attribut partitionValue . Le système fractionne les partitions qui dépassent le nombre pris en charge. Par défaut, les données sont partitionnée en fonction du nombre d’éléments de ligne dans le fichier. Ne définissez pas un nombre fixe d’éléments de ligne ou de taille de fichier dans le code, car ces valeurs peuvent changer. |
| blobCount | Nombre total de fichiers pour cet ID de locataire partenaire. |
| blobs | Tableau JSON d’objets « blob » qui contiennent les détails du fichier pour l’ID de locataire partenaire. |
| objet blob | Objet contenant les détails suivants : name et partitionValue |
| name | Le nom de l’objet Blob. |
| partitionValue | Partition contenant le fichier. Partition qui contient le fichier. Les partitions volumineuses sont divisées en plusieurs fichiers, chacune contenant la même « partitionValue ». |
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": "0e195b37-4574-4539-bc42-0e539b9684c0",
"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"
}
\]
}
}
Étape 3 : Télécharger les éléments de ligne de rapprochement de facture facturés à 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 d’objets blob. Vous trouverez ces détails dans les propriétés « sasToken » et « rootDirectory » de la réponse de l’API de charge utile du manifeste. Ensuite, pour télécharger et décompresser le fichier blob, utilisez le kit sdk/outil Stockage Azure. Il est au format JSONLines .
Conseil
Veillez à consulter notre exemple de code. Il vous montre comment télécharger et décompresser le fichier blob Azure dans votre base de données locale.
États de réponse de l’API standard
Vous pouvez obtenir ces états HTTP à partir de la réponse de l’API :
| Code | Description |
|---|---|
| 400 Demande incorrecte. | La demande est manquante ou contient des données incorrectes. Recherchez les détails de l’erreur dans le corps de la réponse. |
| 401 - Non autorisé | L’authentification est requise avant d’effectuer le premier appel. Authentifiez-vous auprès du service d’API partenaire. |
| 403 - Interdit | Vous n’avez pas l’autorisation nécessaire pour effectuer la demande. |
| 404 - Non trouvé | Les ressources demandées ne sont pas disponibles avec les paramètres d’entrée fournis. |
| 410 - Disparu | Le lien manifeste n’est plus valide ou actif. Envoyez une nouvelle demande. |
| 500 - Erreur interne du serveur | L’API ou ses dépendances ne peuvent pas répondre à la demande pour le moment. Réessayez plus tard. |
| 5000 – Aucune donnée disponible | Le système n’a pas de données pour les paramètres d’entrée fournis. |
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 au tableau suivant. Pour en savoir plus sur ces attributs, consultez Utilisation du fichier de reconquête.
| Attribut | COMPLET | De base |
|---|---|---|
| PartnerId | Oui | Oui |
| CustomerId | Oui | Oui |
| CustomerName | Oui | Oui |
| CustomerDomainName | Oui | non |
| CustomerCountry | Oui | non |
| InvoiceNumber | Oui | Oui |
| MpnId | Oui | non |
| Tier2MpnId | Oui | Oui |
| OrderId | Oui | Oui |
| OrderDate | Oui | Oui |
| ProductId | Oui | Oui |
| SkuId | Oui | Oui |
| AvailabilityId | Oui | Oui |
| SkuName | Oui | non |
| ProductName | Oui | Oui |
| ChargeType | Oui | Oui |
| UnitPrice | Oui | Oui |
| Quantité | Oui | non |
| Sous-total | Oui | Oui |
| TaxTotal | Oui | Oui |
| Total | Oui | Oui |
| Devise | Oui | Oui |
| PriceAdjustmentDescription | Oui | Oui |
| PublisherName | Oui | Oui |
| PublisherId | Oui | non |
| SubscriptionDescription | Oui | non |
| SubscriptionId | Oui | Oui |
| ChargeStartDate | Oui | Oui |
| ChargeEndDate | Oui | Oui |
| TermAndBillingCycle | Oui | Oui |
| EffectiveUnitPrice | Oui | Oui |
| UnitType | Oui | non |
| AlternateId | Oui | non |
| BillableQuantity | Oui | Oui |
| BillingFrequency | Oui | non |
| PricingCurrency | Oui | Oui |
| PCToBCExchangeRate | Oui | Oui |
| PCToBCExchangeRateDate | Oui | non |
| MeterDescription | Oui | non |
| ReservationOrderId | Oui | Oui |
| CreditReasonCode | Oui | Oui |
| SubscriptionStartDate | Oui | Oui |
| SubscriptionEndDate | Oui | Oui |
| ReferenceId | Oui | Oui |
| ProductQualifiers | Oui | non |
| PromotionId | Oui | Oui |
| ProductCategory | Oui | Oui |
Exemple de code
Pour utiliser cette API, consultez le lien suivant, qui inclut l’exemple de code C#.