API rekonsiliasi faktur yang ditagih v2 (GA)

Berlaku untuk: Pusat Mitra (tidak tersedia di sovereign cloud)

API asinkron kami menawarkan cara yang lebih cepat dan lebih mudah dikelola untuk mengakses data penagihan dan rekonsiliasi melalui blob Azure. Dengan API ini, Anda tidak perlu menjaga koneksi tetap terbuka selama berjam-jam atau mengulangi batch 2.000 item baris pada satu waktu.

Kami telah mengoptimalkan API rekonsiliasi faktur yang ditagih perdagangan baru kami menggunakan kunci valet dan pola balasan permintaan asinkron. API ini memberi Anda token tanda tangan akses bersama (SAS) yang dapat Anda gunakan untuk mengakses semua atribut atau subset data rekonsiliasi faktur yang ditagih.

Catatan

API baru tidak dihosting di host API Pusat Mitra. Sebagai gantinya, Anda dapat menemukannya di MS Graph di Gunakan Microsoft Graph API untuk mengekspor data tagihan mitra - Microsoft Graph v1.0. Untuk mengakses API ini, lihat detail berikut.

Penting

Untuk memberi aplikasi Anda izin yang diperlukan untuk mengakses data tagihan mitra, Anda perlu mengikuti tautan ini dan mempelajari tentang dasar-dasar autentikasi dan otorisasi untuk Microsoft Graph.

Biasanya, Anda dapat menggunakan pusat admin portal Azure atau Entra untuk menetapkan izin yang diperlukan: "PartnerBilling.Read.All." Berikut adalah langkah-langkah untuk melakukannya:

• Daftarkan aplikasi Anda di beranda Microsoft Entra di bawah bagian Pendaftaran aplikasi.
• Tetapkan izin ke aplikasi Anda di halaman Aplikasi Microsoft Entra di bawah bagian Izin API. Pilih "Tambahkan izin" dan pilih cakupan "PartnerBilling.Read.All".

Ringkasan API

Untuk mengambil data rekonsiliasi faktur perdagangan baru yang ditagih secara asinkron, gunakan dua titik akhir API. Berikut prosesnya:

Titik akhir rekonsiliasi faktur yang ditagih

Gunakan API ini untuk mengambil item baris rekonsiliasi faktur yang ditagih perdagangan baru. API mengembalikan status HTTP 202 dan header lokasi yang berisi URL. Polling URL ini secara berkala hingga Anda menerima status sukses dengan URL manifes.

Titik akhir status operasi

Untuk mendapatkan status sukses, terus panggil API ini secara berkala. Jika data belum siap, respons API menyertakan header Coba Lagi-Setelah untuk memberi tahu Anda berapa lama menunggu sebelum mencoba lagi. Setelah operasi selesai, Anda mendapatkan sumber daya manifes dengan folder penyimpanan tempat Anda dapat mengunduh data penggunaan. Respons memecah file menjadi bagian yang lebih kecil untuk throughput dan paralelisme I/O yang dioptimalkan.

Diagram urutan

Berikut adalah diagram urutan yang menunjukkan langkah-langkah untuk mengunduh data rekonsiliasi faktur perdagangan baru.

Urutan tindakan pengguna

Untuk mengambil data rekonsiliasi faktur yang ditagih, ikuti langkah-langkah berikut:

Langkah 1: Kirim permintaan

Kirim permintaan POST ke titik akhir API.

Mendapatkan item baris rekonsiliasi faktur yang ditagih

Permintaan API

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

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Parameter kueri

T/A

Isi permintaan

Atribut	Wajib	Tipe	Deskripsi
attributeSet	Salah	String	Pilih "penuh" untuk semua atribut atau "dasar" untuk set terbatas. Nilai defaultnya adalah "penuh." (Lihat daftar atribut dalam artikel ini). Opsional.
invoiceId	Benar	String	Pengidentifikasi unik untuk setiap faktur. Harus diisi.

Header permintaan

Header permintaan untuk API menggunakan langkah-langkah yang tercantum di Praktik terbaik untuk menggunakan Microsoft Graph.

Respons API

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

API biasanya merespons dengan status HTTP 202. Status lain yang mungkin, berdasarkan permintaan Anda, tercantum dalam status respons API Standar dalam artikel ini.

Kode	Deskripsi
202 – Diterima	Permintaan Anda diterima. Untuk memeriksa status permintaan Anda, kueri URL yang disediakan di header lokasi.

Langkah 2: Periksa status permintaan

Untuk memeriksa status permintaan, tunggu respons HTTP 200 dengan status "berhasil" atau "gagal." Anda mendapatkan URL manifes di atribut "resourceLocation" jika permintaan berhasil.

Dapatkan status Operasi

Mengambil status permintaan.

Permintaan API

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

Parameter permintaan

Nama	Sertakan dalam	Wajib	Tipe	Deskripsi
operationId	URI Permintaan	Benar	String	ID unik untuk memeriksa status permintaan. Harus diisi.

Header permintaan

Header permintaan untuk API menggunakan langkah-langkah yang tercantum di Praktik terbaik untuk menggunakan Microsoft Graph.

Isi permintaan

T/A.

Status Respons

Selain status HTTP standar yang tercantum dalam status respons API Standar dalam artikel ini, API dapat mengembalikan status HTTP berikut:

Kode	Deskripsi
410 – Hilang	Tautan manifes kedaluwarsa setelah waktu yang ditetapkan. Untuk mendapatkan tautan manifes lagi, kirim permintaan baru.

Payload respons

Payload respons API mencakup atribut berikut:

Atribut	Wajib	Deskripsi
id	Benar	ID unik untuk setiap respons Harus diisi.
status	Benar	Nilai dan tindakan: Diperlukan. notstarted: Tunggu waktu yang ditentukan di header "Coba Lagi-Setelah", lalu lakukan panggilan lain untuk memeriksa status. berjalan: Tunggu waktu yang ditentukan di header "Coba Lagi-Setelah", lalu lakukan panggilan lain untuk memeriksa status. berhasil: Data siap. Ambil payload manifes menggunakan URI yang ditentukan dalam resourceLocation. gagal: Operasi gagal secara permanen. Hidupkan ulang.
createdDateTime	Benar	Waktu ketika permintaan dibuat. Harus diisi.
lastActionDateTime	Benar	Waktu status terakhir diubah. Harus diisi.
resourceLocation	Salah	URI untuk payload manifes. Opsional.
kesalahan	Salah	Jika operasi gagal, detail kesalahan disediakan dalam format JSON. Opsional. Atribut berikut disertakan: pesan: Deskripsi terperinci tentang kesalahan. kode: Jenis kesalahan yang terjadi.

Objek lokasi sumber daya

Atribut	Deskripsi
id	Pengidentifikasi unik untuk manifes.
schemaVersion	Versi skema manifes.
dataFormat	Format file data penagihan. compressedJSON: Format data di mana setiap blob adalah file terkompresi yang berisi data dalam format baris JSON . Untuk mengambil data dari setiap blob, dekompresi.
createdDateTime	Tanggal dan waktu ketika file manifes dibuat.
eTag	Versi data manifes. Perubahan informasi penagihan menghasilkan nilai baru.
partnerTenantId	ID penyewa mitra.
rootDirectory	Direktori akar file.
sasToken	Token SAS (tanda tangan akses bersama) yang memungkinkan Anda membaca semua file di bawah direktori.
partitionType	Membagi data menjadi beberapa blob berdasarkan atribut partitionValue . Sistem membagi partisi yang melebihi angka yang didukung. Secara default, data dipartisi berdasarkan jumlah item baris dalam file. Jangan tetapkan jumlah item baris atau ukuran file dalam kode, karena nilai-nilai ini dapat berubah.
blobCount	Jumlah total file untuk ID penyewa mitra ini.
blob	Array JSON objek "blob" yang berisi detail file untuk ID penyewa mitra.
objek blob	Objek yang berisi detail berikut: nama: Nama blob. partitionValue: Partisi yang berisi file. Partisi besar dibagi menjadi beberapa file, dengan setiap file berisi "partitionValue" yang sama.
nama	Nama blob.
partitionValue	Partisi yang berisi file. Partisi besar dibagi menjadi beberapa file, dengan setiap file berisi "partitionValue" yang sama.

Permintaan API

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

Respons API

Respons merekomendasikan untuk menunggu selama 10 detik sebelum mencoba lagi saat data Anda masih diproses.

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"  
}

Permintaan API

(10 detik setelah permintaan sebelumnya...)

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

Respons API

API mengembalikan status "berhasil" dan URI untuk "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"

            }

        \]

    }

}

Langkah 3: Mengunduh data rekonsiliasi faktur yang ditagih dari penyimpanan blob Azure

Dapatkan token tanda tangan akses bersama (SAS) dan lokasi penyimpanan blob dari properti "sasToken" dan "rootDirectory" respons API payload manifes. Azure Storage SDK/tool untuk mengunduh dan membuka zip file blob. Ini dalam format JSONLines .

Tip

Lihat kode sampel kami untuk mengunduh dan membuka zip file blob Azure ke database lokal Anda.

Status respons API standar

Anda mungkin mendapatkan status HTTP ini dari respons API:

Kode	Deskripsi
400 – Permintaan Buruk	Permintaan hilang atau berisi data yang salah. Periksa isi respons untuk detail kesalahan.
401 – Tidak sah	Pemanggil tidak diautentikasi, dan Anda harus mengautentikasi dengan layanan API mitra sebelum melakukan panggilan pertama.
403 – Terlarang	Anda tidak memiliki otorisasi yang diperlukan untuk membuat permintaan.
404 – Tidak Ditemukan	Sumber daya yang diminta tidak tersedia dengan parameter input yang disediakan.
410 – Hilang	Tautan manifes tidak lagi valid atau aktif. Kirim permintaan baru.
500 – Kesalahan Server Internal	API atau salah satu dependensinya tidak dapat memenuhi permintaan saat ini. Coba lagi nanti.
5000 – Tidak ada data yang tersedia	Sistem tidak memiliki data untuk parameter input yang disediakan.

Atribut data rekonsiliasi faktur yang ditagih

Untuk membandingkan atribut yang dikembalikan oleh API rekonsiliasi faktur yang ditagih untuk set atribut "lengkap" atau "dasar", lihat tabel berikut. Untuk mempelajari selengkapnya tentang atribut ini, lihat Menggunakan file pengintaian.

Atribut	Penuh	Dasar
PartnerId	yes	yes
ID Pelanggan	yes	yes
CustomerName	yes	yes
CustomerDomainName	yes	no
CustomerCountry	yes	no
InvoiceNumber	yes	yes
MpnId	yes	no
Tier2MpnId	yes	yes
OrderId	yes	yes
OrderDate	yes	yes
ProductId	yes	yes
SkuId	yes	yes
AvailabilityId	yes	yes
SkuName	yes	no
ProductName	yes	yes
chargeType	yes	yes
UnitPrice	yes	yes
Quantity	yes	no
Subtotal	yes	yes
TaxTotal	yes	yes
Total	yes	yes
Mata Uang	yes	yes
PriceAdjustmentDescription	yes	yes
PublisherName	yes	yes
PublisherId	yes	no
SubscriptionDescription	yes	no
SubscriptionId	yes	yes
ChargeStartDate	yes	yes
ChargeEndDate	yes	yes
TermAndBillingCycle	yes	yes
EffectiveUnitPrice	yes	yes
UnitType	yes	no
AlternateId	yes	no
BillableQuantity	yes	yes
BillingFrequency	yes	no
PricingCurrency	yes	yes
PCToBCExchangeRate	yes	yes
PCToBCExchangeRateDate	yes	no
MeterDescription	yes	no
ReservationOrderId	yes	yes
CreditReasonCode	yes	yes
SubscriptionStartDate	yes	yes
SubscriptionEndDate	yes	yes
ReferenceId	yes	yes
ProductQualifiers	yes	no
PromotionId	yes	yes
ProductCategory	yes	yes

Kode Sampel

Untuk panduan tentang menggunakan API, lihat tautan berikut yang menyertakan kode sampel di C#.

Partner-Center-Billing-Recon-Samples: Sampel untuk API untuk mendapatkan data rekonstruksi Penagihan dari Pusat Mitra (github.com).