Developer API

Материал из Ace Stream
(Различия между версиями)
Перейти к: навигация, поиск
(createUserKey)
 
Строка 1: Строка 1:
==Общее описание API==
+
==Common description of API==
Данное API позволяет разработчикам приложений работать с [[User_key|ключами пользователей]] в системе Ace Stream. API предоставляет методы для создания ключей пользователей и для активации различных опций для ключей.
+
This API allows application developers to work with [[User_key|user keys]] in Ace Stream system. API provides methods for creating user keys and activating different options for the keys.
   
==Формат запросов==
+
==Requests format==
Запросы API отправляются методом HTTP-GET на такие адреса:
+
API requests are sent via HTTP-GET method to the following addresses:
* тестовый режим: <tt><nowiki>https://api-sandbox.acestream.net/developer</nowiki></tt>
+
* test mode: <tt><nowiki>https://api-sandbox.acestream.net/developer</nowiki></tt>
* боевой режим: <tt><nowiki>https://api.acestream.net/developer</nowiki></tt>
+
* work mode: <tt><nowiki>https://api.acestream.net/developer</nowiki></tt>
   
Ответы на запросы приходят в формате json.
+
Responses for these requests comes in JSON format.
   
Если при обработке запроса возникла ошибка, будет отослан ответ такого вида:
+
If during query processing an error was occurred, the following kind of response will be sent:
 
<tt><nowiki>{"error":"error descrtiption"}</nowiki></tt>
 
<tt><nowiki>{"error":"error descrtiption"}</nowiki></tt>
   
Ответы за успешно обработанные запросы зависят от вызываемого метода.
+
Responses to successfully processed requests depend on a method being called.
   
===Обязательные общие параметры для всех запросов===
+
===Required common parameters for all requests===
* '''method''' - вызываемый метод API
+
* '''method''' - called API method
* '''api_key''' - ключ клиента API
+
* '''api_key''' - API client key
* '''api_version''' - поддерживаемая версия API (текущая версия: 1.0)
+
* '''api_version''' - supported API version (current version: 1.0)
* '''product''' - публичная часть [[Product_key|ключа продукта]]
+
* '''product''' - public part of [[Product_key/en|product key]]
* '''sign''' - цифровая подпись запроса
+
* '''sign''' - request's digital signature
   
===Алгоритм формирования цифровой подписи===
+
===Algorithm for generating a digital signature===
* создается массив строк вида "название_параметра=значение_параметра"
+
* array of strings like "parameter_name=parameter_value" is created
* полученный массив сортируется
+
* the resulting array is sorted
* элементы отсортированного массива объединяются в строку с разделителем "#"
+
* elements of the sorted array are combined in a string with a separator "#"
* к полученной строке добавляется секретный ключ клиента API
+
* private key of API client is added to the resulting string
* подписью является sha1-хеш от полученной строки (в шестнадцатеричном представлении, 40 символов, маленькими буквами)
+
* signature is sha1-hash of the resulting string (in hexadecimal representation, 40 characters, lowercase)
   
Код на PHP:
+
PHP code:
 
<tt><nowiki>function makeSignature(array $params, $apiSecret)
 
<tt><nowiki>function makeSignature(array $params, $apiSecret)
 
{
 
{
Строка 43: Строка 43:
 
}</nowiki></tt>
 
}</nowiki></tt>
   
==Методы API==
+
==API methods==
   
 
===getServiceCost===
 
===getServiceCost===
Получить стоимость опции
+
Get the cost of a service
   
параметры:
+
parameters:
* '''service''' (''string'') - идентификатор опции
+
* '''service''' (''string'') - service ID
* '''period''' (''string'') - идентификатор периода
+
* '''period''' (''string'') - period ID
   
поля в ответе:
+
fields in response:
* '''cost''' (''decimal'') - стоимость опции на указанный период в EUR
+
* '''cost''' (''decimal'') - the cost of the service for a specified period in EUR
   
пример запроса:
+
request example:
 
<nowiki>https://api.acestream.net/developer?method=getServiceCost &crarr;
 
<nowiki>https://api.acestream.net/developer?method=getServiceCost &crarr;
 
&api_version=1.0 &crarr;
 
&api_version=1.0 &crarr;
 
&api_key=be6f66e0848528139583b567fb222215444fc8ac &crarr;
 
&api_key=be6f66e0848528139583b567fb222215444fc8ac &crarr;
&product=kjYX790gTytRaXV04IvC &crarr;
+
&app=9_50gh753t6uscog88800kcksw04s0o0wccscco8kgsogwkocwgw &crarr;
 
&service=noAds &crarr;
 
&service=noAds &crarr;
 
&period=m1 &crarr;
 
&period=m1 &crarr;
 
&sign=45c84ceffd3ec443586e8f4666b28abde8400768</nowiki>
 
&sign=45c84ceffd3ec443586e8f4666b28abde8400768</nowiki>
   
ответ:
+
response:
 
<nowiki>{"cost":1}</nowiki>
 
<nowiki>{"cost":1}</nowiki>
   
 
===activateService===
 
===activateService===
Активировать опцию для пользователя.
+
Activate service for user
   
В результате успешной активации средства будут списаны с баланса разработчика.
+
As a result of successful activation, funds will be charged from developer's balance.
   
параметры:
+
parameters:
* '''user_key''' (''string'') - ключ пользователя
+
* '''user_key''' (''string'') - user key
* '''service''' (''string'') - идентификатор опции
+
* '''service''' (''string'') - service ID
* '''period''' (''string'') - идентификатор периода
+
* '''period''' (''string'') - period ID
   
поля в ответе:
+
fields in response:
* '''validFrom''' (''unix timestamp'') - с какого времени опция активна
+
* '''validFrom''' (''unix timestamp'') - from what time service is active
* '''validTo''' (''unix timestamp'') - до какого времени опция активна
+
* '''validTo''' (''unix timestamp'') - till what time service will be active
   
пример запроса:
+
request example:
 
<nowiki>https://api.acestream.net/developer?method=activateService &crarr;
 
<nowiki>https://api.acestream.net/developer?method=activateService &crarr;
 
&api_version=1.0 &crarr;
 
&api_version=1.0 &crarr;
 
&api_key=be6f66e0848528139583b567fb222215444fc8ac &crarr;
 
&api_key=be6f66e0848528139583b567fb222215444fc8ac &crarr;
&product=kjYX790gTytRaXV04IvC &crarr;
+
&app=9_50gh753t6uscog88800kcksw04s0o0wccscco8kgsogwkocwgw &crarr;
 
&user_key=a455865e5800fd7efab75f2b4852fc2497f9fc39 &crarr;
 
&user_key=a455865e5800fd7efab75f2b4852fc2497f9fc39 &crarr;
 
&service=noAds &crarr;
 
&service=noAds &crarr;
Строка 91: Строка 91:
 
&sign=c4df772a4a41ad7bbb4d7d07e46cad5e3622c59e</nowiki>
 
&sign=c4df772a4a41ad7bbb4d7d07e46cad5e3622c59e</nowiki>
   
ответ (успешная активация опции):
+
response (successful activation):
 
<nowiki>{"validFrom":1376048972,"validTo":1378640972}</nowiki>
 
<nowiki>{"validFrom":1376048972,"validTo":1378640972}</nowiki>
   
ответ (на балансе разработчика недостаточно средств для активации опции):
+
response (there are not enough funds on developer's balance to activate the service):
 
<nowiki>{"error":"not enough credits"}</nowiki>
 
<nowiki>{"error":"not enough credits"}</nowiki>
   
 
===getUserKeyInfo===
 
===getUserKeyInfo===
Получить информацию о ключе пользователя
+
Get information about user key
   
параметры:
+
parameters:
* '''user_key''' (''string'') - ключ пользователя
+
* '''user_key''' (''string'') - user key
   
поля в ответе:
+
fields in response:
* '''services''' (''array'') - массив опций, привязанных к данному ключу пользователя. Каждая опция описывается такими полями:
+
* '''services''' (''array'') - array of services, bound to this user key. Each service ia described with the following fields
** '''id''' (''string'') - идентификатор опции
+
** '''id''' (''string'') - service ID
** '''validFrom''' (''unix timestamp'') - с какого времени опция активна
+
** '''validFrom''' (''unix timestamp'') - from what time service is active
** '''validTo''' (''unix timestamp'') - до какого времени опция активна
+
** '''validTo''' (''unix timestamp'') - till what time service will be active
** '''enabled''' (''boolean'') - активна ли опция в данный момент
+
** '''enabled''' (''boolean'') - is service active at this moment
   
пример запроса:
+
request example:
 
<nowiki>https://api.acestream.net/developer?method=getUserKeyInfo &crarr;
 
<nowiki>https://api.acestream.net/developer?method=getUserKeyInfo &crarr;
 
&api_version=1.0 &crarr;
 
&api_version=1.0 &crarr;
 
&api_key=be6f66e0848528139583b567fb222215444fc8ac &crarr;
 
&api_key=be6f66e0848528139583b567fb222215444fc8ac &crarr;
&product=kjYX790gTytRaXV04IvC &crarr;
+
&app=9_50gh753t6uscog88800kcksw04s0o0wccscco8kgsogwkocwgw &crarr;
 
&user_key=8fb311be3836b04f61817dbf8a23c05739ebb13e &crarr;
 
&user_key=8fb311be3836b04f61817dbf8a23c05739ebb13e &crarr;
 
&sign=5e0fc46d908e5f224ce9fce9f6a83dd6b3502cc0</nowiki>
 
&sign=5e0fc46d908e5f224ce9fce9f6a83dd6b3502cc0</nowiki>
   
ответ (нет опций):
+
response (no services):
 
<tt>{"services":[]}</tt>
 
<tt>{"services":[]}</tt>
   
ответ (есть опции):
+
response (there are services):
 
<nowiki>{"services": [
 
<nowiki>{"services": [
 
{"id": "noAds", "validFrom": 1374673235, "validTo": 1445089235, "enabled": true},
 
{"id": "noAds", "validFrom": 1374673235, "validTo": 1445089235, "enabled": true},
Строка 129: Строка 129:
   
 
===createUserKey===
 
===createUserKey===
Создать новый ключ пользователя
+
Create a new user key
   
Действие ключа пользователя распостраняется только на продукт разработчика, указанный в параметре <tt>product</tt>.
+
Effect of user key applies only to developer's product, specified in parameter <tt>product</tt>.
   
поля в ответе:
+
fields in response:
* '''userKey''' (''string'') - созданный ключ пользователя
+
* '''userKey''' (''string'') - created user key
* '''extension''' (''string'') - [[extension string]] (строка, которая используется для последующей загрузки созданного ключа пользователя в движок)
+
* '''extension''' (''string'') - content of extension file which is used for the following loading to the engine
   
пример запроса:
+
request example:
   
 
<nowiki>https://api.acestream.net/developer?method=createUserKey &crarr;
 
<nowiki>https://api.acestream.net/developer?method=createUserKey &crarr;
 
&api_key=cd3119af58cfa8833ba105a4fd4eb791395b921c &crarr;
 
&api_key=cd3119af58cfa8833ba105a4fd4eb791395b921c &crarr;
 
&api_version=1.0 &crarr;
 
&api_version=1.0 &crarr;
&product=kjYX790gTytRaXV04IvC &crarr;
+
&app=3_250o55jdisu88skggogg4g4w4wc8wgskss4gkgkkk40k0gcsw8 &crarr;
 
&sign=99982a11708ef4a80e12f1ca845d314340db8869</nowiki>
 
&sign=99982a11708ef4a80e12f1ca845d314340db8869</nowiki>
   
ответ:
+
response:
 
<tt>{
 
<tt>{
 
"userKey": "c7456d962209ce22a8edd0c788940a15792bc575",
 
"userKey": "c7456d962209ce22a8edd0c788940a15792bc575",
Строка 155: Строка 155:
 
}</tt>
 
}</tt>
   
==Идентификаторы опций==
+
==Service ID==
* '''noAds''' - опция "No ADs" (отключение рекламы Ace Stream)
+
* '''noAds''' - service "No ADs" (disable Ace Stream ads)
* '''premium''' - опция "Premium Streams" (доступ к премиум-контенту)
+
* '''premium''' - service "Premium Streams" (access to premium content)
* '''premium1device''' - премиум на одно устройство
+
* '''premium1device''' - service "Premium Streams" for one device
   
==Идентификаторы периодов==
+
==Period ID==
* '''m1''' - 30 дней
+
* '''m1''' - 30 days
* '''y1''' - 365 дней
+
* '''y1''' - 365 days

Текущая версия на 13:16, 5 сентября 2017

Содержание

[править] Common description of API

This API allows application developers to work with user keys in Ace Stream system. API provides methods for creating user keys and activating different options for the keys.

[править] Requests format

API requests are sent via HTTP-GET method to the following addresses:

  • test mode: https://api-sandbox.acestream.net/developer
  • work mode: https://api.acestream.net/developer

Responses for these requests comes in JSON format.

If during query processing an error was occurred, the following kind of response will be sent:

{"error":"error descrtiption"}

Responses to successfully processed requests depend on a method being called.

[править] Required common parameters for all requests

  • method - called API method
  • api_key - API client key
  • api_version - supported API version (current version: 1.0)
  • product - public part of product key
  • sign - request's digital signature

[править] Algorithm for generating a digital signature

  • array of strings like "parameter_name=parameter_value" is created
  • the resulting array is sorted
  • elements of the sorted array are combined in a string with a separator "#"
  • private key of API client is added to the resulting string
  • signature is sha1-hash of the resulting string (in hexadecimal representation, 40 characters, lowercase)

PHP code:

function makeSignature(array $params, $apiSecret)
{
    $checkParams = array();
    foreach($params as $k => $v) {
        $checkParams[] = $k . '=' . $v;
    }
    sort($checkParams);
    
    $payload = join('#', $checkParams);
    $sign = sha1($payload . $apiSecret);
    
    return $sign;
}

[править] API methods

[править] getServiceCost

Get the cost of a service

parameters:

  • service (string) - service ID
  • period (string) - period ID

fields in response:

  • cost (decimal) - the cost of the service for a specified period in EUR

request example:

https://api.acestream.net/developer?method=getServiceCost ↵
  &api_version=1.0 ↵
  &api_key=be6f66e0848528139583b567fb222215444fc8ac ↵
  &app=9_50gh753t6uscog88800kcksw04s0o0wccscco8kgsogwkocwgw ↵
  &service=noAds ↵
  &period=m1 ↵
  &sign=45c84ceffd3ec443586e8f4666b28abde8400768

response:

{"cost":1}

[править] activateService

Activate service for user

As a result of successful activation, funds will be charged from developer's balance.

parameters:

  • user_key (string) - user key
  • service (string) - service ID
  • period (string) - period ID

fields in response:

  • validFrom (unix timestamp) - from what time service is active
  • validTo (unix timestamp) - till what time service will be active

request example:

https://api.acestream.net/developer?method=activateService ↵
  &api_version=1.0 ↵
  &api_key=be6f66e0848528139583b567fb222215444fc8ac ↵
  &app=9_50gh753t6uscog88800kcksw04s0o0wccscco8kgsogwkocwgw ↵
  &user_key=a455865e5800fd7efab75f2b4852fc2497f9fc39 ↵
  &service=noAds ↵
  &period=m1 ↵
  &sign=c4df772a4a41ad7bbb4d7d07e46cad5e3622c59e

response (successful activation):

{"validFrom":1376048972,"validTo":1378640972}

response (there are not enough funds on developer's balance to activate the service):

{"error":"not enough credits"}

[править] getUserKeyInfo

Get information about user key

parameters:

  • user_key (string) - user key

fields in response:

  • services (array) - array of services, bound to this user key. Each service ia described with the following fields
    • id (string) - service ID
    • validFrom (unix timestamp) - from what time service is active
    • validTo (unix timestamp) - till what time service will be active
    • enabled (boolean) - is service active at this moment

request example:

https://api.acestream.net/developer?method=getUserKeyInfo ↵
  &api_version=1.0 ↵
  &api_key=be6f66e0848528139583b567fb222215444fc8ac ↵
  &app=9_50gh753t6uscog88800kcksw04s0o0wccscco8kgsogwkocwgw ↵
  &user_key=8fb311be3836b04f61817dbf8a23c05739ebb13e ↵
  &sign=5e0fc46d908e5f224ce9fce9f6a83dd6b3502cc0

response (no services):

{"services":[]}

response (there are services):

{"services": [
     {"id": "noAds", "validFrom": 1374673235, "validTo": 1445089235, "enabled": true},
     {"id": "premium", "validFrom": 1374858187, "validTo": 1448301787, "enabled": true}
 ]}


[править] createUserKey

Create a new user key

Effect of user key applies only to developer's product, specified in parameter product.

fields in response:

  • userKey (string) - created user key
  • extension (string) - content of extension file which is used for the following loading to the engine

request example:

https://api.acestream.net/developer?method=createUserKey ↵
  &api_key=cd3119af58cfa8833ba105a4fd4eb791395b921c ↵
  &api_version=1.0 ↵
  &app=3_250o55jdisu88skggogg4g4w4wc8wgskss4gkgkkk40k0gcsw8 ↵
  &sign=99982a11708ef4a80e12f1ca845d314340db8869

response:

{
 "userKey": "c7456d962209ce22a8edd0c788940a15792bc575",
 "extension": "F5T6L+X\/TnhqoXP\/Tyzlad51LoGI3InF676iap ↵
n6vuJUOLbFJNGfYQcakQMXAhSTrlc7XlmUydoGcnCXhw5qefoinHZHIL ↵
VW51Pd5I0\/0YbKsmn\/Y78F1JhG1ckBExCtQTf\/NgLj+8TeTyPOfQS ↵
lRub3k4G\/m0+Iqyq4hshKnmTIBlkDcytWZ5DyQFLetllUUz9rLFjvR8 ↵
mF0qy3GCYtAw=="
}

[править] Service ID

  • noAds - service "No ADs" (disable Ace Stream ads)
  • premium - service "Premium Streams" (access to premium content)
  • premium1device - service "Premium Streams" for one device

[править] Period ID

  • m1 - 30 days
  • y1 - 365 days
Персональные инструменты