واجهة BabylonCare البرمجية والتكاملاتBabylonCare API and integrations

نظرة عامةOverview

لبابيلون كير ثلاث طرق للتكامل مع الأنظمة الخارجية، ولكل منها غرضها:BabylonCare offers three ways to integrate with outside systems, each with its own purpose:

• واجهة REST بمفتاح bk_: يدفع متجرك أو برنامجك الطلبات إلى كير، ويقرأ المراجع، ويقرأ الطلبات والمتابعة والإحصائيات إن مُنح الصلاحية.REST API with a bk_ key: your store or software pushes orders into Care, reads reference lists, and reads orders, tracking and stats if granted the scope.
• Webhook صادر: يرسل كير إلى رابطك حدثاً موقّعاً عند كل تغيّر في الطلب.Outbound webhook: Care sends a signed event to your URL whenever an order changes.
• ربط الموقع (bsl1): عقد موقّع بمفتاح واحد تعتمد عليه BabylonWeby (موقعك من بابيلون) وإضافة ووكومرس؛ تصل به الطلبات إلى صندوق «طلبات الموقع» لتعتمدها بنفسك.Site link (bsl1): a contract signed with a single key, used by BabylonWeby (our own website service) and the WooCommerce plug-in; orders land in the “Website orders” inbox for you to approve.

لمن هذه الوثائق؟ لمطوّر يربط متجراً أو ERP أو نظام نقاط بيع ببابيلون كير، ولصاحب متجر يريد استخدام إضافة جاهزة دون برمجة (انتقل إلى الإضافات).Who is this for? A developer connecting a store, ERP or point-of-sale system to BabylonCare, and a shop owner who wants a ready-made plug-in without coding (jump to Plug-ins).

العنوان الأساسي والصيغةBase URL and format

عنوان الواجهة هو عنوان نسخة بابيلون كير الخاصة بمتجرك (مثل https://your-shop.example.com)، دائماً عبر HTTPS. الطلبات والردود JSON بترميز UTF-8. الخطأ يعود بهذا الشكل:The API address is your own BabylonCare address (for example https://your-shop.example.com), always over HTTPS. Requests and responses are UTF-8 JSON. An error looks like this:

{ "error": { "code": "INVALID_PHONE", "message": "..." } }

رسائل الخطأ (message) بالعربية للقراءة البشرية؛ اعتمد في برمجتك على code ورمز الحالة HTTP. فحص الحياة GET /api/health متاح لكل مفتاح ويردّ {"ok":true,"time":"…"}.The message text is Arabic for humans; build your logic on code and the HTTP status. The liveness check GET /api/health is open to every key and returns {"ok":true,"time":"…"}.

المصادقة والصلاحياتAuthentication and scopes

أرسل المفتاح في كل طلب:Send the key on every request:

Authorization: Bearer bk_xxxxxxxxxxxxxxxxxxxxxxxx

• ينشئ المدير المفتاح من الإعدادات ← التكاملات ← مفاتيح API ويختار صلاحياته.The manager creates the key under Settings, Integrations, API keys and chooses its scopes.
• يظهر المفتاح مرة واحدة فقط لحظة إنشائه، ويُحفظ في كير مجزّأً (hash) فلا يمكن استرجاعه. إن ضاع احذفه وأنشئ غيره.The key is shown only once, when it is created, and Care stores only a hash of it, so it cannot be recovered. If you lose it, delete it and create a new one.
• يمكن تعطيل المفتاح أو حذفه في أي وقت؛ ويُردّ 401 BAD_API_KEY للمفتاح المعطّل أو المحذوف أو الخاطئ. كل إنشاء أو تعطيل أو حذف يُسجَّل ويُبلَّغ في تنبيهات الأمان لدى المتجر.A key can be disabled or deleted at any time; a disabled, deleted or wrong key gets 401 BAD_API_KEY. Every creation, disable or deletion is logged and sent to the shop's security alerts.
• اختياري عند الإنشاء: تاريخ انتهاء (بعده يُردّ 401 API_KEY_EXPIRED فأنشئ مفتاحاً جديداً)، وقائمة عناوين IP مسموحة (عناوين IPv4/IPv6 مفردة أو شبكات CIDR، حتى 20؛ من خارجها يُردّ 403 API_KEY_IP_DENIED). يُنصح بهما لكل موصّل يعمل من خادم بعنوان ثابت.Optional at creation: an expiry date (after it you get 401 API_KEY_EXPIRED; create a new key) and an IP allow-list (single IPv4/IPv6 addresses or CIDR networks, up to 20; anything else gets 403 API_KEY_IP_DENIED). Both are recommended for any connector running on a server with a fixed address.
• المفتاح الصحيح لا يُحجب أبداً بسبب محاولات فاشلة لغيره. المحاولات الخاطئة تُقفل لدقيقة: 20 لكل بادئة مفتاح من العنوان نفسه، أو 120 من العنوان نفسه أياً كانت البادئة، فيُردّ 429 بدل 401.A valid key is never blocked by someone else's failed attempts. Wrong keys are locked out for a minute: 20 per key prefix from the same address, or 120 from the same address whatever the prefix; you then get 429 instead of 401.
• لا تضع المفتاح في كود يعمل في المتصفح أو تطبيق جوال؛ ضعه في خادمك فقط.Never put the key in browser or mobile-app code; keep it on your server only.

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

POST /api/registrations

يسجّل طلباً (زبون واحد وعدة منتجات) ويعيد رقم الطلب ومعرّفات الضمان. يتطلب orders:create. الحد الأقصى لحجم الجسم 2 ميغابايت.Registers an order (one customer, several products) and returns the order number and warranty IDs. Requires orders:create. Maximum body size is 2 MB.

حقول الطلبRequest fields

حقول كل منتج في items[]Each entry of items[]

مثالExample

curl -X POST https://your-shop.example.com/api/registrations \
  -H "Authorization: Bearer bk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "clientRef": "ORDER-1001",
    "customerName": "Ali Hassan",
    "phone": "07701234567",
    "governorate": "بغداد",
    "area": "زيونة",
    "landmark": "near the mosque",
    "priceWithDelivery": 25000,
    "items": [
      { "productName": "Bluetooth speaker X1", "color": "Black", "quantity": 1, "warrantyType": "none" }
    ]
  }'

الردّ 201 لطلب جديد (للمفاتيح ذات الصلاحيات):A new order returns 201 (for scoped keys):

{
  "registration": {
    "orderId": "…", "orderNumber": "BOD-XXXXXX", "createdAt": "2026-10-17T09:30:00.000Z",
    "orderState": "pending", "orderType": "normal", "deliveryMode": "company",
    "scheduledFor": null, "clientRef": "ORDER-1001", "totalQuantity": 1,
    "items": [ { "productName": "Bluetooth speaker X1", "quantity": 1, "warrantyType": "none", "warrantyIds": ["…"] } ]
  }
}

عدم التكرار (Idempotency)Idempotency

• clientRef إلزامي (وإلا 400 CLIENT_REF_REQUIRED)، وصيغته تُفحص (400 BAD_CLIENT_REF)، والبادئة المحجوزة ترفض بـ 400 RESERVED_REF.clientRef is mandatory (otherwise 400 CLIENT_REF_REQUIRED), its format is checked (400 BAD_CLIENT_REF), and the reserved prefix is refused with 400 RESERVED_REF.
• إعادة إرسال الطلب نفسه (انقطاع شبكة مثلاً) لا تكرّره: يردّ 200 بالطلب الأصلي مع "duplicate": true.Re-sending the same request (after a network drop, say) never duplicates it: you get 200 with the original order and "duplicate": true.
• إعادة المرجع نفسه بمحتوى مختلف ترفض بـ 409 IDEMPOTENCY_MISMATCH. المرجع محصور بمفتاحك: لا يتعارض مع مراجع مفاتيح أخرى.Re-using the same reference with a different body is refused with 409 IDEMPOTENCY_MISMATCH. A reference belongs to your key only and never clashes with other keys' references.

أخطاء التسجيل الشائعةCommon registration errors

أخطاء 400 و409 دائمة (لا فائدة من إعادتها كما هي)، أما 429 و5xx فأعد المحاولة بعد مهلة بنفس clientRef بأمان.400 and 409 errors are permanent (retrying as-is is pointless); for 429 and 5xx, retry later with the same clientRef, which is safe.

GET /api/registrations/status?clientRef=…

حالة طلب سجّله مفتاحك نفسه بمرجعه، بالحد الأدنى من الحقول (بلا هاتف ولا عنوان ولا مبالغ). يتطلب orders:create. لا طلب بهذا المرجع من هذا المفتاح = 404 NOT_FOUND.The status of an order registered by your own key, by its reference, with minimal fields (no phone, address or amounts). Requires orders:create. No order with that reference from this key returns 404 NOT_FOUND.

{
  "order": {
    "orderId": "…", "orderNumber": "BOD-XXXXXX", "createdAt": "…",
    "orderState": "pending", "orderType": "normal", "deliveryMode": "company",
    "deliveryCompanyKey": null, "deliveryOrderId": null, "deliverySentAt": null,
    "selfStatus": null, "scheduledFor": null, "totalQuantity": 1,
    "deliveryStatus": null, "deliveryStatusAt": null,
    "items": [ { "productName": "…", "quantity": 1, "warrantyType": "none" } ]
  }
}

deliveryStatus هي آخر حالة وصلت من شركة التوصيل (نصها كما تعطيه الشركة) وتبقى null قبل أن يُرسل الطلب إليها.deliveryStatus is the latest status received from the delivery company (its text exactly as the company gives it) and stays null before the order is sent to it.

المراجع: المناطق وأنواع الضمانReference: regions and warranty types

يتطلب الاثنان reference:read.Both require reference:read.

GET /api/regions

قائمة المحافظات ومناطقها لشركة التوصيل المفعّلة، لتعبئة قوائم العنوان. الردّ يُخزَّن في المتصفح يوماً؛ خزّنه أنت أيضاً ولا تطلبه مع كل طلب. المحافظة والمنطقة تُرسلان بالاسم حرفياً.The governorates and their areas for the active delivery company, to fill address dropdowns. The response may be cached for a day; cache it yourself and do not fetch it for every order. Send governorate and area by name, exactly.

{ "governorates": [ { "id": 1, "name": "بغداد", "areas": [ { "id": 101, "name": "زيونة" } ] } ], "company": "…" }

GET /api/warranty-types

الرموز التي يقبلها warrantyType (يضبطها المدير، فلا تكتب رموزاً يدوياً):The codes warrantyType accepts (the manager sets them, so do not hard-code any):

{ "warrantyTypes": [ { "code": "none", "label": "بدون ضمان", "months": 0 } ] }

الطلبات والمتابعة والإحصائياتOrders, tracking and stats

مسارات قراءة للأنظمة الموثوقة فقط، وكلها تتطلب صلاحية حساسة مذكورة أعلاه. تعيد حقولاً مسموحة فقط؛ لا تُعاد روابط التتبع ولا مواقع GPS ولا صور الدفع ولا الحقول الداخلية.Read routes for trusted systems only, each requiring a sensitive scope from the table above. They return allow-listed fields only; tracking links, GPS positions, payment proof images and internal fields are never returned.

الترقيم: limit وcursorPagination: limit and cursor

limit عدد صحيح من 1 إلى 100 (افتراضياً 100). إن كان nextCursor غير null فمرّره في الطلب التالي كقيمة cursor حتى يصبح null. قيمة غير صالحة تردّ 400 BAD_LIMIT أو 400 BAD_CURSOR.limit is an integer from 1 to 100 (default 100). While nextCursor is not null, pass it as cursor in the next request until it becomes null. An invalid value returns 400 BAD_LIMIT or 400 BAD_CURSOR.

GET /api/admin/orders?limit=50
GET /api/admin/orders?limit=50&cursor=50

الحدود والأخطاء العامةLimits and general errors

عند تجاوز المعدل يردّ 429 RATE_LIMITED مع ترويسة Retry-After (ثوانٍ) في الحدود المشتركة للمفتاح؛ انتظر ثم أعد المحاولة. أخطاء المصادقة: 401 BAD_API_KEY، 401 API_KEY_EXPIRED، 403 API_KEY_IP_DENIED، 403 API_KEY_SCOPE، 403 FEATURE_DISABLED.When a rate is exceeded you get 429 RATE_LIMITED, with a Retry-After header (seconds) on the key-wide limits; wait and retry. Authentication errors: 401 BAD_API_KEY, 401 API_KEY_EXPIRED, 403 API_KEY_IP_DENIED, 403 API_KEY_SCOPE, 403 FEATURE_DISABLED.

Webhook الصادرOutbound webhook

يرسل كير POST بجسم JSON إلى رابط تحدده في الإعدادات ← التكاملات عند أحداث الطلب. يمكنك اختيار الأحداث، وتوجد «إرسال تجربة» (حدث test) للتأكد من الاستقبال.Care sends a POST with a JSON body to a URL you set under Settings, Integrations when order events happen. You can choose which events to receive, and a “send test” button (event test) checks your receiver.

الأحداثEvents

الجسم والترويساتBody and headers

POST https://your-receiver.example.com/hooks/care
Content-Type: application/json
User-Agent: BabylonCare-Webhook/1
X-Babylon-Event: order.registered
X-Babylon-Delivery: evt_3f9a…            (unique id, same as body.id; unchanged on retries)
X-Babylon-Attempt: 1                     (1 to 5)
X-Babylon-Timestamp: 2026-10-17T09:30:00.000Z   (same as body.at)
X-Babylon-Signature: sha256=…            (HMAC-SHA256 of the raw body)
X-Babylon-Signature-Ts: sha256=…         (HMAC-SHA256 of  at + "." + raw body)
X-Babylon-Signature-Previous: sha256=…   (only during a secret rotation: same, with the previous secret)
X-Babylon-Signature-Ts-Previous: sha256=…

{ "id": "evt_3f9a…", "event": "order.registered", "at": "2026-10-17T09:30:00.000Z", "data": { … } }

data يحمل الطلب (أو الطلب مع تفاصيل الحدث) وفيه بيانات الزبون؛ عامله كبيانات حساسة.data carries the order (or the order plus the event details), including customer data; treat it as sensitive.

التحقق من التوقيع (إلزامي)Verifying the signature (mandatory)

1. احسب HMAC-SHA256 بسرّ الـ webhook على البايتات الخام للجسم كما وصلت (لا بعد إعادة ترميز JSON)، وقارنه بـ X-Babylon-Signature بمقارنة زمن ثابت.Compute HMAC-SHA256 with the webhook secret over the raw body bytes exactly as received (not a re-encoded JSON) and compare it with X-Babylon-Signature in constant time.
2. ارفض الرسالة إن مضى على at أكثر من 5 دقائق (حماية من إعادة الإرسال). التوقيع الأول يغطي at لأنه داخل الجسم.Reject the message if at is more than 5 minutes old (replay protection). The first signature covers at because it sits inside the body.
3. تجاهل أي id رأيته من قبل (احتفظ بالمعرّفات ساعتين على الأقل: إعادة المحاولة تحمل المعرّف نفسه حتى ساعة).Ignore any id you have already seen (keep ids for at least two hours: retries carry the same id for up to an hour).
4. تدوير السرّ: عند تدويره من الإعدادات يبقى السرّ القديم صالحاً 24 ساعة، ويُرسل خلالها توقيع إضافي به في X-Babylon-Signature-Previous (و-Ts-Previous)، بينما X-Babylon-Signature بالسرّ الجديد. اقبل الرسالة إن طابق سرّك أياً من الترويستين، ثم حدّث سرّك قبل انقضاء المدة.Secret rotation: when the secret is rotated in Settings, the old secret stays valid for 24 hours. During that window an extra signature made with it is sent in X-Babylon-Signature-Previous (and -Ts-Previous), while X-Babylon-Signature uses the new secret. Accept the message if your secret matches either header, then switch to the new secret before the window ends.
5. إن كنت تعتمد ترويسة X-Babylon-Timestamp فتحقق من X-Babylon-Signature-Ts بدل الأول: هو HMAC على X-Babylon-Timestamp + "." + الجسم الخام، فالترويسة مشمولة بالتوقيع. لا تثق بترويسة الوقت وحدها مع التوقيع الأول.If you rely on the X-Babylon-Timestamp header, verify X-Babylon-Signature-Ts instead: it is an HMAC over X-Babylon-Timestamp + "." + raw body, so the header is covered. Do not trust the time header alone with the first signature.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: Buffer exactly as received. Returns the parsed message, or null if it must be rejected.
export function verifyCareWebhook(rawBody, headers, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const got = String(headers['x-babylon-signature'] || '');
  const a = Buffer.from(expected), b = Buffer.from(got);
  if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
  const msg = JSON.parse(rawBody.toString('utf8'));
  if (Math.abs(Date.now() - Date.parse(msg.at)) > 5 * 60_000) return null;   // replay window
  // then: skip msg.id if you have processed it before
  return msg;
}

PHP

<?php
$raw      = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$got      = $_SERVER['HTTP_X_BABYLON_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) { http_response_code(401); exit; }
$msg = json_decode($raw, true);
if (abs(time() - strtotime($msg['at'])) > 300) { http_response_code(401); exit; }   // replay window
// skip $msg['id'] if already processed, then handle $msg['event'] / $msg['data']
http_response_code(200);

Python

import hashlib, hmac, json, time
from datetime import datetime

def verify_care_webhook(raw: bytes, headers: dict, secret: str):
    expected = "sha256=" + hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, headers.get("X-Babylon-Signature", "")):
        return None
    msg = json.loads(raw)
    sent = datetime.fromisoformat(msg["at"].replace("Z", "+00:00")).timestamp()
    if abs(time.time() - sent) > 300:      # replay window
        return None
    return msg                              # skip msg["id"] if already processed

قواعد التسليمDelivery rules

• HTTPS فقط وعلى المنفذ 443 أو 8443. الروابط غير الآمنة والعناوين الداخلية مرفوضة.HTTPS only, on port 443 or 8443. Insecure URLs and internal addresses are refused.
• سرّ التوقيع من 16 إلى 200 حرفاً (حروف وأرقام ورموز بلا مسافات)، ويولّده كير تلقائياً (whsec_…) إن لم تكتبه. لا يُضمَّن في الرسائل.The signing secret is 16 to 200 characters (letters, digits, symbols, no spaces) and Care generates one (whsec_…) if you leave it empty. It is never included in messages.
• مهلة الاستقبال 10 ثوانٍ، ويُعدّ أي ردّ 2xx نجاحاً. إعادة محاولة تلقائية عند أي ردّ آخر أو خطأ شبكة: حتى 5 محاولات خلال أقل من ساعة (فوراً، ثم بعد 30 ثانية، 2 دقيقة، 10 دقائق، 40 دقيقة) بنفس id ووقت at جديد موقَّع. الطابور محفوظ ويكمل بعد إعادة تشغيل كير، وله سقف (عند امتلائه يُسقط الأقدم). أجب بسرعة وعالج العمل في الخلفية، وصالح ما فات بعد المحاولة الخامسة بقراءة الطلبات عبر الواجهة.The receive timeout is 10 seconds and any 2xx counts as success. Automatic retries on any other response or network error: up to 5 attempts within an hour (immediately, then after 30 seconds, 2 minutes, 10 minutes and 40 minutes), with the same id and a fresh signed at. The queue is persisted, resumes after a Care restart, and is capped (when full, the oldest is dropped). Answer quickly, do the work in the background, and reconcile anything still missing after the fifth attempt by reading orders through the API.

عقد ربط المتجر (للمطوّرين)Store-link contract (for plug-in developers)

لمن يبني إضافة أو موقع متجر (غير BabylonWeby، فهو مربوط جاهزاً) يرسل طلباته إلى «طلبات الموقع» في كير. هذا ملخّص؛ العقد الكامل (الإصدار 1 مع التعديلات 1.1 إلى 1.3) يتضمن أشكال الطلبات والردود ومتجهات اختبار التوقيع، ويُرسل للمطوّرين عند الطلب على [email protected].For anyone building a plug-in or a store website (other than BabylonWeby, which comes pre-integrated) that sends orders to Care's “Website orders” inbox. This is a summary; the full contract (version 1 with revisions 1.1 to 1.3) includes request and response shapes and signature test vectors, and is sent to developers on request at [email protected].

• مفتاح bsl1: bsl1.<base64url(host)>.<base64url(32 random bytes)>. ينشئه المدير في الإعدادات ويُعرض مرة واحدة؛ ويحوي عنوان كير نفسه فلا يحتاج الموقع حقلاً آخر. مفاتيح bk_ لا تعمل هنا والعكس.The bsl1 key: bsl1.<base64url(host)>.<base64url(32 random bytes)>. The manager creates it in Settings and it is shown once; it contains Care's own address so the site needs no other field. bk_ keys do not work here, and vice versa.
• المعرّف والمفاتيح الفرعية: key_id = "slk_" + أول 12 خانة hex من sha256(key). توقيع الموقع إلى كير بمفتاح HMAC-SHA256(key, "babylon-store-link/v1/site-to-care") (hex)، وتوقيع كير إلى الموقع بـ …/care-to-site.Key id and sub-keys: key_id = "slk_" + first 12 hex chars of sha256(key). The site signs to Care with HMAC-SHA256(key, "babylon-store-link/v1/site-to-care") (hex), and Care signs to the site with …/care-to-site.
• الترويسات على كل طلب: X-Store-Link-Version: 1، X-Store-Key-Id، X-Store-Timestamp (ثوانٍ epoch)، X-Store-Nonce (16 إلى 64 حرفاً فريدة)، X-Store-Signature: v1=<hex>.Headers on every request: X-Store-Link-Version: 1, X-Store-Key-Id, X-Store-Timestamp (epoch seconds), X-Store-Nonce (16 to 64 unique characters), X-Store-Signature: v1=<hex>.
• النص الموقَّع: timestamp.nonce.METHOD.path_with_query.sha256hex(body). النافذة الزمنية ±300 ثانية، والـ nonce لا يتكرر خلال 10 دقائق.String to sign: timestamp.nonce.METHOD.path_with_query.sha256hex(body). The time window is ±300 seconds and a nonce cannot repeat within 10 minutes.
• المسارات تحت https://<care-host>/api/store-link/v1: POST /link وPOST /unlink وGET /ping وGET /regions وPOST /orders (يتطلب Idempotency-Key) وGET /orders/{code} وPOST /orders/{code}/cancel-request و…/messages و…/payment وGET /identity وGET /reviews. كير يرسل الأحداث إلى رابط الاستدعاء الذي يسجّله الموقع عبر /link.Endpoints under https://<care-host>/api/store-link/v1: POST /link, POST /unlink, GET /ping, GET /regions, POST /orders (requires Idempotency-Key), GET /orders/{code}, POST /orders/{code}/cancel-request, …/messages, …/payment, GET /identity and GET /reviews. Care sends events to the callback URL the site registers through /link.
• الحدود لكل مفتاح: 120 طلباً في الدقيقة، و30 إنشاء طلب في الدقيقة، وجسم حتى 64 كيلوبايت وحتى 30 بنداً. وما لم يُفعَّل الربط يردّ كير 404 على كل المسارات.Limits per key: 120 requests a minute, 30 order creations a minute, a body up to 64 KB and up to 30 items. While the link is off Care answers 404 on every path.

الإضافات والموصّلات الجاهزةReady-made plug-ins and connectors

إن لم تكن مطوّراً فاستخدم إحدى الإضافات التالية. الإضافتان من تطوير Babylon Core LLC، وليستا من منتجات الشركات المذكورة أو معتمدتين منها؛ الأسماء والشعارات لأصحابها.If you are not a developer, use one of these. Both are made by Babylon Core LLC; they are not products of, or endorsed by, the companies named. Names and logos belong to their owners.

Babylon Care Connector (ووكومرس / ووردبريسWooCommerce / WordPress)

تصل طلبات متجرك إلى «طلبات الموقع» في كير تلقائياً، ويعود رقم التتبع وتحديثات الحالة إلى الطلب في ووكومرس.Your store's orders reach Care's “Website orders” inbox automatically, and the tracking number and status updates flow back to the order in WooCommerce.

تنزيل الإضافة (ZIP)Download plug-in (ZIP) · 51.4 KB

SHA-256: 9bd5cf2944ec3ed742c75723083d268d25d919ddb99f8b764bba3a940dd7484b

قبل أن تبدأBefore you start

• ووردبريس + ووكومرس، وعنوان المتجر يبدأ بـ https://.WordPress + WooCommerce, with a store address starting with https://.
• المتجر على جذر النطاق (مثل shop.example.com) لا في مجلد فرعي.The store is at the root of its domain (such as shop.example.com), not in a sub-folder.
• الأسعار بالدينار العراقي (IQD) وحساب مدير في المتجر وفي بابيلون كير.Prices in Iraqi dinar (IQD), and an administrator account in the store and in BabylonCare.

التثبيت في 4 خطواتInstall in 4 steps

1. ارفع الإضافة وفعّلها: من لوحة ووردبريس: إضافات ← أضف جديدة ← رفع إضافة ← اختر babylon-care-connector.zip ← ثبّت الآن ← فعّل.Upload and activate: in WordPress: Plugins, Add New, Upload Plugin, choose babylon-care-connector.zip, Install Now, Activate.
2. أنشئ مفتاح الربط في بابيلون كير: الإعدادات ← Webhook و API ← ربط الموقع ← إنشاء مفتاح الربط، ثم انسخه (يبدأ بـ bsl1. ويظهر مرة واحدة).Create the link key in BabylonCare: Settings, Webhook and API, site link, Create link key, then copy it (it starts with bsl1. and is shown once).
3. الصق المفتاح واحفظ: ووكومرس ← بابيلون كير ← الصق المفتاح في الخانة الوحيدة ← حفظ وربط. تظهر نقطة خضراء وكلمة «مرتبط» مع عنوان كير؛ تأكد أنه العنوان الصحيح.Paste the key and save: WooCommerce, Babylon Care, paste the key into the only field, Save and connect. A green dot and “Connected” appear with Care's address; check it is the right one.
4. جرّب بطلب: اطلب منتجاً بالدفع عند الاستلام؛ يظهر في «طلبات الموقع» خلال دقيقة، وعند موافقتك عليه يظهر رقم التتبع في ووكومرس.Try an order: place a cash-on-delivery order; it appears under “Website orders” within a minute, and once you approve it the tracking number shows up in WooCommerce.

حالة الإضافة بصدق: مغطّاة باختبارات آلية، لكنها لم تُجرَّب بعد على موقع ووردبريس حقيقي. جرّبها على نسخة تجريبية من متجرك قبل الاعتماد عليها. لا تتوفر في دليل إضافات ووردبريس الرسمي؛ تُثبَّت برفع الملف. طلبات الدفع المسبق المعلّقة لا تُرسل حتى تصبح مدفوعة. يتحمّل المتجر نفسه مسؤولية إعدادات الاستضافة (شهادة SSL وضبط الوقت: فرق أكثر من 5 دقائق يرفض الربط).Honest status: covered by automated tests, but not yet run on a real WordPress site. Try it on a staging copy of your store before relying on it. It is not in the official WordPress plug-in directory; you install it by uploading the file. Unpaid prepaid orders are not sent until paid. Hosting settings are your responsibility (an SSL certificate and a correct clock: a difference of more than 5 minutes is refused).

محوّل Shopify ذاتي الاستضافةSelf-hosted Shopify adapter

Worker صغير على Cloudflare بلا تبعيات، تنشره أنت على حسابك: يستقبل webhook الطلب من Shopify ويسجّله في كير عبر هذه الواجهة (POST /api/registrations) بمفتاح bk_ محدود الصلاحية.A small, dependency-free Cloudflare Worker that you deploy to your own account: it receives Shopify's order webhook and registers it in Care through this API (POST /api/registrations) with a limited-scope bk_ key.

تنزيل المحوّل (ZIP)Download adapter (ZIP) · 30.3 KB

SHA-256: a8579294cc06f8c226475d8115f475bcbdb0a49831ab601a6c2c57d4032d7ffd

الحالة بصدق: ليس تطبيقاً في متجر تطبيقات Shopify (Shopify App Store)؛ لم يُقدَّم ولم يُراجَع ولم يُعتمد. هو محوّل تنشره بنفسك. مختبَر بوحدات آلية ونماذج طلبات، ولم يُجرَّب بعد على متجر Shopify حقيقي؛ جرّبه على متجر تجريبي أولاً. الاتجاه واحد فقط: من Shopify إلى كير (طلب جديد)؛ لا تعود حالات التوصيل إلى Shopify ولا تُزامَن تعديلات الطلب.Honest status: it is not an app on the Shopify App Store; it was not submitted, reviewed or approved. It is an adapter you deploy yourself. It is covered by automated tests and sample orders, and has not yet been run against a real Shopify store; try it on a development store first. It works in one direction only, from Shopify to Care (new order); delivery statuses do not flow back to Shopify and later order edits are not synced.

ما يتطلبهWhat it needs

1. مفتاح bk_ في كير بصلاحيتي orders:create وreference:read فقط (باقة احترافية).A bk_ key in Care with only orders:create and reference:read (Professional plan).
2. حساب Cloudflare ينشر عليه الـ Worker (wrangler deploy)، مع إعداد العنوان والمتاجر المسموحة والأسرار، كما في ملف README داخل الحزمة.A Cloudflare account to deploy the Worker (wrangler deploy), with the address, allowed shops and secrets configured as described in the README inside the package.
3. webhook «Order creation» في Shopify يشير إلى الـ Worker، وطريقة دفع «الدفع عند الاستلام».An “Order creation” webhook in Shopify pointing to the Worker, and a “Cash on Delivery” payment method.

الطلبات المدفوعة كلياً أونلاين، أو التي لا تطابق مدينتها قائمة مناطق كير، تُدرَج في قائمة «يدوي» لتسجّلها بنفسك؛ لا يُخمَّن شيء ولا يضيع طلب بصمت. التفاصيل الكاملة في README داخل الحزمة.Orders paid fully online, or whose city does not match Care's area list, are put on a “manual” list for you to register yourself; nothing is guessed and no order is dropped silently. Full details are in the README inside the package.

تحتاج تكاملاً آخر أو مساعدة في الربط؟ راسلنا على [email protected] أو واتساب.Need another integration or help connecting? Write to [email protected] or WhatsApp us.