Gefactureerde factuurafstemming-API v2 (GA)

Van toepassing op: Partnercentrum (niet beschikbaar in onafhankelijke cloud)

Onze nieuwe asynchrone API biedt een snellere en efficiëntere manier om toegang te krijgen tot uw facturerings- en afstemmingsgegevens via Azure-blobs. In plaats van een verbinding uren open te houden of batches van 2000 regelitems te verwerken, kunt u uw werkstroom stroomlijnen, de belasting van de server verminderen en de verwerkingstijden van gegevens verbeteren.

De nieuwe facturerings-API voor factuurafstemming maakt gebruik van geavanceerde technieken zoals valetsleutel en asynchrone aanvraagantwoordpatronen . Het valetsleutelpatroon biedt veilige toegang tot resources zonder referenties te delen, terwijl het asynchrone aanvraagantwoordpatroon efficiënte communicatie tussen systemen mogelijk maakt.

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. Dit token verbetert de beveiliging door beperkte toegang te verlenen en biedt flexibiliteit bij het beheren van machtigingen voor gegevenstoegang.

Door gebruik te maken van onze geoptimaliseerde API's, kunt u sneller resultaten bereiken met minder inspanning, de toegang tot uw gegevens vereenvoudigen en de algehele efficiëntie verbeteren. Gebruik deze hulpprogramma's om uw werkstroom te stroomlijnen en machtigingen effectiever te beheren.

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.

Belangrijk

Volg deze koppeling om uw app toegang te geven tot factureringsgegevens van partners en vertrouwd te raken met de basisbeginselen voor verificatie en autorisatie voor Microsoft Graph. Deze stap is van cruciaal belang omdat uw app veilig toegang heeft tot de benodigde gegevens.

U kunt de machtiging PartnerBilling.Read.All toewijzen met behulp van de Azure-portal of het Entra-beheercentrum. U doet dit als volgt:

• Registreer uw app op de startpagina van Microsoft Entra onder de sectie App-registraties.
• Als u de benodigde machtigingen wilt verlenen, gaat u naar de pagina Microsoft Entra App. Selecteer in de sectie API-machtigingen de optie Een machtiging toevoegen en kies het bereik PartnerBilling.Read.All.

Door deze stappen uit te voeren, moet u ervoor zorgen dat uw app beschikt over de vereiste toegang tot factureringsgegevens van partners.

API-overzicht

Om u te helpen bij het asynchroon ophalen van gefactureerde nieuwe handelsfactuuritems voor factuurafstemming, bieden we twee belangrijke API-eindpunten. Volg deze gestroomlijnde handleiding om snel en efficiënt aan de slag te gaan!

Factureringseindpunt voor factuurafstemming

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.

Eindpunt van 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.

Door deze stappen te volgen, kunt u uw factuurafstemmingsproces efficiënt beheren.

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

Stap 2: Status van aanvraag 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"

            }

        \]

    }

}

Stap 3: Gefactureerde regelitems voor factuurafstemming downloaden uit Azure Blob Storage

Eerst moet u het SAS-token (Shared Access Signature) en de blobopslaglocatie ophalen. U vindt deze details in de eigenschappen 'sasToken' en 'rootDirectory' van het antwoord van de payload-API van het manifest. Gebruik vervolgens de Azure Storage SDK/het hulpprogramma om het blobbestand te downloaden en uit te pakken. Deze heeft de JSONLines-indeling .

Tip

Zorg ervoor dat u onze voorbeeldcode bekijkt. U ziet hoe u het Azure-blobbestand downloadt en uitpakt naar uw lokale database.

Standaard-API-antwoordstatussen

Mogelijk krijgt u deze 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 deze handleidingvoor 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

Noteer deze wijzigingen wanneer u overstapt van API v1 naar v2.

• Elke kenmerknaam begint nu met een hoofdletter letter om de consistentie met het bestand te behouden en de leesbaarheid te verbeteren.

Voorbeeldcode

Als u deze API wilt gebruiken, raadpleegt u de volgende koppeling, die C#-voorbeeldcode bevat.

Partner-Center-Billing-Recon-Samples: Voorbeelden voor API voor het ophalen van factureringsgegevens van partnercentrum (github.com).