דלגו לתוכן
Guidez DocsGuidez Docsמרכז העזרה של Guidez

מדריך ה-API

כתובת בסיס: https://api.guidez.app/developer-api/v1

כל בקשה שולחת את המפתח בכותרת Authorization. התשובות הן JSON עם שדות ב-camelCase. הזמנים בפורמט ISO-8601 ב-UTC.

Authorization: Bearer gz_live_...

חדשים ב-API? התחילו בAPI למפתחים כדי לקבל מפתח.

רשימת המפות

Section titled “רשימת המפות”
GET /maps

המפות שהיוצר/ת פרסמו, לפי הסדר שבו הם סידרו אותן. כל פריט הוא תצוגה מקדימה של מפה.

Terminal window
curl https://api.guidez.app/developer-api/v1/maps \
  -H "Authorization: Bearer $GUIDEZ_API_KEY"

מפה אחת

Section titled “מפה אחת”
GET /maps/{mapId}

תצוגה מקדימה של מפה אחת, לפי ה-mapId מהרשימה.

Terminal window
curl https://api.guidez.app/developer-api/v1/maps/3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $GUIDEZ_API_KEY"

תצוגה מקדימה של מפה

Section titled “תצוגה מקדימה של מפה”
{
  "mapId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
  "title": "Lisbon Food Crawl",
  "subtitle": "24 tried-and-true stops",
  "description": "Every stop worth your appetite.",
  "coverUrl": "https://media.guidez.app/...",
  "placeCount": 24,
  "isPaid": true,
  "priceCents": 4900,
  "currency": "ILS",
  "landingPageUrl": "https://web.guidez.app/map-preview/lisbon-food-crawl-3f2a9c1e5b7d",
  "mapUrl": "https://web.guidez.app/map/lisbon-food-crawl-3f2a9c1e5b7d",
  "isHidden": false,
  "updatedAt": "2026-10-20T08:14:03"
}
שדה הערות
title, subtitle, description מדף הנחיתה של המפה כשיש לה כזה, ואחרת מהמפה עצמה. subtitle ו-description יכולים להיות null.
coverUrl תמונת השער של דף הנחיתה, או תמונה מהמפה כשאין כזו. יכול להיות null.
isPaid true כשהמפה נמכרת. במפות חינמיות priceCents ו-currency הם null.
landingPageUrl דף המכירה של המפה ב-Guidez. כפתורי “לקבלת המפה” צריכים להוביל לכאן. null כשלמפה אין דף נחיתה מפורסם.
mapUrl פותח את המפה עצמה ב-Guidez.
isHidden מפורסמת, אבל לא מוצגת בפרופיל של היוצר/ת ב-Guidez.

התצוגה המקדימה אף פעם לא כוללת את המקומות במפה. מטיילים מקבלים אותם ב-Guidez.

המכירות של מפה

Section titled “המכירות של מפה”
GET /maps/{mapId}/sales

המכירות שהושלמו של המפה לאורך זמן, מקובצות לתקופות. רכישות בדיקה והחזרים לא נספרים.

פרמטר ברירת מחדל הערות
start 30 יום לפני end תאריך ושעה בפורמט ISO-8601, כולל. UTC כשלא מצוין הפרש שעות.
end עכשיו תאריך ושעה בפורמט ISO-8601, לא כולל. חייב להיות אחרי start.
interval day day, week (שני עד ראשון) או month, ב-UTC.
Terminal window
curl "https://api.guidez.app/developer-api/v1/maps/3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f/sales?start=2026-03-01T00:00:00Z&end=2026-04-01T00:00:00Z&interval=week" \
  -H "Authorization: Bearer $GUIDEZ_API_KEY"
{
  "mapId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
  "start": "2026-03-01T00:00:00",
  "end": "2026-04-01T00:00:00",
  "interval": "week",
  "totalSalesCount": 7,
  "totalRevenueCents": { "ILS": 34300 },
  "buckets": [
    { "start": "2026-02-23T00:00:00", "salesCount": 1, "revenueCents": { "ILS": 4900 } },
    { "start": "2026-03-02T00:00:00", "salesCount": 0, "revenueCents": {} },
    { "start": "2026-03-09T00:00:00", "salesCount": 4, "revenueCents": { "ILS": 19600 } },
    { "start": "2026-03-16T00:00:00", "salesCount": 0, "revenueCents": {} },
    { "start": "2026-03-23T00:00:00", "salesCount": 2, "revenueCents": { "ILS": 9800 } },
    { "start": "2026-03-30T00:00:00", "salesCount": 0, "revenueCents": {} }
  ]
}
  • לכל תקופה יש דלי, עם 0 כשלא היו מכירות, כך שאפשר להציג את הרשימה בגרף כמו שהיא.
  • ה-start של דלי הוא תחילת היום, השבוע או החודש שלו, ולכן הראשון יכול להתחיל לפני ה-start שלכם. רק מכירות בתוך הטווח שלכם נספרות.
  • ההכנסות לפי מטבע. revenueCents ממפה קוד מטבע לסכום שהקונים שילמו, לפני עמלות, כי מפה יכולה להימכר ביותר ממטבע אחד.
  • עד 1000 דליים בבקשה. לטווחים ארוכים השתמשו ב-week או ב-month.

שגיאות

Section titled “שגיאות”

שגיאות מחזירות JSON עם הודעה בשדה detail.

סטטוס משמעות
401 המפתח חסר, שגוי או בוטל.
404 המפה לא של היוצר/ת הזה, או שאינה מפורסמת.
422 פרמטר לא תקין, למשל start אחרי end או יותר מדי דליים.
429 יותר מ-120 בקשות בדקה עם המפתח הזה. נסו שוב אחרי מספר השניות ב-Retry-After.