واجهة GeoWise البرمجية
محرّك واحد، وأربعة نداءات هي المهمة. تبحث عن الإتاحة لعنوان، وتحجز موعداً مؤقتاً، وتُنشئ الحجز من هذا الحجز المؤقت، وتستمع إلى ويب هوكس. وكل موعد تعيده الواجهة يكون قد فُحص مسبقاً مقابل المناطق وخطة التغطية وساعات العمل والتنقل من المهام المجاورة والفواصل والمهارات والسعة.
Base URL https://api.geowise.com/v1
Sandbox same URL — sandbox is selected by your key prefix (sk_test_)
Format JSON in, JSON out · UTF-8 · times are RFC 3339 with offset
Versioning path version (v1); additive changes are not versioned
Spec https://docs.geowise.com/openapi.json (OpenAPI 3.1)القاعدة التي يتفرّع عنها كل ما عداها: لا تحسب موعداً ولا تخمّنه أبداً. فعمليات الكتابة لا تقبل إلا قيم slot_id وhold_id التي أعادتها الواجهة، لا مواعيد نصية حرة.
المصادقة
رموز Bearer، لكل شركة. sk_test_… مفاتيح تصل إلى بيئة الاختبار (فريق وهمي، وأزمنة تنقل وهمية، وبلا إرسال رسائل)؛ وsk_live_… مفاتيح تعمل على التقويم الحقيقي. ويستبدل شركاء المنصات عميل OAuth بمفاتيح لكل مستأجر.
curl https://api.geowise.com/v1/availability \
-H "Authorization: Bearer sk_test_51Q…" \
-H "Content-Type: application/json" \
-d '{ "service_id": "boiler-service", "address": "12 Oak Street, Sarajevo" }'عدم التكرار وإعادة المحاولة
أرسل ترويسة Idempotency-Key (أي نص فريد، يُحفظ 24 ساعة) مع كل طلب POST. فإعادة المحاولة عبر الشبكة بالمفتاح نفسه تعيد النتيجة الأصلية بدل إنشاء حجز ثانٍ. والحجوزات المؤقتة هي شبكة الأمان الثانية: فالحجز المُنشأ من حجز مؤقت منتهٍ يُرفض بـhold_expired مع بدائل جديدة. ولا يُنقل أبداً إلى موعد آخر بصمت.
الأخطاء وحدود المعدل
تستخدم الأخطاء غلافاً واحداً. والإتاحة محدودة بـ 60 طلباً في الدقيقة لكل مفتاح (وذروة 120)، وعمليات الكتابة بـ 20 في الدقيقة. واستجابات 429 تحمل ترويسة Retry-After.
{ "error": { "code": "hold_expired",
"message": "Hold hold_h7 expired at 14:02. Re-check availability.",
"alternatives": [ { "slot_id": "slt_a12", "start": "2026-09-01T14:50:00+02:00" } ] } }invalid_address تعذّر تحديد الإحداثياتoutside_zones لا منطقة تغطيه، والبدائل مذكورةslot_taken سبقك أحدهم إلى حجزه، والبدائل مذكورةhold_expired أعد التحقق من الإتاحةdeposit_required أكمل الدفع للتأكيدrate_limited التزم بـ Retry-After/v1/availabilityنداء المحرّك. يأخذ عنواناً وخدمة، ويُدخل المهمة مبدئياً في يوم كل فني مؤهَّل، ثم يعيد المواعيد التي يختار نمط الجدولة عرضها، مع وسوم ودرجات اختيارية وشرح من جملة واحدة يمكنك عرضه على عميل أو وكيل ذكي.
service_id مطلوب الخدمة المطلوب حجزها، وتأتي مدتها من إعداداتهاaddress مطلوب عنوان نصي حر أو {lat, lng}، يُحوَّل إلى إحداثيات ويُطابَق بمنطقةdate_from · date_to نافذة البحث، وافتراضياً من مهلة الإشعار إلى أفق الحجزlimit أقصى عدد مواعيد (6 افتراضياً، و10 كحد أقصى)، ويُبقي الاستجابات صغيرة للصوت والمحادثةanswers إجابات الاستقبال التي تُشتق منها المدة (مثلاً غرف: 4 ← 150 دقيقة)POST /v1/availability
{ "service_id": "boiler-service",
"address": "12 Oak Street, Sarajevo",
"date_from": "2026-09-01", "date_to": "2026-09-07", "limit": 6 }
→ 200 OK
{ "zone": { "id": "north", "name": "North", "coverage_days": ["tue", "thu"] },
"mode": "back_to_back",
"slots": [
{ "slot_id": "slt_9f3", "start": "2026-09-01T11:55:00+02:00",
"window": "11:55–12:25", "technician": "Ana", "labels": ["nearby"],
"grade": 94, "why": "Ana is already on Oak Street at 11:30" },
{ "slot_id": "slt_a11", "start": "2026-09-01T09:05:00+02:00",
"window": "09:05–09:35", "technician": "Ana", "labels": ["first_of_day"] } ],
"fallbacks": { "request": true, "waitlist": true, "urgent": false,
"adjacent_zone": null } }/v1/holdsيحجز موعداً مؤقتاً بينما يُكمل العميل الدفع (المدة الافتراضية 600 ثانية، والحد الأقصى 1800). ويختفي الموعد من إتاحة الجميع طوال تلك المدة. والحجوزات المؤقتة مجانية وتنتهي بصمت، ولا يُحجز شيء حتى تحوّل أحدها إلى حجز.
POST /v1/holds
{ "slot_id": "slt_9f3", "ttl_seconds": 600 }
→ 201 Created
{ "hold_id": "hold_h7", "slot_id": "slt_9f3",
"expires_at": "2026-09-01T14:02:11+02:00" }/v1/bookingsيُنشئ الحجز من حجز مؤقت. وتكون حالة الاستجابة confirmed حين تسمح قواعدك بالتأكيد الفوري، أو pending حين يتحول إلى طلب (خارج الخطة، أو يحتاج عرض سعر، أو يتجاوز حدّ القيمة لديك، أو جاء من قناة غير موثوقة). وتظل الطلبات المعلّقة تحجز السعة حتى تقرّر.
POST /v1/bookings
Idempotency-Key: 4d3c…
{ "hold_id": "hold_h7",
"customer": { "name": "L. Hodžić", "phone": "+387 61 …", "channel": "whatsapp" },
"notes": "Combi boiler, error E119" }
→ 201 Created
{ "booking_id": "bkg_28xq", "status": "confirmed",
"start": "2026-09-01T11:55:00+02:00", "window": "11:55–12:25",
"technician": "Ana", "manage_url": "https://book.geowise.com/m/bkg_28xq",
"payment": { "deposit": null, "card_on_file": false } }إعادة الجدولة والإلغاء
إعادة الجدولة تتبع العقد نفسه الذي يتبعه الحجز: اجلب الإتاحة، ثم احجز مؤقتاً، ثم ثبّت الحجز المؤقت على الحجز القائم. والعمليتان موسومتان كإجراءين مدمّرين في مخطط MCP، فيؤكّد المساعد مع العميل قبل التنفيذ. والإلغاءات تُشغّل تعبئة قائمة الانتظار تلقائياً.
GET /v1/bookings/bkg_28xq → status, times, technician, ETA link
PATCH /v1/bookings/bkg_28xq/reschedule { "hold_id": "hold_k2" }
POST /v1/bookings/bkg_28xq/cancel { "reason": "customer_request" }
→ cancellation policy applied,
gap offered to the waitlist/v1/customers?phone=…بحث بالهاتف أو البريد، ليتمكن مساعد ذكي أو وكيل صوتي من الإجابة عن سؤال «متى موعدي؟» دون تحويل إلى إنسان. ويعيد العميل وحجوزاته القادمة وفنيه المفضّل.
GET /v1/customers?phone=%2B38761…
→ 200 OK
{ "customer_id": "cus_77b", "name": "L. Hodžić",
"preferred_technician": "Ana",
"upcoming": [ { "booking_id": "bkg_28xq",
"start": "2026-09-01T11:55:00+02:00", "service": "Boiler service" } ] }/v1/visits/{id}/etaتقدير الوصول الحيّ لزيارة، يُعاد حسابه باستمرار من موقع الفني (المشارَك أثناء نوبات العمل فقط) ومن حركة المرور في Google Maps. والبيانات نفسها تُشغّل رابط الخريطة الحيّة للعميل والتنبيهات الاستباقية بالتأخير.
→ 200 OK
{ "visit_id": "vis_3kk", "status": "en_route",
"promised_window": "11:55–12:25", "eta": "2026-09-01T12:07:00+02:00",
"delay_minutes": 12, "track_url": "https://book.geowise.com/t/vis_3kk" }ويب هوكس
موقّعة بـ HMAC-SHA256 في ترويسة Geowise-Signature، ويُعاد إرسالها بتباعد متزايد لمدة 24 ساعة. واضبط نقاط النهاية لكل حدث من لوحة التحكم أو عبر POST /v1/webhook_endpoints.
booking.confirmed booking.pendingbooking.rescheduled booking.cancelledvisit.en_route visit.arrivedvisit.completed visit.delayedroute.locked gap.openedwaitlist.offered payment.succeededpayment.failed{ "event": "visit.delayed", "created": "2026-09-01T11:41:02+02:00",
"data": { "visit_id": "vis_3kk", "booking_id": "bkg_28xq",
"promised_window": "11:55–12:25", "new_eta": "12:07",
"downstream_notified": true } }خادم MCP
خادم مستضاف واحد على https://mcp.geowise.com يتيح المحرّك نفسه لـ Claude وChatGPT وGemini وCopilot وPerplexity وأي عميل MCP. والأدوات تطابق مسار REST واحدة بواحدة، والاستجابات محدودة بعشرة مواعيد حتى لا تفيض سياقات المحادثة والصوت.
find_availability(business, service, address, date_range?) → slots with labels
hold_slot(slot_id, ttl?) → hold_id
create_booking(hold_id, customer) → confirmed | pending
lookup_bookings(phone | email) → upcoming bookings
reschedule_booking(booking_id, hold_id) ⚠ destructive — agent must confirm
cancel_booking(booking_id, reason?) ⚠ destructive — agent must confirm
get_eta(visit_id) → live arrival estimateالحزم البرمجية والمواصفة وllms.txt
حزم TypeScript وPython مولّدة من مواصفة OpenAPI 3.1، ومكوّن ويب ومكوّن React للأداة المدمجة، وفهرس وثائق مقروء آلياً لوكلاء البرمجة.
npm install @geowise/sdk # TypeScript, typed responses, retries built in
pip install geowise # Python
https://docs.geowise.com/llms.txt # index for agents — Claude Code, Cursor, Lovable, Bolt
npx skills add https://docs.geowise.comتبني بأداة برمجة ذكية؟ موجّه التكامل في صفحة الميزة مكتوب ليُلصق فيها مباشرة.
GeoWise واجهة برمجية أولاً. وكل ما في المنتج متاح عبرها.