Остатки участников

1. Общие сведения

Данная часть API предназначена для загрузки и получения остатков компаний-участников РАЭК. Доступ к данному функционалу имеют только компании со статусом "Действующий участник"

2. Авторизация  

Авторизация запроса происходит по API-KEY, который должен быть указан в HEADER каждого запроса.

Коды состояния ответа сервера

200 - OK.

400 - Bad Request.

401 - You must be authorized to view this page.

403 - Forbidden

404 - The requested URL was not found.

500 - The server encountered an error processing your request.

501 - The requested method is not implemented.

505 - HTTP Version Not Supported

3. Загрузка остатков

Для загрузки остатков необходимо вызвать POST запрос на адрес https://catalog.raec.su/api/remainscompany/.

Идентификация товара производиться по 3-м возможным вариантам, достаточно использовать один из возможных вариантов:

  • raecId (код товара в РАЭК)
  • supplierId и brand (код поставщика и бренд)
  • article и companyId (артикул товара в учетной системе участника и id компании)

Идентификация склада производиться по storageName (название склада) или storageId (id склада в РАЭК). Если переданы оба параметра анализироуется только storageId, а storageName игнорируется.


Параметры запроса зависят от способа загрузки. Параметр companyId является обязательным во всех запросах.


3.1 Загрузка единичной складской позиции.

Полный перечень возможных параметров

ПараметрОписаниеВозможные значения
companyIdID компании-участника РАЭКДанные по компании можно узнать, используя метод company
raecIdRAEC ID товараint
supplierIdКод поставщикаstring
brandБрендint | string Данные по брендам можно узнать, используя метод brand
articleАртикул компанииstring
storageNameНазвание складаstring Склад должен быть предварительно занесен в базу РАЭК через администраторов
storageIdID склада в РАЭКint Узнать ID всех складов можно методом companystorage (см. пункт 5 данного руководства)
illiquidCountКоличество неликвидаfloat Округляется до 6 знаков после запятой.
illiquidPriceЦена неликвида, рубfloat Округляется до 2 знаков после запятой.
illiquidAmountСумма неликвида, рубfloat Округляется да 2 знаков после запятой.
unitЕдиница измеренияпо классификатору ОКЕИ
countКоличество на складеfloat Округляется до 6 знаков после запятой. Максимальное значение 9 999 999 999.999 999
relevanceDateДата актуальности

datetime в формате 'yyyy-MM-dd', 'yyyy-MM-dd HH:mm:ss', 'dd.MM.yyyy', 'dd.MM.yyyy HH:mm:ss'

Не обязательное. По умолчанию выставляется текущая дата

Пример кода на PHP с использование клиента
<?php
$client = new RestClient('https://catalog.raec.su/api/', 'f85aa1473448577845a7094d4ab5bc22'); // используйте ваш ключ
 
// одиночная позиция, идентификация товара по артикулу, информация о неликвидах, идентификация склада по названию
$response = $client->post('remainscompany', [
	'companyId' => 1,
    'article' => 'С0000091180',
    'storageName' => 'Холмогорова  Основной, г.Ижевск',
    'unit' => 'шт',
    'count' => '10',
    'illiquidCount' => '5',
    'illiquidPrice' => '1.0',
    'illiquidAmount' => '5.0',
    'relevanceDate' => '2018-01-01 23:55:55',
]);

// одиночная позиция, идентификация товара по raecId, дата актуальности текущая, неликвидов нет, идентификация склада по ID (storageName игнорируется)
$response = $client->post('remainscompany', [
	'companyId' => 1,
	'raecId' => 1,
	'storageName' => 'Холмогорова Основной, г.Ижевск',
	'storageId' => 1,
	'unit' => 'м',
	'count' => '12.5',
]);

// одиночная позиция, идентификация товара по коду поставщика и бренду, обнуление остатков, идентификация склада по ID
$response = $client->post('remainscompany', [
	'companyId' => 1,
	'supplierId' => '1754-0-4107',
	'brand' => 'ABB',
	'storageId' => 1,
	'unit' => 'шт',
	'count' => '0',
	'relevanceDate' => '31.12.2018',
]);

В случае успешного запроса возвращается код 200. В случае ошибки - код и описание ошибки.

вариант ответа
{
	"description":"Parameter 'companyId' is empty",
	"code":400,
	"title":"Bad Request",
	"message":"Bad Request"
}

3.2 Пакетная загрузка


Параметры запроса

ПараметрОписаниеВозможные значения
companyIdID компании-участника РАЭКДанные по компании можно узнать, используя метод company
xmlXML файл с данными по остаткамПолную структуру XML смотрите ниже. Требования к складским позициям аналогичны единичной загрузки из п. 3.1.
Структура XML
<?xml version="1.0" encoding="utf-8"?>
<raec>
	<remains>
	    <offers>
	        <offer>
	            <supplierId>D60P-Д</supplierId>
	            <brand>Legrand</brand>
	            <storageName>Сарапул Основной, г. Сарапул</storageName>
	            <count>123</count>
	            <unit>шт</unit>
	        </offer>
	        <offer>
	            <article>8465345</article>
	            <storageName>Уфа-1  Основной, г. Уфа</storageName>
	            <count>123,254</count>
	            <unit>шт</unit>
	            <relevanceDate>31.12.2018</relevanceDate>
	        </offer>
	        <offer>
	            <raecId>1</raecId>
	            <storageName>Холмогорова  Основной, г.Ижевск</storageName>
	            <count>123,456</count>
	            <unit>м</unit>
	            <relevanceDate>2018-01-01 23:56</relevanceDate>
	        </offer>
	    </offers>
	</remains>
</raec>
Пример кода на PHP с использование клиента
<?php
$client = new RestClient('https://catalog.raec.su/api/', 'f85aa1473448577845a7094d4ab5bc22'); // используйте ваш ключ
 
$filePath = 'path\to\file\reamins_company.xml';
$cfile = curl_file_create($filePath, 'text/xml', 'remains_company.xml');
$post = ['xml' => $cfile, 'companyId' => 1];
$response = $client->post('remainscompany',$post);
вариант ответа в случае проблем на этапе авторизации и получения файла
{
	"description":"Parameter 'companyId' is empty",
	"code":400,
	"title":"Bad Request",
	"message":"Bad Request"
}

В случае успешной загрузки файла всегда возвращается код 200. Ошибки по загрузке каждой складской позиции будет содержаться в параметре report в том порядке, как они перечислены в XML или 'ok' если ошибок нет. Общее количество обработанных позиций в параметре count.

вариант ответа в случае успешной обработки файла
 {
    "report": [
      "Product not found",
      "Product not found",
      "ok"
    ],
    "count": 3
  }


3.3 Обнуление всех остатков компании

Для обнуления складкских позиций компании необходимо вызвать POST запрос на адрес https://catalog.raec.su/api/remainscompany/zero передав в параметре companyId.

Параметры запроса

ПараметрОписаниеВозможные значения
companyIdID компании-участника РАЭКДанные по компании можно узнать, используя метод company
storageId

массив ID складов компании, по которым требуется обнуление.

Не обязательный. В случае остуствия обнуление производится по всем складам компании

array int Узнать ID всех складов можно методом companystorage (см. пункт 5 данного руководства)

В случае успеха будет возвращей ответ с кодом 200 и указанием количества обнуленных позиций.

вариант ответа в случае успеха
 {
   "count": 3
 }

При ошибке будет возвращен код и описание ошибки аналогично другим методам.

Примеры:

Пример кода на PHP с использование клиента
<?php
$client = new RestClient('https://catalog.raec.su/api/', '*********************************'); // используйте ваш ключ
 
$response = $client→post('remainscompany/zero', ['companyId' => 1]); // обнуление всех остатков компании с ID = 1
$response = $client→post('remainscompany/pages', ['companyId' => 1, 'storageID' => [2,3]); // обнуление остатков на складах 2 и 3
Пример кода Curl
curl --location --request POST 'https://catalog.raec.su/api/remainscompany/zero' \
--header 'API-KEY: ****************************' \
--form 'companyId="1"' \
--form 'storageId[]="2"' \
--form 'storageId[]="3"'


4. Получение остатков

Для получения остатков необходимо вызвать GET запрос на адрес http://catalog.raec.su/api/remainscompany/.

Для данного метода есть возможность только получать список складских позиций и количество страниц. Задавать фильтр по RAEC_ID товара (productId), по бренду (brandId), по дате актуальности (relevanceDate), дате обновления (modifiedDate), компании (remainsCompanyId), ID компании по наличию индивидуального кода (companyId).


Параметр

Тип

Описание

Пример

raecId

int

RAEC_ID товара

870533

supplierId

string

Код поставщика

4911003320

descriptionShort

string

Краткое название

Светильник 214 ALD 16521430/1004000050

descriptionRu

string

Название RU


countfloatКоличество с 6 знаками после запятой83.123456
illiquidCountfloatКоличество неликвида с 6 знаками после запятой5.000000
illiquidPricefloatЦена неликвида в рублях с 2 знаками после запятой1.00
illiquidAmountfloatСумма неликвида в рублях с 2 знаками после запятой5.00
remainsCompanyarrayИнформация о компании{"id":2,"name":"Элевел"}
modifiedDatestringДата обновления2015-07-21 11:37:59
relevanceDatestringДата актуальности2015-07-21
brandarrayИнформация о бренде товара/поставщика{"id":3,"name":"3M"}
storagearray

Информация о складе.

shipments - массив - информация о условиях отгрузки, где:

  • storage - информация о складе-получателе
  • deliveryDays - срок поставки в днях
  • minOrder - минимальная сумма заказа
        "storage": {
            "id": 4,
            "name": "Уфа-1  Основной, г. Уфа",
            "address": null,
            "shipments": [
                {
                    "storage": {
                        "company": "Уралэнерго",
                        "id": "1",
                        "name": "Распределительный центр  ОПТ(Основной), г.Ижевск",
                        "address": "г.Ижевск, Ленина 1"
                    },
                    "deliveryDays": "4",
                    "minOrder": null
                }
            ]
        },
    
unitarrayЕдиница измерения{"id":145,"name":"Москва"}
Пример кода на PHP с использование клиента
<?php
$client = new RestClient('https://catalog.raec.su/api/', 'f85aa1473448577845a7094d4ab5bc22'); // используйте ваш ключ
 
$response = $client→get('remainscompany'); // список остатков
$response = $client→get('remainscompany/pages', ['limit' => 500]); // количество страниц по 500 позиций на страницу, максимум limit = 1000
$response = $client→get('remainscompany/page-1', ['limit' => 500]); // первая страница
$response = $client->get('remainscompany', ['filter[productId]' => 812440]); // фильтр по raecId товара
$response = $client->get('remainscompany', ['filter[brandId]' => 2]); // фильтр по бренду товара
$response = $client->get('remainscompany', ['filter[companyId]' => 2]); // фильтр по наличию у товара индивидуального кода от компании с ID=2 (пользователь, от имени которого идет запрос, должен быть привязан к данной компании).
$response = $client->get('remainscompany', ['filter[relevanceDate]' => strtotime('02.04.2016')]); // фильтр по дате актуальности
$response = $client->get('remainscompany', ['filter[modifiedDate]' => strtotime('21.01.2017 16:34Z')]); // При использовании фильтра по датам с использованием времени не забывайте устанавливать временную зону UTC:
$response = $client->get('remainscompany', ['filter[remainsCompanyId]' => 1]); // фильтр по компании
$response = $client->get('remainscompany', ['filter[remainsCompanyId]' => 1, 'filter[companyId]' => 2]]); // список остатков компании Уралэнерго (ID=1), у которых есть наличие индивидуального кода компании Элевел (ID=2)
$response = $client->get('remainscompany', ['filter[storageId]' => '1,42']);  // фильтр по списку ID складов участников (указывается через запятую)
Структура ответа
 [
    {
      "raecId": 1,
      "modifiedDate": "2019-01-23 14:13:20",
      "relevanceDate": "2018-01-01 23:56:00",
      "count": "123.456000",
      "illiquidCount" => 5.000000,
      "illiquidPrice" => 1.00,
      "illiquidAmount" => 5.00,
      "supplierId": "1754-0-4107",
      "descriptionRu": "ABB BJE Solo Хром Рамка 4-ая",
      "descriptionShort": "Рамка 4-постовая, серия solo/future, матовый хром",
      "brand": {
        "id": 1,
        "name": "ABB"
      },
      "remainsCompany": {
        "id": 1,
        "name": "Уралэнерго"
      },
      "storage": {
		"id": 4,
		"name": "Уфа-1  Основной, г. Уфа",
		"address": null,
		"shipments": [
			{
				"storage": {
					"company": "Уралэнерго",
					"id": "1",
                    "name": "Распределительный центр  ОПТ(Основной), г.Ижевск",
                    "address": "г.Ижевск, Ленина 1"
                },
                "deliveryDays": "4",
                "minOrder": null
            }
        ]
	  },
      "unit": {
        "id": 4,
        "name": "м"
      }
    }
  ]


5. Список складов компаний.

Для получения списка всех складов компаний-участников РАЭК необходимо вызвать GET запрос на адрес http://catalog.raec.su/api/companystorage/.

Структура ответа
 [
    {
        "id": "1",
        "name": "Распределительный центр  ОПТ(Основной), г.Ижевск",
        "address": "г.Ижевск, Ленина 1",
        "company": {
            "id": "1",
            "name": "Уралэнерго"
        }
    },
    {
        "id": "2",
        "name": "Холмогорова  Основной, г.Ижевск",
        "address": null,
        "company": {
            "id": "1",
            "name": "Уралэнерго"
        }
    }
]


6. Режим тестирования  при загрузке остатков

Для для использования режима тестирования нужно в хедере запроса передать параметр Debug: 1

При таком режиме изменение данных в БД не произойдет. Будет сделана валидация параметров запроса. Если валидация не проходит то вернется ошибка, в противном случае всегда 200 код и подробные данные по результатам импорта с подробным отчетом по каждой позиции.

7. Общий порядок использования

  • Актуализируйте список складов своей компании в базе РАЭК
  • Получите API-KEY
  • Используйте пакетную загрузку для первоначальной загрузки остатков и периодической сверки
  • Используйте единичную загрузку по факту изменения складского остатка для большей оперативности
  • Особое внимание уделите корректному обнулению остатков. Если товар снимается с продажи и вы в дальнейшем не планируете передавать информацию по остаткам по такому товару в пакетной загрузке, не забудьте обнулить эти остатки в базе РАЭК, чтобы об этом узнали все участники. Нулевые остатки, по которым не было изменения больше недели из базы РАЭК удаляются.
  • При первоначальном получении остатков других компаний используйте постраничную навигацию, запрос на получение следующий страницы отправляйте только после того, как получили ответ на предыдущую, так запросы обрабатываются быстрее.
  • В дальнейшем используйте фильтр по дате обновления для получения только тех позиций, по которым произошло изменение.
  • В дальнейшем поддерживайте актуальность своих складов. В случае добавления/удаления/переименования склада информацию об этом нужно отправить в РАЭК.

8. Support

По любым вопросам, связанными с API или работой Базы RAEC, вы можете связаться со специалистами по email  support@raec.su