• API. Product supplier API
Commands

Supplier catalogue structure:

Category
.. Subcategory 1
.. Subcategory n
Category n
.. Subcategory n

The supplier gives the partner information about the structure of the product catalogue before the launch of the project and does not change it afterwards.

The supplier's showcase is located at:
https://mybill.your_url.ru/ - supplier's test environment.
https://api.your_url.ru/ - supplier's production environment.

The showcase accepts POST requests via https. The data is transmitted in XML format.

Any request to the showcase contains the following parameters:
In what follows, all command addresses will be specified relative to URL of the supplier's environment used by the partner.

The basic layout of the request that the partner send to the supplier's showcase:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>1</TransactionID>
       <MethodName>UserRegistration</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
   <Parameters>
      …
      Here will be the list of parameters required by the command.
      …
   </Parameters>
</Request>
Example of the supplier's showcase response in case of error:

<?xml version="1.0" encoding="utf-8"?>
<Return>
   <Error>
       <ErrorCode>ClientEMail_NotUnique</ErrorCode>
       <ErrorMessage></ErrorMessage>
   </Error>
   <Status>1</Status>
</Return>
By status 1, it is possible to determine that commands's execution ended with an error. (1 - error, 2 - operation successfully completed).

Approximate logic for working of the partner with a supplier service

  1. Using the GetCategories command, the partner receives a list of available product categories.
  2. Using the GetProduct command, the partner receives a list of available goods for displaying on the showcase.
  3. The partner registers the customer.
  4. After the customer has built a basket and is ready to place an order, the partner uses the GetDeliveryVariants command, in which the supplier returns available delivery methods and their cost for each product.
  5. After the customer has chosen the delivery method, the partner uses the MakeOrder command to place an order with the supplier.
  6. After receiving information about the successful order from the supplier, the partner uses the ConfirmOrder command for final confirmation.

Common supplier commands
Command for retrieving account status (Account)

  1. POST request is sent by the partner to /Account
  2. This command returns the amount of funds in the partner's personal account within which they can place orders.
Request parameters:
Response parameters:
Example of the request:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>Account</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
</Request>
An example of a response if completed successfully:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <Account>100000.00</Account>
</Return>
Command for retrieving order status (GetOrderStatus)

  1. POST request is sent by the partner to /GetOrderStatus
  2. This command returns the current order status to the partner.

Request parameters:
Response parameters:
Order statuses:
Example of the request:

<?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>
An example of a response if completed successfully:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <OrderStatus>
    <ID>4</ID>
    <Status>Delivered</Status>
    <Changed>2020-11-12 22:23:24</Changed>
  </OrderStatus>
</Return>
Possible error codes:
Supplier commands for ordering goods
Command for retrieving a list of categories (GetCategories)

  1. POST request is sent by the partner to /GetCategories
  2. This command returns a list of categories and possible parameters (and their values) for goods in each category.

Request parameters:
Response parameters:
Example of the request:

<?xml version="1.0" encoding="utf-8"?>
<Request>
   <Authentication>
       <Login>mybill</Login>
       <TransactionID>3</TransactionID>
       <MethodName>GetCategories</MethodName>
       <Hash>f5bb0c8de146c67b88babbf4e6584cc0</Hash>
   </Authentication>
</Request>
An example of a response if completed successfully:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
  <Categories>
    <Category id="1">
      <name>TVs</name>
      <Params>
        <Param id="1">
          <name>Screen size</name>
          <value id="1" unit="inch">27</value>
          <value id="2" unit="inch">32</value>
          <value id="3" unit="inch">54</value>
        </Param>
      </Params>
    </Category>
    <Category id="2">
      <name>Door fitting</name>
      <Params>
        <Param id="2">
          <name>Цвет</name>
          <value id="5">White</value>
          <value id="7">Bronze</value>
          <value id="8">Black</value>
          <value id="8">Silver</value>
        </Param>
        <Param id="3">
          <name>Country</name>
          <value id="21">Russia</value>
          <value id="22">Italy</value>
        </Param>
      </Params>
    </Category>
   </Categories>
</Return>
Command for retrieving products (GetProduct)

  1. POST request is sent by the partner to /GetProduct
  2. This command returns information about products. The following filters can be passed in the request: product ID(s), category ID, parameter values. If a product cannot be ordered at the moment, no description is passed. If no matching goods are found as a result, an error is returned. Filters can be combined in the request. For example, you can request a list of products from categories "Door handles" and "Door fittings" and with white colour. The information by category and possible parameters can be determined by the following command.

Request parameters:
Response parameters:
Example of the request by product 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>
Example of the request by category ID and parameter value:

<?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>
Example of the response in case of an error:

<?xml version="1.0" encoding="utf-8"?>
<Return>
   <Error>
       <ErrorCode>NotFoundProducts</ErrorCode>
       <ErrorMessage>No products matching the request were found</ErrorMessage>
   </Error>
   <Status>1</Status>
</Return>
Possible error codes:
Command for retrieving delivery options (GetDeliveryVariants)

  1. POST request is sent by the partner to /GetDeliveryVariants
  2. This command returns a list of delivery options with their parameters for the specified products and delivery region. The delivery options are mapped to the order ID in the supplier's system.

Specification of the DeliveryAddress section is mandatory if the list of products contains products requiring physical delivery.

Request parameters:
Response parameters:
Example of the request:

<?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>
Example of the response if completed successfully:

<?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>Online download or receipt by SMS</Name>
          <Type>Electronically</Type>
          <Price>0</Price>
          <EstimatedDeliveryTime>1</EstimatedDeliveryTime>
        </DeliveryVariant>
      </DeliveryVariants>
      <Products>
          <ProductId>1</ProductID>
          <ProductId>2</ProductID>
      </Products>
    </Logistician>
  </Deliverys>
</Return>
Possible error codes:
Ordering command (MakeOrder)

  1. POST request is sent by the partner to /MakeOrder
  2. This command places the order and sends it to the supplier. The command sends the customer's data and information on products - which delivery method the customer selected for each product. If successful, it returns empty positive response (with Status = 2) without any data.
  3. The customer's address for delivery is required if the selected delivery method is courier or postal. The address is not required for pick-up or electronic delivery. The Street and Building parameters are compulsory. The location where the address is used is obtained by calling the GetDeliveryVariants command.

The order is made once. If a partner resubmits a MakeOrder request with the same BasketID value (due to errors, network problems, etc.), no additional requests to the supplier and goods orders are made. The result is displayed corresponding to the result of the first received request (successful, or error). In case of repeating a request with parameters differing from the first, the WrongBasketID error will be displayed (It is impossible to change the order). That is, if for some reason the partner has not received a response to the MakeOrder request, they can repeat it with the same parameters. However, the best option is to make GetOrderStatus request before repeating MakeOrder. Probably, the order has already been successfully accepted and is in operation.

Request parameters:
Example of the request:

<?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>Krasivaya str.</Street>
      <Building1>1</Building1>
      <Room>10</Room>
    </DeliveryAddress>
    <User>
      <FirstName>Ivan</FirstName>
      <MiddleName>Ivanovich</MiddleName>
      <LastName>Ivanov</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>
Example of response if completed successfully:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
</Return>
Possible error codes:
Command of order payment confirmation (ConfirmOrder)

  1. POST request is sent by the partner to /ConfirmOrder
  2. This command confirms payment for the order already placed and sends it to the supplier. The ID of the basket with which the order was created is sent. In case of successful transfer of the order to the supplier, an empty positive response (with Status = 2) without data is returned.
  3. Confirmation of payment for the order is made once. In case of repeated transfer of ConfirmOrder request by the partner with the same BasketID value (due to errors, network problems, etc.) no additional requests to the supplier or goods orders are made. The result is displayed in accordance with the result of the first request (successful or error). That is, if for some reason the partner failed to receive a reply to ConfirmOrder request, he/she can repeat it with the same BasketID. However, the best way is to make GetOrderStatus request before repeating ConfirmOrder.

When confirming the order, the price of the goods in the order, the availability and accessibility of the necessary quantities of these goods are checked. In case of impossibility to execute the order (price change, goods out of stock) the supplier will give an error and the order will pass to the status "cancelled (conditions are changed)". This status is final and to repeat the order you will need to do it again. An unconfirmed order is stored in the supplier's system for X amount of time. If the order is not confirmed within this time, the supplier's system will automatically cancel it.

Request parameters:
Example of the request:

<?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>
An example of the response if completed successfully:

<?xml version="1.0" encoding="utf-8"?>
<Return>
  <Status>2</Status>
  <Error/>
</Return>
Possible error codes:
Common supplier errors for all commands:
Request code example

Example of the PHP code for an API request:

<?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>Ivanov</FirstName>
           <MiddleName>Ivan</MiddleName>
           <LastName>Ivanovich</LastName>
           <Email>ivanov@email.ru</Email>
           <Phone>+79091231234</Phone>
       </User>
       <DeliveryAddress>
           <ZipCode>249034</ZipCode>
           <Region>Kaluga region</Region>
           <City>Kaluga</City>
           <Address>apt.1, Krasivaya str.</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);
Back