API för fakturerad fakturaavstämning v2 (GA)

Gäller för: Partnercenter (ej tillgängligt i nationellt moln)

Vårt nya asynkrona API erbjuder ett snabbare och effektivare sätt att komma åt dina fakturerings- och avstämningsdata via Azure-blobar. I stället för att hålla en anslutning öppen i timmar eller bearbeta batchar med 2 000 radobjekt kan du nu effektivisera arbetsflödet, minska serverbelastningen och förbättra databearbetningstiderna.

Det nya API:et för fakturaavstämning som faktureras för handel använder avancerade tekniker som valet-nyckel och asynkrona mönster för begärandesvar . Valet-nyckelmönstret möjliggör säker åtkomst till resurser utan att dela autentiseringsuppgifter, medan det asynkrona mönstret för begäran-svar möjliggör effektiv kommunikation mellan system.

Det här API:et ger dig en SAS-token (signatur för delad åtkomst) som du kan använda för att komma åt antingen alla attribut eller en delmängd av fakturaavstämningsdata. Den här token förbättrar säkerheten genom att ge begränsad tidsåtkomst och ger flexibilitet när det gäller att hantera dataåtkomstbehörigheter.

Genom att använda våra optimerade API:er kan du uppnå snabbare resultat med mindre ansträngning, förenkla din dataåtkomst och förbättra den övergripande effektiviteten. Använd de här verktygen för att effektivisera arbetsflödet och hantera behörigheter mer effektivt.

Kommentar

Det nya API:et finns inte på API-värden för Partnercenter. I stället kan du hitta den i MS Graph på Använda Microsoft Graph API för att exportera partnerfaktureringsdata – Microsoft Graph v1.0. Om du vill komma åt det här API:et läser du följande information.

Viktigt!

Om du vill ge din app åtkomst till partnerfaktureringsdata följer du den här länken och bekantar dig med grunderna för autentisering och auktorisering för Microsoft Graph. Det här steget är avgörande eftersom det säkerställer att din app på ett säkert sätt kan komma åt nödvändiga data.

Du kan tilldela behörigheten "PartnerBilling.Read.All" med antingen Azure Portal eller Administrationscenter för Entra. Så här gör du:

• Registrera din app på Microsoft Entra-startsidan under avsnittet Appregistreringar.
• Om du vill bevilja nödvändig behörighet går du till sidan Microsoft Entra-app. Under avsnittet API-behörigheter väljer du "Lägg till en behörighet" och väljer omfånget "PartnerBilling.Read.All".

Genom att slutföra de här stegen ser du till att din app har nödvändig åtkomst till partnerfaktureringsdata.

API-översikt

För att hjälpa dig att hämta fakturerade nya handelsfakturaavstämningsradobjekt asynkront erbjuder vi två viktiga API-slutpunkter. Följ den här smidiga guiden för att komma igång snabbt och effektivt!

Slutpunkt för fakturerad fakturaavstämning

Använd först det här API:et för att hämta nya fakturerade fakturaavstämningsradobjekt för handel . När du gör en begäran får du HTTP-status 202 och en platsrubrik med en URL. Avsök den här URL:en regelbundet tills du får en lyckad status och en manifest-URL.

Slutpunkt för åtgärdsstatus

Fortsätt sedan att kontrollera åtgärdsstatusen genom att anropa det här API:et med jämna mellanrum. Om data inte är klara innehåller svaret ett återförsökshuvud som anger hur lång tid det tar att vänta innan du försöker igen. När åtgärden är klar får du en manifestresurs med en länk till lagringsmappen för att ladda ned användningsdata. Svaret segmentar filerna för att förbättra dataflödet och möjliggöra I/O-parallellitet.

Genom att följa dessa steg kan du effektivt hantera fakturaavstämningsprocessen.

Sekvensdiagram

Här är ett sekvensdiagram som visar stegen för att ladda ned nya handelsfakturaavstämningsdata.

Åtgärdssekvens för användare

Följ dessa steg för att hämta fakturerade fakturaavstämningsdata:

Steg 1: Skicka begäran

Skicka en POST-begäran till API-slutpunkten.

Hämta fakturerade fakturaavstämningsradobjekt

API-begäran

POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Frågeparametrar

Ej tillämpligt

Begärandetext

Attribut	Obligatoriskt	Type	Beskrivning
attributeSet	Falsk	String	Välj "fullständig" för alla attribut eller "grundläggande" för en begränsad uppsättning. Om det inte anges är "full" standardvärdet. Kontrollera listan över attribut i det här avsnittet. Valfritt.
invoiceId	Sant	String	En unik identifierare för varje faktura. Obligatoriska.

Begärandehuvuden

Begär rubriker för API:et med hjälp av de steg som anges i Metodtips för att använda Microsoft Graph. Genom att följa dessa riktlinjer säkerställer du tillförlitlighet och support för ditt program. Din uppmärksamhet på detaljer i det här steget är avgörande för sömlös integrering och optimala prestanda.

API-svar

HTTP/1.1 202 Accepted  
Location: <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

API:et svarar vanligtvis med http 202-status. Du kan också stöta på andra statusar beroende på dina begäranden. Dessa statusar visas i avsnittet Standard-API-svarsstatusar .

Kod	Beskrivning
202 – Godkänd	Din begäran godkändes. Om du vill kontrollera statusen för din begäran frågar du url:en som anges i platsrubriken.

Steg 2: Kontrollera status för begäran

Om du vill hålla reda på status för en begäran ser du till att du får ett HTTP 200-svar som är en standardstatuskod som anger "lyckades" eller "misslyckades". Om det lyckas hittar du manifest-URL:en i attributet "resourceLocation". Det här attributet ger en slutpunkt för åtkomst till nödvändig information.

Hämta åtgärdsstatus

Hämtar status för en begäran.

API-begäran

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Parametrar för begäran

Name	Inkludera i	Obligatoriskt	Type	Beskrivning
operationId	URI för förfrågan	Sant	String	En unik identifierare för att kontrollera status för begäran. Obligatoriska.

Begärandehuvud

Begär rubriker för API:et med hjälp av de steg som anges i Metodtips för att använda Microsoft Graph. Genom att följa dessa riktlinjer säkerställer du tillförlitlighet och support för ditt program. Din uppmärksamhet på detaljer i det här steget är avgörande för sömlös integrering och optimala prestanda.

Begärandetext

Saknas.

Svarsstatus

Förutom de standard-HTTP-statusar som anges i Standard API-svarsstatusar kan API:et också returnera följande HTTP-status:

Kod	Beskrivning
410 – Borta	Manifestlänken upphör att gälla efter en angiven tid. Om du vill hämta manifestlänken igen skickar du en ny begäran.

Svarsnyttolast

API-svarsnyttolasten innehåller följande attribut:

Attribut	Obligatoriskt	Beskrivning
id	Sant	En unik identifierare för varje svar Obligatoriska.
status	Sant	Värden och åtgärder: Krävs. inte startad: Vänta under den angivna varaktigheten i rubriken "Försök igen" och gör sedan ett nytt anrop för att kontrollera statusen. körs: Vänta tills den angivna varaktigheten i rubriken "Försök efter igen" och gör sedan ett nytt anrop för att kontrollera statusen. lyckades: Data är klara. Hämta manifestnyttolasten med hjälp av den URI som anges i resourceLocation. misslyckades: Åtgärden misslyckades permanent. Starta om den.
createdDateTime	Sant	Den tid då begäran gjordes. Obligatoriska.
lastActionDateTime	Sant	Senaste gången statusen ändrades. Obligatoriska.
resourceLocation	Falsk	URI:n för manifestnyttolasten. Valfritt.
fel	Falsk	Information om eventuella fel, som anges i JSON-format. Valfritt. Attribut som ingår: message: Beskrivning av felet. kod: Typ av fel.

Resursplatsobjekt

Attribut	Beskrivning
id	En unik identifierare för manifestet.
schemaVersion	Version av manifestschemat.
dataFormat	Format för faktureringsdatafilen. compressedJSON: Dataformat där varje blob är en komprimerad fil som innehåller data i JSON-linjeformat . Om du vill hämta data från varje blob expanderar du dem.
createdDateTime	Datum och tid då manifestfilen skapades.
eTag	Version av manifestdata. Ett nytt värde genereras när faktureringsinformationen ändras.
partnerTenantId	Microsoft Entra-ID för partnerns klientorganisation.
rootDirectory	Rotkatalogen för filen.
sasToken	SAS-token (signatur för delad åtkomst) som gör att du kan läsa alla filer under katalogen.
partitionType	Delar upp data i flera blobar baserat på attributet partitionValue . Systemet delar partitioner som överskrider det antal som stöds. Som standard partitioneras data baserat på antalet radobjekt i filen. Undvik att hårdkoda antal radobjekt eller filstorlekar när de kan ändras.
blobCount	Totalt antal filer för det här partnerklient-ID:t.
blobar	En JSON-matris med "blob"-objekt som innehåller filinformationen för partnerklient-ID:t.
blob-objekt	Ett objekt som innehåller följande information: name och partitionValue
name	Namnet på bloben.
partitionValue	Partition som innehåller filen. Den stora partitionen är uppdelad i flera filer baserat på vissa kriterier, till exempel filstorlek eller antal poster, där varje fil innehåller samma "partitionValue".

API-begäran

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

API-svar

Svaret rekommenderar att du väntar i 10 sekunder innan du försöker igen när dina data fortfarande bearbetas.

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-begäran

(10 sekunder efter föregående begäran...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

API-svar

API:et returnerar statusen "lyckades" och URI:n för "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"

            }

        \]

    }

}

Steg 3: Ladda ned fakturerade fakturaavstämningsradobjekt från Azure Blob Storage

Först måste du hämta sas-token (signatur för delad åtkomst) och bloblagringsplatsen. Du hittar den här informationen i egenskaperna "sasToken" och "rootDirectory" för api-svaret för manifestnyttolasten. Om du sedan vill ladda ned och packa upp blobfilen använder du Azure Storage SDK/-verktyget. Den är i JSONLines-format .

Dricks

Se till att kolla in vår exempelkod. Den visar hur du laddar ned och packar upp Azure-blobfilen till din lokala databas.

Standard-API-svarsstatusar

Du kan få dessa HTTP-statusar från API-svaret:

Kod	Beskrivning
400 – Felaktig begäran	Begäran saknas eller innehåller felaktiga data. Kontrollera svarstexten om du vill ha felinformation.
401 – behörighet saknas	Autentisering krävs innan du gör det första anropet. Autentisera med partner-API-tjänsten.
403 – förbjuden	Du har inte den behörighet som krävs för att göra begäran.
404 – Hittades inte	De begärda resurserna är inte tillgängliga med de angivna indataparametrarna.
410 – Borta	Manifestlänken är inte giltig eller aktiv längre. Skicka en ny begäran.
500 – Internt serverfel	API:et eller dess beroenden kan inte uppfylla begäran just nu. Försök igen senare.
5000 – Inga tillgängliga data	Systemet har inga data för de angivna indataparametrarna.

Attribut för fakturerade fakturaavstämningsobjekt

Om du vill jämföra attributen som returneras av API:et för fakturerad fakturaavstämning för attributuppsättningarna "full" eller "basic" läser du den här tabellen. Mer information om dessa attribut och deras betydelser finns i den här guide.

Attribut	Fullständig	Grundläggande
PartnerId	ja	ja
CustomerId	ja	ja
CustomerName	ja	ja
CustomerDomainName	ja	nej
CustomerCountry	ja	nej
InvoiceNumber	ja	ja
MpnId	ja	nej
Tier2MpnId	ja	ja
OrderId	ja	ja
OrderDate	ja	ja
Produkt-ID	ja	ja
SkuId	ja	ja
AvailabilityId	ja	ja
SkuName	ja	nej
ProductName	ja	ja
ChargeType	ja	ja
UnitPrice	ja	ja
Kvantitet	ja	nej
Delsumma	ja	ja
TaxTotal	ja	ja
Totalt	ja	ja
Valuta	ja	ja
PriceAdjustmentDescription	ja	ja
PublisherName	ja	ja
PublisherId	ja	nej
SubscriptionDescription	ja	nej
SubscriptionId	ja	ja
ChargeStartDate	ja	ja
ChargeEndDate	ja	ja
TermAndBillingCycle	ja	ja
EffectiveUnitPrice	ja	ja
UnitType	ja	nej
AlternateId	ja	nej
BillableQuantity	ja	ja
BillingFrequency	ja	nej
PricingCurrency	ja	ja
PCToBCExchangeRate	ja	ja
PCToBCExchangeRateDate	ja	nej
MeterDescription	ja	nej
ReservationOrderId	ja	ja
CreditReasonCode	ja	ja
SubscriptionStartDate	ja	ja
SubscriptionEndDate	ja	ja
ReferenceId	ja	ja
ProductQualifiers	ja	nej
PromotionId	ja	ja
ProductCategory	ja	ja

Viktigt!

Anteckna dessa ändringar när du flyttar från API v1 till v2.

• Varje attributnamn börjar nu med en stor bokstav för att upprätthålla konsekvens med filen och förbättra läsbarheten.

Exempelkod

Om du vill använda det här API:et läser du följande länk, som innehåller C#-exempelkod.

Partner-Center-Billing-Recon-Samples: Exempel för API för att hämta faktureringsrekonfigureringsdata från Partnercenter (github.com).