Gefactureerde factuurafstemming-API v2 (GA)
Van toepassing op: Partnercentrum (niet beschikbaar in onafhankelijke cloud)
Onze asynchrone API biedt een snellere en beter beheerbare manier om toegang te krijgen tot facturerings- en afstemmingsgegevens via Azure-blobs. Met deze API hoeft u gedurende uren geen verbinding open te houden of de batches van 2000 regelitems tegelijk te doorlopen.
We hebben onze nieuwe facturerings-API voor factuurafstemming geoptimaliseerd met behulp van valetsleutel en asynchrone aanvraagantwoordpatronen . Deze API biedt u een SAS-token (Shared Access Signature) dat u kunt gebruiken voor toegang tot alle kenmerken of een subset van de gefactureerde factuurafstemmingsgegevens.
Notitie
De nieuwe API wordt niet gehost op de Partner Center API-host. In plaats daarvan vindt u deze op MS Graph in De Microsoft Graph-API gebruiken om factureringsgegevens van partners te exporteren - Microsoft Graph v1.0. Raadpleeg de volgende details om toegang te krijgen tot deze API.
U kunt deze API nu alleen gebruiken voor de openbare/wereldwijde MS Graph-cloud. Het is nog niet beschikbaar voor Azure Government, Azure Duitsland of Azure China 21Vianet.
API-overzicht
Gebruik twee API-eindpunten om gefactureerde nieuwe factuurafstemmingsgegevens asynchroon op te halen. Dit is het proces:
Factureringseindpunt voor factuurafstemming
Gebruik deze API om nieuwe gefactureerde factuurafstemmingsitems op te halen. De API retourneert een 202 HTTP-status en een locatieheader die een URL bevat. Peil deze URL regelmatig totdat u een geslaagde status met een manifest-URL ontvangt.
Eindpunt van bewerkingsstatus
Als u een successtatus wilt krijgen, moet u deze API regelmatig aanroepen. Als de gegevens niet gereed zijn, bevat het API-antwoord een header Opnieuw proberen na om u te laten weten hoe lang moet worden gewacht voordat u het opnieuw probeert. Wanneer de bewerking is voltooid, krijgt u een manifestresource met een opslagmap waarin u de gebruiksgegevens kunt downloaden. Het antwoord breekt de bestanden op in kleinere stukken voor geoptimaliseerde doorvoer en I/O-parallelle uitvoering.
Sequentiediagram
Hier volgt een sequentiediagram met de stappen voor het downloaden van nieuwe afstemmingsgegevens voor handelsfacturen.
Gebruikersactiereeks
Volg deze stappen om gefactureerde factuurafstemmingsgegevens op te halen:
Stap 1: Aanvraag indienen
Dien een POST-aanvraag in bij het API-eindpunt.
Gefactureerde regelitems voor factuurafstemming ophalen
API-aanvraag
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Queryparameters
N.v.t.
Aanvraagtekst
| Kenmerk | Vereist | Type | Description |
|---|---|---|---|
| attributeSet | Onwaar | String | Kies 'volledig' voor alle kenmerken of basic voor een beperkte set. De standaardwaarde is 'vol'. (Zie de lijst met kenmerken in dit artikel). Optioneel. |
| InvoiceId | Waar | String | Een unieke id voor elke factuur. Vereist. |
Aanvraagheaders
Aanvraagheaders voor de API met behulp van de stappen in Best practices voor het gebruik van Microsoft Graph.
API-reactie
HTTP/1.1 202 Accepted
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
De API reageert meestal met een HTTP 202-status. Andere mogelijke statussen, op basis van uw aanvragen, worden vermeld in de statussen van standard-API-antwoorden in dit artikel.
| Code | Beschrijving |
|---|---|
| 202 – Geaccepteerd | Uw aanvraag is geaccepteerd. Als u de status van uw aanvraag wilt controleren, voert u een query uit op de URL die is opgegeven in de locatieheader. |
Stap 2: Status van aanvraag controleren
Als u de status van een aanvraag wilt controleren, wacht u op een HTTP 200-antwoord met de status Geslaagd of Mislukt. Als de aanvraag is geslaagd, krijgt u de manifest-URL in het kenmerk resourceLocation.
Bewerkingsstatus ophalen
Haalt de status van een aanvraag op.
API-aanvraag
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Aanvraagparameters
| Naam | Opnemen in | Vereist | Type | Description |
|---|---|---|---|---|
| operationId | Aanvraag-URI | Waar | String | Een unieke id om de aanvraagstatus te controleren. Vereist. |
Aanvraagheader
Aanvraagheaders voor de API met behulp van de stappen in Best practices voor het gebruik van Microsoft Graph.
Aanvraagtekst
N.v.t.
Antwoordstatus
Naast de standaard HTTP-statussen die worden vermeld in de standaard-API-antwoordstatussen in dit artikel, kan de API de volgende HTTP-status retourneren:
| Code | Beschrijving |
|---|---|
| 410 – Weg | De manifestkoppeling verloopt na een ingestelde tijd. Als u de manifestkoppeling opnieuw wilt ophalen, verzendt u een nieuwe aanvraag. |
Nettolading van antwoord
De nettolading van het API-antwoord bevat de volgende kenmerken:
| Kenmerk | Vereist | Beschrijving |
|---|---|---|
| id | Waar | Een unieke id voor elk antwoord Vereist. |
| status | Waar | Waarden en acties: vereist. notstarted: Wacht op de tijd die is opgegeven in de header 'Opnieuw proberen-na' en voer vervolgens nog een aanroep uit om de status te controleren. wordt uitgevoerd: Wacht op de tijd die is opgegeven in de header 'Opnieuw proberen-na' en voer vervolgens een andere aanroep uit om de status te controleren. geslaagd: de gegevens zijn gereed. Haal de nettolading van het manifest op met behulp van de URI die is opgegeven in resourceLocation. mislukt: de bewerking is permanent mislukt. Start het opnieuw op. |
| createdDateTime | Waar | Het tijdstip waarop de aanvraag is ingediend. Vereist. |
| lastActionDateTime | Waar | De tijd waarop de status voor het laatst is gewijzigd. Vereist. |
| resourceLocation | Onwaar | De URI voor de nettolading van het manifest. Optioneel. |
| error | Onwaar | Als de bewerking mislukt, worden foutdetails opgegeven in JSON-indeling. Optioneel. De volgende kenmerken zijn opgenomen: bericht: Een gedetailleerde beschrijving van de fout. code: het type fout dat is opgetreden. |
Resourcelocatieobject
| Kenmerk | Beschrijving |
|---|---|
| id | Een unieke id voor het manifest. |
| schemaVersion | Versie van het manifestschema. |
| dataFormat | Indeling van het factureringsgegevensbestand. compressedJSON: gegevensindeling waarbij elke blob een gecomprimeerd bestand is dat gegevens in JSON-regelsindeling bevat. Als u de gegevens uit elke blob wilt ophalen, moet u deze decomprimeren. |
| createdDateTime | Datum en tijd waarop het manifestbestand is gemaakt. |
| eTag | Versie van de manifestgegevens. Een wijziging in factureringsgegevens genereert een nieuwe waarde. |
| partnerTenantId | Id van de tenant van de partner. |
| rootDirectory | Hoofdmap van het bestand. |
| sasToken | SAS-token (Shared Access Signature) waarmee u alle bestanden in de map kunt lezen. |
| partitionType | Verdeelt gegevens in meerdere blobs op basis van het kenmerk partitionValue . Het systeem splitst partities die het ondersteunde aantal overschrijden. Standaard worden gegevens gepartitioneerd op basis van het aantal regelitems in het bestand. Stel geen vast aantal regelitems of bestandsgrootte in de code in, omdat deze waarden kunnen worden gewijzigd. |
| blobCount | Totaal aantal bestanden voor deze partnertenant-id. |
| blobs | Een JSON-matrix van 'blob'-objecten die de bestandsgegevens voor de tenant-id van de partner bevatten. |
| blobobject | Een object met de volgende details: name: Naam van de blob. partitionValue: Partitie die het bestand bevat. De grote partitie wordt gesplitst in meerdere bestanden, waarbij elk bestand dezelfde 'partitionValue' bevat. |
| naam | Naam van de blob. |
| partitionValue | Partitie die het bestand bevat. De grote partitie wordt gesplitst in meerdere bestanden, waarbij elk bestand dezelfde 'partitionValue' bevat. |
API-aanvraag
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-reactie
Het antwoord raadt aan 10 seconden te wachten voordat u het opnieuw probeert wanneer uw gegevens nog steeds worden verwerkt.
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"
}
API-aanvraag
(10 seconden na de vorige aanvraag...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API-reactie
De API retourneert de status Geslaagd en de URI voor 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"
}
\]
}
}
Stap 3: Gefactureerde factuurafstemmingsgegevens downloaden uit Azure Blob Storage
Haal het SAS-token (Shared Access Signature) en de blob-opslaglocatie op uit de eigenschappen sasToken en rootDirectory. Azure Storage SDK/hulpprogramma om het blobbestand te downloaden en uit te pakken. Deze heeft de JSONLines-indeling .
Tip
Bekijk onze voorbeeldcode om het Azure-blobbestand te downloaden en uit te pakken in uw lokale database.
Standaard-API-antwoordstatussen
Mogelijk krijgt u deze HTTP-statussen uit het antwoord van de API:
| Code | Beschrijving |
|---|---|
| 400 – Ongeldige aanvraag | De aanvraag ontbreekt of bevat onjuiste gegevens. Controleer de hoofdtekst van het antwoord op foutdetails. |
| 401 - Niet geautoriseerd | De aanroeper wordt niet geverifieerd en u moet zich verifiëren met de partner-API-service voordat u de eerste aanroep doet. |
| 403 - Verboden | U hebt niet de benodigde autorisatie om de aanvraag te doen. |
| 404 – Niet gevonden | De aangevraagde resources zijn niet beschikbaar met de opgegeven invoerparameters. |
| 410 – Weg | De manifestkoppeling is niet meer geldig of actief. Dien een nieuwe aanvraag in. |
| 500 – Interne serverfout | De API of een van de bijbehorende afhankelijkheden kan momenteel niet voldoen aan de aanvraag. Probeer het later opnieuw. |
| 5000 – Geen gegevens beschikbaar | Het systeem heeft geen gegevens voor de opgegeven invoerparameters. |
Kenmerken van gefactureerde factuurafstemmingsgegevens
Raadpleeg de volgende tabel om de kenmerken te vergelijken die worden geretourneerd door de gefactureerde factuurafstemmings-API voor de 'volledige' of 'basis'-kenmerksets.
| Kenmerk | Volledig | Basis |
|---|---|---|
| PartnerId | ja | ja |
| CustomerId | ja | ja |
| CustomerName | ja | ja |
| CustomerDomainName | ja | nee |
| CustomerCountry | ja | nee |
| InvoiceNumber | ja | ja |
| MpnId | ja | nee |
| Tier2MpnId | ja | ja |
| OrderId | ja | ja |
| OrderDate | ja | ja |
| Product-id | ja | ja |
| SkuId | ja | ja |
| AvailabilityId | ja | ja |
| SkuName | ja | nee |
| ProductName | ja | ja |
| ChargeType | ja | ja |
| UnitPrice | ja | ja |
| Hoeveelheid | ja | nee |
| Subtotaal | ja | ja |
| TaxTotal | ja | ja |
| Totaal | ja | ja |
| Valuta | ja | ja |
| PriceAdjustmentDescription | ja | ja |
| PublisherName | ja | ja |
| PublisherId | ja | nee |
| SubscriptionDescription | ja | nee |
| SubscriptionId | ja | ja |
| ChargeStartDate | ja | ja |
| ChargeEndDate | ja | ja |
| TermAndBillingCycle | ja | ja |
| EffectiveUnitPrice | ja | ja |
| UnitType | ja | nee |
| AlternateId | ja | nee |
| BillableQuantity | ja | ja |
| BillingFrequency | ja | nee |
| PricingCurrency | ja | ja |
| PCToBCExchangeRate | ja | ja |
| PCToBCExchangeRateDate | ja | nee |
| MeterDescription | ja | nee |
| ReservationOrderId | ja | ja |
| CreditReasonCode | ja | ja |
| SubscriptionStartDate | ja | ja |
| SubscriptionEndDate | ja | ja |
| ReferenceId | ja | ja |
| ProductQualifiers | ja | nee |
| PromotionId | ja | ja |
| ProductCategory | ja | ja |
Voorbeeldcode
Zie de volgende koppeling met voorbeeldcode in C# voor hulp bij het gebruik van de API.
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor