FrontPad API: приём заказов и обновление статусов

FrontPad — одна из самых популярных касс у доставок и небольших кафе, и почти всё в ней можно автоматизировать через API. Разбираем на пальцах: как заказ попадает в кассу, как читаются статусы и где обычно всё ломается.

Зачем вам вообще FrontPad API

Если у вас доставка или кафе на FrontPad, то каждый заказ, который приходит не из зала, кто-то заводит руками. Оператор читает сообщение в WhatsApp, открывает кассу, вбивает позиции, адрес, телефон, комментарий. На одном заказе это 2-3 минуты. На сотне заказов в день — это отдельный человек, который весь день только перепечатывает.

API нужен ровно для того, чтобы убрать эту ручную работу. Через FrontPad API внешняя система (сайт, чат-бот, агрегатор, ИИ-администратор) сама кладёт заказ в кассу — с товарами, скидками, адресом и способом оплаты. А обратно касса отдаёт статус: приняли, готовят, отдали курьеру, закрыли. Клиент видит, что происходит, а вы не тратите руки оператора на копирование текста.

Простое правило: если действие в кассе повторяется больше 20 раз в день и не требует головы — его почти наверняка можно отдать API. Приём заказа и смена статуса как раз из этого списка.

Как устроен доступ: секрет и один эндпоинт

FrontPad работает по простой схеме. У вас есть секретный ключ (Secret) — он лежит в настройках кассы, в разделе для интеграций. Этот ключ подставляется в каждый запрос, и по нему касса понимает, к какому заведению относится заказ. Никаких сложных OAuth-танцев, как у крупных ERP, здесь нет — и это одновременно плюс (быстро подключить) и минус (ключ нельзя светить нигде публично).

Запросы уходят на адрес вида https://app.frontpad.ru/api/index.php?p=МЕТОД, данные передаются обычным POST. Основные методы, которые закрывают 90% задач:

• new_order — создать новый заказ в кассе;
• update_order — изменить уже созданный заказ;
• get_order — получить заказ и его текущий статус;
• get_products — выгрузить список товаров с артикулами и ценами;
• get_status — получить справочник статусов заведения;
• get_clients — данные по клиенту (история, телефон).

Ключевой момент, из-за которого спотыкаются новички: товары в заказе передаются по артикулу (product[]), а не по названию. То есть сначала вы выгружаете get_products, запоминаете, что «Пепперони 30 см» — это артикул 10452, и уже его кладёте в заказ. Названием заказ не соберёшь.

Как выглядит приём заказа

Метод new_order принимает массив товаров, их количество и набор полей по клиенту и доставке. Минимальный рабочий заказ — это связка «что заказали + куда везти + как платят». Вот основные поля, которые встречаются почти в каждом заказе:

В ответ касса присылает order_id и order_number — внутренний идентификатор и человекочитаемый номер. Их обязательно нужно сохранить у себя: без order_id вы потом не сможете ни обновить заказ, ни спросить его статус.

Про склад и «красные» позиции

Если в FrontPad включён складской учёт, касса при приёме заказа проверяет остатки. Заказали то, чего нет в наличии — заказ либо не создастся, либо создастся с предупреждением, а позиция подсветится. Это важно учитывать: нельзя слепо доверять «заказ ушёл в кассу», нужно проверять ответ. Иначе клиент оформит пиццу, которой сегодня физически не готовят, и узнает об этом только когда позвонит оператор.

Статусы: как понять, что происходит с заказом

Статусы в FrontPad — это не жёсткий стандарт, а справочник, который вы сами настраиваете под своё заведение. У одного это «Новый → Готовится → В доставке → Выполнен», у другого добавлены «Ждёт оплаты» и «Отменён». Поэтому первым делом через get_status вы выгружаете список статусов именно вашей кассы и запоминаете их ID.

Дальше два сценария работы со статусами FrontPad:

1. Опрос (polling). Раз в 20-60 секунд дёргаете get_order по сохранённым order_id и смотрите, не сменился ли статус. Просто, надёжно, работает всегда, но создаёт лишние запросы.
2. Смена статуса извне. Через update_order вы сами переводите заказ в нужный статус — например, когда клиент подтвердил оплату онлайн, ставите «Оплачен».

Именно на статусах строится вся коммуникация с гостем. Перешёл заказ в «В доставке» — клиенту улетает сообщение «Курьер выехал». Стал «Выполнен» — через час можно спросить, всё ли понравилось, и попросить оценку. Это тот самый момент, где ИИ-администратор вроде Людочки закрывает боль целиком: она видит смену статуса, сама пишет гостю нужный текст в его мессенджере и не забывает про отзыв — оператору вообще не нужно за этим следить.

Где обычно всё ломается

Интеграция с FrontPad несложная, но грабли одни и те же у всех. Держите чек-лист, чтобы не наступить:

• Артикулы разъехались. В кассе поменяли товар или пересобрали меню — старые артикулы стали недействительны, и заказы начинают падать. Выгрузку get_products нужно обновлять регулярно, а не один раз при запуске.
• Не сохранили order_id. Создали заказ, ответ проигнорировали — и теперь не к чему привязать статус. Всегда пишите ответ кассы в свою базу.
• Способ оплаты и статусы захардкодили. ID оплаты и статусов у каждого заведения свои. Перенесли код с одной точки на другую без выгрузки справочников — заказы уходят «в никуда».
• Секрет утёк. Ключ в открытом коде сайта или в переписке — любой сможет создавать заказы от вашего имени. Секрет живёт только на сервере, в переменных окружения.
• Нет проверки ответа. Касса вернула ошибку (нет товара, невалидное поле), а система отрапортовала клиенту «заказ принят». Проверяйте поле result в ответе — success или error.
• Лимиты запросов. Слишком частый polling по всем заказам разом упирается в ограничения. Опрашивайте только активные заказы и с разумным интервалом.

Что делает API, а что — сервис поверх него

Важно честно разделять. Сам FrontPad API — это транспорт: он умеет положить заказ, отдать статус, вернуть список товаров. Но он не решает, что именно сказать клиенту, не собирает заказ из свободного текста «привет, хочу две пепперони и колу на Ленина 5», не напоминает про оплату и не просит отзыв. Всю эту логику строит система поверх кассы.

То есть таблица ответственности примерно такая: API отвечает за передачу данных в кассу и обратно; сайт или агрегатор — за форму заказа; ИИ-администратор — за разговор с гостем, сборку заказа из обычной речи, подтверждение и сообщения по статусам. Людочка как раз работает на этом верхнем слое: принимает заказ в мессенджере на человеческом языке, кладёт его в FrontPad по артикулам, а потом ведёт гостя по статусам до отзыва. Касса остаётся кассой — она просто перестаёт требовать живого оператора на рутину.

Если вы только подключаете интеграцию, начните с малого: выгрузите get_products и get_status, создайте один тестовый заказ через new_order, убедитесь, что он появился в кассе и корректно сменил статус. Когда эта цепочка работает стабильно — можно наращивать автоматизацию и подключать общение с гостем.