Endpoint Reference

Use the following routes for new integrations:

/api/partner/**

The manager provides the base URL for the test or production environment. This documentation uses the placeholder address:

https://coupon-api.example.com

The full method URL is formed as follows:

{BASE_URL}{PATH}

For example:

https://coupon-api.example.com/api/partner/coupons/active

Recommended API

Common Headers

For an authenticated request:

Authorization: Bearer <token>
Accept: application/json

For a request with a JSON body, also send:

Content-Type: application/json

Coupon ownership is determined by the client JWT. There is no separate header for switching to another partner.

Availability Check

GET /api/partner/health

No authorization or parameters are required.

Response:

{
  "code": 1,
  "body": "ok",
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 1,
  "path": "/api/partner/health"
}

This method checks HTTP API availability, but does not confirm that credentials, a JWT, or any specific coupon data are valid.

Authentication

POST /api/partner/login

Body:

{
  "username": "<username>",
  "password": "<password>"
}

The login field is supported as a compatible alias for username.

The main result is:

body.token

Send the token as a Bearer JWT in all other protected methods.

Login business errors return HTTP 200 with code = 0:

See Authentication for details.

Coupon Creation

POST /api/partner/coupons/place

With code = 1, the API atomically creates every coupon and deducts the total amount from the client account balance. With multi = false, one amount is deducted; with multi = true, one amount is deducted for each single created. An insufficient balance returns 507; no partial coupons are created.

Main JSON fields:

Successfully created coupons are located in:

body.coupons[]

Even when one coupon is created, coupons is an array.

See Coupon Creation for details.

Retrieving One Coupon

GET /api/partner/coupons/get?coupon_code={coupon_code}

Recommended query parameter:

coupon_code

Compatible names:

code
coupon_id
bet_code

The coupon is returned directly in:

body

If the coupon does not exist or belongs to another partner:

error_code = 471

See Retrieving One Coupon for details.

Retrieving Coupons by Code or Period

POST /api/partner/coupons/results

The method has two mutually exclusive modes.

By code:

{
  "coupon_ids": [
    "000000000272",
    "000000000273"
  ]
}

No more than 100 codes per request.

By creation period:

{
  "start_date": 1784880000000,
  "end_date": 1784966400000
}

One interval cannot exceed 24 hours.

Result:

body.query_type = "ids" or "time"
body.coupons[]

See Retrieving Coupons by List and Period for details.

Recently Settled Coupons

GET /api/partner/coupons/calculated?time={minutes}

time:

• is optional;
• defaults to 5 minutes;
• is replaced with 5 when its value is <= 0;
• is limited to a maximum of 120 minutes.

Filtering uses final settlement time, not creation time.

The result is an array of complete models directly in:

body[]

See Active and Recently Settled Coupons for details.

Active Coupons

GET /api/partner/coupons/active

No parameters are required.

The result is an array of complete models directly in:

body[]

An empty array is a successful result.

See Active and Recently Settled Coupons for details.

Client Account Balance

GET /api/partner/balance

The GET /api/partner/balance method itself only reads the balance and performs no credit or deduction. Successful coupon creation through POST /api/partner/coupons/place deducts funds from this balance.

GET /api/partner/balance HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Accept: application/json

Response:

{
  "code": 1,
  "body": {
    "balance": 100
  },
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 3,
  "path": "/api/partner/balance"
}

This is the balance of the authenticated client account in the SportAPI Coupon Settlement System. The method does not manage the balances of the partner’s end users.

Do not confuse the two balances:

• the SportAPI client balance changes automatically when coupons are created;
• the end-user balance resides in the partner system and is managed by the partner.

Partner Callback

A callback is not an incoming SportAPI endpoint. It is an HTTP endpoint created and hosted by the partner.

When creating a coupon, the partner sends:

{
  "callback_url": "https://partner.example.com/api/coupon-result"
}

After a settlement change, the SportAPI Coupon Settlement System sends:

POST {callback_url}
Content-Type: application/json
X-Coupon-Signature: sha256=<hex_hmac_sha256>

No JWT is sent in the callback. Authenticity is verified using the HMAC signature.

Callbacks are optional. To enable them, the partner informs the manager, who enables the feature and creates a secret phrase.

More information:

• Result Callbacks;
• Callback Signature Verification.

Successful Result Shapes

Do not confuse the coupon locations:

Checking the Result

For the new API:

HTTP 2xx and code = 1 → successful operation
HTTP 2xx and code = 0 → business error
HTTP 401 → JWT is absent, invalid, or expired
HTTP 403 → token lacks the required access
HTTP 5xx → server error

HTTP 200 alone does not confirm a successful business operation.

See API Response Format for details.

Compatible Aliases of the New Format

These routes remain available for compatibility, but are not recommended for new integrations:

The /api/v3/partner/bet/list route uses the old list contract and is not an alias for the new /coupons/results method.

Legacy Routes

Legacy routes are still supported, and there are currently no plans to remove them. Use /api/partner/** for new integrations.

Legacy and new routes may return different data structures and error codes.

More information:

• Migrating from the Legacy API;
• Compatible Legacy Routes.

Cashout

Current experimental route:

GET /coupons/cashout?coupon_code={coupon_code}

Status:

• under development;
• not fully tested;
• has no new /api/partner/** route;
• not recommended for production.

The method returns an estimated value only; it does not sell the coupon or change any balance.

See Cashout for details.

Trailing Slash

A trailing / is accepted for the listed routes:

/api/partner/coupons/active
/api/partner/coupons/active/

Use a consistent URL format throughout one integration.

Checklist

• New code uses /api/partner/**.
• The base URL was obtained from the manager.
• Protected requests send a Bearer JWT.
• JSON requests send Content-Type: application/json.
• Both the HTTP status and code field are checked.
• The body shape is determined by the specific method.
• coupon_code is stored as a string.
• The callback endpoint belongs to the partner and verifies HMAC.
• Legacy routes are not mixed with the new response model.
• Cashout is not used in production.

Next section: API Response Format.