• API поставщика товаров
Методы

Структура каталога поставщика:

Категория 1
.. Подкатегория 1
.. Подкатегория n
Категория n
.. Подкатегория 1

Поставщик передает партнеру информацию о структуре товарного каталога до запуска проекта и после не меняет ее.

Витрина поставщика находится по адресу:
https://mybill.your_url.ru/ - тестовый контур поставщика.
https://api.your_url.ru/ - продакшен поставщика.

Витрина принимает POST запросы по https. Данные передаются в формате xml.
Любой запрос на витрину содержит следующие параметры:
В дальнейшем все адреса методов будут указаны относительно исходного адреса контура который использует партнер.

Базовое оформление запроса, который выполняет партнер на витрину поставщика:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>1</TransactionID>
       <MethodName>UserRegistration</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
   <Parameters>
      …
      Здесь будет перечень параметров, необходимых методу.
      …
   </Parameters>
</Request>
Пример ответа витрины поставщика в случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<Return>
   <Error>
       <ErrorCode>ClientEMail_NotUnique</ErrorCode>
       <ErrorMessage></ErrorMessage>
   </Error>
   <Status>1</Status>
</Return>
По статусу 1 - можно определить, что выполнение метода закончилось с ошибкой. (1 - ошибка, 2 – операция успешно выполнена).

Примерная логика работы с сервисом поставщика партнером

  1. Методом GetCategories партнер получает список доступных товарных категорий.
  2. Методом GetProduct партнер получает список доступных товаров и формируете витрину.
  3. Партнер регистрирует у себя покупателя.
  4. После того как покупатель собрал корзину и готов к оформлению заказа, партнер использует метод GetDeliveryVariants, в котором поставщик возвращает доступные способы доставки и их стоимость для каждого товара.
  5. После выбора покупателем способа доставки, партнер использует метод MakeOrder для оформления заказа у поставщика.
  6. После получения информации об успешном формировании заказа от поставщика, партнер использует метод ConfirmOrder для его итогового подтверждения.

Общие методы поставщика
Метод получения состояния счета (Account)

  1. POST запрос посылается партнером на /Account
  2. Данный метод возвращает размер средств на лицевом счете партнера в пределах которого он может размещать заказы.
Поля запроса:
Поля ответа:
Пример запроса:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>Account</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
</Request>
Пример ответа в случае успешного выполнения:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <Account>100000.00</Account>
</Return>
Метод получения статуса заказа (GetOrderStatus)

  1. POST запрос посылается партнером на /GetOrderStatus
  2. Данный метод возвращает партнеру текущий статус заказа
Поля запроса:
Поля ответа:
Статусы заказов:
Пример запроса:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>GetOrderStatus</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
   <Parameters>
       <BasketID>100</BasketID>
   </Parameters>
</Request>
Пример ответа в случае успешного выполнения:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <OrderStatus>
    <ID>4</ID>
    <Status>Доставляется</Status>
    <Changed>2020-11-12 22:23:24</Changed>
  </OrderStatus>
</Return>
Возможные коды ошибок:
Методы поставщика для заказа товаров
Метод получения списка категорий (GetCategories)
  1. POST запрос посылается партнером на /GetCategories
  2. Данный метод возвращает список категорий и возможные параметры (и их значения) для товаров в каждой категории.
Поля запроса:
Поля ответа:
Пример запроса:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>GetCategories</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
</Request>
Пример ответа в случае успешного выполнения:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <Categories>
    <Category id="1">
      <name>Телевизоры</name>
      <Params>
        <Param id="1">
          <name>Диагональ экрана</name>
          <value id="1" unit="дюйм">27</value>
          <value id="2" unit="дюйм">32</value>
          <value id="3" unit="дюйм">54</value>
        </Param>
      </Params>
    </Category>
    <Category id="2">
      <name>Дверная фурнитура</name>
      <Params>
        <Param id="2">
          <name>Цвет</name>
          <value id="5">Белый</value>
          <value id="7">Бронза</value>
          <value id="8">Черный</value>
          <value id="8">Серебристый</value>
        </Param>
        <Param id="3">
          <name>Страна</name>
          <value id="21">Россия</value>
          <value id="22">Италия</value>
        </Param>
      </Params>
    </Category>
   </Categories>
</Return>
Метод получения товаров (GetProduct)

  1. POST запрос посылается партнером на /GetProduct
  2. Данный метод возвращает информацию о товарах. В запросе могут передаваться следующие фильтры: ID товара(ов), ID категорий, значения параметров. В случае если товар в данный момент невозможно заказать, описание не передается. Если в результате не найдено ни одного подходящего товара – возвращается ошибка. Фильтры в запросе могут комбинироваться – например можно запросить список товаров относящихся к категориям «Дверные ручки» и «Дверная фурнитура» и имеющих при этом белый цвет. Информация по категориям и возможным параметрам получается методом.
Поля запроса:
Поля ответа:
Пример запроса по ID товаров:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>GetProduct</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
   <Parameters>
       <Products>
           <Product>136311798</Product>
           <Product>27665879</Product>
       </Products>
   </Parameters>
</Request>
Пример запроса по ID категорий и значению параметров:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>GetProduct</MethodName>
       <Hash>2cfc084ba11ac55371a9a24cc34121e7</Hash>
   </Authentication>
   <Parameters>
       <Limit offset="0" row_count="500"/>
       <Categories>
           <Category>83</Category>
           <Category>87</Category>
       </Categories>
       <Params>
           <Param>5305</Param>
           <Param>1807</Param>
       </Params>
   </Parameters>
</Request>
Пример ответа в случае ошибки:

<?xml version="1.0" encoding="utf-8"?>
<Return>
   <Error>
       <ErrorCode>NotFoundProducts</ErrorCode>
       <ErrorMessage>Продуктов соответствующих запросу не найдено</ErrorMessage>
   </Error>
   <Status>1</Status>
</Return>
Возможные коды ошибок:
Метод получения вариантов доставки (GetDeliveryVariants)

  1. POST запрос посылается партнером на /GetDeliveryVariants
  2. Данный метод возвращает список вариантов доставки с их параметрами для указанных товаров и региона доставки. Варианты доставки привязываются к номеру заказа в системе поставщика.
Указание секции DeliveryAddress является обязательным если в списке товаров присутствуют товары требующие физической доставки.

Поля запроса:
Поля ответа:
Пример запроса:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>GetDeliveryVariants</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
   <Parameters>
       <BasketID>356</BasketID>
       <DeliveryAddress>
       </DeliveryAddress>
       <Products>
           <Product>
               <Id>1</Id>
               <Quantity>1</Quantity>
           </Product>
           <Product>
               <Id>2</Id>
               <Quantity>5</Quantity>
           </Product>
       </Products>
   </Parameters>
</Request>
Пример ответа в случае успешного выполнения:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <BasketID>333</BasketID>
  <Deliverys>
    <Logistician>
      <Id>4</Id>
      <DeliveryVariants>
        <DeliveryVariant>
          <Id>1</Id>
          <Name>Загрузка онлайн или получение в SMS</Name>
          <Type>Электронным способом</Type>
          <Price>0</Price>
          <EstimatedDeliveryTime>1</EstimatedDeliveryTime>
        </DeliveryVariant>
      </DeliveryVariants>
      <Products>
          <ProductId>1</ProductID>
          <ProductId>2</ProductID>
      </Products>
    </Logistician>
  </Deliverys>
</Return>
Возможные коды ошибок:
Метод оформления заказа (MakeOrder)

  1. POST запрос посылается партнером на /MakeOrder
  2. Данный метод оформляет заказ и передает его поставщику. Методу передаются данные покупателя и информация по товарам – какой метод доставки выбран покупателем для каждого товара. В случае успешного оформления заказа возвращается пустой положительный ответ (с Status = 2) без данных.
  3. Адрес покупателя для доставки обязателен в случае если выбраны способы доставки: курьерская доставка или почтовая. Если доставка самовывоз или электронная адрес передавать не обязательно. При передаче адреса обязательными являются параметры Street и Building1. Населенный пункт в котором находится адрес используется полученный при вызове метода GetDeliveryVariants.
Заказ делается однократно. В случае повторной передачи партнером запроса MakeOrder с тем же значением BasketID (по причине ошибок, сетевых проблем и т.п.) дополнительных запросов к поставщику и заказов товаров не делается. Результат выводится соответствующий результату первого полученного запроса (успешный, либо ошибка). В случае повторной отправки запроса с параметрами отличающимися от первого будет выдана ошибка WrongBasketID (Нельзя изменить заказ). То есть если по какой то причине партнер не получил ответ на запрос MakeOrder, то он может его повторить с теми же параметрами. Однако оптимальным вариантом будет перед повторением MakeOrder сделать запрос GetOrderStatus - возможно заказ уже был успешно принят и находится в работе.

Поля запроса:
Пример запроса:

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <Authentication>
    <Login>mybill</Login>
    <TransactionID>1547203965</TransactionID>
    <MethodName>MakeOrder</MethodName>
    <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
  </Authentication>
  <Parameters>
    <BasketID>123</BasketID>
    <OrderID>100</OrderID>
    <DeliveryAddress>
      <Street>ул. Красивая</Street>
      <Building1>1</Building1>
      <Room>10</Room>
    </DeliveryAddress>
    <User>
      <FirstName>Иван</FirstName>
      <MiddleName>Иванович</MiddleName>
      <LastName>Иванов</LastName>
      <Email>ivanov@email.ru</Email>
      <Phone>+79091231234</Phone>
    </User>
    <Products>
      <Product>
        <Id>69713</Id>
        <DeliveryID>1</DeliveryID>
      </Product>
      <Product>
        <Id>55711</Id>
        <DeliveryID>3</DeliveryID>
      </Product>
    </Products>
  </Parameters>
</Request>
Пример ответа в случае успешного выполнения:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
</Return>
Возможные коды ошибок:
Метод подтверждения оплаты заказа (ConfirmOrder)

  1. POST запрос посылается партнером на /ConfirmOrder
  2. Данный метод подтверждает оплату уже оформленного заказа и передает его поставщику. Методу передаются ID корзины с которым был создан заказ. В случае успешной передачи заказа поставщику возвращается пустой положительный ответ (с Status = 2) без данных.
  3. Подтверждение оплаты заказа делается однократно. В случае повторной передачи партнером запроса ConfirmOrder с тем же значением BasketID (по причине ошибок, сетевых проблем и т.п.) дополнительных запросов к поставщику и заказов товаров не делается. Результат выводится соответствующий результату первого полученного запроса (успешный, либо ошибка). То есть если по какой то причине партнер не получил ответ на запрос ConfirmOrder, то он может его повторить с тем же BasketID. Однако оптимальным вариантом будет перед повторением ConfirmOrder сделать запрос GetOrderStatus.
При подтверждении заказа проверяется неизменность цены товаров в заказе, доступность и наличие необходимого количества этих товаров. В случае невозможности исполнения заказа (изменилась цена, товара нет в наличии) поставщиком будет выдана ошибка и заказ перейдет в статус "Отменен (изменились условия)". Это финальный статус и для повторения заказа его надо будет сделать снова. Неподтвержденный заказ хранится в системе поставщика в течении Х? времени. В случае если в течении этого времени заказ не будет подтвержден - система поставщика его автоматически отменит.

Поля запроса:
Пример запроса:

<?xml version="1.0" encoding="utf-8"?>
<Request>
  <Authentication>
    <Login>mybill</Login>
    <TransactionID>1547203965</TransactionID>
    <MethodName>ConfirmOrder</MethodName>
    <Hash>162e20c14cae620c27fee4c63afaa927</Hash>
  </Authentication>
  <Parameters>
    <BasketID>333</BasketID>
  </Parameters>
</Request>
Пример ответа в случае успешного выполнения:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
</Return>
Возможные коды ошибок:
Общие ошибки поставщика для всех методов
Пример кода для запроса

Пример кода на PHP для запроса к API:

<?php

$transationID = time();
$login = 'Login';
$password = 'Password';

$method = 'MakeOrder';
$url = 'http://mybill.your_utl.ru/…/' . $method;
$hash = md5($transationID . $method . $login . $password);

$request = <<<XML
<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>{$login}</Login>
       <TransactionID>{$transationID}</TransactionID>
       <MethodName>{$method}</MethodName>
       <Hash>{$hash}</Hash>
   </Authentication>
   <Parameters>
       <OrderID>363</OrderID>
       <User>
           <FirstName>Иванов</FirstName>
           <MiddleName>Иван</MiddleName>
           <LastName>Иванович</LastName>
           <Email>ivanov@email.ru</Email>
           <Phone>+79091231234</Phone>
       </User>
       <DeliveryAddress>
           <ZipCode>249034</ZipCode>
           <Region>Калужская область</Region>
           <City>Калуга</City>
           <Address>ул. Красивая, д. 1, кв. 1</Address>
       </DeliveryAddress>
       <Products>
           <Product>
               <Id>1</Id>
               <DeliveryID>1</DeliveryID>
               <Quantity>2</Quantity>
           </Product>
           <Product>
               <Id>2</Id>
               <DeliveryID>1</DeliveryID>
               <Quantity>1</Quantity>
           </Product>
       </Products>
   </Parameters>
</Request>
XML;

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Content-Type: text/xml; charset=utf-8',
    'Content-Length: ' . strlen($request))
);
curl_setopt($curl, CURLOPT_POSTFIELDS, $request);

$response = curl_exec($curl);
curl_close($curl);

Вернуться назад