إرسال الطلبات من موقعك الإلكتروني المخصص إلى eGrow (دليل API للمطورين وأدوات البرمجة بالذكاء الاصطناعي)

لماذا ترسل طلباتك إلى eGrow

الموقع الإلكتروني المخصص ممتاز في تلقي الطلبات. لكنه ليس مصممًا لإدارة كل ما يحدث بعد الطلب — وبالنسبة للدفع عند الاستلام، فإن "ما بعد" هو حيث يتم كسب المال أو خسارته. بمجرد وصول الطلب إلى eGrow:

• يتم التأكيد تلقائيًا — تأكيد عبر WhatsApp، أو وكيل الذكاء الاصطناعي، أو مركز الاتصال الخاص بك، مع تسجيل إجابات العميل على الطلب.
• الشحن بنقرة واحدة (أو صفر) — يتم إنشاء الطرد لدى شركة التوصيل الخاصة بك ويتم حفظ رقم التتبع على الطلب؛ وتتم مزامنة الحالات تلقائيًا.
• يتم إبقاء العملاء على اطلاع — رسائل "تم استلام الطلب"، "في طريقه"، "فشل التسليم، هل يمكننا المحاولة مرة أخرى؟" تُرسل من رقم WhatsApp الخاص بك دون أي تدخل منك.
• تنخفض المرتجعات — يتم التحقق من صحة العناوين والمدن، ويتم الإبلاغ عن التكرارات، ويتم متابعة العملاء الذين لا يمكن الوصول إليهم، ويمكن استعادة عمليات الشراء المهجورة.
• ترى الأرقام الحقيقية — معدل التأكيد، معدل التسليم، المرتجعات، الإيرادات حسب المنتج والحملة (UTM)، كل ذلك في مكان واحد.

موقعك يبقى موقعك. eGrow هو محرك العمليات خلفه.

كيف يعمل

1. تقوم بإنشاء Personal API Key في eGrow (دقيقتان).
2. عندما يضع العميل طلبًا على موقعك، يرسل الخادم الخاص بك هذا الطلب إلى eGrow API (orderFullCreate).
3. يرد eGrow بمعرف الطلب — ويتولى الأمر من هناك.

هذا هو التكامل بأكمله. كل ما يلي هو تفاصيل.

الخطوة 1: احصل على مفتاح API الخاص بك

1. في eGrow، افتح Settings → Developer → API Key.
2. انقر على Generate وانسخ المفتاح (يبدأ بـ egrow_).
3. احفظه في بيئة مشروعك كـ EGROW_API_KEY.

الخطوة 2: إرسال الطلب

eGrow API هو GraphQL. ترسل دائمًا طلب POST إلى نفس نقطة النهاية مع نص JSON يحتوي على query و variables الخاصة به.

• نقطة النهاية: https://api5.egrow.com/graphql
• الرؤوس (Headers): Authorization: Bearer YOUR_API_KEY و Content-Type: application/json
• التحويل (Mutation): orderFullCreate — ينشئ طلبًا كاملاً (عميل، عنوان، منتجات، أسعار) في مكالمة واحدة.

التحويل (The mutation)

mutation CreateOrder($input: OrderFullCreateInput!) {
 orderFullCreate(input: $input) {
 order { id orderNumber }
 userErrors { field message code }
 }
}

المتغيرات (طلب دفع عند الاستلام حقيقي)

{
 "input": {
 "orderExternalId": "WEB-10245",
 "orderNumber": "10245",
 "orderType": "Order",
 "paymentMethod": "COD",
 "financialStatus": "Pending",
 "currency": "MAD",
 "phone": "+212612345678",
 "email": "[email protected]",
 "customer": {
 "firstName": "Amina",
 "lastName": "El Idrissi",
 "phone": "+212612345678",
 "email": "[email protected]"
 },
 "shippingAddress": {
 "firstName": "Amina",
 "lastName": "El Idrissi",
 "phone": "+212612345678",
 "address1": "12 Rue Al Massira, Apt 4",
 "city": "Casablanca",
 "province": "Casablanca-Settat",
 "countryCode": "MA"
 },
 "lineItems": [
 {
 "title": "Leather wallet — brown",
 "sku": "WAL-BR-01",
 "externalProductId": "prod_88",
 "quantity": 2,
 "price": 149.00,
 "imageUrl": "https://yourshop.ma/img/wallet-brown.jpg"
 }
 ],
 "subtotal": 298.00,
 "shippingPrice": 30.00,
 "note": "Customer prefers delivery after 6pm",
 "tags": ["website"],
 "utmParameters": { "source": "facebook", "campaign": "ramadan-2026" }
 }
}

ما هو الغرض من كل حقل

الاستجابة (The response)

{
 "data": {
 "orderFullCreate": {
 "order": { "id": 1834512, "orderNumber": "10245" },
 "userErrors": []
 }
 }
}

احفظ order.id بجانب طلبك الخاص. إذا لم يكن userErrors فارغًا، لم يتم إنشاء أي شيء — تخبرك message بالحقل الذي يجب إصلاحه.

الخطوة 3: أمثلة الكود

كل مثال يقوم بنفس الشيء: بناء المتغيرات من بيانات إتمام الشراء الخاصة بك وإرسالها كـ POST. استبدل المفتاح بمتغير البيئة الخاص بك.

cURL (اختبره من طرفيتك)

curl -X POST https://api5.egrow.com/graphql \
 -H "Authorization: Bearer $EGROW_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "mutation CreateOrder($input: OrderFullCreateInput!) { orderFullCreate(input: $input) { order { id orderNumber } userErrors { field message code } } }",
 "variables": { "input": { "orderExternalId": "WEB-10245", "paymentMethod": "COD", "currency": "MAD",
 "customer": { "firstName": "Amina", "lastName": "El Idrissi", "phone": "+212612345678" },
 "shippingAddress": { "address1": "12 Rue Al Massira", "city": "Casablanca", "countryCode": "MA", "phone": "+212612345678" },
 "lineItems": [ { "title": "Leather wallet — brown", "sku": "WAL-BR-01", "quantity": 2, "price": 149 } ],
 "subtotal": 298, "shippingPrice": 30 } }
 }'

Node.js / Next.js (معالج مسار أو مسار API)

// app/api/checkout/route.js — runs on the server, the key never reaches the browser
const MUTATION = `mutation CreateOrder($input: OrderFullCreateInput!) {
 orderFullCreate(input: $input) { order { id orderNumber } userErrors { field message code } }
}`;

export async function sendOrderToEgrow(order) {
 const input = {
 orderExternalId: String(order.id),
 orderNumber: String(order.number),
 orderType: "Order",
 paymentMethod: order.paidOnline ? "CARD" : "COD",
 financialStatus: order.paidOnline ? "Paid" : "Pending",
 currency: "MAD",
 phone: order.customer.phone,
 email: order.customer.email,
 customer: { firstName: order.customer.firstName, lastName: order.customer.lastName,
 phone: order.customer.phone, email: order.customer.email },
 shippingAddress: { firstName: order.customer.firstName, lastName: order.customer.lastName,
 phone: order.customer.phone, address1: order.address.line1,
 city: order.address.city, province: order.address.region, countryCode: "MA" },
 lineItems: order.items.map(i => ({ title: i.name, sku: i.sku, externalProductId: String(i.productId),
 quantity: i.qty, price: i.unitPrice, imageUrl: i.image })),
 subtotal: order.subtotal,
 shippingPrice: order.shipping,
 note: order.note || undefined,
 tags: ["website"],
 utmParameters: order.utm || undefined,
 };

 const res = await fetch("https://api5.egrow.com/graphql", {
 method: "POST",
 headers: { "Authorization": `Bearer ${process.env.EGROW_API_KEY}`, "Content-Type": "application/json" },
 body: JSON.stringify({ query: MUTATION, variables: { input } }),
 });
 const json = await res.json();
 const result = json.data?.orderFullCreate;
 if (!result || result.userErrors?.length) {
 throw new Error("eGrow rejected the order: " + JSON.stringify(result?.userErrors ?? json.errors));
 }
 return result.order; // { id, orderNumber } — store it with your order
}

PHP (Laravel, WordPress, plain PHP)

function sendOrderToEgrow(array $order): array {
 $mutation = 'mutation CreateOrder($input: OrderFullCreateInput!) {
 orderFullCreate(input: $input) { order { id orderNumber } userErrors { field message code } }
 }';
 $input = [
 'orderExternalId' => (string)$order['id'],
 'paymentMethod' => 'COD',
 'financialStatus' => 'Pending',
 'currency' => 'MAD',
 'phone' => $order['phone'],
 'customer' => ['firstName' => $order['first_name'], 'lastName' => $order['last_name'], 'phone' => $order['phone']],
 'shippingAddress' => ['address1' => $order['address'], 'city' => $order['city'], 'countryCode' => 'MA', 'phone' => $order['phone']],
 'lineItems' => array_map(fn($i) => ['title' => $i['name'], 'sku' => $i['sku'], 'quantity' => (int)$i['qty'], 'price' => (float)$i['price']], $order['items']),
 'subtotal' => (float)$order['subtotal'],
 'shippingPrice' => (float)$order['shipping'],
 ];
 $ch = curl_init('https://api5.egrow.com/graphql');
 curl_setopt_array($ch, [
 CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20,
 CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('EGROW_API_KEY'), 'Content-Type: application/json'],
 CURLOPT_POSTFIELDS => json_encode(['query' => $mutation, 'variables' => ['input' => $input]]),
 ]);
 $json = json_decode((string)curl_exec($ch), true);
 curl_close($ch);
 $result = $json['data']['orderFullCreate'] ?? null;
 if (!$result || !empty($result['userErrors'])) {
 throw new RuntimeException('eGrow rejected the order: ' . json_encode($result['userErrors'] ?? $json['errors'] ?? null));
 }
 return $result['order']; // ['id' => …, 'orderNumber' => …]
}

Python (Django, FastAPI, Flask)

import os, requests

MUTATION = """mutation CreateOrder($input: OrderFullCreateInput!) {
 orderFullCreate(input: $input) { order { id orderNumber } userErrors { field message code } }
}"""

def send_order_to_egrow(order):
 payload = {
 "orderExternalId": str(order["id"]),
 "paymentMethod": "COD", "financialStatus": "Pending", "currency": "MAD",
 "phone": order["phone"],
 "customer": {"firstName": order["first_name"], "lastName": order["last_name"], "phone": order["phone"]},
 "shippingAddress": {"address1": order["address"], "city": order["city"], "countryCode": "MA", "phone": order["phone"]},
 "lineItems": [{"title": i["name"], "sku": i["sku"], "quantity": i["qty"], "price": i["price"]} for i in order["items"]],
 "subtotal": order["subtotal"], "shippingPrice": order["shipping"],
 }
 r = requests.post("https://api5.egrow.com/graphql",
 headers={"Authorization": f"Bearer {os.environ['EGROW_API_KEY']}", "Content-Type": "application/json"},
 json={"query": MUTATION, "variables": {"input": payload}}, timeout=20)
 result = r.json().get("data", {}).get("orderFullCreate")
 if not result or result.get("userErrors"):
 raise RuntimeError(f"eGrow rejected the order: {result and result.get('userErrors')}")
 return result["order"] # {"id": …, "orderNumber": …}

تحديث طلب أرسلته بالفعل

هل غير العميل العنوان، أو ألغيت الطلب على موقعك؟ استخدم orderCreateOrUpdate بنفس orderExternalId — فهو يأخذ نفس المدخلات تمامًا، ويقوم eGrow بتحديث الطلب الحالي بدلاً من إنشاء طلب ثانٍ. هذا هو أيضًا الخيار الأكثر أمانًا إذا لم تكن متأكدًا مما إذا كان الطلب قد تم إرساله بالفعل.

mutation UpsertOrder($input: OrderCreateOrUpdateInput!) {
 orderCreateOrUpdate(input: $input) {
 order { id orderNumber }
 userErrors { field message code }
 }
}

اختبره قبل كتابة الكود

يحتوي API Playground (Settings → Developer → Playground) على إجراء Add order الذي يبني هذا الطلب بالضبط من نموذج، ويشغله، ويعرض الاستجابة المباشرة. انقر على Fill dummy data، ثم قم بتشغيله، وسترى طلبًا جديدًا يظهر في قائمة طلباتك. ثم انسخ cURL الذي تم إنشاؤه — إنه نفس الاستدعاء أعلاه، مع معرفات حسابك الحقيقية لخط الأنابيب والمتجر.

دع مبرمج الذكاء الاصطناعي الخاص بك يقوم بذلك: موجه يمكنك لصقه

إذا تم بناء موقعك باستخدام Claude، Codex، Cursor، Lovable، Bolt أو أداة مماثلة، فلن تضطر إلى كتابة أي من هذا بنفسك. الصق الموجه أدناه في نفس الأداة، في مشروعك، وسوف يجد كود إتمام الشراء الخاص بك ويضيف التكامل. المساعد موجود أصلاً داخل الكود الخاص بك، لذلك سيجد إتمام الشراء، ويتبع تقنيتك وأسلوبك، ويضيف التكامل. لا شيء لتعبئته.

Integrate this project's checkout with eGrow so every new order is sent to eGrow through its API.
You are already in the codebase: find where an order is saved, use the language, framework and
conventions this project already has, and reuse my existing order/customer/product objects.

1. Add a server-side function (e.g. sendOrderToEgrow) that POSTs JSON to https://api5.egrow.com/graphql
 with headers Authorization: Bearer <EGROW_API_KEY> and Content-Type: application/json.
 Read the key from an environment variable named EGROW_API_KEY. It must never reach the browser.
2. Send this GraphQL mutation:
 mutation CreateOrder($input: OrderFullCreateInput!) {
 orderFullCreate(input: $input) { order { id orderNumber } userErrors { field message code } }
 }
 and map my order into `input` like this:
 orderExternalId = my order id (always), orderNumber, orderType "Order",
 paymentMethod "COD" + financialStatus "Pending" (or "Paid" when paid online), currency "MAD",
 phone, email, customer {firstName,lastName,phone,email},
 shippingAddress {firstName,lastName,phone,address1,city,province,countryCode "MA"},
 lineItems [{title,sku,externalProductId,quantity,price (unit price),imageUrl}],
 subtotal, shippingPrice, note, tags ["website"], utmParameters {source,medium,campaign,content,term}.
 Phone numbers must be in international format (+212…). Leave out fields I don't have.
3. Call it right after the order is saved, without blocking the customer's confirmation page
 (background job, queue, or after the response is sent). On failure log the error and retry
 later with the same orderExternalId — never create the same order twice.
4. Store the returned order.id and orderNumber on my order record (add a field if needed).
5. Treat a non-empty userErrors as a failure and include its messages in the log.
6. Add a small script or test that sends one sample order and prints the response.
Show me the diff, then run the test.

موجه للتحديثات والإلغاءات

Extend the eGrow integration: when an order is edited or cancelled on my site, send it again with
the mutation orderCreateOrUpdate (input type OrderCreateOrUpdateInput, same fields as before,
same orderExternalId) so eGrow updates the existing order instead of creating a new one.

استكشاف الأخطاء وإصلاحها

الخطوات التالية

• قم بتوصيل شركة التوصيل الخاصة بك ضمن Integrations، وقم بتشغيل الأتمتة التي تنشئ الطرد بمجرد تأكيد الطلب.
• قم بتشغيل order auto-confirmation via WhatsApp حتى يتم تأكيد الطلبات الجديدة أثناء نومك.
• ادفع عمليات الشراء المهجورة باستخدام orderType: "AbandonedCart" ودع eGrow يستعيدها.
• استكشف بقية API — العملاء، المنتجات، خطوط الأنابيب — في Playground.