API ChatFood. Документация для разработчиков

Базовые сведения

ChatFood поддерживает широкие возможности для взаимодействия через API. С его помощью вы сможете получать информацию о заказах, клиентах и каталоге. Функционал постоянно дополняется новыми возможностями. Если у вас есть предложения по развитию функциональности API, обратитесь в службу поддержки.

Поддерживаемые методы

Клиенты

Получение списка клиентов
Получение клиента по ID
Изменение клиента
Начисление/списание бонусов
Получение адресов клиента по ID

Количество запросов к API бота не должно превышать 50 шт в секунду в сумме со всех токенов.

Документация для работы с API дополняется.

Подключение

Для работы с API необходим токен. Чтобы получить его, перейдите в личный кабинет, затем в раздел "Настройки" — "API". GUID — уникальный ключ бота, который вы можете получить из URL в личном кабинете. Он имеет следующий формат: ABCD123456-ABCD123456-ABCD123456-ABCD123456. Все запросы отправляются с помощью HTTP по адресу: https://chatfood.ru/core/{method}. Каждый запрос должен включать два обязательных параметра: guid и token. Эти параметры необходимо передавать в заголовках каждого запроса.

Заказы

Для работы с заказами используется метод orders.

Для оперативного получения новых заказов, используйте вебхук.

Получение списка заказов

GET https://chatfood.ru/core/orders

Метод возвращает массив объектов заказов. Лимит отображения записей за один запрос — 20.

Доступные параметры запроса:

Параметр	Описание	Тип
sort	Сортировка	string
filter	Фильтрация	array
page	Страница	int

Сортировка (sort). Для сортировки от меньшего к большему используйте sort=id, и наоборот sort=-id.

Доступные поля для сортировки:

Параметр	Описание
id	Сортировка по идентификатору
created_at	Сортировка по времени заказа
payment	Сортировка по идентификатору способу оплаты
receipt	Сортировка по способу получения
status	Сортировка по идентификатору статуса заказа
point	Сортировка по идентификатору точки продаж
amount	Сортировка по сумме заказа
price_products	Сортировка по стоимости товаров
price_delivery	Сортировка по стоимости доставки
discount_promocode	Сортировка по скидке по промокоду
discount_bonus	Сортировка по сумме оплаты бонусами
rating	Сортировка по рейтингу
client	Сортировка по идентификатору клиента

Фильтрация (filter). Фильтр передается в ввиде массива. Например filter[payment]=1 получит все заказы, у которых идентификатор способа оплаты равен 1. Подробнее о фильтрах.

Для фильтрации заказов доступны поля:

Параметр	Описание	Тип
created_at	Время создания заказа	int
payment	Способ оплаты заказа	int
receipt	Способ получения заказа	int
status	Статус заказа	int
point	Точка продаж	int
amount	Сумма заказа	float
price_products	Сумма товаров	float
price_delivery	Сумма доставки	float
discount_bonus	Оплачено бонусами	float
rating	Рейтинг	float
client	Клиент	int

Получение заказа по ID

GET https://chatfood.ru/core/orders/{ID}

Возвращает объект заказа. Вместо {ID} используйте номер заказа.

Изменение заказа

PUT https://chatfood.ru/core/orders/{ID}

Обновляет данные заказа и в случае успеха возвращает объект заказа. Вместо {ID} используйте номер заказа.

Доступные поля для изменения:

Поле	Описание	Тип
status_id	Статус заказа. Идентификатор существующего статуса. Так же сработает событие CHANGE_STATUS_ORDER	int

Удаление заказа

DELETE https://chatfood.ru/core/orders/{ID}

Удаляет заказ. В случае успеха вернет 204 ответ с пустым содержимым. Вместо {ID} используйте номер заказа. Так же сработает событие DELETE_ORDER

Объект заказа

Поле	Описание	Тип
id	Идентификатор заказа, он же номер заказа	int
point	Точка продажи, в которую поступил заказ	object
address	Адрес доставки	string
client	Объект клиента совершившего заказ	object
status	Статус заказа	object
receipt	Способ получения заказа	object
payment	Способ оплаты заказа	object
fields	Дополнительные поля заказа	array
created_at	Время создания заказа	int
price_products	Стоимость товаров заказа	float
price_delivery	Стоимость доставки заказа	float
discount_promocode	Скидка по промокоду	float
discount_bonus	Оплачено бонусами	float
amount	Общая стоимость заказа	float
rating	Рейтинг заказа	float
basket	Массив объектов корзины	array
review	Объект отзыва	object

Объект корзины

Поле	Описание	Тип
product_id	Идентификатор товара	int
product_external_code	Внешний код товара	string
product_data	Объект товара	object
quantity	Количество товара в корзине	int
price	Стоимость 1 товара	float
amount	Стоимость товаров	float
options_data	Выбранные опции	object
variation_data	Выбранная вариация товара	object

Клиенты

Для работы с заказами используется метод clients

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

GET https://chatfood.ru/core/clients

Метод возвращает массив объектов клиентов. Лимит отображения записей за один запрос — 20.

Доступные параметры запроса:

Параметр	Описание	Тип
sort	Сортировка	string
filter	Фильтрация	array
page	Страница	int

Сортировка (sort). Для сортировки от меньшего к большему используйте sort=id, и наоборот sort=-id.

Доступные поля для сортировки:

Параметр	Описание
id	Сортировка по идентификатору
created_at	Сортировка по дате регистрации
username	Сортировка по юзернейму
name	Сортировка по имени
lastname	Сортировка по фамилии
phone	Сортировка по номеру телефона
bonus	Сортировка по сумме бонусов
active	Сортировка по активности
invite	Сортировка по приглашенным клиентам
qr	Сортировка по QR ссылке
count_orders	Сортировка по количеству заказов
amount_orders	Сортировка по сумме заказов

Фильтрация (filter). Фильтр передается в ввиде массива. Например filter[qr]=3 получит все заказы, у которых идентификатор QR ссылки равен 3. Подробнее о фильтрах.

Для фильтрации заказов доступны поля:

Параметр	Описание	Тип
created_at	Дата регистрации	int
chat_id	Идентификатор telegram	int
username	Юзернейм	string
name	Имя	string
lastname	Фамилия	string
phone	Телефон	int
bonus	Бонусы	float
invite	Идентификатор приглашенного клиента	int
qr	Идентификатор QR ссылки	int
count_orders	Количество заказов	int
amount_orders	Сумма заказов	float
active	Активность	int

Получение клиента по ID

GET https://chatfood.ru/core/clients/{ID}

Возвращает объект клиента. Вместо {ID} используйте идентификатор клиента.

Изменение клиента

PUT https://chatfood.ru/core/clients/{ID}

Обновляет данные клиента и в случае успеха возвращает объект клиента. Вместо {ID} используйте идентификатор клиента.

Доступные поля для изменения:

Поле	Описание	Тип
bonus	Бонусы клиента	float

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

Начисление/списание бонусов

POST https://chatfood.ru/core/clients/{ID}/bonus

Начисляет бонусы клиенту и в случае успеха возвращает объект клиента. Вместо {ID} используйте идентификатор клиента.

Поле	Описание	Тип
value	Сумма начисления/списания	float

Получение адресов клиента по ID

GET https://chatfood.ru/core/clients/{ID}/addresses

Возвращает массив адресов клиента. Вместо {ID} используйте идентификатор клиента.

Доступные параметры запроса:

Параметр	Описание	Тип
page	Страница	int

Объект клиента

Поле	Описание	Тип
id	Идентификатор клиента	int
chat_id	Идентификатор telegram	int
username	Юзернейм	string
created_at	Дата регистрации	int
name	Имя	string
lastname	Фамилия	string
phone	Телефон	int
bonus	Бонусы клиента	float
invite	Идентификатор приглашенного клиента	int
qr	Идентификатор QR ссылки	int
count_orders	Количество заказов	int
amount_orders	Сумма заказов	float
active	Активность	boolean
preview	Объект изображения	object

Вебхук

Вебхук отправляет HTTP запрос методом POST с объектом вебхука при выполнении каждого события.

Чтобы установить вебхук, перейдите в раздел "Настройки" — "Служебное" и заполните поле "Вебхук". При установке вебхука будет отправлен запрос.

Каждый запрос содержит заголовок x-chatfood-secret-token, который уникален для каждого бота. Вы можете использовать его в качестве проверки, что данные действительно были отправлены с сайта chatfood.ru

Объект вебхука

Поле	Описание	Тип
event	Название события	string
data	Объект события	object

События вебхука

Событие	Описание	Объект
NEW_ORDER	При создании нового заказа	Объект заказа
CHANGE_STATUS_ORDER	При изменении статуса заказа	Объект заказа
SIGNUP_CLIENT	Регистрация клиента в боте	Объект клиента

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

Прочее

Фильтры

Операторы фильтрации:

Оператор	Название	Описание	Пример
==	равенство	Проверяет, что значение поля равно указанному значению.	?filter[id]=1
!=	не равно	Проверяет, что значение поля не равно указанному значению.	?filter[id][!=]=1
>	больше чем	Проверяет, что значение поля больше указанного значения.	?filter[amount][gt]=100
<	меньше чем	Проверяет, что значение поля меньше указанного значения.	?filter[amount][lt]=100
>=	больше или равно	Проверяет, что значение поля больше или равно указанному значению.	?filter[amount][gte]=18
<=	меньше или равно	Проверяет, что значение поля меньше или равно указанному значению.	?filter[amount][lte]=18
LIKE	частичное совпадение	Ищет значения, которые частично совпадают с указанным текстом (аналог SQL LIKE).	?filter[address][like]=самара
IN	вхождение в список	Проверяет, что значение поля находится в указанном списке.	?filter[id][in]=1,2,3
NOT IN	не входит в список	Проверяет, что значение поля не находится в указанном списке.	?filter[id][nin]=1,2,3
AND	И	Используется по умолчанию, когда указано несколько параметров фильтрации.	Запрос, где нужно найти сумму заказа больше 100 и статус с идентификатором 1 ?filter[amount][gt]=100&filter[status]=1
OR	ИЛИ	Для использования OR необходимо задать составной фильтр в виде массива.	Запрос, где нужно найти либо сумму заказа больше 100, либо статус с идентификатором 1 ?filter[or][0][amount][gt]=100&filter[or][1][status]=1

Поддерживаются комбинированные условия с вложенностью. Этот запрос выберет записи, где либо сумма заказа больше 100, либо идентификатор статуса равен 1, и при этом адрес содержит 'самара'.

?filter[and][0][or][0][amount][gt]=100&filter[and][0][or][1][status]=1&filter[and][1][address][like]=самара

Объект изображения

Поле	Описание	Тип
id	Идентификатор файла	int
type	Тип файла	string
data	Объект изображения с ссылками на миниатюры	object

Объект адреса

Поле	Описание	Тип
id	Идентификатор адреса	int
addres	Полный адрес	string
entrance	Подъезд	int
intercom_code	Код домофона	string
floor	Этаж	int
apartment	Квартира/офис	string
comment	Комментарий к адресу	string
coordinates	Координаты адреса	array

Объект статуса

Поле	Описание	Тип
id	Идентификатор статуса	int
name	Название статуса	string
color	Цвет статуса в HEX	string
sort	Индекс сортировки	int
global	Глобальный тип статуса	string

Объект способа получения

Поле	Описание	Тип
id	Идентификатор способа	int
name	Название способа	string
global	Глобальный тип способа	string

Объект способа оплаты

Поле	Описание	Тип
id	Идентификатор способа	int
name	Название способа	string
global	Глобальный тип способа	string

События

Событие	Описание
ADD_BONUS_CLIENT	Начисление бонусов клиенту
BLOCK_CLIENT	Блокировка клиента
CHANGE_STATUS_ORDER	Смена статуса заказа
DELETE_ORDER	Удаление заказа
GET_RATING_ORDER	Запрос оценки заказа
NEW_ORDER	Новый заказ
REDUCE_BONUS_CLIENT	Списание бонусов с клиента
SET_RATING_ORDER	Установка рейтинга заказу
SIGNUP_CLIENT	Регистрация клиента
ADD_BONUS_CLIENT	Начисление бонусов клиенту
START	Вызов команды /start
UNBLOCK_CLIENT	Разблокировка клиента

Базовые сведения Подключение Заказы Клиенты Вебхук Прочее