Клиентское API

Что такое клиентское API Axiom?

Клиентское API Axiom позволяет использовать данные из системы Axiom на сторонних сайтах или приложениях. Например, пользователи Axiom могут использовать клиентское API Axiom, чтобы обеспечивать своим клиентам или партнерам онлайн доступ к своим товарным запасам и ценам.

Процесс использования клиентского API может выглядеть следующим образом:

  • Пользователь Axiom регистрирует в системе Axiom учетные записи (имя, пароль) для своих клиентов (покупателей или партнеров);
  • Пользователь Axiom может использовать клиентское API Axiom у себя на сайте или в интернет-магазине, чтобы обслуживать зарегистрированных клиентов.
  • Зарегистрированные клиенты могут использовать клиентское API Axiom в своих приложениях для получения данных из Axiom.

Данный документ предназначен для разработчиков веб-сайтов и приложений. В этом документе можно ознакомиться с принципами использования API и найти справочный материал по существующим параметрам.

Ограничения на использование

Использование клиентского API Axiom возможно только для пользователей, у которых имеется учетная запись в системе Axiom.  Пока на использование клиентского API Axiom накладывается ограничение, составляющее 200 запросов в день для каждого пользователя.

Клиентское API находится разработке, поэтому возможны изменения в этом документе без предварительного уведомления.

Запросы к клиентскому API

Запрос к клиентскому API должен иметь следующий формат:

http://www.axiomsoft.by/api/function?parameters

здесь function может принимать одно из следующих значений:

  • find-products-by-keyword — поиск товаров по ключевому слову;
  • get-product-by-id — получение данных о товаре по идентификатору;
  • get-product-analogues — получение данных об аналогах товара;
  • get-product-stocks — получение данных о запасах товара;
  • get-product-prices — получение данных о цене товара.

Во всех случаях некоторые параметры являются обязательными, а другие — нет. Параметры разделяются амперсандами (&), что является стандартом для всех адресов URL. Ниже представлен список обязательных параметров для каждой функции и форматы вывода данных.

find-products-by-keyword

Параметры
  • keyword — строка, которую требуется найти в данных о товаре. Любая последовательность символов. Число букв и/или цифр в последовательности должно быть не менее трех.
Пример
http://www.axiomsoft.by/clientapi/find-products-by-keyword?keyword=567
Формат вывода XML
<axiom-response>
  <status>OK</status>
  <products>
    <product>
      <id>31147</id>
      <name>Болт колесный</name>
      <product-no>07456</product-no>
      <alternate-numbers></alternate-numbers>
      <producer>FEBI</producer>
      <unit>шт</unit>
      <has-analogues>true</has-analogues>
      <description>BPW, M22*1,5/M22*2*111, 0980623220, комплект без сухарей с еврогайкой</description>
    </product> 
    <product> 
      <id>13897</id> 
      <name>Накладки тормозные</name> 
      <product-no>B245634010</product-no> 
      <alternate-numbers>1903618505 1903619037</alternate-numbers>
      <producer>PAGIN</producer>
      <unit>компл</unit>
      <has-analogues>false</has-analogues>
      <description></description> 
    </product>
  </products>
</axiom-response>
Ограничения

Может быть возвращено не более 100 товаров в одном запросе.

get-product-by-id

Параметры
  • id — идентификатор товара в Axiom. Целое число.
Пример
http://www.axiomsoft.by/api/get-product-by-id?id=31147
Формат вывода XML
<axiom-response>
  <status>OK</status>
  <product>
    <id>31147</id>
    <name>Болт колесный</name>
    <product-no>07456</product-no>
    <alternate-numbers></alternate-numbers>
    <producer>FEBI</producer>
    <unit>шт</unit>
    <has-analogues>true</has-analogues>
    <description>BPW, M22*1,5/M22*2*111, 0980623220, комплект без сухарей с еврогайкой</description>
  </product> 
</axiom-response>

get-product-analogues

Параметры
  • id — идентификатор товара в Axiom. Целое число.
Пример
http://www.axiomsoft.by/api/get-product-analogues?id=28754
Формат вывода XML
<axiom-response>
  <status>OK</status>
  <products>
    <product>
      <id>31147</id>
      <name>Болт колесный</name>
      <product-no>07456</product-no>
      <alternate-numbers></alternate-numbers>
      <producer>FEBI</producer>
      <unit>шт</unit>
      <has-analogues>true</has-analogues>
      <description>BPW, M22*1,5/M22*2*111, 0980623220, комплект без сухарей с еврогайкой</description>
    </product> 
    <product> 
      <id>13897</id> 
      <name>Накладки тормозные</name> 
      <product-no>B245634010</product-no> 
      <alternate-numbers>1903618505 1903619037</alternate-numbers>
      <producer>PAGIN</producer>
      <unit>компл</unit>
      <has-analogues>false</has-analogues>
      <description></description> 
    </product>
  </products>
</axiom-response>

get-product-stocks

Параметры
  • id — идентификатор товара в Axiom. Целое число.
Пример
http://www.axiomsoft.by/api/get-product-stocks?id=31147
Формат вывода XML
<axiom-response>
  <status>OK</status>
  <stocks>
    <product>
      <id>31147</id>
      <name>Болт колесный</name>
      <product-no>07456</product-no>
      <alternate-numbers></alternate-numbers>
      <producer>FEBI</producer>
      <unit>шт</unit>
      <has-analogues>true</has-analogues>
      <description>BPW, M22*1,5/M22*2*111, 0980623220, комплект без сухарей с еврогайкой</description>
    </product>
    <stock-item>
      <department>
        <name>АГ Витебск</name>
        <address>
          <street>ул. Панковой, 3</street>
          <city>Витебск</city>
          <region></region>
          <district></distring>
          <country>Беларусь</country>
          <zip></zip> 
        </address>
        <phone>8 (0212) 23-74-75</phone>
      </department> 
      <quantity>12.000</quantity>
    </stock-item>
    <stock-item>
      <department>
        <name>АГ Могилев</name>
        <address>
          <street>Калужская, 13</street>
          <city>Могилев</city>
          <region></region>
          <district></distring>
          <country>Беларусь</country>
          <zip></zip> 
        </address>
        <phone>8 (0222) 46-80-96</phone>
      </department> 
      <quantity>4.000</quantity>
    </stock-item>
  </stocks>
</axiom-reponse>

get-product-prices

Параметры
  • id — идентификатор товара в Axiom. Целое число.
  • currency — валюта, в которой следует вернуть цену.  Значением параметра может быть мнемоника или цифровой код валюты. Допускается указание нескольких валют.
Пример
http://www.axiomsoft.by/api/get-product-prices?id=31147&currency=USD&currency=EUR
Формат вывода XML
<axiom-response>
  <status>OK</status>
  <prices>
    <product>
      <id>31147</id>
      <name>Болт колесный</name>
      <product-no>07456</product-no>
      <alternate-numbers></alternate-numbers>
      <producer>FEBI</producer>
      <unit>шт</unit>
      <has-analogues>true</has-analogues>
      <description>BPW, M22*1,5/M22*2*111, 0980623220, комплект без сухарей с еврогайкой</description>
    </product>
    <price>
      <currency>
        <mnemonic>USD</mnemonic>
      </currency> 
      <value>12.22</value>
    </price>
    <price>
      <currency>
        <mnemonic>EUR</mneminic>
      </currency>
      <value>11.09</value>
    </price>
  </prices>
</axiom-reponse>

Необязательные параметры

  • output — задает формат, в котором будет возвращен результат. Возможные значения xml, json. По умолчанию — xml. Формат json в настоящий момент не поддерживается, однако в перспективе планируется сделать json форматом по умолчанию, поэтому рекомендуем до этого момента всегда указывать output в запросе.

Ответы службы клиентского API Axiom

Ответы службы клиентского API Axiom возвращаются в формате, указанном параметром output в пути запроса URL.

Обратите внимание, что ответ в формате XML состоит из одного элемента <axiom-response> и следующих двух элементов верхнего уровня:

  • <status>, содержащий результат выполнения запроса. См. раздел «Коды статуса» ниже.
  • Ноль или более элементов результата (<products>, <stocks>, <prices>), каждый из которых содержит соответствующую запросу информацию.

Коды статуса

Поле "status", входящее в объект ответа клиентского API, содержит статус запроса и может включать в себя отладочную информацию для отслеживания сбоев службы. Поле "status" может содержать следующие значения:

  • "OK" — указывает на отсутствие ошибок. Был возвращен по крайней мере один результат.
  • "ZERO_RESULTS" — указывает, что запрос выполнен успешно, но не было возвращено никаких результатов. Это может произойти, например, если в запросе был передан id несуществующего товара.
  • "OVER_QUERY_LIMIT" — указывает на превышение квоты по количеству запросов в сутки.
  • "OVER_RECORD_LIMIT" — указывает на превышение количества найденных записей.
  • "REQUEST_DENIED" — означает, что запрос отклонен, обычно из-за отсутствия доступа.
  • "INVALID_REQUEST" — указывает, что запрос составлен некорректно.

Авторизация и поддержка сеанса

Вызывающее приложение должно обеспечивать возможность авторизации при первом вызове клиентского API Axiom, а также поддержку сеанса (при успешной авторизации на стороне Axiom создается сеанс, идентификатор которого передается клиентскому приложению).