API başvurusu

mapps.one REST API ile kendi kodundan, CI sürecinden ya da entegrasyonundan uygulama oluşturabilir ve güncelleyebilir, mağaza bağlantılarını yönetebilir, mağaza bilgilerini içe aktarabilir, analitiği okuyabilir, QR kod oluşturabilir ve webhook'lara abone olabilirsin. API, Studio planında kullanılabilir.

Temel adres

https://mapps.one/api/v1

Tüm istekler HTTPS kullanır. İstek gövdelerini Content-Type: application/json ile JSON olarak gönder; hataların da JSON olarak dönmesi için her zaman Accept: application/json gönder.

Kimlik doğrulama

Panelde Geliştiriciler bölümünden bir token oluştur. Bunu çalışma alanı sahipleri ve yöneticileri yapabilir. Token'a "GitHub Actions" gibi bir ad ver ve yetkilerini seç. Token yalnızca bir kez gösterilir; hemen gizli anahtar yöneticine kaydet.

Token'lar bir kişiye değil çalışma alanına aittir, bu yüzden biri ekipten ayrıldığında çalışmaya devam eder. Süreleri dolmaz. Artık ihtiyacın olmadığında ya da sızmış olabileceğini düşündüğünde token'ı aynı sayfadan iptal et.

Token'ı bearer token olarak gönder:

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

Yetkiler

GET /workspace ve GET /events geçerli her token'la çalışır. Her entegrasyona yalnızca ihtiyaç duyduğu yetkileri ver.

Kurallar

• Kimlikler, 01j8b2k6r3xq9v7m4n5p0s1t2w gibi 26 karakterlik küçük harfli ULID'lerdir. Uygulamalara bağlantı adıyla değil id ile erişilir; böylece bağlantı adını değiştirmek entegrasyonunu bozmaz.
• Zaman damgaları UTC'de ISO 8601 biçimindedir, örneğin 2026-09-14T08:12:44+00:00.
• Yanıtlar sonucu bir data anahtarı içinde döndürür.
• Mağaza anahtarları: app_store, google_play, app_gallery, microsoft_store ve web.
• Platform anahtarları: ios, android, huawei, windows, macos ve other. Hedef anahtarları, mağaza anahtarlarına ek olarak landing'dir.

İstek sınırları

Her çalışma alanı dakikada 120 istek yapabilir; bu sınırı tüm token'ları ortak kullanır. Her yanıtta X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları bulunur. Sınırı aştığında API, beklemen gereken saniyeyi belirten bir Retry-After başlığıyla 429 Too Many Requests döndürür.

Hatalar

Hatalar, insanların okuyabileceği bir message içeren JSON gövdesi döndürür. Bazı hatalar makinelerin okuyabileceği bir code da içerir; doğrulama hataları ise sorunları alan bazında errors içinde listeler.

Hata mesajları API'de İngilizce döner:

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."]
  }
}

Uç noktalar

Uygulama nesnesi

Bir uygulamayı getirme

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"
  }
}

Uygulamaları listeleme

Çalışma alanındaki uygulamaları döndürür. Sonuçlar sayfalara bölünür: links.next değeri null olana kadar onu izle ya da ?page=2 gönder.

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
  }
}

Bu örnekte uygulama nesneleri kısaltılmıştır. Her öğe tüm alanları içerir.

Uygulama oluşturma

Uygulamayı güncelleme bölümünde listelenen alanları da gönderebilirsin.

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"
    }
  }'

Yanıt, yeni uygulama nesnesiyle birlikte 201 Created olur. Mağaza bağlantıları standart biçimde kaydedilir ve arka plan kontrolü bitene kadar durumları unverified olur. Simge, ekran görüntüleri ve açıklamayı doldurmak için ardından Mağaza bilgilerini içe aktarma uç noktasını çağır.

Uygulamayı güncelleme

Yalnızca değiştirmek istediğin alanları gönder.

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" }
  }'

Yanıt, güncellenmiş uygulama nesnesidir.

Uygulamayı silme

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

Yanıt 204 No Content olur. Silme işlemi kalıcıdır: uygulamanın akıllı bağlantısı, açılış sayfası, yasal belgeleri, medyası ve analitiği kaldırılır.

Mağaza bağlantılarını ayarlama

PUT /apps/{id}/links, mağazaya göre anahtarlanmış bir links nesnesi alır:

• bir URL, o mağazanın bağlantısını ekler ya da değiştirir,
• null ya da boş bir metin bağlantıyı kaldırır,
• göndermediğin mağazalar değişmez.

Her URL kendi mağazası için geçerli bir sayfa olmalıdır: uygulama kimliği içeren bir apps.apple.com bağlantısı, paket kimliği içeren bir play.google.com bağlantısı gibi. web bağlantısı herhangi bir http ya da https adresi olabilir. URL'ler en fazla 1024 karakter olabilir. Bağlantılar standart biçimde kaydedilir ve arka planda kontrol edilir.

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
    }
  }'

Yanıt, links dahil uygulama nesnesidir. Geçersiz bir bağlantı 422 döndürür:

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

Mağaza bilgilerini içe aktarma

POST /apps/{id}/metadata, App Store sayfasını ya da okunabilir bir App Store bağlantısı yoksa Google Play sayfasını okur ve bilgilerini içe aktarır.

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 }'

Yanıt, links ve screenshots dahil uygulama nesnesidir; ayrıca bir app.metadata_fetched webhook'u gönderilir. Hiçbir mağaza sayfası okunamazsa:

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

Analitik

GET /apps/{id}/analytics şu sorgu parametrelerini kabul eder:

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 dahildir, to hariçtir. İkisi de UTC anlarıdır.
• İstenen aralık planın geçmişine göre kısaltıldıysa clamped_to_plan true olur.
• daily, tıklama olmayan günler dahil yerel tarih başına tıklamaları sayar.
• Kırılımlar en sık görülenden başlayarak en fazla 10 değer listeler. Boş anahtar "" bilinmiyor ya da ayarlanmamış demektir.
• Metriklerin tanımları Analitik sayfasında.

QR kod

GET /apps/{id}/qr bir görsel döndürür. format=svg (varsayılan) ya da format=png ile birlikte herkese açık QR adresleriyle aynı seçenekleri kullan: fg, bg, margin, ecc, size, logo ve download. Ayrıntılar QR kodlar ve basın kiti sayfasında.

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

Çalışma alanı

GET /workspace; çalışma alanını, plan sınırlarını ve özelliklerini, güncel kullanımı ve kullanılan token'ı döndürür. Bir token'ın çalıştığını kontrol etmek için iyi bir ilk çağrıdır.

{
  "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 sınır, sınırsız demektir.

Olay türleri

GET /events, webhook olay türlerini kısa açıklamalarıyla listeler. Entegrasyonlar bunu bir olay seçici oluşturmak için kullanabilir. Açıklamalar İngilizce döner.

{
  "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." }
  ]
}

Webhook abonelikleri

Webhook aboneliklerini koddan oluştur, örneğin bir kullanıcı entegrasyonunu bağladığında; bağlantıyı kestiğinde de sil. POST /webhooks şunları alır:

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"
  }
}

İmzalama anahtarı secret yalnızca abonelik oluşturulurken döndürülür. Onu imzaları doğrulamak için kullan. Bir Studio çalışma alanında en fazla 10 webhook uç noktası olabilir. Bir aboneliği DELETE /webhooks/{id} ile sil; yanıt 204 No Content olur.

Örnek: CI'dan beta yayınlama

Bu betik bir uygulama oluşturur, Google Play bağlantısını ekler, mağaza sayfasını içe aktarır ve akıllı bağlantıyı yazdırır. curl, jq ve apps:write yetkili bir token gerekir.

#!/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'

Sürümler

Bu, API'nin 1. sürümüdür. İstediğimiz zaman yeni uç noktalar, alanlar ve olay türleri ekleyebiliriz; bu yüzden tanımadığın alanları yok say. Uyumluluğu bozan değişiklikler önceden duyurularak yeni bir sürüm olarak yayınlanır.