انتقل إلى المحتوى
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» ولمفاتيح API ذات النطاق read (وكما في السابق، للمفاتيح ذات النطاق write).

المصادقة

أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.

معاملات الترويسة

  • X-View-Asstring

    لمفاتيح API ذات الدور admin فقط. ينفّذ الطلب بصفة ملف تعريف البيانات <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 (وpaid مع payments).

  • 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، إضافةً إلى الرموز العامة لكل طلب.

إعادة المحاولة بأمان

أرسل الترويسة Idempotency-Key (قيمة UUID مثلًا) مع كل طلب POST وPATCH. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة المحفوظة بدل تنفيذ الطلب مرة أخرى.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← finance · مرجع API