مرجع REST API

استخدم REST API v1 من الخادم فقط. لا تدعم صلة استخدام مفاتيح API طويلة العمر من المتصفح أو تطبيقات الجوال في هذا الإصدار.

المصادقة

أرسل المفتاح عبر ترويسة Authorization بصيغة Bearer. استخدم مفاتيح منفصلة لبيئات الاختبار والإنتاج عند الإمكان.

bash
curl https://your-convex-site.convex.site/api/v1/conversations \
  -H "Authorization: Bearer sk_live_..."

النقاط المدعومة

GET

/api/v1/conversations

يعرض قائمة محادثات المؤسسة. يتطلب الصلاحية conversations:read.

bash
curl "https://your-convex-site.convex.site/api/v1/conversations?limit=25&status=open" \
  -H "Authorization: Bearer sk_live_..."
GET

/api/v1/messages

يعرض رسائل محادثة محددة. يتطلب الصلاحية messages:read ومعامل conversation_id.

bash
curl "https://your-convex-site.convex.site/api/v1/messages?conversation_id=jt7..." \
  -H "Authorization: Bearer sk_live_..."
GET

/api/v1/orders

يعرض طلبات المطاعم التي أنشأتها صلة. يتطلب الصلاحية orders:read ويدعم status بقيم pending و approved و arrived و rejected و failed و cancelled و all.

bash
curl "https://your-convex-site.convex.site/api/v1/orders?status=pending&limit=25" \
  -H "Authorization: Bearer sk_live_..."
POST

/api/v1/orders/action

يوافق على الطلب، يرفضه، أو يضعه كواصل. يتطلب الصلاحية orders:write. ترسل صلة رسائل الموافقة والرفض للعميل.

bash
curl "https://your-convex-site.convex.site/api/v1/orders/action" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "toolExecutions:...",
    "action": "approve",
    "external_order_id": "menu-123"
  }'

الترقيم

جميع نقاط القراءة تدعم limit و cursor وتعيد next_cursor و is_done داخل meta.

json
{
  "data": [],
  "meta": {
    "request_id": "c6f1...",
    "next_cursor": "eyJ...",
    "is_done": false,
    "limit": 25
  }
}

الأخطاء

تعيد جميع الاستجابات معرف طلب في الترويسة X-Sela-Request-Id وفي جسم الاستجابة لتسهيل التتبع.

json
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded.",
    "request_id": "c6f1..."
  }
}