Distributor APIv5 Integration

Documentation

updated: 2020.03.09
version 1.0.0
Table of Contents
References........................................................................................................................................3
Distributor API overview......................................................................................................................4
Endpoint overview...........................................................................................................................4
API details............................................................................................................................................5
Authentication..................................................................................................................................5
Security............................................................................................................................................5
Response structure...........................................................................................................................5
Error response..................................................................................................................................5
API endpoints.......................................................................................................................................6
/wallet/balance.................................................................................................................................6
/vouchers/status................................................................................................................................6
/vouchers/purchase...........................................................................................................................7
/vouchers/generate...........................................................................................................................7
/vouchers/transfer.............................................................................................................................8
/licenses/purchase............................................................................................................................8
/licenses/cf.......................................................................................................................................9
Code values and error messages.........................................................................................................10
Integration from APIv4.......................................................................................................................11
Version history....................................................................................................................................12

2
References

Application Endpoint URL usage

Gateway API https://api.mikrotik.com/distributors For JSON Rest API

3
Distributor API overview
Distributor API uses REST protocol to Gateway API, url communicates in JSON format.

This resource is aimed to help distributors to automate their business activities with MikroTik,
changing activities previously available only in user interface to be enabled in client side
operations.

Endpoint overview

/wallet/balance Retrieves actual ROS Wallet asset balance (previously known as deposit
money)
/vouchers/status Retrieves amount of vouchers (previously: prepaid keys) available for usage
/vouchers/purchase Purchase vouchers using ROS Wallet assets
/vouchers/generate Converts voucher into ROS license
/vouchers/transfer Send vouchers to other MikroTik client account
/licenses/purchase Purchase ROS license using ROS Wallet assets
/licenses/cf Upgrade ROS license with Custom Frequency option

4
API details
All available endpoints are accessible using Gateway API url. Operations are performed using
standart HTTP method POST.

Supported communication format: Content-Type: application/json

Authentication

Each operation request contains value „apikey”, that can be acquired in distributor MikroTik
account under account details in „Account API key” section. This API key is valid for 1 year after
generation or until it is regenerated and .

Please note, that non-distributors can generate „Account authorization key”, this key is similar by
structure to „Account API key”, but cannot be used as API service authenticator – only to
authenticate receiving client.

Security

All connections are carried out over TLS connection, to prevent Man-in-the-middle attacks.

Response structure

Each operation returns integer value named „code”. If such value is not present, there is
communication error. If „code” is 1, then request was successfull and response structure contains all
response values. If „code” is other than 1, response contains string value named „message”, where
problem is explained in human readable format.

Error response

If „code” value in response is other than 1, response contains string value named „message”, where
problem is explained in human readable format. You can read common errors in „Code errors”
section.
Additionaly there can be additional value named „error_reference”. If this value exists, keep this
reference to communicate to support about this particular error.

Error response parameters:

Parameter Description
code Returns something other than 1
error Error message in human readable text
error_reference Optional reference to request values

5
API endpoints

/wallet/balance

Used for retrieving asset balance in ROS Wallet (Deposit money)

Request parameters

Parameter Optional Description

apikey Mandatory Authentication key

Successfull response parameters

Parameter Description
code Returns 1
balance Current amount of ROS Wallet assets

/vouchers/status

Used for retrieving amount of available vouchers, can be filtered by level.

Request parameters

Parameter Optional Description

apikey Mandatory Authentication key
level Optional If provided, responds with voucher status for this particular level only,
otherwise responds with total status for all levels

Successfull response parameters

Parameter Description
code Returns 1
vouchers How many unused vouchers together are available
transferable How many vouchers can be transferable to other accounts
for_ros How many vouchers can be used for generating only ROS licenses
for_chr How many vouchers can be used for generating only CHR licenses

There exists difference between total vouchers and transferable vouchers, please take that in mind
when transferring vouchers.
There are also specific vouchers for generating only CHR licenses, also noted in status.

6
/vouchers/purchase

Used for purchasing additional voucher(s) using ROS Wallet assets

Request parameters

Parameter Optional Description

apikey Mandatory Authentication key
level Mandatory What level voucher to purchase (4,5,6)
amount Optional How many vouchers to purchase. Default is 1

Successfull response parameters

Parameter Description
code Returns 1
proof_of_delivery Number of proof of delivery document
vouchers How many vouchers were purchased. Should correspond to asked
amount.

/vouchers/generate

Used for generating new ROS license buy using available vouchers in account.

Request parameters

Parameter Optional Description

apikey Mandatory Authentication key
software_id Mandatory Future license Software ID (AAAA-BBBB)
level Mandatory Future license level (4,5,6)
is_cf Optional Optional true/false value. Generates licence with added Custom-
Frequency option. Considered obsolete. See integration from v4.

Successfull response parameters

Parameter Description
code Returns 1
license Generated license key
software_id Generated license Software ID (should be the same as in request)
level Generated license level (should be the same as in request)

7
/vouchers/transfer

Used for transfering your vouchers to other account. Other account is identified by access key, that
client should generate and provide for transaction. Please consult „transferable” value from
/vouchers/status endpoint.

Request parameters
Parameter Optional Description
apikey Mandatory Authentication key
level Mandatory Voucher level (4,5,6)
amount Mandatory Amout of vouchers to transfer
client Mandatory API key where to transfer vouchers

Successfull response parameters

Parameter Description
code Returns 1
transfered Amount of transfered vouchers (Should be the same as in request)

/licenses/purchase

Used for acquiring new ROS licence by using ROS Wallet assets

Request parameters
Parameter Optional Description
apikey Mandatory Authentication key
software_id Mandatory Future license Software ID (AAAA-BBBB)
level Mandatory Future license level (4,5,6)
is_cf Optional Optional true/false value. Generates licence with added Custom-
Frequency option. Considered obsolete. See integration from v4.
note Optional Base64 encoded note

Successfull response parameters

Parameter Description
code Returns 1
proof_of_delivery Number of proof of delivery document
license Generated license key
software_id License Software ID (should be the same as in request)
level License level (should be the same as in request)

8
/licenses/cf

Used for adding Custom Frequency option for license. This option is becoming obsolete and only
usable for older routers.

Request parameters

Parameter Optional Description

apikey Mandatory Authentication key
software_id Mandatory License Software ID (AAAA-BBBB)
level Optional License level (4,5,6)

Successfull response parameters

Parameter Description
code Returns 1
license Generated license key
software_id License Software ID (should be the same as in request)
level License level (should be the same as in request)

9
Code values and error messages

Code Message How to resolve

1 Successful response. Not an error code.
2 Could not authorize! Check your api key if it is correct and current.
3 Could not do that! Check if provided action is correct and all values
exist
11 Could not retrieve ROS Wallet balance! Please try again after a short break or report to
support.
12 Could not locate license by provided Did not found license in your account – please
Software ID! check if there is one to add to.
13 License by this Software ID is read-only! Provided license was changed, please check
actual license in your account.
14 Failed to generate license with CF! Please try again after a short break or report to
support.
15 Failed to generate license with CF! Please send info about this to support.
16 Failed to generate license with CF! Did not found license in your account – please
check if there is one to add to.
17 Failed to transfer voucher! Please try again after a short break or report to
support.
18 Could not process licence order! Please check your deposit status, try again after a
short break or report to support.
19 Could not list vouchers! Please try again after a short break or report to
support.
20 Could not purchase vouchers! Please check your deposit status or report to
support.
21 Could not generate license from voucher! Please try again after a short break or report to
support.
22 Could not generate license, because there Please check if there are unused vouchers
are no available vouchers!

10
Integration from APIv4
In distributor documents you should be able to download distributor API library for PHP, replace
previous v4 library and all function calls should work as there exists support for all the old
functions.

However, please note there are notable changes from previous API version, please read the
following.

In APIv5 distributor access is authentificated by „Account API key” - this key has write privileges
and is available only for distributors. In APIv4 authentification was done by MikroTik account login
and password. Buy using API key, distributor is free to change his account password frequently,
increasing account security. And distributor can also provide store api key on his integration, not
worrying if his web account can be compromised.

Previously existing Custom-Frequency option is considered obsolete for latest routers. So it is

removed from vouchers (prepaid keys) and can be invoked when purchasing actual licences with
any voucher.

There are no more „Credit keys”. Old v4 function „checkCreditkeys” now returns permanent error
„not supported” and there is no endpoint in APIv5 for that.

APIv5 has implemented endpoint call to purchase vouchers (prepaid keys) using ROS Wallet
(Deposit money). This option was not available in APIv4.

APIv5 has implemented endpoint call to transfer vouchers (prepaid keys) to other account,
identified by their „Authorization key”. This option was not available in APIv4.

In APIv4 library call „keypurchase” and invoking function purchaseKey had parameters „board”
and „pay_type”. Both of those are removed. In APIv5 board type is determined automatically, so
there is no need to provide it. In APIv4 „pay_type” had specific codes for each payment: 0 –
prepaid key, 1 – deposit money, 2 – credit key, 255 – test mode. Now there are specific endpoint
calls for each available action: paying by prepaid key is done by call to /vouchers/generate and
paying by deposit money is done by calling /licences/purchase.

11
Version history

Date Version Change

2020.03.09 1.0.0 Initial document of Distributor APIv5

12