Playbox
Open app

Playbox Organizer API

წაიკითხე მონაცემები შენი თამაშების, ლიგებისა და მატჩების შესახებ შენი სკრიპტიდან ან სერვერიდან: ვინ ითამაშა და როგორ გადაიხადა, ცხრილები, საუკეთესო ბომბარდირები, გოლები, ბარათები და ნათელი მომენტები. მხოლოდ წასაკითხია და მხოლოდ შენს მონაცემებს აბრუნებს.

საბაზისო URL: https://app.play-box.xyz/api/organizer/v1/

პირველი მოთხოვნა 5 წუთში

  1. მიიღე გასაღები. Playbox აპლიკაციაში გახსენი პარამეტრები → ორგანიზატორის ხელსაწყოები → API გასაღებები → გასაღების შექმნა. მიეცი გასაღებს სახელი და მონიშნე „ვეთანხმები API-ის პირობებს“. გასაღები ასე გამოიყურება: pbo_xxxxxxxx.long-secret და მხოლოდ ერთხელ ჩანს. შეინახე ის შენი სერვერის გარემოს ცვლადებში.
  2. შეამოწმე კავშირი.
curl -H "X-Api-Key: $PLAYBOX_KEY" https://app.play-box.xyz/api/organizer/v1/me/

200 პასუხი აბრუნებს შენს მომხმარებლის სახელს, გასაღების სახელს და თარიღს, რომლამდეც გასაღები მოქმედებს.

  1. მიიღე შენი თამაშები.
curl -H "X-Api-Key: $PLAYBOX_KEY" "https://app.play-box.xyz/api/organizer/v1/events/?from=2026-09-01&status=FINISHED"

გასაღები

რა ითვლება შენს მონაცემებად

სხვისი თამაში ან ლიგა 404-ს აბრუნებს, ისევე როგორც ის, რომელიც არ არსებობს. მოთამაშეების კონტაქტები და ფოტოები არასდროს ბრუნდება.

ლიმიტები

წუთში 60 მოთხოვნა თითო გასაღებზე. მოთხოვნა არის ნებისმიერ API URL-ზე ერთი მიმართვა სწორი გასაღებით, 404 და 400 პასუხების ჩათვლით. ფანჯარა ყოველი წუთის დასაწყისში ნულდება.

პასუხის ჰედერიმნიშვნელობა
X-RateLimit-Limitლიმიტი წუთში
X-RateLimit-Remainingმიმდინარე წუთში დარჩენილი მოთხოვნები
X-RateLimit-Resetწამები ფანჯრის განულებამდე
Retry-Afterმხოლოდ 429-ზე: რამდენი წამი უნდა დაელოდო ხელახლა ცდამდე

შეინახე მონაცემები შენს მხარეს და მოითხოვე მხოლოდ ახალი: ბოლო თამაშები from-ით და დასრულებული თამაშების მატჩები. თუ მთელ ისტორიას ყოველ ჯერზე ხელახლა ჩამოტვირთავ, როცა შენი საიტი იხსნება, ლიმიტს წამებში ამოწურავ.

შეცდომები

ყველა შეცდომას ერთი და იგივე ფორმა აქვს. ლოგიკა code-ზე ააგე, message კი ლოგში ჩაწერე.

{"error": {"code": "invalid_parameter", "message": "from: Use YYYY-MM-DD.", "fields": {"from": "Use YYYY-MM-DD."}}}
HTTPcodeრა უნდა გააკეთო
401not_authenticatedგასაღების ჰედერი აკლია
401invalid_keyგასაღები არასწორია ან გაუქმებულია, შექმენი ახალი
401key_expiredგასაღებს ვადა გაუვიდა, შექმენი ახალი
403browser_not_allowedმოთხოვნა ბრაუზერიდან მოვიდა, API-ს შენი სერვერიდან მიმართე
404not_foundობიექტი არ არსებობს ან შენი არ არის
400invalid_parameterპარამეტრი არასწორია, დეტალები fields-შია
405method_not_allowedAPI მხოლოდ წასაკითხია, გამოიყენე GET
429rate_limitedდაელოდე retry_after წამი

მონაცემების ფორმატი

ენდპოინტები

GET /me/

ვისია ეს გასაღები: მომხმარებელი, გასაღების სახელი, ვადის გასვლის თარიღი, პირობების ვერსია, ლიმიტები.

GET /leagues/

შენი ლიგები: id, slug, name, status (active, finished, archived), format, city, date_start, date_end, teams_count, price, game_price, url.

GET /leagues/{id}/

ლიგა და მისი წესები: ტექნიკური წაგება, დისციპლინა (ყვითელი ბარათების ლიმიტი, დისკვალიფიკაციები), შემადგენლობის ზომა.

GET /leagues/{id}/table/

ტურნირის ცხრილი იმავე თანმიმდევრობით, როგორც აპლიკაციაში: position, team, played, wins, draws, losses, goals_for, goals_against, goal_difference, points.

GET /leagues/{id}/players/

მოთამაშეების ცხრილი: player, team, position, games, goals, assists, yellow_cards, red_cards, suspension_games_left. დალაგებულია გოლებით, შემდეგ ასისტებით.

GET /leagues/{id}/rosters/

გუნდების შემადგენლობები: თითოეული გუნდი თავისი მოთამაშეებით და მათი დამატების თარიღით.

GET /events/

შენი თამაშები, ჯერ უახლესი. ფილტრები: from, to (YYYY-MM-DD დაწყების თარიღით, UTC), status (NOT_STARTED, STARTED, FINISHED, CANCELLED), league (id), format (მოთამაშეები გუნდში, მაგალითად 8). ველები: id, league_id, starts_at, ends_at, status, results_status, format, venue, is_paid, price, price_per_player, capacity, players_count, teams_count, is_ranked, is_private, url.

GET /events/{id}/

მთელი თამაში: გუნდები (ფერი, მოგებები, ფრეები, წაგებები, შემადგენლობა), მატჩები ანგარიშით და url-ით, mvp_player_id, YouTube ჩანაწერები, პირდაპირი ეთერები.

GET /events/{id}/participants/

ვინ ჩაეწერა და როგორ გადაიხადა: player, status (In game, Late, Did not come, Invited), team_id, joined_at, payment_method (CASH, WALLET, CARD, STRIPE, APPLE_PAY, GOOGLE_PAY, TELEGRAM), paid, payment_confirmed, paid_by, amount, is_early_bird. ეს მონაცემები მხოლოდ შენთვისაა: ნუ გამოაქვეყნებ.

GET /events/{id}/player-stats/

თითოეული მოთამაშის შედეგი თამაშში: wins, draws, losses, goals, assists, goals_conceded, yellow_cards, red_cards, rating, rating_change, is_confirmed. ხელმისაწვდომია თამაშის დასრულების შემდეგ.

GET /matches/{id}/

მთელი მატჩი: event_id, league_id, number, tour, starts_at, ends_at, state, teams, score, technical_defeat, referee, video_url, url, timeline (ქრონოლოგია), penalty_shootout (პენალტების სერია), lineups (ვინ დაიწყო, წამები მოედანზე) და highlights (ნათელი მომენტები YouTube ბმულებად).

"timeline": [
  {"type": "period", "half": 1, "is_extra_time": false, "started_at": "...", "ended_at": "...", "duration_seconds": 1200},
  {"type": "goal", "game_time_seconds": 305, "team_id": 1, "player": {}, "assistant": {}, "is_own_goal": false, "youtube_url": "..."},
  {"type": "card", "game_time_seconds": 700, "team_id": 2, "player": {}, "card": "YELLOW", "reason": "Dissent"},
  {"type": "substitution", "game_time_seconds": 900, "team_id": 2, "player_out": {}, "player_in": {}, "until_end": true}
]

მაგალითები

Python

import os, requests

API = "https://app.play-box.xyz/api/organizer/v1"
session = requests.Session()
session.headers["X-Api-Key"] = os.environ["PLAYBOX_KEY"]

def fetch_all(path, **params):
    offset = 0
    while offset is not None:
        page = session.get(f"{API}/{path}", params={**params, "offset": offset, "limit": 100}).json()
        yield from page["results"]
        offset = page["next_offset"]

for event in fetch_all("events/", status="FINISHED", **{"from": "2026-09-01"}):
    detail = session.get(f"{API}/events/{event['id']}/").json()
    for match in detail["matches"]:
        print(event["starts_at"], match["score"], match["url"])

JavaScript (Node 18+, სერვერის მხარე)

const API = "https://app.play-box.xyz/api/organizer/v1";
const headers = { "X-Api-Key": process.env.PLAYBOX_KEY };

const res = await fetch(`${API}/leagues/8/players/`, { headers });
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const { results } = await res.json();
console.log(results.slice(0, 10).map(r => `${r.player.username}: ${r.goals}`));

გამოყენების პირობები (ვერსია 2026-10-01)

ვერსიები

ვერსია URL-შია (v1). პასუხებში ახალი ველები შეიძლება ვერსიის შეცვლის გარეშე გამოჩნდეს, ამიტომ უცნობ ველებზე შეცდომას ნუ ისვრი. ველის წაშლა ან გადარქმევა მხოლოდ v2-ში მოხდება, v1 კი მუშაობას გააგრძელებს.