Delen via


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

  1. 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.

  2. Beveiligingsverbeteringen

    Het valetsleutelpatroon, geïmplementeerd via SAS-tokens, biedt:

    • Beperkte toegang.

    • Beperkte machtigingen.

    • Verwijdering van het delen of opslaan van permanente referenties.

    • Fijnmazig toegangsbeheer.

  3. 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:

  1. Registreer uw app op de startpagina van Microsoft Entra onder de sectie App-registraties.
  2. 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.

diagram met de stappen voor het downloaden van afstemmingsgegevens.

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

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:

  1. Download het blobbestand met behulp van de Azure Storage SDK/het hulpprogramma.
  2. 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.