Common API Conventions

This page describes the conventions shared by all methods of the SportAPI Coupon Settlement System. Method-specific fields and business errors are documented on the corresponding method pages.

Base URL

The manager provides the base URL for the test or production environment. The documentation examples use this placeholder address:

https://coupon-api.example.com

Append the method path to the provided base URL:

{BASE_URL}/api/partner/coupons/active

We recommend storing the base URL without a trailing /. The API accepts a trailing / in a method path, but a single integration should use one consistent format.

Request format

The API accepts and returns UTF-8 encoded JSON.

For requests with a JSON body, include:

Accept: application/json
Content-Type: application/json

Protected methods also require a client JWT:

Authorization: Bearer <client_token>

Do not include the token in a URL or query parameters. Detailed rules for obtaining and using a JWT are provided in Authentication.

Common response envelope

New methods return a common response envelope:

{
  "code": 1,
  "body": {},
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 12,
  "path": "/api/partner/coupons/get"
}

The body value does not have one common type across all methods. It may be an object, array, string, or null. Always follow the documentation for the specific method.

Determining whether an operation succeeded

Check both the HTTP status and the code field:

A business error is usually returned with HTTP 200. Checking only the HTTP status may therefore cause a failed coupon placement to be incorrectly recorded as accepted.

Example business error:

{
  "code": 0,
  "body": null,
  "error_code": 471,
  "error_message": "Coupon not found",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/coupons/get"
}

Do not automatically retry a coupon placement request after an indeterminate network or server error until you have ruled out the possibility that the first request was processed. Otherwise, one user selection may create multiple coupons.

Dates and times

All dates and times in the Client API are Unix timestamps in milliseconds unless a field explicitly states otherwise.

Example:

{
  "date": 1784970000000,
  "event_date": 1784977200000,
  "calculate_date": null
}

• date — object creation time or response generation time, depending on the context;
• event_date — scheduled start time of the sporting event;
• calculate_date — coupon or bet settlement time.

Before settlement, calculate_date is null. The value 0 is not used for an unsettled coupon or outcome.

Do not confuse milliseconds with seconds. A timestamp in milliseconds usually contains 13 digits.

Decimal numbers

Amounts, odds, and payouts are returned as JSON numbers without a fixed number of decimal places:

{
  "amount": 10,
  "coef": 1.85,
  "potential_win": 18.5
}

Do not treat 10, 10.0, and 10.00 as different amounts. The integration must not depend on the textual number of decimal places.

For monetary calculations, use an appropriate decimal data type instead of a binary floating-point type. The partner defines the rounding and display rules.

null values, omitted fields, and empty strings

These values have different meanings:

• null — the field is present, but its value is currently unavailable or not applicable;
• omitted field — the parameter was not provided, or the field is not part of the specific response format;
• "" — an empty string was provided.

Do not substitute one value for another unless the field description explicitly permits it.

For example, null and "" for callback_url mean that no callback will be sent for the coupon being placed. If the partner does not use callbacks, the partner may also provide the main domain of its website in this field. For numeric, boolean, and required fields, an empty string is not a substitute for null.

Language of names

The lang field defines the language used for sport, tournament, team, bet group, and outcome names in coupon data.

• provide a two-letter language code;
• the API supports approximately 50 languages;
• register and submit one agreed language code for each coupon;
• the language is fixed when the coupon is placed: an existing coupon cannot currently be retrieved in another language;
• the full list of languages is not published in this documentation.

Ask the manager if you do not know the required language code. Do not rely on automatic conversion of an arbitrary value.

Support for multiple translation variants of the same coupon is in development.

Coupon code

coupon_code is the public coupon number. It usually contains 12 digits:

{
  "coupon_code": "000000000272"
}

Store and submit coupon_code as a string:

• leading zeros are part of the code;
• converting the value to a number may turn "000000000272" into 272;
• coupon_code is not the internal database record ID;
• use it to associate a SportAPI coupon with the corresponding record in the partner’s system.

New coupon retrieval methods accept several compatible query parameter names, but new integrations should use the canonical name coupon_code.

Data access

The owner of coupons and the balance is determined by the client JWT. No additional header or parameter can switch a request to another partner’s data.

The API returns only data belonging to the account associated with the token. When another client’s coupon is requested, the system does not disclose whether it exists and responds in the same way as it does for an unknown code.

Compatibility

The main documentation describes the new /api/partner/** methods. Legacy methods remain supported for now, but may differ in:

• the fields included in the common response envelope;
• error codes;
• the location of data inside body;
• HTTP status rules;
• the format of individual parameters.

Do not mix old and new contracts in the same handler without explicitly checking the endpoint. To update an existing integration, use the standalone Migrating from the old API guide.

When reading JSON, do not rely on field order, and allow new optional fields to be added in future backward-compatible updates.

Next section: Bet pointer.