Langsung ke konten
Sursa Developers

POST/v1/finance/report

Dapatkan laporan ringkasan keuangan

finance_report

Mengembalikan total faktur atau pembayaran organisasi, dikelompokkan menurut hingga tiga dimensi (kategori, grup, jenis usaha pemasok, pemasok, pembeli, pihak lawan transaksi, arah, mata uang, bulan, kuartal, tahun), dengan metrik invoiced, paid, unpaid, dan tax. Total hanya mencakup dokumen yang terlihat oleh pengguna (koleksi dan kategori profil datanya, serta pengaturan “jawab hanya dari kartu terverifikasi”); filter permintaan mempersempit cakupan ini tetapi tidak pernah memperluasnya.

Dalam mode reporting (default), jumlah dikonversi ke mata uang pelaporan organisasi dengan kurs pada tanggal dokumen, dan jumlah tanpa kurs dicantumkan di conversion.unconverted. Dalam mode original, jumlah dalam mata uang yang berbeda tidak dijumlahkan, dan mata uang menjadi dimensi baris. Jika jumlah baris melebihi limit, truncated bernilai true, dan totals tetap mencakup semua baris. Memerlukan profil data dengan akses ke data keuangan (finance.forbidden).

Laporan, daftar faktur dan pembayaran, serta ekspornya adalah operasi baca meskipun memakai POST: semuanya tersedia dalam mode “View as” dan bagi kunci API dengan cakupan read (dan, seperti sebelumnya, bagi kunci dengan cakupan write).

Autentikasi

Kirim kunci API di header Authorization: Authorization: Bearer <kunci>.

Parameter header

  • X-View-Asstring

    Hanya untuk kunci API dengan peran admin. Menjalankan permintaan sebagai profil data <profile>[:viewer|verifier|editor], misalnya employee:viewer. Kunci instalasi tidak dapat memakai header ini (403).

Parameter cookie

  • kb_view_asstring

    Cookie mode “View as” (Lihat sebagai) untuk sesi. POST /auth/view-as menetapkannya dan DELETE /auth/view-as menghapusnya.

Isi permintaan

application/json

Objek: FinanceReportRequest

  • basisstring

    invoices: faktur, nota kredit, dan kuitansi. payments: log pembayaran (arus kas). Dengan payments, satu-satunya metrik adalah paid, sedangkan dimensi direction dan totalnya menunjukkan pergerakan uang, in atau out, dan transfer antar-badan hukum Anda sendiri adalah internal.

    Nilai yang diizinkan: invoicespayments

    Default: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Default: invoiced (paid untuk payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Tanggal mana yang menentukan periode dan filter from/to: tanggal dokumen atau tanggal pembayaran.

    Nilai yang diizinkan: documentpayment

    Default: "document"

  • filtersFinanceFilter
  • order_bystring

    Metrik atau dimensi untuk pengurutan. Secara default, metrik pertama dalam urutan menurun.

  • order_descboolean

    Default: true

  • limitinteger

    Default: 1000≥ 1, ≤ 10000

  • languagestring

    Bahasa label kategori dan grup, en|ru. Default: en.

Respons

200Laporan

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: FinanceReport

  • currency_modeFinanceCurrencyModewajib
  • currencystring

    Mata uang pelaporan (mode reporting).

  • rowsarray of FinanceReportRowwajib
  • totalsarray of FinanceReportTotalwajib

    Total atas semua baris sebelum dipangkas, satu catatan per mata uang (untuk laporan yang dipisah menurut arah, per mata uang dan arah, FinanceReportTotal.direction).

  • truncatedbooleanwajib
  • limitintegerwajib
  • total_rowsintegerwajib

    Jumlah baris yang dikelompokkan sebelum dipangkas.

  • conversionFinanceConversion
  • warningsarray of string

    Kode peringatan: profile_missing, data perusahaan organisasi belum diisi, sehingga arah faktur default-nya in; catalog_missing, direktori perusahaan belum dimuat; fx_rate_missing, sebagian jumlah tidak memiliki kurs (conversion.unconverted); fx_rate_stale, sebagian kurs sudah usang; enrichment_pending, sebagian dokumen masih diproses dan belum masuk ke total. Tampilkan kode yang tidak dikenal dengan pesan umum.

400Permintaan tidak valid: nilai parameter atau status objek tidak memungkinkan tindakan ini (`detail` berisi pesan).

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

401Kredensial tidak dikirim (baik cookie sesi maupun kunci API), atau kunci tidak ditemukan.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

403Tindakan tidak diizinkan: peran tidak memadai, tidak ada akses ke koleksi atau kartu, permintaan berjalan dalam mode “View as”, atau organisasi ditangguhkan atau dihapus (`detail` adalah objek dengan `code: org_suspended | org_deleted`).

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

429Terlalu banyak permintaan (`api.rate_limited`), kuota organisasi untuk menit, hari, atau bulan sudah habis (`api.quota_exceeded`; `error.details` berisi `quota`, `limit`, dan `reset_at`), batas organisasi tercapai, atau layanan jawaban sedang sibuk (`answers.engine_busy`). Tunggu selama waktu di header `Retry-After`.

Header respons

  • Retry-After

    Jumlah detik yang perlu ditunggu sebelum Anda mencoba ulang permintaan.

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

503Layanan yang dibutuhkan permintaan ini untuk sementara tidak tersedia. Coba lagi nanti.

Header respons

  • RateLimit-Policy

    Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.

  • RateLimit

    Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).

  • X-RateLimit-Remaining

    Sisa permintaan dalam batas paling ketat.

  • X-RateLimit-Reset

    Detik hingga batas paling ketat direset.

application/json

Objek: Error

Kode error

Kode yang dapat dikembalikan endpoint ini di error.code, selain kode umum yang berlaku untuk setiap permintaan.

Percobaan ulang yang aman

Kirim header Idempotency-Key (misalnya UUID) bersama setiap POST dan PATCH. Percobaan ulang dengan kunci yang sama dalam 24 jam mengembalikan respons yang tersimpan alih-alih menjalankan permintaan lagi.

Batas laju

Respons berisi header RateLimit dan RateLimit-Policy serta header lama X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Respons 429 berisi Retry-After dalam detik: tunggu, lalu coba lagi.

← finance · Referensi API