Shuffly API (1.0.0)

Send the refresh token in the JSON body as { "refreshToken": "..." }. For clients that prefer the header convention, Authorization: Bearer <refreshToken> is accepted as a fallback. The body takes precedence when both are present — this prevents auto-attached JWT Bearer headers (common in mobile HTTP clients) from being mistakenly treated as a refresh credential.

Send the refresh token in the JSON body as { "refreshToken": "..." }. For clients that prefer the header convention, Authorization: Bearer <refreshToken> is accepted as a fallback. The body takes precedence when both are present.

Mobile sign-in via a Google ID token obtained by the client through the google_sign_in Flutter package. The server verifies the token's signature against Google's JWKS, asserts iss and aud, and on first sign-in creates a users row with a synthetic +999... callerid plus matching user_identities and user_profiles rows. Returns the same token bundle as the OTP login path so downstream code is identical. Public — no JWT required (this IS the login).

Mobile sign-in via an Apple identity token obtained by the client through the sign_in_with_apple Flutter package. The server verifies the token against Apple's JWKS, asserts iss=https://appleid.apple.com and the configured bundle ID as aud, then creates or returns a user as with Google. Apple emits the user's name only on the very first sign-in, so the client may pass givenName/familyName as a fallback for display_name. The user's email may be a private-relay address; this is reported via profile.isPrivateRelay. Public — no JWT required (this IS the login).

Generates a 6-digit code, hashes and stores it in otp_requests, then sends it via SMS (vendor-specific routing for 90* numbers). Rate-limited: one send per phone per otp_resend_cooldown_seconds (system_config knob, default 60), and at most otp_max_hourly_requests per hour (default 10). A Memcached lock with the same TTL as the resend cooldown prevents duplicate sends from the same phone.

Public route — no JWT required. The same endpoint is the canonical "resend" surface — call it again once the cooldown has elapsed.

Successful responses include resendAvailableAtMs (epoch ms) — the earliest time at which a subsequent call to this endpoint will be accepted. Clients should use it to gate a "Resend code" button. The expiresAt field is the OTP TTL (configurable via otp_ttl_minutes, default 5 minutes).

When debug_otp_return=true (system_config), the response also includes the plaintext OTP under debugOtp — never enable in production.

Validates the user-supplied OTP against the most recent unused otp_requests row for the phone. On success: creates the user if new, upserts user_identities/user_profiles, registers/refreshes user_devices if deviceId is supplied, mints JWT + refresh tokens via AuthTokenService, and writes a user_sessions row.

Public route — no JWT required (this IS the login).

/otpCheck is an alias for the same handler, kept for legacy clients.

Same handler as /otpSmsCheck. Legacy alias.

Updates whitelisted columns on users (callerid, status, is_deleted, last_login_at) and/or user_profiles (username, full_name, gender, second_language, birth_date, avatar_id, bio, rating). userId (users.id) is required.

Setting avatar_id is ownership-gated — the caller must already own the target avatar (purchase via POST /v1/avatars/{avatarId}/buy first). Invalid or unowned ids return 403 / 404.

The old free-text avatar_url field was dropped — avatar_url is now a derived response field emitted via JOIN from user_profiles.avatar_id → avatars.image_url.

Most mobile clients should use /userUpdateProfile (profile-only, with stricter validation) — this endpoint is the broader admin variant.

Profile-only update with input validation (gender enum, birth_date format YYYY-MM-DD, bio ≤ 500 chars). Empty fields are ignored — only supplied fields are touched. Inserts a user_profiles row if none exists yet.

Setting avatar_id is ownership-gated — caller must own the target avatar (purchase via POST /v1/avatars/{avatarId}/buy first).

The old avatar_url/profileAvatarUrl free-text write fields are gone — avatar URL is now derived in responses via user_profiles.avatar_id → avatars.image_url JOIN.

Sets users.status='deleted', is_deleted=1. Idempotent: a second call returns OK with "Hesap zaten silinmiş". Either userId or callerid is required.

Returns { countryCode, dialCode } from a hardcoded ISO-2 → dial-code map. Unknown codes default to +90.

Used by the 1-on-1 discovery feature. Pass a single userId, an array userIds[] (max 50), or pool=true to get a random batch of active users (excluding the caller). Identifier accepts numeric users.id, UUID, normalized callerid, or user_key.

Returns a list of profile cards: { userId, fullName, username, bio, birthDate, gender, profileAvatarUrl, rate }. Empty list (200 or 404) when nothing matches.

Returns user + profile + interests in one call. Identifier: either callerId (or callerid) or userId (users.id). Computes age from birth_date. avatarUrl / profileAvatarUrl are derived via JOIN from user_profiles.avatar_id → avatars.image_url — the legacy free-text columns are gone. Both bio/about and profileAvatarUrl/avatarUrl are aliased in the response for client-version compatibility.

Uses the new error envelope ({ error: { code, message, details } }) unlike most legacy endpoints — see USER_IDENTIFIER_REQUIRED / USER_NOT_FOUND / GET_USER_PROFILE_FAILED.

Returns the public profile shown on a user's profile page: names, viewer's private alias for the target, avatar, rating, age, bio, interests, plus viewer-relative isFriend (bidirectional friendship edge) and isSelf flags. JWT-protected; callerId is the target user's users.callerid (digits-only, verbatim — no re-normalization). The viewer is resolved from the JWT.

Returns active rows from interests, sorted by sort_order, id.

name is localized via interest_localized_info: requested locale → en → interests.name (legacy canonical column). Supplying neither ?locale= nor Accept-Language yields English — wire shape is unchanged, so pre-localization clients keep working.

Atomically upserts gender + second_language on user_profiles and replaces the user's user_profile_interests rows. Validates: gender ∈ {male, female, other}, secondLanguage non-empty, at least one valid interest id.

Uses the new error envelope ({ error: { code, message, details } }).

name is localized the same way as /get-interests (requested locale → en → interests.name).

callerId is in the query string (not body — legacy quirk). Body is { interests: [ids] }. Atomically wipes and re-inserts the user's user_profile_interests rows.

callerId in query, secondLanguage in body.

Returns rows from user_purchases for the supplied userId. Used by the mobile client's purchase-history screen.

Inserts a row into paymentHistory. Whitelisted body fields: salesChannel, phoneNumber, productCode, transactionDate, purchaseID, ipAdress, durationMinutes, status. Used by the legacy phone/IVR billing flow — RevenueCat purchases use /revenueCatPaymentWebhook.

Public endpoint called by RevenueCat. Payload shape per RC docs.

Behavior:

• Validates and dedupes by event.id against revenuecat_webhook_events (idempotent on retries).
• For VIRTUAL_CURRENCY_TRANSACTION (or coin_* product): credits coins via wallet_transactions + user_wallet_summary. Hardcoded coin map: coin_1=10000, coin_2=70000, coin_3=150000.
• For VIP products (vippackage1=1, vippackage2=7, vippackage3=30): inserts user_purchases for the audit ledger, then pushes the subscription to IVR via POST /ivr/subscriptionsAdd. To preserve renewal-while-active stacking, the handler first queries IVR for the user's current expiry and offsets the new subscription's subscriptionsStart accordingly. There is no local VIP table — IVR is authoritative.
• VIP lifecycle events (EXPIRATION, BILLING_ISSUE, SUBSCRIPTION_PAUSED, UNCANCELLATION, CANCELLATION) are observability-only — logged and acked, no DB writes. IVR independently expires its own subscriptions based on the durationMinutes it received at subscriptionsAdd.
• Anonymous ($RCAnonymousID:*) and unknown product events are marked processed and ignored.

No JWT — public route. Future hardening: signature verification via REVENUECAT_WEBHOOK_SECRET (planned in wallet-system.md).

Returns the static packages_map from config/payment_packs.php. Mobile client uses this for the shop / paywall display alongside the live price catalog from RevenueCat.

Renders an HTML page with monthly counts of distinct paying phones, broken down by salesChannel (Google vs Apple). Accepts year and month either as query params (GET) or form body (POST). Returns text/html — not JSON.

No JWT in current implementation; treat as internal-only.

Reads up to 10 paymentHistory rows with status='Pbx System ERROR' from the last hour and retryCount < 3, replays them against the configured IVR subscriptionsAdd endpoint, then writes back the outcome (OK-LastError on success, retryCount++ and lastRetryError on failure). Returns success/fail counts.

Operationally invoked from a scheduled job — no auth in current implementation; lock down at the network layer.

Atomically debits the user's user_wallet_summary balance, writes a coin_spend_transactions ledger row + coin_history entry, then best-effort notifies RevenueCat to mirror the spend (failures logged to rc_deduct_log, never returned to client).

Debits are guarded by row-lock + balance >= amount check so concurrent spends can't double-debit. The idempotency key is server-derived (spend-{userId}-{reason}-{rand}) — clients who need true idempotency across retries should use the wallet-skill pattern in newer endpoints (e.g. WalletService::spendCoins) instead.

Legacy passthrough that POSTs { callerId: <phone> } to the upstream IVR subscriptionsGet endpoint and returns the response verbatim. The response shape is IVR's, not ours — see /subscriptionsGet for the full field list.

Kept for Flutter diagnostic-screen backwards-compat. New callers should use GET /vip/me (JWT-self) — that endpoint returns a normalized envelope and correctly handles the IVR quirk where uuid stays populated after the subscription expires.

Resolves the user's active subscription on IVR (POST /ivr/subscriptionsGet), then cancels it (POST /ivr/subscriptionsDelete with the resolved uuid). Returns { status: "OK" } on successful cancellation.

Pre-2026-04-29 this endpoint wrote to a now-defunct local vipUsers table — a silent no-op. The current implementation actually performs the cancellation against IVR.

Returns { vip: true|false|null, vipStatus, source, stale } based on whether the caller has an active subscription on IVR. Active means BOTH the IVR record's uuid is set AND subscriptionsEnd is in the future — IVR retains the latest subscription's uuid even after it expires, so uuid-presence alone is not a reliable signal.

Routes through VipSummaryService (Redis read-through cache fronting IVR). On IVR outage the last cached envelope is served (source: 'cache', stale: true). On IVR outage AND cache miss, vip is null and vipStatus is 'unknown' — clients MUST treat null as 'preserve prior state', NOT as false.

Pre-2026-04-29 this returned a raw vipUsers row and used uuid-presence as the active marker (incorrectly returning vip: true for expired records). Pre-2026-05-11 it surfaced IVR transport errors as 503 which the Flutter client silently treated as vip: false, causing intermittent crown-swing for actual VIP users. Both behaviors are now fixed.

Passthrough that POSTs { callerId } to ${service_base_url}/ivr/subscriptionsGet and returns IVR's response verbatim. Used by the legacy IVR/PBX billing flow and by Flutter's VIP diagnostic screen.

IVR response fields (all strings, present even when empty): uuid, callerId, productCode, subscriptionsStart, subscriptionsEnd, subscriptionsFlag, plus a few telephony fields (genderTalk, genderDetected, malecount, femalecount) that are not relevant to subscription state.

Quirk: uuid remains populated after subscriptionsEnd passes — it's the uuid of the most-recent subscription record, not an active-marker. Use both uuid non-empty AND subscriptionsEnd > now to determine active VIP. GET /vip/me does this for you.