# Cara kerja API Laporan Akses laporan keuangan Stripe secara programatis untuk mengotomatiskan alur kerja rekonsiliasi Anda. > Sekarang Anda dapat secara otomatis mengirim laporan dan data Stripe ke Snowflake atau Amazon Redshift dalam beberapa klik dengan Stripe Data Pipeline. [Pelajari selengkapnya](https://stripe.com/data-pipeline). [Laporan keuangan](https://dashboard.stripe.com/reports) 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: - [Saldo](https://docs.stripe.com/reports/report-types/balance.md) - [Rekonsiliasi payout](https://docs.stripe.com/reports/report-types/payout-reconciliation.md) - [Tipe laporan biaya](https://docs.stripe.com/reports/report-types/fees.md) - [Pajak](https://docs.stripe.com/reports/report-types/tax.md) - [Platform Connect](https://docs.stripe.com/reports/report-types/connect.md) > #### 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](https://www.iana.org/time-zones) 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](https://docs.stripe.com/reports/options.md#data-availability) 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](https://docs.stripe.com/api.md#retrieve_reporting_report_type) si `ReportType` objek yang menarik. Misalnya, laporan **Ringkasan saldo** memiliki ID `balance.summary.1`, sehingga Anda dapat mengambil objek sebagai berikut: #### curl ```bash curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u <>: ``` 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: ```json { "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](https://docs.stripe.com/webhooks.md#register-webhook) 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](https://docs.stripe.com/connect/webhooks.md). Setelah menerima acara, Anda dapat menjalankan laporan. Untuk detailnya, lihat [Pola integrasi yang direkomendasikan](https://docs.stripe.com/reports/api.md#integration-pattern). ## Buat dan akses eksekusi laporan Objek `ReportRun` API mewakili instance `ReportType` yang dihasilkan dengan parameter tertentu. Tinjau dokumentasi untuk [tipe laporan](https://docs.stripe.com/reports/api.md#report-types) bagi daftar parameter wajib dan opsional untuk tipe tersebut. Misalnya, Anda dapat [membuat](https://docs.stripe.com/api/reporting/report_run/create.md) laporan **Perubahan saldo dari ringkasan aktivitas** untuk April 2020 sebagai berikut: #### curl ```bash curl https://api.stripe.com/v1/reporting/report_runs \ -u <>: \ -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"`: ```json { "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](https://docs.stripe.com/api/reporting/report_run/retrieve.md) pembuatan laporan di atas setelah selesai, responsnya adalah: ```json { "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`: #### curl ```bash curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u <>: ``` ### 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`. > 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. > Jika Anda menggunakan [sandbox](https://docs.stripe.com/sandboxes.md), 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.) 1. Saat menerima webhook `reporting.report_type.updated` untuk tipe laporan yang diinginkan dan rentang ketersediaan data, [lakukan pembuatan laporan](https://docs.stripe.com/api/reporting/report_run/create.md). Tanggapan berisi objek `ReportRun` baru, yang diprakarsai dengan `status=pending`. 1. 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.) 1. 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.