Описание API 4biz.ru для агентов
Оглавление
Общие характеристики программного интерфейса................................................................................................. 2
API 4biz. ru..................................................................................................................................................................... 2
Аутентификация...................................................................................................................................................... 2
Получить список УТ агента................................................................................................................................... 2
Получить список заказов........................................................................................................................................ 3
Получить состав заказа........................................................................................................................................... 5
Сообщить о перемещении или реализации (выдаче/доставке) заказа............................................................... 6
Сообщения об ошибках.......................................................................................................................................... 7
«Живая документация»............................................................................................................................................... 8
Общие характеристики программного интерфейса
Все ответы API имеют формат XML. Корневой элемент всех XML-ответов – «response», имена всех вложенных элементов соответствуют именам описанных ниже параметров.
API 4biz. ru
URL тестового интерфейса: https://4biz. ru:3000/agent
Начальная часть URL для запросов: https://4biz. ru/cgi-bin/api/
Аутентификация
Аутентификация осуществляется по трём значениям:
· id (идентификатор агента);
· salt (произвольная строка);
· sig (значение, полученное в результате генерации md5 хэша из строки, объединяющей salt и персональный ключ API; например, если salt = qwerty12345 и персональный ключ API = 00000000000000000000000000000000, то sig = a6ee49d89ed69e8186feeeb3f3b1da35).
В целях аутентификации эти значения присоединяются к запросам API в следующем виде (пример запроса списка УТ агента):
4biz. ru/cgi-bin/api/agent/rpoints? id=1111&salt=qwerty12345&sig=2b972c2d6add0dd656c723833dc256a0
Получить список УТ агента
URL: agent/rpoints
Тип запроса: GET
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<rpoints>
<rpoint>
<id>3014</id>
<name>Москва, м. Ясенево</point_name>
<status>1</point_status_archive>
<type>0</type>
<code/>
</rpoint>
</rpoints>
</response>
Поле | Описание | Формат, возможные значения |
id | id точки | целое число |
name | название | строка |
status | статус точки | 0 - УТ работает; 1 - УТ ещё не открыта или заблокирована; 2 - архивная УТ |
type | тип точки | 0 - пункт выдачи заказов; 1 - курьерская служба |
code | код точки в базе данных Агента | строка |
Получить список заказов
URL: agent/orders
Тип запроса: GET
Запрос используется для получения агентом информации обо всех заказах, которые 1) в пути к агенту, 2) у агента, 3) у агента, но ожидают возврата, 4) возвращаются на склад 4biz. ru.
Этот же запрос с опцией 'sold' и датами начала и конца отчётного периода используется для получения информации о заказах, реализованных агентом за период.
Все параметры в запросе являются необязательными.
Параметр | Тип | Описание |
ordids | строка | id заказа или нескольких заказов через запятую |
rpids | строка | id одной или нескольких УТ через запятую |
ordstatuses | строка | коды состояния заказа через запятую: 40 - отправлен в ПВЗ/КС, 70 - находится в ПВЗ/КС, 180 - ожидает возврата из ПВЗ/КС на склад 4biz. ru, 190 - возвращается из ПВЗ/КС на склад 4biz. ru |
datefrom | дата в формате YYYY-MM-DD | дата отправки в УТ (если mode = 'sold', дата реализации) , с |
dateto | дата в формате YYYY-MM-DD | дата отправки в УТ (если mode = 'sold', дата реализации), по |
mode | строка 'sold' | значение 'sold' означает, что необходимо вернуть информацию о заказах, реализованных за указанный период; при использовании режима 'sold' параметры datefrom и dateto становятся обязательными |
parts | "0" (по умолчанию) или "1" | "1" - признак того, что дополнительно необходимо вернуть составы заказов, если они известны |
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<orders>
<order>
<id>9859563</id>
<orderno>9324300</orderno>
<codcost>10647.00</codcost>
<rcptype>1</rcptype>
<eans>
<ean>2090032922614</ean>
<ean>2018063243003</ean>
</eans>
<status>70</status>
<shop_id>1</shop_id>
<name>Фамилия Имя</name>
<addrcomment/>
<phone>+7 (495) 000-00-00</phone>
<shop_name>Магазин</shop_name>
<packages>1</packages>
<fulfillment_date>2017-05-24</fulfillment_date>
<rpid>2049</rpid>
<send_date>2017-05-11</send_date>
<address/>
<paytype>1</paytype><orders>
</order>
</orders>
</response>
Поле | Описание | Формат, возможные значения |
id | Идентификатор заказа в 4biz. ru | целое число |
orderno | Номер заказа для получателя | строка |
codcost | Наложенный платёж, руб. | число вида «1.12» (до двух знаков после точки, разделитель – точка) |
rcptype | Тип получателя | 1 – физическое лицо, 2 – юридическое лицо, 3 – индивидуальный предприниматель |
status | Статус заказа | 40 — отправлен в ПВЗ/КС; 70 — находится в ПВЗ/КС; 100 — доставлен получателю; 180 — ожидает возврата из ПВЗ/КС на склад 4biz. ru; 190 — возвращается из ПВЗ/КС на склад 4biz. ru |
shop_id | Идентификатор магазина (отправителя) | целое число |
shop_name | Название магазина (отправителя) | строка |
name | Ф. И.О. или наименование получателя | строка |
addrcomment | Комментарий к адресу | текст |
phone | Телефон | текст (пример: «8 (000) 0000000, доб. 000») |
rpid | Идентификатор удалённой точки | целое число |
send_date | Дата отправки в УТ | дата в формате YYYY-MM-DD |
fulfillment_date | Дата реализации | дата в формате YYYY-MM-DD |
address | Адрес | строка |
paytype | Способ оплаты | 1 – наложенный платёж, 2 – предоплата |
ean | EAN13 (штрих-код) | строка вида «1234567890123» |
packages | Количество мест | целое число |
Получить состав заказа
URL: agent/order_parts
Тип запроса: GET
Параметр | Тип | Описание |
ordids | строка | id заказа или нескольких заказов через запятую |
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<ordparts>
<ordpart>
<id>9845237</id>
<vat>18</vat>
<pricewithvat>1533.00</pricewithvat>
<sumwithvat>1533.00</sumwithvat>
<prodid>2248976</prodid>
<q>1</q>
<title>Воздушный змей "Кайт салатовый"</title>
<sumvat>233.85</sumvat>
</ordpart>
</ordparts>
</response>
В следующей таблице приводится перечень полей структуры описания отдельной позиции заказа (ordpart):
Поле | Описание | Формат, возможные значения |
id | Идентификатор заказа в 4biz. ru | целое число |
prodid | Идентификатор товара | текст (до 64 символов) |
title | Наименование позиции заказа | текст (до 128 символов) |
vat | Ставка НДС | -1 (без НДС), 0, 10 или 18 |
q | Количество | целое число от 1 до 65535 |
pricewithvat | Цена за штуку с НДС, руб. | число вида «1.12» (до двух знаков после точки, разделитель – точка, значения от 0.01 до 9999999.99) |
sumwithvat | Сумма с НДС, руб. | число вида «1.12» (до двух знаков после точки, разделитель – точка, значения от 0.01 до 9999999.99) |
sumvat | Сумма НДС, руб. | число вида «1.12» (до двух знаков после точки, разделитель – точка, значения от 0.00 до 9999999.99) |
Сообщить о перемещении или реализации (выдаче/доставке) заказа
URL: agent/change_order_status
Тип запроса: POST
Параметр | Тип | Описание | Обязательное поле |
ordids | строка | id заказа или нескольких заказов через запятую. | да |
status | новый статус заказа | 70 — находится в ПВЗ/КС (сообщить о поступлении заказа в УТ); 100 — выдан/доставлен получателю (сообщить о реализации заказа); 190 — возвращается из ПВЗ/КС на склад 4biz. ru (сообщить об отправке заказа обратно). | да |
fulfillment_date | дата реализации | Только для запроса «сообщить о реализации заказа» (код нового статуса — 100). Дата в формате YYYY-MM-DD Допускаются даты с 1-го числа текущего месяца по сегодняшний день. Если с начала месяца прошло не более четырех дней (сегодня 1–4 число месяца), также допускаются любые даты предыдущего месяца. Не допускаются даты до поступления заказа в УТ. Если дата не указана или является недопустимой, используется текущая дата. | нет |
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<updated>1</updated>
<ordids_skipped>91123736,91123737</ordids_skipped>
</response>
Поле | Описание | Формат, возможные значения |
updated | Количество заказов с обновленным статусом. | число |
ordids_skipped | id заказов, статус которых не был изменён (через запятую). | строка |
Сообщения об ошибках
Формат сообщения об ошибке:
<?xml version="1.0" encoding="utf-8"?>
<response><error>1007</error><errortext>Заказа с таким идентификатором не существует</errortext></response>
Поле | Описание | Формат, возможные значения |
error | Код ошибки, возвращаемый данным API в параметре «error». | число |
errortext | Текстовое описание ошибки. | строка |
«Живая документация»
https://4biz. ru:3000/agent
В интерфейсе "живой документации" API можно не только увидеть список всех методов и параметров, которые доступны, но также и выполнить сами запросы непосредственно к API.
Предварительно в верхней панели "API Credentials" следует указать данные авторизации:
· Login: id (идентификатор агента);
· API Salt: произвольная строка;
· Secret key: можно получить в личном кабинете в разделе "Ключ API".
