İçeriğe geç
Sursa Developers

POST/v1/finance/report

Finansal özet raporunu getirme

finance_report

Kuruluşun faturalarının ya da ödemelerinin toplamlarını, en fazla üç boyuta (kategori, grup, tedarikçinin faaliyet türü, tedarikçi, alıcı, karşı taraf, yön, para birimi, ay, çeyrek, yıl) göre gruplandırılmış olarak invoiced, paid, unpaid ve tax ölçüleriyle döndürür. Toplamlar yalnızca kullanıcıya görünen belgeleri içerir (veri profilinin koleksiyonları ve kategorileri ile “answer only from verified cards” (yalnızca doğrulanmış kartlardan yanıt ver) ayarı); istek filtreleri bu sınırı daraltır ama hiçbir zaman genişletmez.

reporting modunda (varsayılan) tutarlar belge tarihindeki kurla kuruluşun raporlama para birimine çevrilir; kuru olmayan tutarlar conversion.unconverted içinde listelenir. original modunda farklı para birimlerindeki tutarlar toplanmaz ve para birimi satırın bir boyutu olur. Satır sayısı limit değerinden fazlaysa truncated değeri true olur ve totals yine tüm satırları kapsar. Finansal verilere erişimi olan bir veri profili gerektirir (finance.forbidden).

Rapor, fatura ve ödeme listeleri ve bunların dışa aktarmaları POST kullansalar da okuma işlemleridir: “View as” modunda ve read kapsamına sahip API anahtarlarına (ve önceden olduğu gibi write kapsamına sahip anahtarlara) açıktır.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Başlık parametreleri

  • X-View-Asstring

    Yalnızca admin rolündeki API anahtarları için. İsteği <profile>[:viewer|verifier|editor] veri profili adına yapar, örneğin employee:viewer. Kurulum anahtarı bu başlığı kullanamaz (403).

Çerez parametreleri

  • kb_view_asstring

    Bir oturum için “View as” modunun (başka bir kullanıcı gibi görüntüleme) çerezi. POST /auth/view-as bu çerezi ayarlar, DELETE /auth/view-as temizler.

İstek gövdesi

application/json

Nesne: FinanceReportRequest

  • basisstring

    invoices: faturalar, iade faturaları ve makbuzlar. payments: ödeme günlüğü (nakit akışı). payments ile tek ölçü paid olur; direction boyutu ve toplam, para hareketini in ya da out olarak gösterir, kendi tüzel kişileriniz arasındaki bir aktarım ise internal olur.

    Geçerli değerler: invoicespayments

    Varsayılan: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Varsayılan: invoiced (payments için paid).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Dönemi ve from/to filtresini hangi tarihin belirlediği: belge tarihi ya da ödeme tarihi.

    Geçerli değerler: documentpayment

    Varsayılan: "document"

  • filtersFinanceFilter
  • order_bystring

    Sıralamada kullanılacak ölçü ya da boyut. Varsayılan olarak ilk ölçü, azalan sırada.

  • order_descboolean

    Varsayılan: true

  • limitinteger

    Varsayılan: 1000≥ 1, ≤ 10000

  • languagestring

    Kategori ve grup adlarının dili, en|ru. Varsayılan: en.

Yanıtlar

200Rapor

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: FinanceReport

  • currency_modeFinanceCurrencyModezorunlu
  • currencystring

    Raporlama para birimi (reporting modu).

  • rowsarray of FinanceReportRowzorunlu
  • totalsarray of FinanceReportTotalzorunlu

    Kırpmadan önce tüm satırların toplamları, para birimi başına bir kayıt (yöne göre bölünmüş bir raporda para birimi ve yön başına, FinanceReportTotal.direction).

  • truncatedbooleanzorunlu
  • limitintegerzorunlu
  • total_rowsintegerzorunlu

    Kırpmadan önceki gruplanmış satır sayısı.

  • conversionFinanceConversion
  • warningsarray of string

    Uyarı kodları: profile_missing, kuruluşun şirket bilgileri girilmemiş, bu yüzden fatura yönü varsayılan olarak in; catalog_missing, şirket rehberi yüklenmemiş; fx_rate_missing, bazı tutarların döviz kuru yok (conversion.unconverted); fx_rate_stale, bazı kurlar güncel değil; enrichment_pending, bazı belgeler hâlâ işleniyor ve toplamlara dahil değil. Bilinmeyen bir kodu genel bir iletiyle gösterin.

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

  • Retry-After

    İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

503Bu isteğin bağlı olduğu bir hizmet geçici olarak kullanılamıyor. Daha sonra yeniden deneyin.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← finance · API başvurusu