API de rapprochement de facture facturée v2 (GA)
S’applique à : Espace partenaires (indisponible dans le cloud souverain)
Notre API asynchrone offre un moyen plus rapide et plus gérable d’accéder aux données de facturation et de rapprochement par le biais d’objets blob Azure. Avec cette API, vous n’avez pas besoin de conserver une connexion ouverte pendant des heures ou de parcourir les lots de 2 000 éléments de ligne à la fois.
Nous avons optimisé notre nouvelle API de rapprochement des factures facturées par le commerce à l’aide de modèles de clé de valet et de réponse de requête asynchrone. 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.
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.
Vous pouvez utiliser cette API uniquement pour le cloud public/global MS Graph maintenant. Il n’est pas encore disponible pour Azure Government, Azure Allemagne ou Azure China 21Vianet.
Présentation de l’API
Pour récupérer de façon asynchrone les nouvelles données de rapprochement de facture commerciale facturées, utilisez deux points de terminaison d’API. Le processus est le suivant :
Point de terminaison de rapprochement de facture facturé
Utilisez cette API pour récupérer les nouveaux éléments de ligne de rapprochement des factures facturés au commerce . L’API retourne un état HTTP 202 et un en-tête d’emplacement contenant une URL. Interrogez cette URL à intervalles réguliers jusqu’à ce que vous receviez un état de réussite avec une URL de manifeste.
Point de terminaison d’état de l’opération
Pour obtenir un état de réussite, continuez à appeler cette API à intervalles réguliers. Si les données ne sont pas prêtes, la réponse de l’API inclut un en-tête Retry-After pour vous indiquer le délai d’attente avant de réessayer. Une fois l’opération terminée, vous obtenez une ressource de manifeste avec un dossier de stockage dans lequel vous pouvez télécharger les données d’utilisation. La réponse décompose les fichiers en morceaux plus petits pour un débit optimisé et un parallélisme d’E/S optimisés.
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é. La valeur par défaut est « full ». (Consultez la liste des attributs de cet article). 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.
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. D’autres états possibles, basés sur vos demandes, sont répertoriés dans les états de réponse de l’API Standard dans cet article.
| 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 vérifier l’état d’une requête, attendez une réponse HTTP 200 avec l’état « réussi » ou « échec ». Vous obtenez l’URL du manifeste dans l’attribut « resourceLocation » si la requête réussit.
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.
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 dans cet article, l’API peut 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 | ID 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 | Heure de la dernière modification de l’état. Obligatoire. |
| resourceLocation | False | URI de la charge utile du manifeste. facultatif. |
| error | False | Si l’opération échoue, les détails de l’erreur sont fournis au format JSON. facultatif. Les attributs suivants sont inclus : message : description détaillée de l’erreur. code : type d’erreur qui s’est produite. |
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 modification des informations de facturation génère une nouvelle valeur. |
| partnerTenantId | ID 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 qui contient les détails suivants : nom : nom de l’objet blob. partitionValue : partition qui contient le fichier. La grande partition est divisée en plusieurs fichiers, chaque fichier contenant le même « partitionValue ». |
| name | Le nom de l’objet Blob. |
| partitionValue | Partition qui contient le fichier. La grande partition est divisée en plusieurs fichiers, chaque fichier contenant le 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 données de rapprochement de facture facturées à partir du stockage Blob Azure
Obtenez le jeton de signature d’accès partagé (SAP) et l’emplacement de stockage d’objets blob à partir des propriétés « sasToken » et « rootDirectory » la réponse de l’API de charge utile du manifeste. Stockage Azure SDK/outil pour télécharger et décompresser le fichier blob. Il est au format JSONLines .
Conseil
Consultez notre exemple de code pour 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’appelant n’est pas authentifié et vous devez vous authentifier auprès du service d’API partenaire avant d’effectuer le premier appel. |
| 403 - Interdit | Vous n’avez pas l’autorisation nécessaire pour effectuer la demande. |
| 404 – Introuvable | 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 l’une de ses dépendances ne peut pas répondre à la demande pour l’instant. 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 de données 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.
| Attribut | Complète | 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 obtenir des conseils sur l’utilisation de l’API, consultez le lien suivant qui inclut un exemple de code en C#.
Commentaires
Prochainement : Tout au long de l'année 2024, nous supprimerons progressivement les GitHub Issues en tant que mécanisme de retour d'information pour le contenu et nous les remplacerons par un nouveau système de retour d'information. Pour plus d’informations, voir: https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour