Выгрузка заказов в службы доставки

Документация по полной интеграции со службами доставки

С помощью 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": "hi@salesbeat.pro",
		"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, артикул товара
- name: 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, информация об отправителе заказа. Передаётся опционально, если данные не переданы, они берутся из настроек в личном кабинете Salesbeat. Ключи объекта sender:
- 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",
    "salesbeat_order_id": "10189"
}

Пример ответа на запрос с ошибкой:

{
    "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": "79009999999",
			"email": "hi@salesbeat.pro",
			"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,
    "info_message": "Передано заказов в службы доставки: СДЭК – 2, Boxberry – 1."
    "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, запрос удалось обработать успешно
info_message — String, информационное сообщение о количестве заказов по службам доставки
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,    
    "info_message": "Вызвали курьеров из служб доставки: Boxberry (2 заказа), СДЭК (1 заказ)",
    "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, есть ли ошибки при создании заявок
info_message — String, информационное сообщение о количестве заказов по курьерам из разных служб доставки
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: описание ошибки по данному полю