وثائق Ecord API

نظرة سريعة

العنوان الأساسي للـAPI:

https://api.ecord.app/api/public/v1

• كل الطلبات والردود بصيغة JSON (UTF-8).
• كل مفتاح معزول تماماً داخل مؤسسة واحدة — لا يرى ولا يؤثّر إلا على بيانات مؤسستك.
• المرجع التفاعلي الكامل (كل المسارات والحقول + «جرّبها الآن») على docs.ecord.app/reference.

المصادقة — كيف تحصل على مفتاح API؟

1. ادخل لوحة التحكم على app.ecord.app بحساب مدير المؤسسة.
2. اذهب إلى الإعدادات ← مفاتيح API.
3. اضغط إنشاء مفتاح، اختر الصلاحيات (scopes) المطلوبة، ثم احفظ.
4. ⚠️ المفتاح الكامل يظهر مرة واحدة فقط عند الإنشاء. انسخه وخزّنه بأمان — لا يمكن استرجاعه لاحقاً (يُخزَّن مُشفّراً). لو ضاع، ألغِه وأنشئ غيره.

إرسال المفتاح مع كل طلب

بأي من الطريقتين:

Authorization: Bearer <API_KEY>
# أو
X-API-Key: <API_KEY>

اختبار سريع

curl https://api.ecord.app/api/public/v1/ping \
  -H "Authorization: Bearer <API_KEY>"

# 200 OK
# { "ok": true, "tenant_id": "...", "scopes": ["orders:read", ...] }

الصلاحيات (scopes)

كل مفتاح يُمنح صلاحية أو أكثر. الطلب على مسار بدون الصلاحية المطلوبة يرجع 403.

الأسطح

التفاصيل الكاملة لكل حقل ومَعامِل في المرجع التفاعلي.

أمثلة عملية

1) متجر يزامن عملاءه ومنتجاته

أنشئ/حدّث عميلاً (idempotent — لو موجود بنفس external_id أو الهاتف يُدمج):

curl -X POST https://api.ecord.app/api/public/v1/customers \
  -H "Authorization: Bearer <KEY>" -H "Content-Type: application/json" \
  -d '{
    "external_id": "shopify-88",
    "external_platform": "shopify",
    "name": "أحمد علي",
    "phone": "201000000000"
  }'

أنشئ/حدّث منتجاً:

curl -X POST https://api.ecord.app/api/public/v1/products \
  -H "Authorization: Bearer <KEY>" -H "Content-Type: application/json" \
  -d '{ "external_id": "sku-123", "name": "قميص", "sku": "SH-123", "price": "250.00" }'

2) شركة شحن تحدّث حالة الطلبات

تُنشئ المؤسسة «شركة شحن» من الإعدادات ← مفاتيح API ← شركة شحن جديدة، فينتج مفتاح بصلاحية delivery:write. الشركة ترى فقط الطلبات التي سُلّمت لها عهدةً:

# الطلبات المسلَّمة للشركة
curl https://api.ecord.app/api/public/v1/driver/orders \
  -H "Authorization: Bearer <COMPANY_KEY>"

# تحديث الحالة
curl -X PATCH https://api.ecord.app/api/public/v1/driver/orders/<id>/status \
  -H "Authorization: Bearer <COMPANY_KEY>" -H "Content-Type: application/json" \
  -d '{ "status": "out_for_delivery" }'

# تأكيد التسليم (تحصيل نقدي)
curl -X POST https://api.ecord.app/api/public/v1/driver/orders/<id>/deliver \
  -H "Authorization: Bearer <COMPANY_KEY>" -H "Content-Type: application/json" \
  -d '{ "type": "full" }'

3) نظام محاسبي يصدّر المبيعات

فاتورة المبيعات = ما تم تحصيله فعلاً للتاجر (من المناديب أو شركات الشحن، موحّد). فلترة بتاريخ التحصيل:

curl "https://api.ecord.app/api/public/v1/sales-invoices?date_from=2026-07-01&date_to=2026-07-31&limit=100" \
  -H "Authorization: Bearer <KEY>"

# تفاصيل فاتورة (رأس + بنود فرعية لكل طلب: الإجمالي، العمولة، الصافي)
curl https://api.ecord.app/api/public/v1/sales-invoices/<id> \
  -H "Authorization: Bearer <KEY>"

Webhooks

بدل الاستعلام المتكرر، اشترك في الأحداث لتصلك رسالة POST على رابطك فور حدوث الحدث. تُدار من الإعدادات ← Webhooks.

أهم الأحداث

عند تغيّر الحالة نرسل الحدثين معاً: العام order.status_changed والمحدّد (مثل order.delivered).

التحقق من التوقيع

كل رسالة تحمل ترويسات X-Ecord-Event وX-Ecord-Delivery وX-Ecord-Signature. التوقيع هو "sha256=" + HMAC_SHA256(secret, raw_body):

import hmac, hashlib

def verify(raw_body: bytes, header_sig: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_sig or "")

• ردّ بـ 2xx بسرعة (خلال ~10 ثوانٍ).
• الفشل/التأخّر يُعاد بتراجع أُسّي (حتى 6 محاولات).
• التسليم at-least-once: قد يصل الحدث أكثر من مرة — أزِل التكرار باستخدام X-Ecord-Delivery.

الأخطاء

جسم الخطأ بالشكل { "detail": "..." }.