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

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

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

Поддерживаемые методы
Заказы
Клиенты

Количество запросов к 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 Разблокировка клиента