Gefactureerde factuurafstemming-API v2 (GA)
van toepassing op: Partnercentrum (niet beschikbaar in Azure Government of Azure China 21Vianet)
Inzicht in de architectuur
De nieuwe asynchrone API biedt aanzienlijke vooruitgang in de manier waarop we toegang tot facturerings- en afstemmingsgegevens verwerken. Deze aanpak lost uitdagingen op die zijn gekoppeld aan traditionele synchrone methoden, zoals het onderhouden van langdurige verbindingen en het verwerken van grote gegevensbatches. Dit zijn de belangrijkste voordelen en mechanismen van deze API:
Belangrijke onderdelen
Beveiligde toegang met valet sleutel patroon
De -valetsleutel patroon biedt veilige, beperkte toegang tot uw factureringsgegevens. Net als bij hoe iemand met een valetsleutel uw auto kan besturen zonder toegang te krijgen tot de kofferbak, zorgt dit patroon voor gedetailleerd toegangsbeheer. In plaats van referenties te delen, verleent een SAS-token (Shared Access Signature) beperkte, tijdsgebonden toegang tot specifieke resources. Dit patroon vermindert het risico op onbevoegde toegang door nauwkeurige verlooptijden en toegangsmachtigingen te configureren.
Verbeterde efficiëntie via asynchroon aanvraag-antwoordpatroon
U kunt het zien als bestellen in een druk restaurant. In plaats van op de teller te wachten, ontvangt u een buzzer en kunt u andere dingen doen terwijl uw bestelling wordt voorbereid. Wanneer de gegevens gereed zijn, krijgt u een bericht van het systeem.
De asynchrone aard van de API betekent dat u een aanvraag indient en dat het systeem deze op de achtergrond verwerkt. Deze asynchrone verzoek-antwoord maakt efficiënt gebruik van resources, vermindert de belasting van de server en minimaliseert time-outs en fouten die vaak voorkomen bij het ophalen van synchrone gegevens.
Flexibiliteit in machtigingen voor gegevenstoegang
SAS-tokens bieden flexibiliteit bij het beheren van machtigingen voor gegevenstoegang. U kunt tokens genereren die toegang verlenen tot alle kenmerken van de gefactureerde factuurafstemmingsgegevens of de toegang tot specifieke subsets beperken. Met deze granulariteit kunnen organisaties de toegang tot gegevens aanpassen volgens intern beleid en wettelijke vereisten, waardoor beveiliging en naleving worden verbeterd.
Vereenvoudigde werkstroom en verbeterde verwerkingstijden
Het asynchrone aanvraagantwoordpatroon stroomlijnt gegevensverwerking door dynamische toegang toe te staan in plaats van vaste batches van 2000 regelitems. Deze aanpak leidt tot snellere resultaten en verbeterde verwerkingstijden, waardoor de integratie van facturerings- en afstemmingsgegevens in bestaande systemen en werkstromen wordt vereenvoudigd.
Voordelen
Prestatievoordelen
In plaats van langdurige verbindingen te onderhouden en vaste batches te verwerken, kunt u met het nieuwe systeem:
Maak een snelle eerste aanvraag.
Een beveiligd toegangstoken ontvangen.
Gegevens in uw eigen tempo verwerken.
Krijg precies toegang tot wat u nodig hebt wanneer u het nodig hebt.
Beveiligingsverbeteringen
Het valetsleutelpatroon, geïmplementeerd via SAS-tokens, biedt:
Beperkte toegang.
Beperkte machtigingen.
Verwijdering van het delen of opslaan van permanente referenties.
Fijnmazig toegangsbeheer.
Architectonische voordelen
Het asynchrone aanvraagantwoordpatroon fungeert als een persoonlijke assistent die:
Verwerkt uw aanvraag.
Hiermee wordt de taak op de achtergrond verwerkt.
U krijgt een bericht wanneer alles klaar is.
Geoptimaliseerde API's gebruiken voor verbeterde prestaties
Het gebruik van deze geoptimaliseerde API's stroomlijnt de werkstroom en verbetert de algehele prestaties in gegevensbeheer. Door veilige toegangsbeheer en efficiënte mechanismen voor het ophalen te gebruiken, bereikt u betere resultaten met minder inspanning, wat leidt tot een verbeterde operationele efficiëntie.
Tot slot is de nieuwe asynchrone API voor toegang tot facturerings- en afstemmingsgegevens via Azure-blobs een krachtig hulpprogramma. Het biedt veilige, efficiënte toegang tot financiële gegevens, stroomlijnende werkstromen, het verminderen van de belasting van de server en het verbeteren van verwerkingstijden, allemaal met hoge beveiliging en naleving.
Notitie
De nieuwe API wordt niet gehost op de Partner Center API-host. In plaats daarvan kunt u deze vinden in Microsoft Graph op 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.
Uw app toestaan om veilig toegang te krijgen tot factureringsgegevens van partners
Volg deze koppeling om uw app toegang te geven tot factureringsgegevens van partners en vertrouwd te raken met de basisbeginselen voor verificatie en autorisatie van voor Microsoft Graph. Deze stap is van cruciaal belang omdat uw app veilig toegang heeft tot de benodigde gegevens.
Registreer uw app en wijs de toestemming PartnerBilling.Read.All toe
U kunt de machtiging PartnerBilling.Read.All toewijzen met behulp van Azure Portal of het Microsoft Entra-beheercentrum. Door deze stappen uit te voeren, kunt u ervoor zorgen dat uw app over de vereiste toegang tot factureringsgegevens van partners beschikt. U doet dit als volgt:
- Registreer uw app op de startpagina van Microsoft Entra onder de sectie App-registraties.
- Verleen de benodigde machtigingen door naar de Microsoft Entra App-pagina te gaan. Selecteer in de sectie API-machtigingen Een machtiging toevoegen en kies het bereik PartnerBilling.Read.All.
Meer informatie over de belangrijkste API-eindpunten
Om u te helpen bij het asynchroon ophalen van gefactureerde nieuwe handelsfactuuritems voor factuurafstemming, bieden we twee belangrijke API-eindpunten. Met deze eindpunten kunt u uw factuurafstemmingsproces efficiënt beheren. Volg deze gestroomlijnde handleiding om snel aan de slag te gaan.
Het factuurafstemmingseindpunt gebruiken
Gebruik eerst deze API om nieuwe gefactureerde factuurafstemmingsitems op te halen. Wanneer u een aanvraag indient, ontvangt u een HTTP-status van 202 en een locatieheader met een URL. Peil deze URL regelmatig totdat u de status geslaagd en een manifest-URL krijgt.
Gebruik het eindpunt voor de bewerkingsstatus
Controleer vervolgens de bewerkingsstatus door deze API regelmatig aan te roepen. Als de gegevens niet gereed zijn, bevat het antwoord een header Opnieuw proberen na die aangeeft hoe lang moet worden gewacht voordat u het opnieuw probeert. Zodra de bewerking is voltooid, ontvangt u een manifestresource met een koppeling naar de opslagmap om de gebruiksgegevens te downloaden. Het antwoord segmenteren de bestanden om de doorvoer te verbeteren en I/O parallellisme mogelijk te maken.
Controleer het sequentiediagram
Hier volgt een sequentiediagram met de stappen voor het downloaden van nieuwe afstemmingsgegevens voor handelsfacturen.
Volg de actiereeks van de gebruiker om gefactureerde factuurafstemmingsgegevens op te halen
Dit is de gebruikersactiereeks voor het ophalen van gefactureerde factuurafstemmingsgegevens:
- een POST-aanvraag indienen
- Status van aanvraag controleren
- Afstemmingsregelitems downloaden uit Azure Blob Storage-
Een POST-aanvraag indienen
Dien een POST-aanvraag in bij het API-eindpunt.
Gefactureerde regelitems voor factuurafstemming ophalen
Haal de gefactureerde factuurafstemmingsregelitems op.
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. Als dit niet is opgegeven, is 'volledig' de standaardwaarde. Controleer de lijst met kenmerken in deze sectie. 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. Door deze richtlijnen te volgen, zorgt u voor betrouwbaarheid en ondersteuning voor uw toepassing. Uw aandacht voor detail in deze stap is van cruciaal belang voor naadloze integratie en optimale prestaties.
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. U kunt ook andere statussen tegenkomen, afhankelijk van uw aanvragen. Deze statussen worden weergegeven in de sectie Statussen van standaard-API-antwoorden.
| Code | Description |
|---|---|
| 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. |
De aanvraagstatus controleren
Als u de status van een aanvraag wilt bijhouden, moet u ervoor zorgen dat u een HTTP 200-antwoord ontvangt. Dit is een standaardstatuscode die 'geslaagd' of 'mislukt' aangeeft. Als dit lukt, vindt u de manifest-URL in het kenmerk resourceLocation. Dit kenmerk biedt een eindpunt voor toegang tot de vereiste informatie.
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. Door deze richtlijnen te volgen, zorgt u voor betrouwbaarheid en ondersteuning voor uw toepassing. Uw aandacht voor detail in deze stap is van cruciaal belang voor naadloze integratie en optimale prestaties.
Aanvraagtekst
N.v.t.
Antwoordstatus
Naast de standaard HTTP-statussen die worden vermeld in de standaard-API-antwoordstatussen, kan de API ook de volgende HTTP-status retourneren:
| Code | Description |
|---|---|
| 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 | Description |
|---|---|---|
| id | Waar | Een unieke id voor elk antwoord Vereist. |
| status | Waar |
Waarden en acties: vereist. niet gestart: wacht op de opgegeven duur in de header 'Opnieuw proberen-na', en voer vervolgens nog een aanroep uit om de status te controleren. wordt uitgevoerd: wacht op de opgegeven duur in de header 'Opnieuw proberen-na', en voer vervolgens nog een 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 laatste keer dat de status is gewijzigd. Vereist. |
| resourceLocation | Onwaar | De URI voor de nettolading van het manifest. Optioneel. |
| error | Onwaar | Details over eventuele fouten, opgegeven in JSON-indeling. Optioneel. Kenmerken zijn opgenomen: bericht: Beschrijving van de fout. code: Het type fout. |
Resourcelocatieobject
| Kenmerk | Description |
|---|---|
| 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. Er wordt een nieuwe waarde gegenereerd wanneer er een wijziging in de factureringsgegevens is. |
| partnerTenantId | Microsoft Entra-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. Vermijd hardcodering van regelitems of bestandsgrootten, omdat deze kunnen veranderen. |
| 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 en partitionValue |
| naam | Naam van de blob. |
| partitionValue | Partitie die het bestand bevat. De grote partitie wordt gesplitst in meerdere bestanden op basis van bepaalde criteria, zoals de bestandsgrootte of het aantal records, 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": "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"
}
\]
}
}
Afstemmingsregelitems downloaden uit Azure Blob Storage
Eerst moet u het SAS-token (Shared Access Signature) en de blobopslaglocatie verkrijgen. Zoek deze details in de sasToken- en rootDirectory-eigenschappen van de payload API-respons van het manifest.
Voer de volgende stappen uit om door te gaan:
- Download het blobbestand met behulp van de Azure Storage SDK/het hulpprogramma.
- Pak het bestand uit, dat zich in de JSONLines indeling bevindt.
Tip
Bekijk onze voorbeeldcode. Het laat zien hoe u het Azure-blobbestand downloadt en uitpakt naar uw lokale database.
Standaard-API-antwoordstatussen
Mogelijk krijgt u de volgende HTTP-statussen uit het API-antwoord:
| Code | Description |
|---|---|
| 400 – Ongeldige aanvraag | De aanvraag ontbreekt of bevat onjuiste gegevens. Controleer de hoofdtekst van het antwoord op foutdetails. |
| 401 - Niet geautoriseerd | Verificatie is vereist voordat u de eerste aanroep doet. Verifiëren met de partner-API-service. |
| 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 de bijbehorende afhankelijkheden kunnen 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 factuurafstemmingsregelitems
Raadpleeg deze tabel om de kenmerken te vergelijken die worden geretourneerd door de gefactureerde factuurafstemmings-API voor de 'volledige' of 'basis'-kenmerksets. Zie Het afstemmingsbestand gebruikenvoor meer informatie over deze kenmerken en hun betekenissen.
| 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 |
Belangrijk
Elke veld- of kenmerknaam begint met een hoofdletter letter om de consistentie met het bestand te behouden en de leesbaarheid te verbeteren.
Voorbeeldcode
Als u hulp nodig hebt bij het migreren naar deze API, raadpleegt u de koppeling met C#-voorbeeldcode.
API-voorbeelden voor het ophalen van factureringsgegevens van partnercentrum.