البداية مع Wamia Connect

Wamia Connect هو نقطة وصول GraphQL واحدة مع ويب هوك موقّعة. ينشر المتجر منتجاته، ويبقي الأسعار والمخزون متزامنة، ويستقبل طلبات واميا ويشحنها — من منصته أو من تكامل مخصّص. ويمر كل منتج عبر خط اعتماد واميا تمامًا كما لو أُدخل يدويًا.

1. احصل على مفتاح

ينشئ المتجر مفتاحًا مخصّصًا من Wamia Shop في الإعدادات › API مع اختيار صلاحياته. يُعرض المفتاح مرة واحدة؛ خزّنه مشفّرًا. لا تطلب الموصّلات مفاتيح أبدًا: تستخدم تدفق Connect (بأسلوب OAuth مع PKCE) أو رمز اقتران من ثمانية أحرف وتتلقى مفتاحًا مرتبطًا بالمتجر.

تنتهي صلاحية المفاتيح بعد 365 يومًا. دوّرها قبل الانتهاء عبر apiRotateKey؛ يبقى المفتاح السابق صالحًا 24 ساعة.

2. اختر نقطة الوصول

يجيب الإنتاج على https://api.wamia.tn/connect/graphql، وبيئة التجربة على https://api-dev.wamia.tn/connect/graphql. المخطط نفسه في الجهتين؛ تضيف بيئة التجربة createSandboxSeller لفتح متجر تجريبي دون التحدث إلى أحد.

3. أرسل الترويسات المطلوبة في كل نداء

المصادقة عبر Authorization: Bearer wamia_… أو x-api-key. يعرّف الموصّل نفسه عبر User-Agent: WamiaConnect/<app> <semver> (<تفاصيل المنصة>): تقرأ الواجهة الإصدار منه، وترفض الموصّلات الأقدم من الحد الأدنى بـ CONNECTOR_UPGRADE_REQUIRED، ويقارنه apiConnectorLatest بآخر إصدار منشور. أما التكامل المخصص فيرسل أي user agent يشاء. تحمل التعديلات Wamia-Idempotency-Key؛ المفتاح نفسه مع المحتوى نفسه يعيد الإجابة الأولى، والمحتوى المختلف يعيد IDEMPOTENCY_CONFLICT.

نقطة الوصول

الاسم	URL
الإنتاج	https://api.wamia.tn/connect/graphql
بيئة التجربة	https://api-dev.wamia.tn/connect/graphql

نداؤك الأول

اعرض أحدث خمس قوائم مُحدَّثة لمتجر المفتاح. يخبرك state بموضع كل منها في خط الاعتماد وbuyBox إن كان العرض فائزًا حاليًا.

curl

curl -sS https://api.wamia.tn/connect/graphql \
  -H 'content-type: application/json' \
  -H 'x-api-key: wamia_…' \
  -H 'user-agent: my-integration/1.0.0 (+https://shop.example.tn)' \
  -H 'wamia-idempotency-key: 6f0e1a2b-…' \
  --data '{"query":"query FirstCall { apiMyListings(limit: 5) { items { sku state priceMillimes availableQty buyBox updatedAt } nextCursor } }"}'

GraphQL

query FirstCall {
  apiMyListings(limit: 5) {
    items { sku state priceMillimes availableQty buyBox updatedAt }
    nextCursor
  }
}

ترويسات الطلب

الترويسة	القيمة
Authorization	Bearer wamia_… (أو x-api-key: wamia_…)
User-Agent	WamiaConnect/<app> <semver> (<تفاصيل المنصة>) — للموصّلات؛ حر للتكامل المخصص
Wamia-Idempotency-Key	UUID أو أي سلسلة من 8 إلى 128 حرفًا، للتعديلات فقط
Wamia-Dry-Run	true — تحقق وأبلغ دون كتابة
Content-Type	application/json

الأخطاء

على /connect/graphql كل رفض هو خطأ GraphQL (HTTP 200) يحمل extensions.code وعند الفائدة تفاصيل مقروءة آليًا بجانبه (extensions.retryAfterSeconds، extensions.fields، extensions.pendingBatchId، …)؛ عمود HTTP هو ما تجيب به نقاط REST (/connect/token، /connect/pair، /connect/revoke). الوسائط التي يرفضها مدقق المخطط تعود بـ BAD_USER_INPUT. عامل RATE_LIMITED وBATCH_HELD كتدفق طبيعي لا كأعطال.

الرمز	HTTP	المعنى
UNAUTHENTICATED	401	مفتاح مفقود أو مجهول.
KEY_EXPIRED	401	تجاوز `expires_at`؛ دوّر أو أعد الاتصال.
CONNECTION_REVOKED	401	فصل المتجر التطبيق.
CONNECTOR_UPGRADE_REQUIRED	426	إصدار الإضافة أدنى من الحد؛ يحدده `extensions.minSupportedVersion`.
CONNECTOR_SUSPENDED	403	أوقفت واميا هذا الموصّل (قاطع الطوارئ).
FORBIDDEN_SCOPE	403	يفتقر المفتاح إلى الصلاحية التي تتطلبها العملية (انظر الصلاحيات والحدود).
TENANT_MISMATCH	403	المورد يخص متجرًا آخر.
RATE_LIMITED	429	الدلو فارغ؛ انتظر `extensions.retryAfterSeconds`.
IDEMPOTENCY_CONFLICT	409	المفتاح نفسه بمحتوى مختلف.
BATCH_HELD	409	احتجز قاطع دائرة الدفعة (`extensions.pendingBatchId`)؛ يؤكدها المتجر أو يتجاهلها.
BATCH_TOO_LARGE	422	عناصر أكثر من حد الدفعة (`extensions.limit`).
VALIDATION_FAILED	422	مشكلات لكل حقل في `extensions.fields[] { field, message }`.
MEDIA_FETCH_REFUSED	422	تعذّر جلب رابط الصورة (شبكة خاصة، حجم، نوع).
NOT_FOUND	404	SKU أو طلب أو نقطة وصول مجهولة.

الحدود في كل إجابة

تحمل كل إجابة extensions.rateLimit { kind, limit, remaining } للدلو المستهلك، وتنعكس في الترويستين X-RateLimit-Limit وX-RateLimit-Remaining؛ ويضيف 429 الترويسة Retry-After. تحمل الأخطاء extensions.requestId لذكره في تذاكر الدعم. تراجع عندما يقترب remaining من الصفر بدل انتظار 429.

response

{
  "data": { "apiMyListings": { "items": [ … ], "nextCursor": null } },
  "extensions": {
    "rateLimit": { "kind": "read", "limit": 600, "remaining": 599 }
  }
}