انتقل إلى المحتوى
جديدالمرحلة الثانية من الفوترة الإلكترونية أصبحت مدمجة في النظام
Tapat.link

// مرجع الواجهة البرمجية

واجهة Tapat.link البرمجية

كل مستند في Tapat.link متاح عبر واجهة REST آمنة وواضحة. استخدمها لربط المتاجر والبنوك وشركات الشحن وتطبيقاتك الخاصة.

العنوان الأساسيhttps://<company>.tapat.link/api

المصادقة

صادِق كل طلب بمفتاح ورمز سري يُنشآن لكل مستخدم من الإعدادات ← الوصول البرمجي. تُنفَّذ الطلبات بصلاحيات ذلك المستخدم، لذا أنشئ مستخدمًا مخصصًا للتكامل بالأدوار التي يحتاجها فقط.

Verify your credentials
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}حذف سجل مسودة
Get a sales invoice
curl "https://acme.tapat.link/api/resource/Sales%20Invoice/INV-2026-01842" \  -H "Authorization: token $API_KEY:$API_SECRET"
Create a customer
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" }'
Update a customer
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 }'
Delete a draft item
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 unpaid invoices
# 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 ساعة.

Example payload
{  "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 response
{  "error": {    "status": 422,    "code": "validation_error",    "message": "Customer tax ID must be 15 digits",    "field": "tax_id"  }}
الحالةالمعنى
400طلب غير صحيح الصيغة
401بيانات اعتماد مفقودة أو غير صحيحة
403المستخدم لا يملك صلاحية هذا الإجراء
404السجل غير موجود
422فشل التحقق من البيانات
429تجاوز حد الاستخدام