Mandarin

# Basic principles

# Entry points

Production environment for authorization: https://accounts.mandarin.io/ (opens new window) Production environment for API requests: https://api.psp.io/ (opens new window)

# Request Authentication

Each request must be authenticated using a token (access_token), obtained in accordance with the OAuth 2.0 protocol for applications. The token is valid for 36,000 seconds (10 hours). If the validity period has expired, the token must be requested again.

Request for a token

Includes mandatory form-data parameters that are passed in the request body (parametersapplication.client_id and application.client_secretare immutable for the application and stored on the client side).

Parameter Description Example
grant_type Authorization grant (always equal toclient_credentials). client_credentials
client_id Client ID (equal to the valueapplication.client_id, provided by Mandarin). VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret Secret key-password of the client (equal to the valueapplication.client_secret, provided by Mandarin). uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope Requested scopes (access areas):
for example, transactions.read - “Reading transactions”.
The delimiter is a space.
You can request any list of scopes, and the response will return the list of requested scopes that can be provided for this application.		 transactions.read
curl --request POST \
  --url https://accounts.mandarin.io/oauth/token/ \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=transactions.read'

Response

Parameter Description Example
access_token Token (access key). VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in Token validity period (in seconds). Always equal to 36,000 seconds (10 hours). 36000
token_type Token type (always equal toBearer). Bearer
scope Allowed scopes (access areas): for example, transactions.read - “Reading transactions”.
The delimiter is a space.
You can request any list of scopes, and the response will return the list of requested scopes that can be provided for this application.		 transactions.read
{
    "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "transactions.read"
}

Token Usage

Indicated in the headers of each request, in the Authorization field, after a reserved word Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

# Operating principles

The API is implemented according to REST API principles.

The API operates with resources that represent entities - business logic objects (business models, domain models, domain models). There are two main types of resources: collection resource and entity resource.

Collection resources are named in the plural, for example:/transactions.

Entity resource is a resource of a specific entity in some collection. Access to it is always carried out through the collection resource and using a unique number, for example:``` /transactions/


The API uses *JSON* for both responses and requests (if
applicable). API responses are standardized.

Collection resource responses always contain a field named the same as itself
resource, and containing an array of business models. If there is no data in response to the request,
then the array will be empty. For example, if this is a resource response`/transactions`, then
the answer will be:

```json
{  
   "transactions": [  
      { {{transaction_model}} },  
      { ... },  
      { ... }  
   ]  
}

Valid request parameters:

  • filter_by- selection based on specified fields and conditions;

  • sort_by- a list of fields (separated by commas) for sorting in descending order (adding a minus-before the field name, you can switch the sort order to “ascending”). By default sorted byid;

  • limit_to- limit the number of entities issued at one time; number, default 50;

  • cursor- used to get the next/previous part of the output, has priority over other requests, that is, if sentcursor, then the remaining parameters are ignored.

Parameterfilter_byis formed as follows: a list of fields and values, according to which needs to filter entities, comparison operators (=,>,>=,<,<=, it is possible to use the operatorIN), filters are combined with an ampersand:&(which stands for the logical operatorAND).

The following line is generated:

field_name1=value1&field_name2 in value2_1,value2_2&field_name3>=value3_1&field_name3<value3_2

For example,mw_type=transaction&opcode in 1,3&updated>=2019-10-01&updated<2019-10-31.

After which this string is URL-encoded and passed as a value parameterfilter_by:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31

Top level parameterssort_byAndlimit_toand their values ​​are not URL-encoded.

Example resultquery-string:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

Collection resource responses always contain an attached pagination object (cursor). The cursor object always contains fields:

  • count- the number of entities in the current response.

  • total- the total number of entities for this request (with such filters, etc.).

  • next- pointer to the next page of output (null, if such page does not exist).

  • prev- pointer to the previous page of issue (null, if such page does not exist).

An example of a query that will return the first 100 entities:

GET /transactions?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

{
   "transactions": [ ... ],
   "cursor": {
      "count": 100,
      "next": "aad0f17a6af11672",
      "prev": "f0bb6887c3b2f501",
      "total": 4200
   }
}

An example of a request to obtain the next 100 entities (in the parametercursorthe value from the response field is substitutednext):

GET /transactions?cursor=aad0f17a6af11672

Entity resource responses always contain a field named the same as the resource itself, but in the singular, for example:

GET /transactions/12345

{  
   "transactions": {  
      {{transaction_model}}  
   }  
}

← Transactions →