أول اتصال ناجح، خطوة بخطوة.

01 — جهّز بيئة الاتصال

بيئة الفحص الرسمية هي https://demo.harplink.net بحساب demo وكلمة مرور demo؛ بياناتها تجريبية ومشتركة. عند الربط الفعلي استخدم عنوان تثبيت ERP لدى العميل. احصل من مدير ERP على مستخدم تكامل وصلاحيات محدودة حسب الحاجة. استخدم HTTPS. لا تضع كلمة المرور أو التوكن في مستودع الكود أو سجل الأخطاء.

ERP_BASE_URL=https://demo.harplink.net
ERP_USERNAME=demo
ERP_PASSWORD=demo

المنصة هي https://staging.harplink.net؛ لكل شركة عنوان ERP مستقل يدخله المطور. اضبط ERP_DEVELOPER_CORS_ORIGINS=https://staging.harplink.net داخل كل تثبيت ERP ترغب في ربطه بالمنصة. ملفات Postman لا تتطلب CORS.

02 — احصل على التوكن

POST /api/auth/token/
Content-Type: application/json

{"username":"demo","password":"demo"}

لا يحتاج هذا الطلب توكن سابقاً. يعيد access_token وtoken_type وexpires_in وexpires_at وcompany_id وbranch_id. expires_in بالثواني. لا توجد خدمة refresh_token حالياً؛ عند الانتهاء اطلب توكناً جديداً من تسجيل الدخول.

400: صحح الحقول. 401: تحقق من بيانات الدخول وحالة المستخدم. 403: تحقق من HTTPS والشركة والفرع والترخيص. 429: انتظر مدة Retry-After قبل المحاولة.

03 — تحقق من الشركة والفرع

GET /api/auth/me/
Authorization: Bearer <access_token>

تحقق أن company_id وbranch_id يطابقان حساب العميل المتوقع قبل أي كتابة. سياق التوكن يأتي من مستخدم ERP؛ تغيير معرف في جسم الطلب لا يمنح حق الوصول إلى شركة أخرى.

04 — اقرأ أول صفحة من الفواتير

GET /sales/api/invoices/list/?page_size=25
Authorization: Bearer <access_token>

تحقق من ok ثم data وpagination. إذا has_next=true، أرسل next_cursor كمعلمة cursor في الطلب التالي. حافظ على total_bc كقيمة مالية دقيقة؛ لا تحوّلها إلى عدد عائم دون معالجة الدقة.

لا تستخدم page أو offset لهذا المسار. لا تعمم cursor على بقية APIs؛ راجع عقد كل عملية.

05 — أنشئ أو عدّل بعد مراجعة العقد

اختر عملية موثقة تحدد الحقول والصلاحيات والنتيجة، ونفذها على بيانات اختبار أولاً. لا تعِد إرسال عملية مالية بعد انقطاع الاتصال قبل التحقق هل أنشئ المستند. لا تفترض دعم Idempotency-Key في كل API.

401 يحتاج اعتماداً جديداً؛ 403 يحتاج مراجعة صلاحيات أو سياق أو ترخيص. 409 يحتاج معالجة التعارض. أخطاء 5xx لا تعني أن الكتابة لم تحدث.

06 — أنهِ الاتصال بأمان

POST /api/auth/revoke/
Authorization: Bearer <access_token>

يلغي هذا الطلب التوكن المقدم فقط. امسح النسخة المحلية منه بعد النجاح. يتوقف التوكن أيضاً عند انتهاء صلاحيته أو إيقاف المستخدم أو تغيير كلمة مروره.

الفحص من المتصفح دون تنزيل

افتح عملية من مرجع ERP API وأدخل عنوان ERP. من «الحصول على توكن من المتصفح» اضغط «استخدام حساب التجربة demo / demo»، ثم اضغط تسجيل الدخول وتجهيز التوكن. بعدها أرسل طلب القراءة من الشاشة نفسها. Postman خيار بديل، وليس شرطاً.

اختر أداة البداية

ملف Environment جاهز ببيانات demo.harplink.net وحساب demo/demo. اختره ثم نفّذ Login. عند الربط بشركة أخرى غيّر base_url وusername وpassword إلى بياناتها. اترك allow_writes=false حتى تختبر القراءة وتراجع بيانات الكتابة. لطلبات Platform API الخاصة بالإضافات، املأ plugin_authorization محلياً بالقيمة HarplinkPlugin <client-uuid>.<secret> التي يصدرها مسؤول ERP. يمكن اختيار Bearer لهذه الطلبات عند التكامل بحساب مستخدم مخوّل. أرسل القوائم بمعلمات متكررة مثل ids=12&ids=13.