OFFICIAL SANDBOX

جرّب الربط على بيئة HARPLINK التجريبية

https://demo.harplink.net ↗ · اسم المستخدم: demo · كلمة المرور: demo

بيئة مشتركة للفحص ببيانات تجريبية. تظهر نتائج عمليات الكتابة داخل ERP وقد يغيّرها مستخدمون آخرون؛ استخدم بيانات وهمية. كل طلب API يتطلب توكناً والصلاحيات اللازمة. لربط شركة فعلية غيّر عنوان ERP واستخدم حسابها المخوّل.

اختر العملية وافحصها من المتصفح ←

API REFERENCE

مرجع واضح. تكامل أسرع.

ابدأ بالمصادقة، تعرّف على سياق الشركة، ثم استخدم واجهات المنصة لبناء تكامل يمكن الاعتماد عليه.

استكشف ERP API دليل الإضافات

v1واجهات التكامل15مسار في المرجعScopedمصادقة وحماية الطلبات

المصادقة وسياق الوصول

Authorization: HarplinkPlugin <client-id>.<secret>
X-Harplink-Branch-ID: <allowed-branch-id>
Content-Type: application/json

الشركة تأتي من اعتماد العميل، والفرع من الترويسة ضمن الشركة والفروع المسموحة. بعض العمليات المالية تتطلب فرعاً. يجب توفر scope المطلوب وصلاحية مستخدم الخدمة معاً؛ منح scope وحده لا يمنح صلاحية ERP.

المدير يصدر السر مرة واحدة بالأمر التالي بعد plugins sync. لا تضعه في تطبيق متصفح أو تطبيق جوال أو مستودع الكود.

python manage.py plugin_api_client create \
  --plugin example_notes --name "Integration" \
  --username service_user --company-id 1 --branch-id 1 \
  --scope platform.context.read

دورة الاعتماد: plugin_api_client list ثم rotate أو revoke مع --client-id. النطاقات تُحدد عند الإنشاء حسب حاجة التكامل.

ابحث في المسارات والصلاحيات والحقول

GET/api/platform/v1/capabilities/

capabilities

نطاقات الوصول: مصادقة مطلوبة دون scope إضافي

GET/api/platform/v1/context/

context

Stable, read-only context contract for trusted external plugins.

نطاقات الوصول: platform.context.read

POST/api/platform/v1/permissions/check/

permission-check

Batch permission check without exposing permission database models.

نطاقات الوصول: platform.permissions.check

حقول JSON

الحقل	النوع	مطلوب	القيود
`codes`	List	نعم

GET/api/platform/v1/accounts/choices/

account-choices

Tenant-safe posting account choices for installed plugins.

نطاقات الوصول: accounts.chart.read

حقول الاستعلام

الحقل	النوع	مطلوب	القيود
`type`	MultipleChoice	لا	ASSET, LIABILITY, EQUITY, REVENUE, COGS, EXPENSE
`category`	MultipleChoice	لا	GENERAL, CUSTOMER, SUPPLIER, CASH, BANK, INVENTORY, EMPLOYEE
`search`	Char	لا
`ids`	List	لا

GET/api/platform/v1/accounts/cashboxes/

cashbox-choices

Cash and bank boxes visible to the actor for a requested operation.

نطاقات الوصول: accounts.cashbox.read

GET/api/platform/v1/partners/choices/

partner-choices

Tenant-safe customer, supplier, driver, and carrier lookup for plugins.

نطاقات الوصول: partners.read

حقول الاستعلام

الحقل	النوع	مطلوب	القيود
`kind`	Choice	لا	customer, supplier, both, driver, carrier
`search`	Char	لا
`ids`	List	لا
`limit`	Integer	لا	min: 1 max: 200

GET/api/platform/v1/currencies/choices/

currency-choices

Enabled currencies and the effective rate to the ERP base currency.

نطاقات الوصول: currencies.read

حقول الاستعلام

الحقل	النوع	مطلوب	القيود
`on_date`	Date	لا
`active_only`	Boolean	لا

GET/api/platform/v1/users/choices/

user-choices

Active tenant users for assignment fields exposed by installed plugins.

نطاقات الوصول: platform.users.read

حقول الاستعلام

الحقل	النوع	مطلوب	القيود
`search`	Char	لا
`limit`	Integer	لا	min: 1 max: 200

POST/api/platform/v1/notifications/send/

notification-send

نطاقات الوصول: notifications.send

حقول JSON

الحقل	النوع	مطلوب	القيود
`channel`	Choice	نعم	internal, email, sms, whatsapp
`recipient_user_id`	Integer	لا	min: 1
`recipient`	Char	لا
`title`	Char	نعم
`message`	Char	نعم
`url`	Char	لا
`reference`	Char	لا

POST/api/platform/v1/journals/

journal-create

Idempotent journal creation boundary for trusted plugins.

نطاقات الوصول: accounts.journal.write

حقول JSON

الحقل	النوع	مطلوب	القيود
`date`	Date	نعم
`currency_code`	Char	لا
`exchange_rate`	Decimal	لا
`source_type`	Regex	نعم
`source_id`	Integer	نعم	min: 1
`description`	Char	نعم
`posting_status`	Choice	لا	draft, approved, posted
`lines`	ListSerializer	نعم
`lines[].account_id`	Integer	نعم	min: 1
`lines[].debit`	Decimal	لا
`lines[].credit`	Decimal	لا
`lines[].description`	Char	لا
`lines[].cost_center_id`	Integer	لا	min: 1

POST/api/platform/v1/journals/<int:entry_id>/reverse/

journal-reverse

نطاقات الوصول: accounts.journal.reverse

حقول JSON

الحقل	النوع	مطلوب	القيود
`reason`	Char	نعم

POST/api/platform/v1/accounts/vouchers/receipts/

receipt-create

نطاقات الوصول: accounts.receipt.write

حقول JSON

الحقل	النوع	مطلوب	القيود
`date`	Date	نعم
`cashbox_id`	Integer	نعم	min: 1
`account_id`	Integer	نعم	min: 1
`amount`	Decimal	نعم	min: 0.01
`description`	Char	نعم
`source_type`	Regex	نعم
`source_id`	Integer	نعم	min: 1
`posting_status`	Choice	لا	draft, approved, posted
`cost_center_id`	Integer	لا	min: 1

POST/api/platform/v1/accounts/vouchers/payments/

payment-create

نطاقات الوصول: accounts.payment.write

حقول JSON

الحقل	النوع	مطلوب	القيود
`date`	Date	نعم
`cashbox_id`	Integer	نعم	min: 1
`account_id`	Integer	نعم	min: 1
`amount`	Decimal	نعم	min: 0.01
`description`	Char	نعم
`source_type`	Regex	نعم
`source_id`	Integer	نعم	min: 1
`posting_status`	Choice	لا	draft, approved, posted
`cost_center_id`	Integer	لا	min: 1

POST/api/platform/v1/accounts/vouchers/payments/<int:voucher_id>/reverse/

payment-reverse

Reverse a posted plugin payment with a posted counter receipt.

نطاقات الوصول: accounts.payment.reverse

حقول JSON

الحقل	النوع	مطلوب	القيود
`reason`	Char	نعم

POST/api/platform/v1/accounts/vouchers/receipts/<int:voucher_id>/reverse/

receipt-reverse

نطاقات الوصول: accounts.receipt.reverse

حقول JSON

الحقل	النوع	مطلوب	القيود
`reason`	Char	نعم

التعامل مع الاستجابات

200 للقراءة أو نتيجة موجودة، و201 لإنشاء جديد حسب المسار. استجابة context تحتوي api_version وharplink_version وuser وtenant. قوائم الاختيار تستخدم results.

400: حقول غير صحيحة أو مخالفة قواعد العملية. 401: اعتماد مفقود أو غير صالح. 403: صلاحيات غير كافية. 404: مسار أو مورد غير موجود. راجع جسم JSON لمعرفة التفاصيل.

القيد المحاسبي يتطلب سطرين على الأقل وتوازن المدين والدائن. تستخدم بعض عمليات الإنشاء source_type وsource_id للتعرف على المصدر؛ تحقق من عقد العملية قبل إعادة إرسال طلب مالي، ولا تفترض دعماً عاماً لمفتاح Idempotency-Key.