التوفر والمخزون | مطورو AurMap

نقاط النهاية والصلاحيات

الطلب	الصلاحية
`PATCH /places/{place_id}/menu/state`	`inventory:write`
`POST /places/{place_id}/inventory` قريبا	`inventory:write`

لماذا طريق منفصل

العميل يغضب حين يطلب صنفا نفد. لذلك نفصل الحالة عن البنية. تحديث الحالة سريع، لا يمر بتجهيز الصور ولا بمقارنة الأصناف، ويصل إلى التطبيق خلال ثوان.

حالة القائمة

PATCH /places/{place_id}/menu/state بصلاحية inventory:write.

bash

aurmap PATCH /v1/places/plc_9q3w7e/menu/state '{"as_of":"2026-10-14T18:00:00Z","sold_out":{"items":[],"sizes":[{"item_id":"orange-juice","size_id":"l"}],"options":[{"group_id":"extras","option_id":"cheese"}]},"prices":{"items":[],"sizes":[{"item_id":"chicken-burger","size_id":"l","price_minor":3100}],"options":[]}}'

json

{ "place_id": "plc_9q3w7e", "version": 43, "prev_version": 42, "kind": "state", "hash": "a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1", "status": "applied" }

الحقل	الوصف
`as_of`	وقت هذه الحالة في نظامك. مطلوب
`paused`	`true` يوقف الطلب من القائمة كلها، ويبقى المكان ظاهرا
`sold_out`	`items[]` معرفات أصناف، و`sizes[]` من `item_id` و`size_id`، و`options[]` من `group_id` و`option_id`
`prices`	أسعار مؤقتة فوق أسعار القائمة: `items[]` من `item_id` و`price_minor`، و`sizes[]` من `item_id` و`size_id` و`price_minor`، و`options[]` من `group_id` و`option_id` و`price_minor`

كل حقل يستبدل كاملا

كل حقل ترسله من paused وsold_out وprices يحل محل القيمة المحفوظة كلها.
الحقل الذي لا ترسله يبقى كما هو.
لذلك أرسل قائمة النفاد كاملة في كل مرة. إذا نفد صنف آخر، أرسل القائمة القديمة ومعها الصنف الجديد.
لإلغاء كل الأسعار المؤقتة أرسل "prices": { "items": [], "sizes": [], "options": [] }.

في المثال أعلاه تبقى الكنافة نافدة؟ لا. لأن sold_out.items أرسلت فارغة، فصارت الكنافة متاحة. أرسل "items": ["kunafa"] إذا أردت إبقاءها نافدة.

الترتيب

نحفظ as_of لآخر تحديث حالة لكل مكان. إذا وصل طلب أقدم منه نتجاهله كله ونرد 200 مع "status": "ignored". بهذا لا يعود صنف نافد إلى التوفر بسبب طلب تأخر في الشبكة.

json

{ "place_id": "plc_9q3w7e", "version": 43, "kind": "state", "hash": "a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1", "status": "ignored" }

النسخة

تحديث الحالة نسخة مثل غيرها: يزيد version ويغير hash، ويصلك menu.changed بـ "kind": "state". وإذا غير التاجر الحالة من حسابه على AurMap، مثل إيقاف مؤقت أو نفاد صنف، يصلك الحدث نفسه لتعكسه في نظامك.

await aurmap('PATCH', '/v1/places/plc_9q3w7e/menu/state', {
  as_of: new Date().toISOString(),
  sold_out: { items: ['kunafa'], sizes: [], options: [] },
});

php

aurmap('PATCH', '/v1/places/plc_9q3w7e/menu/state', [
    'as_of' => gmdate('Y-m-d\TH:i:s\Z'),
    'sold_out' => ['items' => ['kunafa'], 'sizes' => [], 'options' => []],
]);

أرسل الحالة لحظة تغيرها عند التاجر، لا على فترات. الحد 120 طلبا في الدقيقة لكل مكان.

للقوائم لا توجد الآن كميات معدودة، ولا نفاد أو سعر مؤقت بوقت انتهاء. أرسل الحالة الجديدة حين يتغير شيء.

مخزون المتاجر قريبا

POST /places/{place_id}/inventory بصلاحية inventory:write.

bash

aurmap POST /v1/places/plc_store01/inventory '{"as_of":"2026-10-14T12:20:00Z","variants":[{"variant_id":"tshirt-basic-m","mode":"set","quantity":11},{"sku":"TS-L-BLK","mode":"set","quantity":4}]}'

json

{ "applied": 2, "ignored": [] }

mode: set يضع الكمية كما هي، وهو المفضل.
mode: adjust يضيف أو يطرح.
حدد المتغير بـ variant_id أو sku.
نظامك هو المرجع للمخزون. AurMap يحجز الكمية فقط أثناء دفع العميل، حتى 15 دقيقة، ثم يحررها إذا لم يكتمل الطلب. حين يكتمل الطلب أرسل الكمية الجديدة من نظامك.

أوقات الدوام

أوقات دوام المكان يحددها التاجر في حسابه على AurMap. جداول قائمتك تحدد ما يطلب داخل هذه الأوقات. لإيقاف المكان كله مؤقتا استعمل إيقاف الطلبات.