Jalankan laporan dari API
Catatan
Sekarang Anda dapat secara otomatis mengirim laporan dan data Stripe ke Snowflake atau Amazon Redshift dalam beberapa klik dengan Stripe Data Pipeline. Pelajari selengkapnya.
Laporan keuangan di Dashboard menyediakan laporan yang dapat diunduh dalam format CSV untuk berbagai tugas akuntansi dan rekonsiliasi. Laporan ini juga tersedia melalui API, jadi Anda dapat menjadwalkannya untuk berjalan secara otomatis atau menjalankannya kapan pun Anda perlu menerima file laporan terkait untuk tujuan akuntansi.
Tipe laporan
Setiap laporan keuangan di Dashboard menyediakan beberapa unduhan CSV yang berbeda. Semua unduhan yang tersedia untuk laporan berikut juga tersedia dari API:
Format moneter CSV dan API berbeda-beda
Laporan CSV ini memformat jumlah moneter dalam satuan mata uang utama sebagai angka desimal. Misalnya, CSV memformat 10 USD sebagai dolar dan sen (10.00
). Ini berbeda dengan Stripe API, di mana Anda menentukan jumlah dalam satuan mata uang minor (sen AS) sebagai bilangan bulat. Di API, Anda memformat 10 USD sebagai (1000
).
Jalankan parameter
Setiap laporan memiliki parameter wajib maupun opsional yang Anda berikan ketika menjalankan laporan. Pertimbangkan hal berikut ketika menjalankan laporan:
- Hampir setiap tipe laporan mengharuskan pemberian parameter proses
interval_start
(inklusif) daninterval_end
(eksklusif) sebagai stempel waktu Unix. - Masing-masing sumber daya tipe laporan yang sesuai memiliki bidang
data_available_start
dandata_available_end
. API mengembalikan kesalahan permintaan yang tidak valid (kode status400
) jika proses Anda tidak memenuhi batasan berikut:- Nilai
interval_start
daninterval_end
harus antaradata_available_start
dandata_available_end
(inklusif). - Nilai
interval_start
harus sebelum (dan tidak sama dengan)interval_end
.
- Nilai
- Anda hanya dapat mengunduh laporan dalam zona waktu untuk
ReportType
dengan parametertimezone
. Guna melakukannya, buat objekReportRun
dan berikan nama zona waktu database TZ yang diinginkan. Parametertimezone
bersifat opsional serta default terhadap UTC jika tidak diberikan. Lihat Database Zona Waktu IANA untuk daftar nilai zona waktu yang valid. - Parameter opsional
currency
danreport_category
memfilter hasil menjadi beberapa baris saja yang cocok dengan nilai yang diberikan. - Laporan mengembalikan serangkaian kolom default, tetapi sebagian besar tipe laporan memungkinkan Anda menyesuaikan pemilihan dan pengurutan kolom dalam output dengan menyertakan parameter
columns
opsional bersama daftar nama kolom.
Ketersediaan data
Stripe menyiapkan data untuk laporan Anda setiap setengah hari. Opsi laporan memberikan detail tentang waktu pemrosesan yang diperkirakan dan ketersediaan data untuk setiap laporan.
Untuk menentukan rentang waktu data yang tersedia secara terprogram bagi tipe laporan tertentu, ambil objek ReportType
yang diinginkan. Misalnya, laporan Ringkasan saldo memiliki identifikasi balance.summary.1
, sehingga Anda dapat mengambil objek sebagai berikut:
Dalam contoh respons di bawah, bidang data_available_start
dan data_available_end
mencerminkan rentang waktu valid yang lengkap untuk tipe laporan ini. Namun nanti Anda paling sering menjalankan laporan untuk interval yang lebih kecil dalam rentang itu:
{ "id": "balance.summary.1", "name": "Balance summary", "version": "1", "object": "reporting.report_type", "data_available_start": 1519862400, "data_available_end": 1517356800, "updated": 1517382720, }
Stempel waktu, seperti date_available_start
, diukur dalam hitungan detik sejak masa Unix. Sebagai contoh, 1519862400
mewakili stempel waktu, 2018-03-01 00:00
.
Notifikasi data baru
Begitu tipe laporan memiliki data baru, Stripe menerbitkan kejadian reporting.report_type.updated
dengan objek ReportType
yang diperbarui. Untuk mengakses kejadian ini, Anda harus memiliki webhook yang dikonfigurasi yang secara eksplisit memilih untuk menerima kejadian reporting.report_type.updated
; webhook yang mendengarkan ‘semua kejadian’ tidak akan menerimanya. Setelah menerima kejadian demikian, Anda kemudian dapat menjalankan laporan. Untuk detailnya, lihat rekomendasi pola integrasi.
Membuat dan mengakses pembuatan laporan
Objek ReportRun
API mewakili instance ReportType
yang dihasilkan dengan parameter tertentu. Tinjau dokumentasi untuk tipe laporan bagi daftar parameter wajib dan opsional untuk tipe tersebut. Misalnya, Anda dapat membuat laporan Perubahan saldo dari ringkasan aktivitas untuk April 2020 sebagai berikut:
Saat pertama kali dibuat, objek akan muncul dengan status="pending"
:
{ "id": "frr_123", "object": "reporting.report_run", "livemode": true, "report_type": "balance_change_from_activity.itemized.3", "parameters": { "columns": [ "created", "reporting_category", "net" ], "interval_start": 1577865600, "interval_end": 1580544000, "timezone": "America/Los_Angeles" }, "created": 1580832900, "status": "pending", "result": null }
Bila proses selesai, Stripe akan memperbarui objek, dan objek tersebut memiliki status
succeeded
. Ini juga memiliki objek result
tersarang, yang berisi URL yang dapat Anda gunakan untuk mengakses file dengan kunci API. Misalnya, jika Anda ingin mengambil pembuatan laporan di atas setelah selesai, responsnya adalah:
{ "id": "frr_123", "object": "reporting.report_run", "livemode": true, "report_type": "balance_change_from_activity.itemized.3", "parameters": { "columns": [ "created", "reporting_category", "net" ], "interval_start": 1577865600, "interval_end": 1580544000, "timezone": "America/Los_Angeles" }, "created": 1580832900, "status": "succeeded", "succeeded_at": 1580832960, "result": { "id": "file_xs8vrJzC", "object": "file", "url": "https://files.stripe.com/v1/files/file_xs8vrJzC/contents", "created": 1580832960, "purpose": "report_run", "size": 53075, "type": "csv" } }
Untuk mengambil isi file, gunakan kunci API Anda untuk mengakses file yang disebutkan melalui result.url
:
Notifikasi selesai menjalankan laporan
Sebagian besar selesai dijalankan dalam beberapa menit. Namun, beberapa dijalankan lebih lama—bergantung pada ukuran set data total Anda dan pada rentang waktu yang dicakup oleh laporan Anda.
Bila laporan yang diminta selesai dijalankan, Stripe akan mengirimkan salah satu dari dua webhook:
- Webhook
reporting.report_run.succeeded
akan dikirim jika berhasil dijalankan. - Webhook
reporting.report_run.failed
akan dikirim jika gagal dijalankan. (Ini jarang terjadi, tetapi kami merekomendasikan agar integrasi disiapkan untuk menangani kasus ini dengan cara yang sama seperti saat menangkap respons500
.)
Dalam kedua kasus tersebut, payload webhook menyertakan objek ReportRun
yang diperbarui, yang masing-masing berisi status succeeded
atau failed
.
Rekomendasi pola integrasi untuk pelaporan otomatis
Konfigurasikan webhook yang secara eksplisit memilih untuk menerima kejadian reporting.report_type.updated
; webhook yang mendengarkan ‘semua kejadian’ tidak akan menerimanya.
- Webhook
reporting.report_type.updated
dikirim segera setelah data hari baru tersedia untuk tipe laporan tertentu. Payload menyertakan objekReportType
yang diperbarui. Anda biasanya akan menerima 20-30 webhook setiap hari, dua untuk setiap tipe laporan. (Pengguna yang berbeda memenuhi syarat untuk laporan yang berbeda.) - Saat menerima webhook
reporting.report_type.updated
untuk tipe laporan yang diinginkan dan rentang ketersediaan data, lakukan pembuatan laporan. Tanggapan berisi objekReportRun
baru, yang diprakarsai denganstatus=pending
. - Bila selesai dijalankan, webhook
reporting.report_run.succeeded
akan dikirim. Webhook ini menyertakan bidangresult.url
tersarang. (Seperti disebutkan di atas, dalam kasus kegagalan yang jarang terjadi, kami akan mengirimkan kejadianreporting.report_run.failed
sebagai gantinya.) - Akses konten file di
result.url
, menggunakan kunci API Anda.