AISOLUS Padel API

Base URL

All methods are called relative to the base URL of your platform server. Examples use your-server in its place; substitute the address you received at setup:

https://your-server/api

Paths in the reference start with the version: for example, the full URL of the club list is https://your-server/api/v1/clubs. Transport is HTTPS with UTF-8 JSON; dates are YYYY-MM-DD, times HH:MM, timestamps ISO 8601, amounts whole Russian roubles.

Health check: GET https://your-server/api/v1/health returns {"status": "ok", "service": "padel-api", …}.

Access types

Every cloud method in the reference states its access type. There are five; a sixth, the integration key, applies on the court server.

Player token: SMS sign-in

A player signs in with a phone number. The cloud sends a code by SMS; the code is exchanged for a pair of tokens: a short-lived access token and a long-lived refresh token.

# 1. Request a code (Russian number: +7…, 8… or 10 digits)
curl -X POST "https://your-server/api/v1/auth/phone" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+79000000001"}'
# → {"ok": true, "ttl_min": 5}

# 2. Exchange the SMS code for tokens
curl -X POST "https://your-server/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+79000000001", "code": "<SMS code>"}'
# → {"access_token": "…", "refresh_token": "…", "token_type": "bearer",
#    "expires_in": 900, "is_new": false, "user_id": "…"}

# 3. Refresh the access token when it expires (the old refresh_token is revoked)
curl -X POST "https://your-server/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh token>"}'

• The access token is an RS256-signed JWT; its lifetime comes in expires_in (seconds, 900 — 15 minutes — by default). The refresh token lives 30 days by default and is replaced on every refresh.
• An SMS code is valid for 5 minutes; up to 5 attempts per code; up to 5 SMS per number per hour. Over the limit — 429 too_many_requests or too_many_attempts.
• Sign-in errors: 400 bad_phone, 400 wrong_code, 400 code_expired, 401 invalid_refresh.
• Sign out on a device: POST /v1/auth/logout with the same body as refresh — the refresh token is revoked.
• Phone sign-in currently supports Russian numbers (+7) only.

Club panel account

Panel login and password are issued by the club or the network owner. Sign-in is POST /v1/admin/login with login, password and, if two-factor is on for the account, code from the authenticator app; the response holds a shift token (12 hours). Club panel methods are not part of the public reference; among the published ones, a staff account is needed for POST /v1/matches/{match_id}/score-correction.

Court server club token

Issued per club when AISOLUS courts are connected and shown once: the cloud stores only its hash. Re-issuing replaces the previous token. The token goes in the X-Club-Token header (header names are case-insensitive). Details are in the Court server and cloud guide.

1C token

One token per integration, sent in the X-1C-Token header. While the token is not set in the cloud, the integration is off and every method returns 401 bad_1c_token. See 1C payment import.

Getting access

Club tokens, 1C tokens and staff accounts are issued by the AISOLUS manager. Contact your platform administrator with the club or company name, what you want to connect (court server, 1C, website or app, online payment, a booking system) and a technical contact. Public methods and player SMS sign-in need no separate access.

Responses and errors

A successful response is 200 with JSON. An error is a 4xx or 5xx code with JSON holding detail:

{"detail": "bad_club_token"}
{"detail": {"error": "insufficient_funds", "balance": 1200, "price": 3500}}
{"detail": [{"loc": ["body", "players"], "msg": "…", "type": "…"}]}   // 422 — body validation error

• detail is a string code (bad_club_token, match_not_found) or an object with error and details. Rely on the code, not on text.
• 401 — no token or a wrong one; 403 — not allowed; 404 — not found or belongs to someone else; 409 — conflict (slot taken, game finished); 402 — not enough money in the wallet; 422 — body or parameters failed validation; 429 — too many requests.
• 500 with {"detail": "internal_error"} — a cloud-side failure; retry later.
• Some human-readable values in responses (rating step names and texts, club names and addresses, court names) may be in Russian.

Limits

• Browser calls. The cloud accepts browser requests only from AISOLUS's own domains. A partner website must call the API from its own server.
• Token lifetime. Player token — 15 minutes by default (the exact value is in expires_in), refresh token — 30 days by default, panel account token — 12 hours.
• Batch sizes. 1C payments — up to 500 per request; rally trajectory — up to 400 points, shots — up to 500; heat map — up to 8000 cells; movement grid — up to 4000 cells per player; player levels — up to 16 ids and 16 phones.
• Live score is kept for 180 seconds without updates.
• Video links in the match card are signed per request and live for minutes (15 by default) — do not store them, request the card again.
• Phones — Russian numbers only (+7, 11 digits).

Site map

Guides — integration scenarios with examples:

• 1C payment import
• Court server and cloud
• Local court server API
• Online payment (YooKassa)
• Clubs, courts, slots and bookings
• Live scores and replays
• Leads and rating
• Playtomic integration
• MATCHi integration

Reference — 65 methods by section:

Integration status