Выгрузка заказов в службы доставки
Документация по полной интеграции со службами доставки
С помощью Salesbeat можно передавать заказы в информационные системы служб доставки используя единое API.
Список запросов
Базовый URL API – https://app.salesbeat.pro/delivery_order/, все запросы нужно отправлять методом POST, а данные передавать в формате JSON в тело запроса.

Создать заказ на доставку
/create/

Создать несколько заказов на доставку
/create/bulk/

Вызвать курьера для забора товара со склада ИМ
/order_pick_up/

Удалить заказ на доставку
/delete/
Оповещения
Для смены статусов заказов на доставку — можно воспользоваться хуком оповещений.
Создать заказ на доставку
Запрос методом POST на адрес https://app.salesbeat.pro/delivery_order/create/
с параметрами в формате JSON:
{
	"secret_token": "your SECRET token",
	"test_mode": true,
	"order": {
		"delivery_method_code": "boxberry_pvz",
		"id": "test_order_1",
		"delivery_price": 173,
                "delivery_from_shop": false
	},
	"products": [{
		"id": "1000",
		"name": "Гантели",
		"price_insurance": 5000,
		"price_to_pay": 5000,
		"weight": 10000
	}],
	"recipient": {
		"city_id": "b2601b18-6da2-4789-9fbe-800dde06a2bb",
		"full_name": "Валентин Петухов",
		"phone": "79009999999",
		"email": "barinov.nikita49@gmail.com",
		"courier": {
			"street": "Вересаева",
			"house": 4,
			"flat": 121,
			"date": "2018-10-17"
		},
		"pvz": {
			"id": "71501"
		}
	},
	"sender": {
		"city_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
		"full_name": "Никита",
		"phone": "74959999999",
		"courier": {
			"street": "Одесская",
			"house": 2,
                        "house_block": "C",
			"date": "2018-10-16"
		},
		"pvz": {
			"id": "99401"
		}
	}
}
Необходимо передать параметры:

  • secret_token — Secret-токен магазина
  • test_mode — Boolean, тестовый режим — для тестовых запросов в процессе интеграции. Запросы с переданным параметром true не попадают в личный кабинет службы доставки (опционально — по умолчанию false)
  • order — Object, данные о заказе, ключи:
    • delivery_method_code: String, код способа доставки в Salesbeat (например, 'boxberry_pvz')
    • id: String, ID заказа в системе интернет магазина
    • delivery_price: Number, стоимость доставки, в руб.
    • delivery_from_shop: Boolean, необходимо вызвать курьера для забора заказа со склада ИМ (опционально – по умолчанию false)
  • products — Array, элементами которого являются параметры товаров:
    элементы массива представляют собой Object с ключами:
    • id: String, артикул товара
    • price_to_pay: Number, стоимость к оплате за товар (наложенный платеж), в руб.
    • price_insurance: Number, стоимость страховки (оценочная стоимость), в руб.
    • weight: Number, вес, в граммах
    • quantity: Number, количество этого товара в корзине (опционально — по умолчанию 1)
    • x: Number, длина, в см
    • y: Number, высота, в см
    • z: Number, ширина, в см
      пример:
      [{price_to_pay: 1400, price_insurance: 2222, weight: 5000, x: 40, y: 20, z: 50}, ...]
  • recipient — Object, информация о получателе заказа, ключи:
    • city_id: String, ID города получателя из базы ФИАС
    • full_name: ФИ получателя
    • phone: телефон
    • email: электронная почта
    • courier: Object, данные о курьерской доставке (обязательно при доставке курьером), ключи:
      • postalcode: String, индекс близлежащего почтового отделения (Boxberry осуществляет забор заказов не для всех индексов)
      • street: String, улица
      • house: String, номер дома
      • house_block: String, корпус/строение дома
      • flat: String, квартира/офис
      • date: String, дата доставки, ожидаем формат 'ГГГГ-ММ-ДД'
      • time_from: String, интервал доставки, от, формат – 'ЧЧ:ММ'
      • time_to: String, интервал доставки, до, формат – 'ЧЧ:ММ'pvz: Object, информация о ПВЗ (обязательно при доставке до ПВЗ), ключи
    • pvz: Object, информация о ПВЗ (обязательно при доставке до ПВЗ), ключи:
      • id: ID ПВЗ
  • sender — Object, информация об отправителе заказа, ключи:
    • city_id: String, ID города из базы ФИАС
    • full_name: ФИ получателя (обязательно при доставке со склада ИМ)
    • phone: телефон (обязательно при доставке со склада ИМ)
    • courier: Object, данные о заборе товара курьером со склада ИМ (обязательно при доставке со склада ИМ), ключи:
      • street: String, улица
      • house: String, номер дома
      • house_block: String, корпус/строение дома
      • flat: String, квартира/офис
      • date: String, дата доставки, ожидаем формат 'ГГГГ-ММ-ДД'
      • time_from: String, интервал доставки, от, формат – 'ЧЧ:ММ'
      • time_to: String, интервал доставки, до, формат – 'ЧЧ:ММ'
    • pvz: Object, информация о ПВЗ (обязательно при доставке от ПВЗ), ключи:
      • id: ID ПВЗ
Пример ответа на успешный запрос:
{
    "success": true,
    "track_code": "LUH1457199",
    "order_id": "test_new_api_2"
}
Пример ответа на запрос с ошибкой:
{
    "success": false,
    "error_message": "Переданы неккоректные данные",
    "error_code": "validation",
    "error_list": [
        {
            "field": "order.delivery_price",
            "message": "Поле \"order.delivery_price\" обязательно для заполнения"
        },
        {
            "field": "recipient.city_id",
            "message": "Поле \"recipient.city_id\" обязательно для заполнения"
        }
    ]
}
Описание параметров ответа:

  • success — Boolean, заказ создан/не создан
  • track_code — String, код отслеживания заказа в службе доставки (используется для отслеживания/удаления заказов на доставку)
  • order_id — String, ID заказа в ИС магазина
  • salesbeat_order_id — String, ID заказа на доставку в Salesbeat
  • error_code — String, код ошибки ('validation' – переданы неверные данные, 'delivery_service_error' – служба доставки ответила ошибкой)
  • error_message — String, сообщение об ошибке
  • error_list — Array, детализация ошибок по полям, элементы – Object, с ключами:
    • field: название поля
    • message: описание ошибки по данному полю
Создать несколько заказов на доставку
Запрос методом POST на адрес https://app.salesbeat.pro/delivery_order/create/bulk/
с параметрами в формате JSON:
{
	"secret_token": "your SECRET token",
	"test_mode": true,
	"items": [{
		"order": {
			"delivery_method_code": "boxberry_pvz",
			"id": "test_bulk_order_1",
			"delivery_price": 173,
			"delivery_from_shop": false
		},
		"products": [{
			"id": "1000",
			"name": "Гантели",
			"price_insurance": 5000,
			"price_to_pay": 5000,
			"weight": 10000
		}],
		"recipient": {
			"city_id": "b2601b18-6da2-4789-9fbe-800dde06a2bb",
			"full_name": "Валентин Петухов",
			"phone": "79175615183",
			"email": "barinov.nikita49@gmail.com",
			"pvz": {
				"id": "71501"
			}
		}
	}, ...]
	"sender": {
		"city_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
		"pvz": {
			"id": "99401"
		}
	}
}
Параметры "items[i].order", "items[i].products", "items[i].recipient" аналогичны параметрам "order", "products" и "recipient", соответственно, входным параметрам сервиса /create/.
На данный запрос наш сервис производит валидацию переданных данных и отдаёт результат валидации. Запросы к службам доставки выполняются асинхронно и об их результатах можно узнать из нотификаций.
Пример ответа на запрос:
{
    "success": true,
    "items": [
        {
            "success": true,
            "order_id": "test_bulk_1",
            "salesbeat_order_id": 54,
            "status": "is_sending"
        },
        {
            "success": false,
            "error_message": "Переданы неккоректные данные",
            "error_code": "validation",
            "error_list": [
                {
                    "field": "recipient.phone",
                    "message": "Поле \"recipient.phone\" обязательно для заполнения"
                }
            ],
            "order_id": "test_bulk_invalid_2"
        }
    ]
}
Описание параметров ответа:

  • success — Boolean, запрос удалось обработать успешно
  • items – Array, список, содержащий информацию об успешной/неуспешной валидации в виде Object с ключами:
    • track_code — String, код отслеживания заказа в службе доставки (используется для отслеживания/удаления заказов на доставку)
    • order_id — String, ID заказа в ИС магазина
    • salesbeat_order_id — String, ID заказа на доставку в Salesbeat
    • status — String, статус заказа на доставку, возможные варианты: 'is_sending' (в процессе отправки в службу доставки), 'sent' (отправлен) и 'sending_error' (при отправке произошла ошибка)
    • error_code — String, код ошибки ('validation' – переданы неверные данные, 'delivery_service_error' – служба доставки ответила ошибкой)
    • error_message — String, сообщение об ошибке
    • error_list — Array, детализация ошибок по полям, элементы – Object, с ключами:
      • field: название поля
      • message: описание ошибки по данному полю
Вызов курьера для забора заказов
со склада магазина
Запрос методом POST на адрес https://app.salesbeat.pro/delivery_order/pick_up/
с параметрами в формате JSON:
{
	"secret_token": "your SECRET token",
	"test_mode": true,
	"orders": [{
		"delivery_method_code": "boxberry_pvz",
		"track_code": "LUH1457223"
	}, {
                "salesbeat_order_id": "145"
        },  {
                "salesbeat_order_id": "166"
        }],
	"sender": {
		"city_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
		"full_name": "Никита",
		"phone": "74959999999",
		"courier": {
			"street": "Одесская",
			"house": 2,
                        "house_block": "C",
			"date": "2018-10-16"
		}
	}
}
Входные параметры:

  • secret_token — SECRET токен магазина
  • test_mode — Boolean, тестовый режим — для тестовых запросов в процессе интеграции. Запросы с переданным параметром true не попадают в личный кабинет службы доставки (опционально — по умолчанию false)
  • orders — Array, заказы, которые нужно забрать со склада. Элементы – Object с ключами:
    • salesbeat_order_id: String, ID заказа в Salesbeat (обязательный, если delivery_method_code и track_code не заполнены)
    • delivery_method_code: String, код способа доставки в Salesbeat (например, 'boxberry_pvz')
    • track_code — String, трек-код заказа в службе доставки
  • sender — Object, информация об отправителе заказа, ключи:
    • city_id: String, ID города из базы ФИАС
    • full_name: ФИ получателя (обязательно при доставке со склада ИМ)
    • phone: телефон (обязательно при доставке со склада ИМ)
    • courier: Object, данные о заборе товара курьером со склада ИМ, ключи:
      • street: String, улица
      • house: String, номер дома
      • house_block: String, корпус/строение дома
      • flat: String, квартира/офис
      • date: String, дата доставки, ожидаем формат 'ГГГГ-ММ-ДД'
      • time_from: String, интервал доставки, от, формат – 'ЧЧ:ММ'
      • time_to: String, интервал доставки, до, формат – 'ЧЧ:ММ'
Пример ответа на запрос:
{
    "success": false,
    "pick_ups": [
        {
            "salesbeat_order_id_list": [
                3,
                7,
                8
            ],
            "pick_up_number": "boxberry:7735"
        }
    ],
    "pick_ups_with_error": [
        {
            "salesbeat_order_id_list": [
                5
            ],
            "message": "API службы доставки СДЭК недоступно:( Попробуйте позже или выберите другую службу доставки."
        }
    ]
}
Описание параметров ответа:

  • success — Boolean, есть ли ошибки при создании заявок
  • pick_ups — Array, успешные заявки на забор со склада ИМ. Состоит из Object с ключами:
    • salesbeat_order_id_list: Array, список ID заказов, для которых вызов курьера оказался успешным
    • pick_up_number: String, номер заявки на забор со склада ИМ
  • pick_ups_with_error — Array, с неудачными заявками. Элементы – Object с ключами:
    • salesbeat_order_id_list: Array, список ID заказов, для которых не удалось вызвать курьера
    • message: String, сообщение об ошибке
Удалить заказ на доставку
Запрос методом POST на адрес https://app.salesbeat.pro/delivery_order/delete/
с параметрами в формате JSON
{
	"secret_token": "Your SECRET token",
	"test_mode": true,
	"order": {
		"track_code": "LUH1457258",
		"delivery_method_code": "boxberry_pvz",
                "salesbeat_order_id": "199"
	}
}
Входные параметры:

  • secret_token — SECRET токен магазина
  • test_mode — Boolean, тестовый режим — для тестовых запросов в процессе интеграции. Запросы с переданным параметром true не попадают в личный кабинет службы доставки (опционально — по умолчанию false)
  • order — Object, данные для нахождения заказа, ключи:
    • salesbeat_order_id: String, ID заказа в Salesbeat (обязательный, если delivery_method_code и track_code не заполнены)
    • delivery_method_code: String, код способа доставки в Salesbeat (например, 'boxberry_pvz')
    • track_code — String, трек-код заказа в службе доставки
Пример ответа на успешный запрос:
{
    "success": true
}
Пример ответа на запрос с ошибкой:
{
    "success": false,
    "error_message": "Переданы неккоректные данные",
    "error_code": "validation",
    "error_list": [
        {
            "field": "salesbeat_order_id",
            "message": "Заказ не найден в личном кабинете Boxberry"
        }
    ]
}
Оповещения (нотификации)
Для получения оповещений необходимо заполнить Url для оповещений в настройках магазина в Salesbeat.
Оповещение об изменении статусов заказов на доставку:
{
    "type": "delivery_order.status_changed",
    "secret_token": "your SECRET token",
    "data": {
        "items": [{
            "order_id": "1239", 
            "salesbeat_order_id": "sb12683", 
            "status":"sent", 
            "success": true, 
            "track_code": "LUH1459014"
        }, {
            "error_code": "delivery_service_error",
            "error_list": [{
                "field": null, 
                "message": "Ошибка входящих данных. \"order_id\" содержит недопустимые символы \"&\" (Код символа 38 )"
            }],
            "error_message": "Служба доставки ответила ошибкой",
            "order_id": "1240",
            "salesbeat_order_id": "sb12684",                 
            "status": "sending_error", 
            "success":false
        }]
    }
}
Описание параметров оповещения:
  • type — String, о чём хотим вас оповестить
  • secret_token — Secret-токен магазина (чтобы вы поверили, что мы – это мы)
  • data — Object, данные о событии:
    • items — Array, список, содержащий информацию о статусах заказов на доставку в виде Object с ключами:
      • track_code — String, код отслеживания заказа в службе доставки (используется для отслеживания/удаления заказов на доставку)
      • order_id — String, ID заказа в ИС магазина
      • salesbeat_order_id — String, ID заказа на доставку в Salesbeat
      • status — String, статус заказа на доставку, возможные варианты: 'is_sending' (в процессе отправки в службу доставки), 'sent' (отправлен) и 'sending_error' (при отправке произошла ошибка)
      • error_code — String, код ошибки ('validation' – переданы неверные данные, 'delivery_service_error' – служба доставки ответила ошибкой)
      • error_message — String, сообщение об ошибке
      • error_list — Array, детализация ошибок по полям, элементы – Object, с ключами:
        • field: название поля
        • message: описание ошибки по данному полю
Made on
Tilda