# API reference

> Every endpoint, address and message on one page — the platform API, Baziness Pay, the Baziness pages, and the endpoints your own server should offer.

## Platform API
- **Production:** `https://platform.karizmastudio.com/api`
- **Development:** `https://platform-dev.karizmastudios.org/api`

Step-by-step explanations: [Platform API](platform-api.md).

| Method & path | Auth | Body | Response | Notes |
| --- | --- | --- | --- | --- |
| `POST /client/auth` | — | `{ clientId, clientSecret }` | `{ clientId, token }` | the client token |
| `POST /client/create-user` | client token | `{ deviceId, platform, store, linkedToken }` | `{ userId, token, isLinkedToAccount }` | `platform`: `Web` / `Android` / `Ios` / `Editor`; `store`: `Direct` / `GooglePlay` / `AppStore` / `CafeBazaar` / `Myket` |
| `GET /client/get-user-token/{userId}` | client token | — | `{ userId, token, isLinkedToAccount }` | a fresh user token |
| `GET /client/validate-user-token/{token}` | client token | — | `{ userId, isValid }` | invalid → `200` with `isValid: false`, `userId: 0` |
| `POST /client/add-coin` | client token | `{ userId, amount, transactionId, metaData }` | `{ resourceId, amount }` (new balance) | a repeated `transactionId` → `400 { success: false, error: "add resource failed" }` |
| `GET /user/get-coin` | **user** token | — | `{ resourceId, amount }` | called by the client; any origin allowed |

Any call with a missing or expired client token answers `401`.

## Baziness pages
- **Production:** `https://baziness.com`
- **Development:** `https://platform-web-dev.karizmastudios.org`

Details: [Baziness pages](pages.md).

| Page | Path | Required | Optional |
| --- | --- | --- | --- |
| Sign-in | `/` | `packageName`, `sdkType=js` | `linkedToken`, `allowGuest=false`, `buildStore` |
| Profile | `/profile` | `packageName`, `sdkType=js` | `linkedToken`, `redirect=profile`, `allowGuest=false` |
| Reward shop «انتخاب جایزه» | `/shop` | `packageName`, `sdkType=js`, `linkedToken` | `game_name`, `redirect=shop` |
| Game offer | `/game-offer` | `game_name`, `packageName`, `sdkType=js` | `linkedToken`, `allowGuest=false` |

### Messages from the pages
`{ "type": string, "data"?: string | { "token": string } }`, as JSON text or an object.

| `type` | What to do |
| --- | --- |
| `login` with a token | send it to your server → verify → link or switch → close |
| `login` without data | linked in place → refresh |
| `token` | ignore (a silent handshake) |
| `logout` | close, clear local data, restart as a new visitor |
| `close` | close the view |

## Baziness Pay
- **Production:** `https://pay.baziness.com`
- **Development:** `https://pay-dev.karizmastudios.org`

`uid` must be numeric. Details: [Baziness Pay](pay-api.md).

| Method & path | Body format | Body | Response |
| --- | --- | --- | --- |
| `GET /buy` | query | `sku`, `uid`, `pname` | the payment page |
| `POST /get_payment` | JSON | `{ uid, sku, pname }` | `{ uid, sku, token, time, success }`, or `{ error: "payment_is_not_valid", success: false }` |
| `POST /verify_payment` | **form** | `uid`, `token`, `sku`, `pname` | `{ success, error }` |
| `POST /consume` | JSON | `{ uid, sku, pname }` | `{ success }` |

## Your server's endpoints (recommended)
| Endpoint | Body | Response |
| --- | --- | --- |
| `GET /api/platform/config` | — | `{ enabled, webBase, apiBase, packageName, gameName, gameOfferUrl }` |
| `POST /api/platform/token` | `{ deviceId, linkedToken?, tag?, utm? }` | `{ enabled, …settings, token?, userId?, isLinkedToAccount?, switchToDeviceId?, error? }` |
| `POST /api/platform/login` | `{ deviceId, token }` | `{ ok, switchToDeviceId?, reason? }` |
| `GET /api/shop` | — | the products this player can buy |
| `POST /api/shop/purchase/start` | `{ productId }` | `{ paymentId, url }` |
| `POST /api/shop/purchase/verify` | `{ paymentId }` | `{ status, granted, balances }` |
| `POST /api/shop/purchase/cancel` | `{ paymentId }` | — |
| `GET /api/shop/purchase/pending` | — | `[{ paymentId, productId }]` |

## Settings
| Setting | Default | Meaning |
| --- | --- | --- |
| `BAZINESS_PLATFORM_ENABLED` | `false` | master switch for accounts, coins and pages |
| `BAZINESS_PLATFORM_USE_PRODUCTION` | `false` | production or development addresses |
| `BAZINESS_CLIENT_ID` / `BAZINESS_CLIENT_SECRET` | — | credentials (**secret**) |
| `BAZINESS_PLATFORM_PACKAGE_NAME` | — | `packageName` on page links |
| `BAZINESS_GAME_NAME` | — | `game_name` on the reward and offer pages |
| `BAZINESS_PLATFORM_API_URL` / `BAZINESS_PLATFORM_WEB_URL` | derived | address overrides |
| `BAZINESS_GAME_OFFER_URL` | `{web}/game-offer?game_name=…` | offer page override |
| `BAZINESS_PAY_ENABLED` | `false` | master switch for purchases |
| `BAZINESS_PAY_BASE_URL` | — | `https://pay-dev.karizmastudios.org` or `https://pay.baziness.com` |
| `BAZINESS_PAY_PACKAGE_NAME` | — | `pname` |
| `BAZINESS_SKU_PREFIX` | empty | SKU = prefix + product id |
| `DEV_FAKE_BAZINESS_PAY` | `false` | the local fake gateway (never in production) |