Jalankan laporan dari API

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 mengunduh laporan dalam zona waktu untuk ReportType dengan parameter timezone. Guna melakukannya, buat objek ReportRun dan berikan nama zona waktu database TZ yang diinginkan. Parameter timezone bersifat opsional serta default terhadap UTC jika tidak diberikan. Lihat Database 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 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 respons 500.)

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 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.)
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.
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.)
Akses konten file di result.url, menggunakan kunci API Anda.