// مرجع الواجهة البرمجية
واجهة Tapat.link البرمجية
كل مستند في Tapat.link متاح عبر واجهة REST آمنة وواضحة. استخدمها لربط المتاجر والبنوك وشركات الشحن وتطبيقاتك الخاصة.
https://<company>.tapat.link/apiالمصادقة
صادِق كل طلب بمفتاح ورمز سري يُنشآن لكل مستخدم من الإعدادات ← الوصول البرمجي. تُنفَّذ الطلبات بصلاحيات ذلك المستخدم، لذا أنشئ مستخدمًا مخصصًا للتكامل بالأدوار التي يحتاجها فقط.
curl "https://acme.tapat.link/api/method/ping" \ -H "Authorization: token $API_KEY:$API_SECRET"احفظ الرمز السري على الخادم فقط، ولا تضمّنه أبدًا في متصفح أو تطبيق جوال.
الموارد
كل نوع مستند يمثّل موردًا، وتتبع النقاط الطرفية القياسية النمط نفسه لجميع الموارد:
| الطريقة | النقطة الطرفية | الوصف |
|---|---|---|
| GET | /api/resource/{doctype} | عرض قائمة السجلات |
| GET | /api/resource/{doctype}/{name} | جلب سجل واحد |
| POST | /api/resource/{doctype} | إنشاء سجل |
| PUT | /api/resource/{doctype}/{name} | تحديث سجل |
| DELETE | /api/resource/{doctype}/{name} | حذف سجل مسودة |
curl "https://acme.tapat.link/api/resource/Sales%20Invoice/INV-2026-01842" \ -H "Authorization: token $API_KEY:$API_SECRET"curl -X POST "https://acme.tapat.link/api/resource/Customer" \ -H "Authorization: token $API_KEY:$API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "customer_name": "Gulf Fresh Foods", "tax_id": "300987654300003" }'curl -X PUT "https://acme.tapat.link/api/resource/Customer/Gulf%20Fresh%20Foods" \ -H "Authorization: token $API_KEY:$API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "credit_limit": 250000 }'curl -X DELETE "https://acme.tapat.link/api/resource/Item/SAMPLE-ITEM" \ -H "Authorization: token $API_KEY:$API_SECRET"التصفية وتقسيم الصفحات
تقبل نقاط عرض القوائم المعاملات fields وfilters وorder_by وlimit_start وlimit_page_length. والمرشحات مصفوفات JSON بالصيغة [الحقل، المعامل، القيمة].
# List the 20 most recent unpaid invoicescurl -G "https://acme.tapat.link/api/resource/Sales%20Invoice" \ -H "Authorization: token $API_KEY:$API_SECRET" \ --data-urlencode 'fields=["name","customer","grand_total","status"]' \ --data-urlencode 'filters=[["status","=","Unpaid"]]' \ --data-urlencode 'order_by=posting_date desc' \ --data-urlencode 'limit_page_length=20'- المعاملات المتاحة: =، !=، >، <، >=، <=، like، in، not in، between
- حجم الصفحة الافتراضي 20 سجلًا والحد الأقصى 500
- استخدم limit_start للتنقل بين الصفحات
خطافات الويب
اشترك في الأحداث من الإعدادات ← خطافات الويب. يرسل Tapat.link طلب POST موقّعًا إلى عنوانك عند وقوع أي حدث، ويعيد المحاولة بفواصل متزايدة لمدة تصل إلى 24 ساعة.
{ "event": "sales_invoice.cleared", "created_at": "2026-09-28T10:42:17+03:00", "data": { "name": "INV-2026-01842", "customer": "Riyadh Build Supplies", "grand_total": 44160.0, "zatca_status": "CLEARED" }}تحقّق من الترويسة X-Signature، وهي بصمة HMAC-SHA256 للمحتوى الخام باستخدام الرمز السري لخطاف الويب، قبل الوثوق بأي بيانات.
حدود الاستخدام
تُحدَّد الطلبات لكل مفتاح، وتتضمن كل استجابة الترويستين X-RateLimit-Limit وX-RateLimit-Remaining.
| الباقة | الطلبات في الدقيقة |
|---|---|
| الأساسية | 60 (قراءة فقط) |
| الأعمال | 300 |
| المؤسسات | حسب الاتفاق |
الأخطاء
تستخدم الأخطاء رموز حالة HTTP القياسية مع محتوى JSON موحّد.
{ "error": { "status": 422, "code": "validation_error", "message": "Customer tax ID must be 15 digits", "field": "tax_id" }}| الحالة | المعنى |
|---|---|
| 400 | طلب غير صحيح الصيغة |
| 401 | بيانات اعتماد مفقودة أو غير صحيحة |
| 403 | المستخدم لا يملك صلاحية هذا الإجراء |
| 404 | السجل غير موجود |
| 422 | فشل التحقق من البيانات |
| 429 | تجاوز حد الاستخدام |