مرجع API

تتيح لك REST API من mapps.one إنشاء التطبيقات وتحديثها، وإدارة روابط المتاجر، واستيراد البيانات الوصفية من المتاجر، وقراءة التحليلات، وإنشاء رموز QR، والاشتراك في الويب هوك من الكود الخاص بك أو من مسار CI أو من تكاملك. تتوفر API في خطة Studio.

عنوان URL الأساسي

https://mapps.one/api/v1

تستخدم جميع الطلبات HTTPS. أرسل نصوص الطلبات بتنسيق JSON مع Content-Type: application/json، وأرسل دائمًا Accept: application/json لتُعاد الأخطاء بتنسيق JSON أيضًا.

المصادقة

أنشئ رمزًا في لوحة التحكم ضمن المطورون. يمكن لمالكي مساحة العمل والمسؤولين القيام بذلك. امنح الرمز اسمًا، مثل "GitHub Actions"، واختر صلاحياته. لا يُعرض الرمز إلا مرة واحدة، لذا احفظه في مدير الأسرار لديك فورًا.

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

أرسل الرمز كرمز Bearer:

curl https://mapps.one/api/v1/workspace \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

الصلاحيات

تعمل GET /workspace وGET /events مع أي رمز صالح. امنح كل تكامل الصلاحيات التي يحتاجها فقط.

الاصطلاحات

• المعرّفات هي معرّفات ULID بأحرف صغيرة من 26 حرفًا، مثل 01j8b2k6r3xq9v7m4n5p0s1t2w. يُشار إلى التطبيقات بالمعرّف id لا بالاسم المختصر، لذا لا تؤدي إعادة تسمية الاسم المختصر إلى تعطيل تكاملك أبدًا.
• الطوابع الزمنية بتنسيق ISO 8601 وبتوقيت UTC، مثل 2026-09-14T08:12:44+00:00.
• تضع الاستجابات النتيجة داخل المفتاح data.
• مفاتيح المتاجر هي app_store وgoogle_play وapp_gallery وmicrosoft_store وweb.
• مفاتيح المنصات هي ios وandroid وhuawei وwindows وmacos وother. ومفاتيح الوجهات هي مفاتيح المتاجر إضافةً إلى landing.

حدود المعدل

يمكن لكل مساحة عمل إجراء 120 طلبًا في الدقيقة، تتشاركها جميع رموزها. وتتضمن كل استجابة الترويستين X-RateLimit-Limit وX-RateLimit-Remaining. وعند تجاوز الحد، تستجيب API بالحالة 429 Too Many Requests مع ترويسة Retry-After تحدد عدد الثواني التي يجب انتظارها.

الأخطاء

تُرجع الأخطاء نص JSON يحتوي على رسالة message مفهومة للبشر. وتتضمن بعض الأخطاء أيضًا رمز خطأ code قابلًا للقراءة آليًا، وتسرد أخطاء التحقق من الصحة المشكلات لكل حقل في errors.

HTTP/2 402
{
  "message": "API access requires the Studio plan.",
  "code": "plan_required"
}

HTTP/2 422
{
  "message": "This link is already taken.",
  "errors": {
    "slug": ["This link is already taken."]
  }
}

نقاط النهاية

كائن التطبيق

جلب تطبيق

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": {
    "id": "01j8b2k6r3xq9v7m4n5p0s1t2w",
    "name": "Habitly",
    "slug": "habitly",
    "status": "live",
    "tagline": "Build habits that stick",
    "description": "Habitly helps you build small daily habits with gentle reminders and streaks.",
    "category": "health-fitness",
    "page_theme": "clean",
    "accent_color": "#16a34a",
    "developer": {
      "name": "Habitly Labs",
      "website": "https://habitly.app",
      "email": "hello@habitly.app"
    },
    "social_links": {
      "instagram": "https://instagram.com/habitly.app"
    },
    "features": [
      { "icon": "bell", "title": "Gentle reminders", "description": "Nudges at the time you choose." }
    ],
    "listed_in_explore": true,
    "utm_passthrough": true,
    "redirect_rules": {
      "ios": "app_store",
      "android": "google_play",
      "huawei": "app_gallery",
      "windows": "microsoft_store",
      "macos": "landing",
      "other": "landing"
    },
    "icon_url": "https://mapps.one/storage/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/icon/icon.png",
    "rating": { "value": 4.8, "count": 12450 },
    "urls": {
      "smart_link": "https://mapps.one/habitly",
      "landing_page": "https://mapps.one/habitly/page",
      "qr_svg": "https://mapps.one/habitly/qr.svg",
      "qr_png": "https://mapps.one/habitly/qr.png",
      "privacy_policy": "https://mapps.one/habitly/privacy",
      "terms": "https://mapps.one/habitly/terms"
    },
    "links": {
      "app_store": {
        "url": "https://apps.apple.com/app/id1612345678",
        "status": "verified",
        "verified_at": "2026-09-14T08:12:44+00:00"
      },
      "google_play": {
        "url": "https://play.google.com/store/apps/details?id=com.habitly.app",
        "status": "verified",
        "verified_at": "2026-09-14T08:12:46+00:00"
      }
    },
    "created_at": "2026-09-01T11:20:03+00:00",
    "updated_at": "2026-09-14T08:12:46+00:00"
  }
}

عرض قائمة التطبيقات

تُرجع التطبيقات الموجودة في مساحة العمل. والنتائج مقسّمة إلى صفحات: اتبع links.next، أو مرّر ?page=2، إلى أن تصبح قيمته null.

curl "https://mapps.one/api/v1/apps?page=1" \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": [
    { "id": "01j8b2k6r3xq9v7m4n5p0s1t2w", "name": "Habitly", "slug": "habitly", "status": "live" },
    { "id": "01j8d5r2w9y6a3c0e7g4j1m8p5", "name": "Habitly Focus", "slug": "habitly-focus", "status": "paused" }
  ],
  "links": {
    "first": "https://mapps.one/api/v1/apps?page=1",
    "last": "https://mapps.one/api/v1/apps?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 2
  }
}

كائنات التطبيقات مختصرة في هذا المثال. ويحتوي كل عنصر على المجموعة الكاملة من الحقول.

إنشاء تطبيق

يمكنك أيضًا إرسال أي من الحقول المدرجة ضمن تحديث تطبيق.

curl https://mapps.one/api/v1/apps \
  -X POST \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Habitly",
    "slug": "habitly",
    "links": {
      "app_store": "https://apps.apple.com/us/app/habitly/id1612345678",
      "google_play": "https://play.google.com/store/apps/details?id=com.habitly.app"
    }
  }'

تكون الاستجابة 201 Created مع كائن التطبيق الجديد. تُحفظ روابط المتاجر بالصيغة القياسية مع الحالة unverified إلى أن ينتهي التحقق في الخلفية. ولتعبئة الأيقونة ولقطات الشاشة والوصف، استدعِ استيراد البيانات الوصفية من المتجر بعد ذلك.

تحديث تطبيق

أرسل الحقول التي تريد تغييرها فقط.

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w \
  -X PATCH \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tagline": "Tiny habits, big changes",
    "redirect_rules": { "macos": "landing" }
  }'

تكون الاستجابة كائن التطبيق بعد التحديث.

حذف تطبيق

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w \
  -X DELETE \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

تكون الاستجابة 204 No Content. والحذف نهائي: يُزال الرابط الذكي للتطبيق وصفحته المقصودة ومستنداته القانونية ووسائطه وتحليلاته.

تعيين روابط المتاجر

تقبل PUT /apps/{id}/links كائن links مفاتيحه أسماء المتاجر:

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

يجب أن يكون كل عنوان URL إدراجًا صالحًا في متجره: رابط apps.apple.com يتضمن معرّف التطبيق، ورابط play.google.com يتضمن معرّف الحزمة، وهكذا. ويمكن أن يكون رابط web أي عنوان http أو https. ويمكن أن يصل طول عناوين URL إلى 1024 حرفًا. تُحفظ الروابط بالصيغة القياسية ويُتحقق منها في الخلفية.

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/links \
  -X PUT \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "links": {
      "app_gallery": "https://appgallery.huawei.com/app/C109876543",
      "web": null
    }
  }'

تكون الاستجابة كائن التطبيق، بما في ذلك links. ويُرجع الرابط غير الصالح 422:

{
  "message": "This is not a valid Google Play link.",
  "errors": {
    "links.google_play": ["This is not a valid Google Play link."]
  }
}

استيراد البيانات الوصفية من المتجر

تقرأ POST /apps/{id}/metadata إدراج App Store، أو إدراج Google Play عند عدم وجود رابط App Store قابل للقراءة، وتستورد تفاصيله.

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/metadata \
  -X POST \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "overwrite": true }'

تكون الاستجابة كائن التطبيق، بما في ذلك links وscreenshots، ويُرسَل ويب هوك app.metadata_fetched. وإذا تعذّرت قراءة أي إدراج:

HTTP/2 422
{
  "message": "The store listing could not be read. Add a valid App Store or Google Play link first.",
  "code": "metadata_unavailable"
}

التحليلات

تقبل GET /apps/{id}/analytics معلمات الاستعلام التالية:

curl "https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/analytics?range=7d&timezone=Europe/Istanbul" \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": {
    "app": { "id": "01j8b2k6r3xq9v7m4n5p0s1t2w", "slug": "habitly" },
    "range": {
      "key": "7d",
      "from": "2026-09-07T21:00:00+00:00",
      "to": "2026-09-14T21:00:00+00:00",
      "timezone": "Europe/Istanbul",
      "clamped_to_plan": false
    },
    "summary": {
      "clicks": 1284,
      "visitors": 902,
      "page_views": 356,
      "store_clicks": 141
    },
    "daily": {
      "2026-09-08": 152,
      "2026-09-09": 171,
      "2026-09-10": 168,
      "2026-09-11": 205,
      "2026-09-12": 214,
      "2026-09-13": 190,
      "2026-09-14": 184
    },
    "breakdowns": {
      "os": { "iOS": 702, "Android": 431, "Windows": 88, "macOS": 63 },
      "country": { "TR": 512, "US": 298, "": 236, "DE": 141, "GB": 97 },
      "source": { "instagram": 488, "direct": 402, "qr": 190, "google": 121, "x": 83 },
      "destination": { "app_store": 640, "google_play": 399, "landing": 214, "deep_link": 31 },
      "utm_campaign": { "": 796, "launch": 402, "newsletter-sep": 86 }
    }
  }
}

• يُضمَّن from ويُستثنى to. وكلاهما لحظة زمنية بتوقيت UTC.
• تكون قيمة clamped_to_plan هي true عندما يُقصَّر النطاق المطلوب ليتوافق مع سجل الخطة.
• يحتسب daily النقرات لكل تاريخ محلي، بما في ذلك الأيام التي لا نقرات فيها.
• تسرد التفصيلات ما يصل إلى 10 قيم، بدءًا بالأكثر تكرارًا. والمفتاح الفارغ "" يعني غير معروف أو غير محدد.
• تعريفات المقاييس موجودة في صفحة التحليلات.

رمز QR

تُرجع GET /apps/{id}/qr صورة. استخدم format=svg (الافتراضي) أو format=png، إلى جانب الخيارات نفسها المتاحة في عناوين URL العامة لرمز QR: fg وbg وmargin وecc وsize وlogo وdownload. راجع رموز QR والحقيبة الصحفية.

curl "https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/qr?format=png&size=2048&ecc=Q" \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -o habitly-qr.png

مساحة العمل

تُرجع GET /workspace مساحة العمل، وحدود خطتها وميزاتها، والاستخدام الحالي، والرمز المستخدم. وهي استدعاء أول مناسب للتحقق من أن الرمز يعمل.

{
  "data": {
    "id": "01j8a0f4c7d2e9h6k3m5n8q1r4",
    "name": "Habitly Labs",
    "plan": {
      "key": "studio",
      "name": "Studio",
      "limits": {
        "apps": null,
        "analytics_days": 730,
        "members": 10,
        "custom_domains": 25,
        "legal_locales": null,
        "screenshots": 10,
        "webhooks": 10
      },
      "features": ["remove_badge", "all_themes", "accent_color", "qr_logo", "legal_full", "deep_links", "press_kit", "analytics_export", "custom_domains", "team", "folders", "ab_testing", "api", "webhooks", "white_label"]
    },
    "usage": { "apps": 12, "custom_domains": 3, "members": 4 },
    "token": { "name": "GitHub Actions", "abilities": ["apps:read", "apps:write"] }
  }
}

الحد الذي قيمته null يعني عدم وجود حد.

أنواع الأحداث

تسرد GET /events أنواع أحداث الويب هوك مع وصف قصير لكل منها. ويمكن للتكاملات استخدامها لبناء أداة اختيار الأحداث.

{
  "data": [
    { "type": "app.created", "description": "An app was added to the workspace." },
    { "type": "app.updated", "description": "App details, links or page settings changed." },
    { "type": "app.deleted", "description": "An app was deleted." },
    { "type": "app.status_changed", "description": "An app went live, was paused or was suspended." },
    { "type": "app.metadata_fetched", "description": "Store metadata was imported for an app." },
    { "type": "legal.published", "description": "A privacy policy or terms document was published." },
    { "type": "domain.verified", "description": "A custom domain was verified." },
    { "type": "link.clicked", "description": "Every smart link click. High volume." },
    { "type": "analytics.daily_summary", "description": "Yesterday's click totals for each app, sent once a day." }
  ]
}

اشتراكات الويب هوك

أنشئ اشتراكات الويب هوك من الكود، على سبيل المثال عند ربط أحد المستخدمين لتكاملك، واحذفها عند فصل التكامل. تقبل POST /webhooks الحقول التالية:

curl https://mapps.one/api/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/catch/1234567/abcde12/",
    "events": ["link.clicked"],
    "description": "Zapier: clicks to Google Sheets"
  }'

HTTP/2 201
{
  "data": {
    "id": "01j8c1p4s7v0y3b6e9h2k5n8q1",
    "url": "https://hooks.zapier.com/hooks/catch/1234567/abcde12/",
    "events": ["link.clicked"],
    "description": "Zapier: clicks to Google Sheets",
    "is_active": true,
    "secret": "9f2c4e7a1b8d3f6e0a5c2b9d7e4f1a3c6b8d0e2f4a6c8e0b2d4f6a8c0e2b4d61",
    "created_at": "2026-09-14T10:05:12+00:00"
  }
}

لا يُعاد سر التوقيع secret إلا عند إنشاء الاشتراك. استخدمه للتحقق من التوقيعات. ويمكن أن تحتوي مساحة عمل Studio على ما يصل إلى 10 نقاط نهاية للويب هوك. احذف الاشتراك باستخدام DELETE /webhooks/{id}، التي تُرجع 204 No Content.

مثال: نشر إصدار تجريبي من CI

ينشئ هذا النص البرمجي تطبيقًا، ويضيف رابط Google Play الخاص به، ويستورد الإدراج، ويطبع الرابط الذكي. ويحتاج إلى curl وjq ورمز يملك الصلاحية apps:write.

#!/usr/bin/env bash
set -euo pipefail

API="https://mapps.one/api/v1"
HEADERS=(-H "Authorization: Bearer $MAPPS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json")

APP_ID=$(curl -sf "${HEADERS[@]}" -X POST "$API/apps" \
  -d '{"name": "Habitly Beta", "slug": "habitly-beta"}' | jq -r '.data.id')

curl -sf "${HEADERS[@]}" -X PUT "$API/apps/$APP_ID/links" \
  -d '{"links": {"google_play": "https://play.google.com/store/apps/details?id=com.habitly.beta"}}' > /dev/null

curl -sf "${HEADERS[@]}" -X POST "$API/apps/$APP_ID/metadata" \
  -d '{"overwrite": true}' | jq -r '.data.urls.smart_link'

الإصدارات

هذا هو الإصدار 1 من API. قد نضيف نقاط نهاية وحقولًا وأنواع أحداث في أي وقت، لذا تجاهل الحقول التي لا تعرفها. وستُطرح التغييرات غير المتوافقة مع الإصدارات السابقة كإصدار جديد مع إشعار مسبق.