API 4biz.ru

Описание API 4biz.ru
Оглавление
Оглавление .................................................................................................................................................................................................................................................... 1
API 4biz.ru ..................................................................................................................................................................................................................................................... 1
Аутентификация ...................................................................................................................................................................................................................................... 1
Получить статусы, тарифы и пр. для списка заказов ........................................................................................................................................................................... 2
Трекинг заказа .......................................................................................................................................................................................................................................... 4
Добавить новый заказ.............................................................................................................................................................................................................................. 5
Отгрузка партии заказов ......................................................................................................................................................................................................................... 8
Получить тарифы для заказа .................................................................................................................................................................................................................. 9
Получить список регионов ................................................................................................................................................................................................................... 12
Получить список станций метро .......................................................................................................................................................................................................... 13
Получить список удаленных точек ...................................................................................................................................................................................................... 14
Сообщения об ошибках......................................................................................................................................................................................................................... 16
«Живая документация».............................................................................................................................................................................................................................. 16
API 4biz.ru
URL тестового интерфейса: https://4biz.ru:3000
Начальная часть URL для запросов: https://4biz.ru/cgi-bin/api/
Аутентификация
Аутентификация осуществляется по трём значениям:
 email (e-mail адрес, зарегистрированный в личном кабинете);
 salt (произвольная строка);
 sig (персональный ключ API).
В целях аутентификации эти значения присоединяются к запросам API в следующем виде (пример запроса тарифов):
4biz.ru/cgi-bin/api/order/tarif?email=test%40example.org&salt=qwerty&sig=295971c4e9964ae86d69bf370c1ff90f
Получить статусы, тарифы и пр. для списка заказов
URL: order/status
Тип запроса: GET
Параметр
orders_foid
Пример значения
18889009,1881058
Тип
строка
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<orders>
<order>
<actweight>0.084</actweight>
<rates>
<rate>
<value>220</value>
<name>Доставка</name>
<id>cl_delivery</id>
</rate>
<rate>
<value>10</value>
<name>Ручная обработка упаковок заказа</name>
<id>cl_handling</id>
</rate>
<rate>
<value>13.26</value>
<name>Кассовое обслуживание</name>
<id>cl_cash</id>
</rate>
</rates>
<status>100</status>
<txt_status>доставлен получателю</txt_status>
<oid>358819</oid>
<ndreason>0</ndreason>
<batchid>18639</batchid>
<rbatchid>20</rbatchid>
<orderno>10107</orderno>
</order>
</orders>
</response>
Расположение Описание
GET-запрос
Идентификаторы заказов у клиента (можно указывать
несколько идентификаторов через запятую)
Поле
Описание
actweight Фактический вес
value
Стоимость
name
Название тарифа
строка
id
Идентификатор тарифа
строка1
Статус заказа
0 — новый/редактируется; 10 — отгружен отправителем; 20 — принят на склад 4biz.ru; 30 — ожидает повторной
доставки; 40 — выдан курьеру / отправлен в ПВЗ/КС; 70 — находится в ПВЗ/КС; 100 — доставлен получателю;
180 — ожидает возврата из ПВЗ/КС на склад 4biz.ru; 190 — возвращается из ПВЗ/КС на склад 4biz.ru; 200 —
ожидает возврата отправителю; 205 — возвращается/возвращён отправителю
текст
status
txt_status Текстовое описание
статуса заказа
oid
Идентификатор заказа в
4biz.ru
ndreason Причина недоставки
(только для курьерской
доставки)
batched
Идентификатор партии
заказов
rbatchid
Идентификатор партии
возвращаемых заказов
orderno
Идентификатор заказа у
клиента
1
число
набор тарифов, применяемых для заказа
если возвращается пустое поле, то это означает, что расчет тарифов ещё не завершён
число
rates
Тарифы
Формат, возможные значения
число
10 — по вине получателя; 20 — по вине курьера; 30 — по вине 4biz.ru
число
число
число
Перечень применяемых тарифов:
 Для заказов с курьерской доставкой по Москве и Московской области:
o cl_delivery — доставка;
o cl_call — call-центр: согласование доставки;
o cl_return — возврат заказа клиенту;
o cl_handling — ручная обработка упаковок заказа;
o cl_cash — кассовое обслуживание;
o cltt_sum — итоговая сумма.
 Для заказов, доставляемых через пункты выдачи заказов и региональные курьерские службы:
o
o
o
o
o
o
o
o
cl_freight — доставка до ПВЗ/КС;
cl_call — call-центр: оповещение о поступлении заказа в ПВЗ;
cl_return — комиссия за возврат из ПВЗ/КС;
cl_sms — SMS-оповещение;
cl_handling — ручная обработка упаковок заказа;
cl_fd — выдача заказа;
cl_cash — кассовое обслуживание;
cltt_sum — итоговая сумма.
Трекинг заказа
URL: order/track
Тип запроса: GET
Запрос используется в случае курьерской доставки для получения списка попыток доставки.
Если для заказа выбран другой вид доставки, то возвращается пустой ответ.
Параметр
orders_foid
Пример значения
18889009
Тип
строка (до 32 символов)
Расположение
GET-запрос
Описание
Идентификатор заказа в
4biz.ru
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<deliveries>
<delivery>
<product_type>100</product_type>
<issue_date>0</issue_date>
<date>2015-01-17 11:57:10</date>
<txt_status>доставлен</txt_status>
<alt_title>0</alt_title>
</delivery>
</deliveries>
</response>
Поле
Описание
product_type Статус события доставки
Формат, возможные значения
0 — не определён; 10 — заказ выдан курьеру; 20 — курьер выехал; 100 — заказ доставлен; 110 —
заказ не доставлен
issue_date
Решение
40 — перенос доставки; 200 — возврат клиенту; 250 — решение не принято
date
Дата и время
строка в виде «2015-01-17 11:57:10»
txt_status
Текстовое описание статуса строка
alt_title
Причина недоставки
10 — по вине получателя; 20 — по вине курьера; 25 — отмена доставки; 30 — по нашей вине
Добавить новый заказ
URL: order/add
Тип запроса: POST
Заголовок запроса
Content-Type
Пример значения
application/xml
Пример тела запроса:
<?xml version="1.0" encoding="UTF-8"?>
<request version="1">
<orders>
<order
overwrite="0"
orderno="2"
ean13="1234567890123"
itemcount="5"
width="23"
height="111"
length="20"
volume="24"
estcost="600"
codcost="600"
paytype="1"
rcptype="2"
rgnid="3"
datefrom="2016-01-23"
dateto="2016-01-25"
timefrom="13:00:00"
timeto="18:00:00"
callinit="cst"
Тип
строка
Описание
MIME-тип запроса
weight="4"
name="Тест"
metro="2"
street="Тверская"
house="3 кор 1"
building="C"
suite="-"
phone="8(499)123445"
smsphone="4951234567"
addrcomment=""
courcomment=""
anotify="0"
clientcall="9-21"
/>
</orders>
</request>
В следующей таблице приводится перечень полей, доступных для заполнения при загрузке заказов через API:
№ п/п
1
Поле
orderno
Номер заказа
Описание
2
3
4
5
6
7
8
ean13
itemcount
width
height
length
volume
estcost
Штрих-код EAN-13
Количество мест
Ширина, мм
Высота, мм
Длина, мм
Объём, мм3
Оценочная стоимость, руб.*
9
codcost
Наложенный платёж, руб.*
10
paytype
Способ оплаты
11
rcptype
Тип получателя
Формат, возможные значения
строка5, до 10 символов
класса 0-9A-Za-zА-Яа-я/\_=+строка вида «1234567890123»
целое число
целое число
целое число
целое число
целое число
число вида «1.12» (до двух знаков
после точки, разделитель – точка
или запятая)
число вида «1.12» (до двух знаков
после точки, разделитель – точка
или запятая)
1 – наложенный платёж, 2 –
предоплата
1 – физическое лицо, 2 –
юридическое лицо, 3 –
индивидуальный предприниматель
I
++
II
++
III
++
+
++
+
+
+
+
++
+
++
+
+
+
+
++
+
++
+
+
+
+
++
+**
+**
+**
++
++
++
++
++
++
12
13
rgnid
datefrom
14
dateto
15
16
timefrom
timeto
Идентификатор региона
Дата, начиная с которой можно
доставлять
Дата, до которой (включительно)
нужно доставить
Начало интервала доставки
Конец интервала доставки
17
weight
Вес, кг
18
19
20
21
22
23
24
name
metro
street
house
building
suite
phone
Ф.И.О. или наименование получателя
Идентификатор станции метро
Улица
Дом/владение
Корпус/строение
Квартира/офис
Телефон
25
26
27
28
29
smsphone
addrcomment
courcomment
rpid
anotify
Телефон для SMS-оповещения***
Комментарий к адресу
Комментарий для курьера
Идентификатор удалённой точки
Оповещение о поступлении в ПВЗ
оператором call-центра
30
overwrite
31
callinit
Флаг, разрешающий обновление
данных для ранее добавленного
заказа
Согласование доставки
32
clientcall
Временной интервал, когда оператор
может позвонить по указанным
телефонам, часы (местное время)
целое число
дата (макс. допустимое значение:
текущая дата + месяц)
дата (мин. допустимое значение:
текущая дата + день)
HH:MM (не менее «09:00»)
HH:MM (не более «21:00»;
минимальный интервал времени
доставки – 4 часа)
число вида «1.123» (до трёх знаков
после точки, разделитель – точка
или запятая)
строка
целое число
строка
строка
строка
строка
текст (пример: «8 (000) 0000000,
доб. 000»)
10 цифр; только РФ
текст
текст
целое число
0 — не требуется (по умолчанию);
1 — требуется, если не доставлено
SMS; 2 — требуется независимо от
доставки SMS
0 – обновление данных запрещено;
1 – обновление данных разрешено
++
++
–
–
–
–
++
–
–
++
++
–
–
–
–
++
++
++
++
++
++
++
+
+
++
++
–
–
–
–
–
+4
++
–
++
++
+
+
++
+
+
+
–
–
+
–
–
++
+
+
+
+
++
–
+
+
+
строка «cst» — требуется
согласование доставки
строка вида «9-21» (интервал не
может быть больше интервала
«9-21»)
+
–
–6
+
+
+
Примечания:
Номера по порядку приведены для столбцов загружаемого файла, в которых должны быть записаны соответствующие значения (например, номер заказа
должен быть записан в первом столбце).
I — заказы с курьерской доставкой по Москве и Московской области.
II — заказы, выдаваемые в пунктах выдачи заказов.
III — заказы с курьерской доставкой в другие регионы.
Использование полей:
++
— является обязательным;
+
— используется;
–
— не используется.
* для заказов с предоплатой наложенный платёж должен быть равен нулю; для заказов с наложенным платежом оценочная стоимость должна быть равна
наложенному платежу.
** поле становится обязательным, если в качестве способа оплаты выбран наложенный платёж.
*** заполнение поля «Телефон для SMS-оповещения» означает заказ такой услуги (для соответствующего заказа).
4
поле «Телефон» становится обязательным в случае подключения услуги «Оповещение о поступлении в ПВЗ оператором call-центра».
5
если требуется использование номеров, не соответствующих указанным ограничениям, просим связаться с сотрудниками технической поддержки.
6
для заказов с курьерской доставкой в другие регионы доставка согласовывается всегда (после поступления заказа в УТ) и не является отдельной платной
услугой.
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<added>1</added>
<updated>0</updated>
</response>
Поле
added
Описание
Формат, возможные значения
Количество добавленных заказов число
updated Количество обновлённых заказов число
Отгрузка партии заказов
URL: order/batch
Тип запроса: POST
Заголовок запроса
Content-Type
Пример значения
application/xml
Тип
строка
Описание
MIME-тип запроса
Пример тела запроса:
<?xml version="1.0" encoding="UTF-8"?>
<request version="1">
<orders>
<order orderno="222"/>
<order orderno="333"/>
</orders>
</request>
Поле
Описание
Формат, возможные значения
orderno Идентификатор заказа у клиента строка (до 32 символов)
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<batch_id>16202</batch_id>
</response>
Поле
Описание
Формат, возможные значения
batch_id Идентификатор партии заказов число
Получить тарифы для заказа
URL: order/tarif
Тип запроса: POST
Запрос используется для расчёта тарифов для произвольного заказа (тарифный калькулятор).
Заголовок запроса
Content-Type
Пример значения
application/xml
Тип
строка
Описание
MIME-тип запроса
Пример тела запроса:
<?xml version="1.0" encoding="UTF-8"?>
<request version="1">
<orders>
<order
type="2"
ean13="1"
itemcount="5"
codcost="500.5"
paytype="1"
weight="4"
callinit="cst"
rpid="1701"
pvz_call="1"
pvz_sms="1"
plan="500"
/>
</orders>
</request>
Поле
Описание
type
Тип заказа
ean13
itemcount
На упаковках есть штрих-код, и соответствующий
ему код EAN-13 передаётся в параметрах заказа
Количество мест
codcost
Наложенный платёж, руб.
paytype
Формат, возможные значения
1 — Курьерская доставка по Москве и МО, 2 — Пункт выдачи
заказов, 3 – Курьерская доставка в другие регионы
0 — нет штрих-кода; 1 — есть штрих-код
Обязательное
поле
да
да
целое число
да1
да2
Способ оплаты
число вида «1.12» (до двух знаков после точки, разделитель –
точка или запятая)
1 — наличный расчёт, 2 — предоплата
rgnid
Идентификатор региона
целое число
да3
weight
Вес, кг
да
callinit
Согласование доставки
rpid
Идентификатор удалённой точки
число вида «1.123» (до трёх знаков после точки, разделитель –
точка или запятая)
«cst» — используется услуга «Call-центр: согласование
доставки»
целое число
да
нет
нет
pvz_sms
Оповещение по SMS о поступлении заказа в ПВЗ
0 — не используется; 1 — используется
да
pvz_call
Оповещение через call-центр о поступлении заказа
в ПВЗ
Тарифный план:
 до 200 заказов в месяц;
 до 500 заказов в месяц;
 до 1000 заказов в месяц;
 до 5000 заказов в месяц;
 5000 и более заказов в месяц.
0 — не используется; 1 — используется
да
соответствующие возможные значения:
 0;
 500;
 1000;
 5000;
 10000
нет4
plan
Примечания:
1
если на упаковках есть штрих-код, то достаточно указать itemcount="1"
2
используется только для способа оплаты «наличный расчёт».
3
используется только для типа заказа «Курьерская доставка по Москве и МО».
4
по умолчанию используется текущий тарифный план зарегистрированного пользователя.
Используемые при расчёте тарифов параметры по типам заказов:
Курьерская доставка по Москве и МО
Пункт выдачи заказов
type
type
rgnid
rpid
paytype
paytype
codcost
codcost
ean13
ean13
itemcount
itemcount
weight
weight
callinit
pvz_sms
plan
pvz_call
plan
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<rates>
<rate>
<value>260</value>
<name>Доставка до ПВЗ/КС</name>
Курьерская доставка в другие регионы
type
rpid
paytype
codcost
ean13
itemcount
weight
plan
<id>cl_freight</id>
</rate>
<rate>
<value>7.51</value>
<name>Кассовое обслуживание</name>
<id>cl_cash</id>
</rate>
<rate>
<value>50</value>
<name>Ручная обработка упаковок заказа</name>
<id>cl_handling</id>
</rate>
<rate>
<value>120</value>
<name>Выдача заказа</name>
<id>cl_fd</id>
</rate>
</rates>
</response>
Поле
Описание
Формат, возможные значения
Тарифы
набор тарифов, применяемых для заказа
value
Стоимость
число
name
Название тарифа
строка
id
Идентификатор тарифа
строка1
rates
Получить список регионов
URL: dir/regions
Тип запроса: GET
Запрос используется для получения значения идентификатора региона.
Получаемые идентификаторы могут использоваться при добавлении заказов с курьерской доставкой (Добавить новый заказ) и для дополнительной
фильтрации списка удаленных точек (Получить список удаленных точек).
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<regions>
<region>
<name>Агинский Бурятский округ</name>
<id>201</id>
</region>
<region>
<name>Адыгея респ.</name>
<id>202</id>
</region>
......
</regions>
</response>
Поле
Описание
Формат, возможные значения
name
Наименование региона
id
Идентификатор региона число
строка
Получить список станций метро
Используется только для курьерской доставки по Москве и ближнему Подмосковью.
URL: dir/metro
Тип запроса: GET
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<metro>
<station>
<name>Авиамоторная</name>
<id>82</id>
</station>
<station>
<name>Автозаводская</name>
<id>29</id>
</station>
.......
</metro>
</response>
Поле
Описание
Формат, возможные значения
name
Наименование станции
id
Идентификатор станции число
строка
Получить список удаленных точек
Используется только для заказов, выдаваемых в ПВЗ / доставляемых дополнительными курьерскими службами.
URL: dir/rpoints
Тип запроса: GET
Параметры:
Поле
Описание
Формат, возможные значения
region_id Идентификатор региона, для которого нужно
получить перечень удаленных точек
число; для получения полного перечня
используется пустое значение
Обязательное поле
нет
Формат ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<rpoints>
<rpoint>
<rate_9>0</rate_9>
<max_pay>-1</max_pay>
<point_name>Казань, ул. Карима Тинчурина</point_name>
<point_suspended>1</point_suspended>
<delivery_ndays_txt>3-7 рабочих дней</delivery_ndays_txt>
<rate_13>120</rate_13>
<region_id>269</region_id>
<rate_16>0</rate_16>
<rate_12>30.00</rate_12>
<legal>ООО "Компания Постмастер"</legal>
<id>1030</id>
<address>г. Казань, ул. Карима Тинчурина, д. 9. Пункт выдачи заказов находится в офисе компании "Постмастер", который
расположен в центральной части города в 15 минутах пешком от самого центра - супермаркета "Кольцо", от метро "площадь Тукая" и от
железнодорожного вокзала, в торговом центре "Флагман".
До офиса можно доехать на общественном транспорте до остановки "Карима Тинчурина":
- трамвай: № 7,
- троллейбусы: № 20, 21,
- автобусы: № 1, 6, 8, 31, 53, 71, 85, 99, 99А.
Телефон: 8 (843) 262-44-99.</address>
<rate_15>0</rate_15>
<delivery_weekdays>Вт,Чт</delivery_weekdays>
<rate_14>60</rate_14>
<rate_10>0</rate_10>
<point_type>0</point_type>
<working>понедельник - пятница: 9:00-20:00,
суббота: 9:00-19:00
воскресенье: выходной день.</working>
<storage_days>15</storage_days>
<extra_info/>
<reserve_rpoint_id>0</reserve_rpoint_id>
<delivery_ndays>7</delivery_ndays>
</rpoint>
..........
</rpoints>
</response>
Поле
Описание
Формат, возможные значения
max_pay
Максимальная сумма, при которой разрешается использование наличного расчета
point_name
Название удалённой точки
-1 - без ограничений; 0 - всегда требуется
предоплата
текст
point_type
Тип точки
0 - пункт выдачи заказов; 1 - курьерская служба
point_suspended
Состояние удалённой точки
0 - работает; 1 - не работает
delivery_ndays_txt Ориентировочный срок доставки до точки
строка вида «1 рабочий день», «2-3 рабочих
дня»
текст
working
График работы
storage_days
число
region_id
Срок хранения, календарных дней; для курьерской службы - максимальный срок
согласования доставки
Идентификатор региона
reserve_rpoint_id
Идентификатор точки, которая должна использоваться после закрытия этой
число
extra_info
Дополнительная информация
текст
delivery_ndays
Ориентировочный срок доставки до пункта выдачи / курьерской службы
число
число
legal
Наименование юр. лица / ИП
текст
id
Идентификатор удалённой точки
целое число
address
Адрес
текст
delivery_weekdays Дни отгрузки заказов
набор значений: 'Пн','Вт','Ср','Чт','Пт','Сб','Вс'
rate_9
Количество килограммов, сверх которых применяется доп. тариф за выдачу/возврат
целое число
rate_10
Шаг для дополнительного тарифа за выдачу/возврат, кг
целое число
rate_12
Стоимость доставки/возврата за каждый полный и неполный кг, руб.
десятичное число
rate_13
Базовая стоимость выдачи, руб.
целое число
rate_14
Базовая стоимость возврата, руб.
целое число
rate_15
целое число
lat
Дополнительный тариф за выдачу, руб. (за каждые полные и неполные [rate_10] кг
сверх [rate_9] кг)
Дополнительный тариф за возврат, руб. (за каждые полные и неполные [rate_10] кг
сверх [rate_9] кг)
Широта удалённой точки
long
Долгота удалённой точки
десятичное число
rate_16
целое число
десятичное число
Сообщения об ошибках
Формат сообщения об ошибке:
<?xml version="1.0" encoding="utf-8"?>
<response><errordata/><error>1007</error><errortext>Заказа с таким идентификатором не существует</errortext></response>
Поле
Описание
Формат, возможные значения
errordata Код ошибки, возвращаемый данным API в параметре «error». число
errortext
Текстовое описание ошибки.
«Живая документация»
http://4biz.ru:3000/4biz
строка
В интерфейсе "живой документации" API можно не только увидеть список всех методов и параметров, которые доступны, но также и выполнить сами
запросы непосредственно к API.
Предварительно в верхней панели "API Credentials" следует указать данные авторизации:
 Login: e-mail адрес, зарегистрированный в личном кабинете (отображается в правой части личного кабинета под надписью "ВЫ ВОШЛИ КАК");
 API Salt: произвольная строка;
Secret key: можно получить в личном кабинете в разделе "Ключ API".