Tài liệu tham khảo API

REST API của mapps.one cho phép bạn tạo và cập nhật ứng dụng, quản lý liên kết cửa hàng, nhập siêu dữ liệu cửa hàng, đọc số liệu phân tích, tạo mã QR và đăng ký webhook từ mã nguồn, pipeline CI hoặc tích hợp của riêng bạn. API có trong gói Studio.

Base URL

https://mapps.one/api/v1

Mọi yêu cầu đều dùng HTTPS. Gửi body yêu cầu dưới dạng JSON với Content-Type: application/json, và luôn gửi Accept: application/json để lỗi cũng được trả về dưới dạng JSON.

Xác thực

Tạo token trong bảng điều khiển tại mục Nhà phát triển. Chủ sở hữu và quản trị viên không gian làm việc có thể thực hiện thao tác này. Đặt tên cho token, chẳng hạn "GitHub Actions", và chọn quyền hạn cho token. Token chỉ được hiển thị một lần, vì vậy hãy lưu ngay vào trình quản lý khóa bí mật của bạn.

Token thuộc về không gian làm việc, không thuộc về cá nhân, nên vẫn hoạt động khi có người rời nhóm. Token không hết hạn. Hãy thu hồi token tại cùng trang đó khi bạn không còn cần đến, hoặc nếu token có thể đã bị lộ.

Gửi token dưới dạng bearer token:

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

Quyền hạn

GET /workspace và GET /events hoạt động với mọi token hợp lệ. Chỉ cấp cho mỗi tích hợp những quyền hạn mà tích hợp đó cần.

Quy ước

• ID là ULID gồm 26 ký tự chữ thường, chẳng hạn 01j8b2k6r3xq9v7m4n5p0s1t2w. Ứng dụng được xác định bằng id, không phải bằng slug, nên việc đổi slug không bao giờ làm hỏng tích hợp của bạn.
• Dấu thời gian theo định dạng ISO 8601 ở múi giờ UTC, chẳng hạn 2026-09-14T08:12:44+00:00.
• Phản hồi bọc kết quả trong khóa data.
• Khóa cửa hàng là app_store, google_play, app_gallery, microsoft_store và web.
• Khóa nền tảng là ios, android, huawei, windows, macos và other. Khóa đích đến là các khóa cửa hàng cộng thêm landing.

Giới hạn tốc độ

Mỗi không gian làm việc có thể gửi 120 yêu cầu mỗi phút, dùng chung cho tất cả token của không gian đó. Mọi phản hồi đều có header X-RateLimit-Limit và X-RateLimit-Remaining. Khi bạn vượt quá giới hạn, API phản hồi 429 Too Many Requests kèm header Retry-After cho biết số giây cần chờ.

Lỗi

Lỗi trả về body JSON với message mà con người đọc được. Một số lỗi còn có code mà máy đọc được, và lỗi kiểm tra dữ liệu liệt kê vấn đề theo từng trường trong 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."]
  }
}

Endpoint

Đối tượng ứng dụng

Lấy một ứng dụng

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

Liệt kê ứng dụng

Trả về các ứng dụng trong không gian làm việc. Kết quả được phân trang: hãy đi theo links.next, hoặc truyền ?page=2, cho đến khi giá trị này là 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
  }
}

Các đối tượng ứng dụng trong ví dụ này đã được rút gọn. Mỗi mục thực tế có đầy đủ các trường.

Tạo ứng dụng

Bạn cũng có thể gửi bất kỳ trường nào được liệt kê trong Cập nhật ứng dụng.

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

Phản hồi là 201 Created kèm đối tượng ứng dụng mới. Liên kết cửa hàng được lưu ở dạng chuẩn với trạng thái unverified cho đến khi quá trình kiểm tra trong nền hoàn tất. Để điền biểu tượng, ảnh chụp màn hình và mô tả, hãy gọi tiếp Nhập siêu dữ liệu cửa hàng.

Cập nhật ứng dụng

Chỉ gửi những trường bạn muốn thay đổi.

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

Phản hồi là đối tượng ứng dụng đã được cập nhật.

Xóa ứng dụng

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

Phản hồi là 204 No Content. Việc xóa là vĩnh viễn: liên kết thông minh, landing page, tài liệu pháp lý, tệp media và dữ liệu phân tích của ứng dụng đều bị xóa.

Đặt liên kết cửa hàng

PUT /apps/{id}/links nhận một đối tượng links theo khóa cửa hàng:

• một URL sẽ thêm hoặc thay thế liên kết cho cửa hàng đó,
• null hoặc chuỗi rỗng sẽ xóa liên kết,
• các cửa hàng bạn không gửi sẽ không thay đổi.

Mỗi URL phải là trang ứng dụng hợp lệ của cửa hàng tương ứng: liên kết apps.apple.com có app ID, liên kết play.google.com có package ID, v.v. Liên kết web có thể là bất kỳ địa chỉ http hoặc https nào. URL có thể dài tối đa 1024 ký tự. Liên kết được lưu ở dạng chuẩn và được kiểm tra trong nền.

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

Phản hồi là đối tượng ứng dụng, bao gồm links. Liên kết không hợp lệ trả về 422:

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

Nhập siêu dữ liệu cửa hàng

POST /apps/{id}/metadata đọc trang ứng dụng trên App Store, hoặc trang trên Google Play khi không có liên kết App Store đọc được, và nhập thông tin từ trang đó.

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

Phản hồi là đối tượng ứng dụng, bao gồm links và screenshots, và một webhook app.metadata_fetched được gửi đi. Nếu không đọc được trang ứng dụng nào:

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

Phân tích

GET /apps/{id}/analytics chấp nhận các tham số truy vấn sau:

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 được bao gồm và to bị loại trừ. Cả hai đều là thời điểm theo UTC.
• clamped_to_plan là true khi khoảng thời gian được yêu cầu đã bị rút ngắn theo lịch sử của gói.
• daily đếm lượt nhấp theo ngày địa phương, bao gồm cả những ngày không có lượt nhấp nào.
• Phân tích chi tiết liệt kê tối đa 10 giá trị, giá trị thường gặp nhất xếp trước. Khóa rỗng "" nghĩa là không xác định hoặc chưa được đặt.
• Định nghĩa các chỉ số có trên trang Phân tích.

Mã QR

GET /apps/{id}/qr trả về một hình ảnh. Dùng format=svg (mặc định) hoặc format=png, cùng các tùy chọn giống URL mã QR công khai: fg, bg, margin, ecc, size, logo và download. Xem Mã QR và bộ tài liệu báo chí.

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

Không gian làm việc

GET /workspace trả về không gian làm việc, giới hạn và tính năng của gói, mức sử dụng hiện tại và token đang được dùng. Đây là lệnh gọi đầu tiên phù hợp để kiểm tra xem token có hoạt động hay không.

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

Giới hạn null nghĩa là không giới hạn.

Các loại sự kiện

GET /events liệt kê các loại sự kiện webhook kèm mô tả ngắn. Các tích hợp có thể dùng endpoint này để xây dựng bộ chọn sự kiện.

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

Đăng ký webhook

Tạo đăng ký webhook từ mã nguồn, ví dụ khi người dùng kết nối tích hợp của bạn, và xóa đăng ký khi họ ngắt kết nối. POST /webhooks nhận:

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 dùng để ký chỉ được trả về khi đăng ký được tạo. Hãy dùng giá trị này để xác minh chữ ký. Một không gian làm việc Studio có thể có tối đa 10 endpoint webhook. Xóa đăng ký bằng DELETE /webhooks/{id}, lệnh này trả về 204 No Content.

Ví dụ: xuất bản bản beta từ CI

Script này tạo một ứng dụng, thêm liên kết Google Play, nhập thông tin từ trang ứng dụng và in ra liên kết thông minh. Script cần curl, jq và một token có quyền 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'

Phiên bản

Đây là phiên bản 1 của API. Chúng tôi có thể thêm endpoint, trường và loại sự kiện bất cứ lúc nào, vì vậy hãy bỏ qua các trường bạn không nhận ra. Các thay đổi không tương thích ngược sẽ được phát hành dưới dạng phiên bản mới kèm thông báo trước.