मुख्य कंटेंट पर जाएँ
Sursa Developers

POST/v1/finance/report

वित्तीय सारांश रिपोर्ट पाएँ

finance_report

संगठन के इनवॉइस या भुगतानों का योग लौटाता है, तीन तक आयामों (कैटेगरी, ग्रुप, सप्लायर के कारोबार का टाइप, सप्लायर, ख़रीदार, काउंटरपार्टी, दिशा, करेंसी, महीना, तिमाही, साल) के अनुसार ग्रुप करके, invoiced, paid, unpaid और tax मापों के साथ। योग में सिर्फ़ यूज़र को दिखने वाले दस्तावेज़ शामिल होते हैं (उसकी डेटा प्रोफ़ाइल के कलेक्शन और कैटेगरी, और “सिर्फ़ सत्यापित कार्ड से जवाब दें” सेटिंग); रिक्वेस्ट के फ़िल्टर इस दायरे को छोटा करते हैं, पर कभी बड़ा नहीं करते।

reporting मोड (डिफ़ॉल्ट) में रक़में दस्तावेज़ की तारीख़ की दर पर संगठन की रिपोर्टिंग करेंसी में बदली जाती हैं, और बिना दर वाली रक़में conversion.unconverted में दी जाती हैं। original मोड में अलग-अलग करेंसी की रक़में जोड़ी नहीं जातीं, और करेंसी पंक्ति का आयाम बन जाती है। अगर पंक्तियाँ limit से ज़्यादा हैं, तो truncated true होता है, और totals फिर भी सभी पंक्तियों को कवर करते हैं। वित्तीय डेटा के ऐक्सेस वाली डेटा प्रोफ़ाइल चाहिए (finance.forbidden)।

रिपोर्ट, इनवॉइस और भुगतानों की सूचियाँ और उनके एक्सपोर्ट पढ़ने वाले ऑपरेशन हैं, भले ही वे POST इस्तेमाल करते हैं: ये “View as” मोड में और read स्कोप वाली API कुंजियों के लिए उपलब्ध हैं (और, पहले की तरह, write स्कोप वाली कुंजियों के लिए भी)।

ऑथेंटिकेशन

Authorization हेडर में API कुंजी भेजें: Authorization: Bearer <कुंजी>।

हेडर पैरामीटर

  • X-View-Asstring

    सिर्फ़ admin रोल वाली API कुंजियों के लिए। रिक्वेस्ट को डेटा प्रोफ़ाइल <profile>[:viewer|verifier|editor] की ओर से चलाता है, जैसे employee:viewer। इंस्टॉलेशन कुंजी इस हेडर का इस्तेमाल नहीं कर सकती (403)।

कुकी पैरामीटर

  • kb_view_asstring

    सेशन के लिए “View as” मोड की कुकी। POST /auth/view-as इसे सेट करता है और DELETE /auth/view-as हटाता है।

रिक्वेस्ट बॉडी

application/json

ऑब्जेक्ट: FinanceReportRequest

  • basisstring

    invoices: इनवॉइस, क्रेडिट नोट और रसीदें। payments: भुगतान लॉग (नक़दी का प्रवाह)। payments के साथ इकलौता माप paid है, और आयाम direction और कुल योग पैसे की आवाजाही दिखाते हैं, in या out, जबकि आपकी अपनी क़ानूनी इकाइयों के बीच का ट्रांसफ़र internal होता है।

    मान्य मान: invoicespayments

    डिफ़ॉल्ट: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    डिफ़ॉल्ट invoiced है (payments के लिए paid)।

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    कौन-सी तारीख़ अवधि और from/to फ़िल्टर तय करती है: दस्तावेज़ की तारीख़ या भुगतान की तारीख़।

    मान्य मान: documentpayment

    डिफ़ॉल्ट: "document"

  • filtersFinanceFilter
  • order_bystring

    वह माप या आयाम, जिससे सॉर्ट करना है। डिफ़ॉल्ट रूप से पहला माप, घटते क्रम में।

  • order_descboolean

    डिफ़ॉल्ट: true

  • limitinteger

    डिफ़ॉल्ट: 1000≥ 1, ≤ 10000

  • languagestring

    कैटेगरी और ग्रुप के लेबल की भाषा, en|ru। डिफ़ॉल्ट en है।

रिस्पॉन्स

200रिपोर्ट

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: FinanceReport

  • currency_modeFinanceCurrencyModeज़रूरी
  • currencystring

    रिपोर्टिंग करेंसी (मोड reporting)।

  • rowsarray of FinanceReportRowज़रूरी
  • totalsarray of FinanceReportTotalज़रूरी

    काटने से पहले की सभी पंक्तियों के कुल योग, हर करेंसी के लिए एक रिकॉर्ड (दिशा के हिसाब से बँटी रिपोर्ट में हर करेंसी और दिशा के लिए, FinanceReportTotal.direction)।

  • truncatedbooleanज़रूरी
  • limitintegerज़रूरी
  • total_rowsintegerज़रूरी

    काटने से पहले ग्रुप की गई पंक्तियों की संख्या।

  • conversionFinanceConversion
  • warningsarray of string

    चेतावनी के कोड: profile_missing: संगठन की कंपनी का ब्योरा सेट नहीं है, इसलिए इनवॉइस की दिशा डिफ़ॉल्ट रूप से in है; catalog_missing: कंपनी डायरेक्टरी लोड नहीं हुई है; fx_rate_missing: कुछ राशियों की विनिमय दर नहीं है (conversion.unconverted); fx_rate_stale: कुछ दरें पुरानी हैं; enrichment_pending: कुछ दस्तावेज़ अभी प्रोसेस हो रहे हैं और कुल योग में शामिल नहीं हैं। अज्ञात कोड को सामान्य संदेश के साथ दिखाएँ।

400रिक्वेस्ट अमान्य है: पैरामीटर का मान या ऑब्जेक्ट की स्थिति यह कार्रवाई करने नहीं देती (`detail` एक संदेश है)।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

401कोई क्रेडेंशियल नहीं भेजा गया (न सेशन कुकी, न API कुंजी), या कुंजी नहीं मिली।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

403कार्रवाई की अनुमति नहीं है: रोल काफ़ी नहीं है, कलेक्शन या कार्ड तक ऐक्सेस नहीं है, रिक्वेस्ट “View as” मोड में चल रही है, या संगठन निलंबित है या हटा दिया गया है (`detail` एक ऑब्जेक्ट है, जिसमें `code: org_suspended | org_deleted` है)।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

429बहुत ज़्यादा रिक्वेस्ट (`api.rate_limited`), संगठन का मिनट, दिन या महीने का कोटा ख़त्म हो गया है (`api.quota_exceeded`; `error.details` में `quota`, `limit` और `reset_at` होते हैं), संगठन की सीमा पूरी हो गई है, या जवाब देने वाली सर्विस व्यस्त है (`answers.engine_busy`)। `Retry-After` हेडर में दिए गए समय तक इंतज़ार करें।

रिस्पॉन्स हेडर

  • Retry-After

    रिक्वेस्ट का रीट्राई करने से पहले कितने सेकंड इंतज़ार करना है।

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

503वह सर्विस, जिस पर यह रिक्वेस्ट निर्भर है, कुछ समय के लिए उपलब्ध नहीं है। बाद में फिर से कोशिश करें।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

एरर कोड

हर रिक्वेस्ट के सामान्य कोड के अलावा वे कोड, जो यह एंडपॉइंट एरर होने पर error.code में लौटा सकता है।

सुरक्षित रीट्राई

हर POST और PATCH के साथ Idempotency-Key हेडर भेजें (उदाहरण के लिए, UUID)। 24 घंटे के अंदर उसी कुंजी के साथ रीट्राई करने पर रिक्वेस्ट दोबारा नहीं चलती, बल्कि सेव किया गया रिस्पॉन्स लौटता है।

रेट लिमिट

रिस्पॉन्स में RateLimit और RateLimit-Policy हेडर होते हैं, और पहले वाले X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset भी। 429 रिस्पॉन्स में Retry-After सेकंड में होता है: उतना इंतज़ार करें और रीट्राई करें।

← finance · API रेफ़रेंस