Как работать с API Poster: ответы на часто задаваемые вопросы
В этой статье собрали ответы на часто задаваемые вопросы об API Poster, аккаунте разработчика, создании и публикации интеграций, авторизации, вебхуках, а также работе платформ POS и Device.
Перейдите к нужному разделу, чтобы найти ответ на свой вопрос:
- Общие вопросы — об аккаунте разработчика и возможностях API.
- Маркетплейс и публикация интеграций — о поиске, создании, продаже и модерации приложений.
- Авторизация и доступ — о получении токенов, личных интеграциях и OAuth.
- Web API — об API-запросах, ошибках и передаче данных.
- Вебхуки — о настройке и получении вебхуков.
- POS-платформа — о разработке и настройке приложений для кассы.
- Device-платформа — о работе с устройствами и их эмуляции.
Общие вопросы
Что такое аккаунт разработчика и для чего он нужен
Аккаунт разработчика — это специальный аккаунт Poster, который содержит:
- Тестовую среду — в ней доступны все функции обычного клиентского аккаунта Poster.
- Инструменты для разработки приложений — с их помощью вы создаёте интеграции для дальнейшей публикации в Каталоге приложений Poster.
Зарегистрируйте аккаунт разработчика одним из двух способов по инструкции.
☝️ Отдельный аккаунт разработчика нужен, если вы планируете публиковать интеграцию в Каталоге приложений Poster.
💡 Если вы разрабатываете интеграцию для собственных нужд или одного конкретного клиента, например для подключения личного сайта к Poster, достаточно токена личной интеграции из клиентского аккаунта.
Нужно ли платить за аккаунт разработчика
Нет, аккаунт разработчика бесплатный.
Сразу после регистрации аккаунт автоматически продлевается на 15 дней. По истечении этого срока напишите в чат поддержки и попросите продлить аккаунт разработчика.
Как связать аккаунт разработчика с аккаунтом клиента Poster
Связывать аккаунты не нужно. Аккаунт разработчика — это отдельный аккаунт, в котором вы создаёте и настраиваете интеграцию.
Когда интеграция готова, клиент подключает её к своему аккаунту по прямой ссылке или через Каталог приложений Poster, если интеграция опубликована.
💡 Взаимодействие происходит не между аккаунтами, а между приложением разработчика и аккаунтом клиента через API-запросы. Чтобы определить, к какому аккаунту относится запрос, используется токен доступа.
Можно ли с помощью API добавить собственный функционал в Poster QR?
Нет. Poster QR не имеет собственного API, поэтому напрямую взаимодействовать с ним через интеграцию не получится.
При этом большинство настроек, связанных с меню, доступны через Web API Poster.
Маркетплейс и публикация интеграций
Где найти нужную интеграцию
Все доступные интеграции собраны в Каталоге приложений Poster.
Если вы не нашли нужное приложение, обратитесь к стороннему разработчику. Он поможет создать интеграцию с необходимым функционалом на основе открытого API Poster.
Обязательно ли публиковать приложение в Каталоге приложений Poster
Нет, вы можете не публиковать приложение в каталоге и предоставлять доступ к нему только своим клиентам.
Для подключения интеграции отправьте клиентам прямую ссылку такого формата:
https://joinposter.com/applications/Your-Integration-Name
Могу ли я продавать свою интеграцию через Poster
Да. Вы можете разместить свою интеграцию в Каталоге приложений Poster, чтобы её могли найти и подключить другие пользователи Poster.
Для этого подготовьте название и маркетинговое описание приложения, добавьте изображения и отправьте его на ревью. Также нужно будет презентовать интеграцию нашему менеджеру.
После публикации интеграция станет доступна пользователям Poster в 23 тысячах локаций в 122 странах мира. Вы сможете привлекать новых клиентов и продавать свой продукт через Poster, а встроенный биллинг упростит приём платежей за интеграцию.
Сколько длится ревью интеграции в Каталоге приложений Poster
Проверка интеграции занимает до 14 дней.
💡 Повторное ревью после внесения изменений также занимает до 14 дней.
Чтобы упростить проверку и избежать лишних задержек:
- Протестируйте приложение перед отправкой на ревью. Убедитесь, что оно корректно работает во всех предусмотренных пользовательских сценариях.
- Предоставьте тестовый доступ к своему сервису или сообщите, если такой возможности нет.
- Запишите видеоинструкцию по подключению и использованию интеграции. Она также поможет будущим пользователям быстрее разобраться в работе приложения.
- Укажите клиентов Poster, которые уже тестируют ваше приложение.
- Заполните маркетинговое описание, добавьте инструкцию для пользователей и укажите цены для каждого региона.
Нужно ли повторно отправлять интеграцию на ревью после изменений в POS-платформе или коде приложения
Нет. Если вы изменили код приложения или его POS-платформу, повторное ревью не требуется.
Чтобы применить изменения в POS-платформе, выполните команду: npm run deploy.
Когда изменения станут доступны клиенту после деплоя
После деплоя клиенту нужно дважды перезагрузить приложение Poster. После этого изменения станут доступны.
Нужно ли повторно отправлять интеграцию на ревью после изменения её настроек
Да, повторное ревью требуется, если вы изменили любой из следующих параметров:
- маркетинговое описание;
- URL для вебхуков;
- URL для OAuth;
- URL для Manage;
- доступы к API.
Отправьте интеграцию на повторное ревью, чтобы мы проверили обновлённые данные и опубликовали изменения.
Авторизация и доступ
Где получить токен, если мне не нужно отдельное приложение
Зарегистрируйте аккаунт Poster и откройте админ-панель. Перейдите в Доступ → Интеграции → Личная интеграция и скопируйте ключ.
Токен личной интеграции подходит, если вы создаёте интеграцию для одного клиента, например для подключения собственного сайта к Poster.
☝️ Если интеграцией будут пользоваться разные клиенты, настройте OAuth-авторизацию. Она позволяет получать отдельные токены доступа для каждого клиентского аккаунта.
Как настроить OAuth-авторизацию
Посмотрите наш вебинар об OAuth-авторизации или воспользуйтесь текстовой инструкцией по настройке OAuth.
Сколько действует токен доступа
Токен доступа действителен в течение 2 лет с момента выпуска.
Что делать, если срок действия токена истёк
Если срок действия токена истёк, переподключите интеграцию и пройдите OAuth-авторизацию повторно. После этого вы получите новый токен, действительный ещё 2 года.
Токен личной интеграции могут перевыпустить сотрудники поддержки. Для этого напишите нам в чат.
Web API
Почему Web API возвращает ошибку на мой запрос
Проверьте параметры code и message в ответе с ошибкой.
Параметр message содержит краткое описание причины ошибки, а список кодов ошибок приведён на странице документации Web API.
Как интегрировать сайт на Tilda, OpenCart, Wix, WordPress, uKit или самописный сайт с Poster, чтобы получать онлайн-заказы
Для интеграции сайта с Poster обратитесь к стороннему разработчику. Он поможет настроить передачу онлайн-заказов с помощью API Poster.
Мы также подготовили документацию по интеграции интернет-магазинов с Poster.
Для сайтов на WordPress + WooCommerce в нашем каталоге приложений есть готовая интеграция.
Можно ли через API передавать изображения товаров, тех. карт или категорий
Нет, API Poster не поддерживает передачу изображений для товаров, тех. карт и категорий.
Загружайте фотографии непосредственно в админ-панели Poster в разделе Меню.
Как проверить номер телефона перед созданием онлайн-заказа или карточки клиента
Чтобы проверить формат номера телефона до отправки API-запроса и избежать ошибок из-за некорректных данных, используйте библиотеку libphonenumber.
Вебхуки
Можно ли использовать вебхуки без создания приложения
Нет. Чтобы получать вебхуки от Poster, создайте приложение в аккаунте разработчика и настройте для него URL вебхуков.
Почему мне не приходят вебхуки
Если вы не получаете вебхуки, проверьте следующие настройки:
- URL для вебхуков. Убедитесь, что сервер принимает POST-запросы и возвращает ответ со статусом
200. - Настройки приложения. Проверьте, правильно ли указан URL для вебхуков. После нажатия Проверить должна отображаться зелёная галочка.
- Подписки на вебхуки. Убедитесь, что в настройках приложения вы подписались на получение вебхуков для нужных сущностей.
- Отправка вебхука. Попробуйте имитировать отправку вебхука: измените в админ-панели Poster сущность, для которой ожидаете уведомление.
- Подключение интеграции. Проверьте, подключено ли приложение к аккаунту, от которого вы ожидаете вебхуки.
- Публикация приложения. Если приложение уже опубликовано в Каталоге приложений, дождитесь завершения повторного ревью.💡 Изменения в настройках вступят в силу после их согласования с нашей стороны.
POS-платформа
Почему на кассе нет переключателя Dev/Prod
Чтобы переключатель Dev/Prod появился на кассе:
- Включите переключатель POS-платформа в настройках своего приложения.
- В аккаунте разработчика добавьте в список разработчиков аккаунт Poster, на кассе которого нужно проверить интеграцию.
- Подключите интеграцию к этому аккаунту Poster через Каталог приложений Poster.
Можно ли отправлять CORS-запросы JavaScript через браузер
Нет, такие запросы блокируются. Для отправки запросов используйте сторонние инструменты, например Postman.
Можно ли добавить две или более кнопки приложения в POS-платформе
Нет. Для одного приложения разрешена только одна кнопка в POS-платформе.
Можно ли добавить дополнительную информацию в чек
Да. Чтобы добавить текст для печати, используйте метод orders.setPrintText.
Метод orders.printReceipt позволяет распечатать пречек с QR-кодом и дополнительным текстом.
Device-платформа
Есть ли эмулятор термопринтера и фискального регистратора
Полноценного эмулятора термопринтера и фискального регистратора нет.
Если вам нужно получать только байты, локально запустите сервер принтера на порту 9100.
Если вы не нашли ответ на свой вопрос или вам нужна дополнительная помощь, напишите нам в чат.