Lewati ke konten
Buat akun atau Masuk
Logo Dokumen Stripe
/
Buat akunMasuk

Cara kerja API Laporan

Akses laporan keuangan Stripe secara programatis untuk mengotomatiskan alur kerja rekonsiliasi Anda.

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) dan interval_end (eksklusif) sebagai stempel waktu Unix.
  • Masing-masing sumber daya tipe laporan yang sesuai memiliki bidang data_available_start dan data_available_end. API mengembalikan kesalahan permintaan yang tidak valid (kode status 400) jika proses Anda tidak memenuhi batasan berikut:
    • Nilai interval_start dan interval_end harus antara data_available_start dan data_available_end (inklusif).
    • Nilai interval_start harus sebelum (dan tidak sama dengan) interval_end.
  • Anda hanya dapat mendownload laporan di zona waktu untuk ReportType dengan timezone parameter. Untuk melakukannya, buat ReportRun objek dan menyediakan nama zona waktu database TZ yang diinginkan. Si timezone bersifat opsional dan default ke UTC jika tidak disediakan. Lihat Basis Data Zona Waktu IANA untuk daftar nilai zona waktu yang valid.
  • Parameter opsional currency dan report_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 untuk jenis laporan tertentu secara terprogram, mengambil si ReportType objek yang menarik. Misalnya, laporan Ringkasan saldo memiliki ID balance.summary.1, sehingga Anda dapat mengambil objek sebagai berikut:

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

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

Jika jenis laporan memiliki data baru yang tersedia, Stripe menerbitkan reporting.report_type.updated dengan acara yang diperbarui ReportType benda. Untuk mengakses peristiwa ini, Anda harus memiliki webhook dikonfigurasi yang secara eksplisit memilih untuk menerima peristiwa reporting.report_type.updated; Webhook yang mendengarkan ‘semua acara’ tidak akan menerimanya.

Untuk mengurangi lalu lintas webhook, Stripe tidak mengirimkan peristiwa ini ke Menyambungkan titik akhir webhook. Setelah menerima acara, Anda dapat menjalankan laporan. Untuk detailnya, lihat Pola integrasi yang direkomendasikan.

Buat dan akses eksekusi 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:

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/reporting/report_runs \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "report_type"="balance_change_from_activity.itemized.3" \
  -d "parameters[interval_start]"=1577865600 \
  -d "parameters[interval_end]"=1580544000 \
  -d "parameters[timezone]"="America/Los_Angeles" \
  -d "parameters[columns][]"="created" \
  -d "parameters[columns][]"="reporting_category" \
  -d "parameters[columns][]"="net"

# Timestamps are for 2020-01-01 00:00 PST and 2020-02-01 00:00 PST.
# The columns parameter is optional. A default set of columns will be provided if you don't specify a value.
# Note that a live-mode API key is required.

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:

Command Line
curl
No results
curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Notifikasi eksekusi 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 respons 500.)

Dalam kedua kasus tersebut, payload webhook menyertakan objek ReportRun yang diperbarui, yang masing-masing berisi status succeeded atau failed.

Kesalahan umum

Laporan yang Anda jalankan dari Dashboard tidak memicu peristiwa webhook pelaporan.

Pola integrasi pelaporan otomatis

Konfigurasikan webhook yang secara eksplisit memilih untuk menerima peristiwa reporting.report_type.updated. Webhook yang mendengarkan all events tidak akan menerimanya.

Catatan

Jika Anda menggunakan sandbox, Anda tidak akan menerima kejadian reporting.report_type.updated.

  1. Webhook reporting.report_type.updated dikirim segera setelah data hari baru tersedia untuk tipe laporan tertentu. Payload menyertakan objek ReportType 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.)

  2. Saat menerima webhook reporting.report_type.updated untuk tipe laporan yang diinginkan dan rentang ketersediaan data, lakukan pembuatan laporan. Tanggapan berisi objek ReportRun baru, yang diprakarsai dengan status=pending.

  3. Bila selesai dijalankan, webhook reporting.report_run.succeeded akan dikirim. Webhook ini menyertakan bidang result.url tersarang. (Seperti disebutkan di atas, dalam kasus kegagalan yang jarang terjadi, kami akan mengirimkan kejadian reporting.report_run.failed sebagai gantinya.)

  4. Akses konten file di result.url, menggunakan kunci API Anda.

Stripe memantau proses laporan secara bersamaan untuk setiap akun. Untuk melindungi infrastruktur kami dan memastikan kualitas layanan semua pengguna, kami mungkin membatasi permintaan jika terlalu banyak laporan yang berjalan secara bersamaan. Jika Anda mengalami kesalahan batas kecepatan (HTTP 429), tunggu hingga beberapa proses laporan yang tertunda selesai sebelum meminta laporan baru.