API и интеграции

В разделе Настройки → API и интеграции три вкладки: «API-ключи», «Вебхуки» и «Интеграции».
API и API-ключи бесплатны на всех тарифах, включая Free Forever; аддона для API нет. Штампы, поставленные через API, — такие же Card Operations, как и любые другие, поэтому они останавливаются, когда Card Operations по тарифу заканчиваются. Платная часть — вебхуки, см. ниже.
API стоит дополнительно?
Нет. API и API-ключи бесплатны на всех тарифах, включая Free Forever. Штампы, поставленные через него, — такие же Card Operations, как и любые другие.
Можно ли пользоваться API на Free Forever?
Да. Когда Card Operations по тарифу заканчиваются, штампы через API останавливаются, как и любые другие.
Где настройки API?
В разделе Настройки → API и интеграции, на трёх вкладках — «API-ключи», «Вебхуки» и «Интеграции».
API-ключи

API-ключ создаётся в разделе API-ключи → «Добавить API-ключ» для одного логина персонала. У логина персонала не больше одного API-ключа, а выключенный логин персонала выбрать нельзя. Если выбрать некого, окно «Генерация API-ключа» предлагает создать логин персонала прямо там; новому логину персонала нужен свободный Staff Seat, а если тариф заполнен, окно предлагает вместо этого добавить место или выбрать тариф.
Каждый вызов с API-ключом действует от имени его логина персонала: он имеет доступ только к бизнесу этого логина персонала, ставит штампы на штамп-карту, выбранную для него в блоке «Автоматические штампы», и его штампы учитываются как Card Operations этого логина персонала.
Ключ можно в любой момент снова посмотреть и скопировать в списке API-ключей. Его также можно показать как QR-код, чтобы отсканировать в терминал, и распечатать с именем логина персонала.
Как создать API-ключ?
В разделе Настройки → API и интеграции → API-ключи выберите «Добавить API-ключ» и укажите логин персонала. У каждого логина персонала не больше одного API-ключа.
Я потерял API-ключ. Нужен новый?
Нет. Ключ можно в любой момент снова посмотреть и скопировать в списке API-ключей или показать как QR-код.
На какую штамп-карту ставят штампы вызовы API?
На ту, что выбрана для логина персонала этого ключа в блоке «Автоматические штампы». Её штампы учитываются как Card Operations этого логина персонала.
Почему я не могу выбрать логин персонала для нового ключа?
Выключенный логин персонала выбрать нельзя, а логин персонала, у которого уже есть ключ, не может получить второй. Если выбрать некого, окно предлагает создать логин персонала.
Когда API-ключ перестаёт работать
У API-ключа нет срока действия. Он перестаёт работать, только когда его перевыпускают или удаляют либо когда его логин персонала выключают или удаляют. Новый пароль или логин для логина персонала на него не влияет.
- Перевыпустить выдаёт логину персонала новый API-ключ; старый сразу перестаёт работать.
- Удалить сразу останавливает ключ. Сам логин персонала продолжает работать в 7Stamp Scanner и позже может получить новый ключ.
- При выключении логина персонала его ключ сохраняется: когда логин персонала снова включают, тот же ключ снова работает.
Истекает ли срок действия API-ключа?
Нет. Он перестаёт работать, только когда его перевыпускают или удаляют либо когда его логин персонала выключают или удаляют.
Я сменил пароль логина персонала. Нужен ли новый API-ключ?
Нет. Новый пароль или логин не влияет на API-ключ.
Я снова включил логин персонала. Работает ли его старый API-ключ?
Да. При выключении логина персонала его ключ сохраняется, и тот же ключ снова работает, когда логин включают.
Что умеет API
Через API система может:
- выдать штамп-карту в виде ссылки или QR;
- поставить штампы;
- прочитать карту с её штампами, целями и ваучерами;
- выдать ваучер напрямую на карту;
- погасить ваучер по его номеру ваучера;
- отправить сообщение покупателю.
API находит карту покупателя по собственному идентификатору бизнеса, например ID в CRM, телефону или email, переданному как external_id. Идентификатор хранится на карте и возвращается в каждом вебхуке о ней. В API нет вызова, который возвращает список покупателей бизнеса: вся база покупателей выгружается только через экспорт в админ-панели.
Вместо API-ключа приложение может входить с логином и паролем логина персонала — для устройства, в которое входит кассир. API-ключ подходит для устройства, которое работает без присмотра. Вебхуки добавляются только в админ-панели; в API нет вызова, чтобы подписаться на события или получить их список.
API не ограничивает частоту запросов: вызовы не ограничиваются ни по количеству, ни по частоте, и ту же карту можно сразу отсканировать снова. Штампы через него ограничены только Card Operations по тарифу.
Можно ли добавлять штампы из нашей CRM или POS?
Да, через API. Он выдаёт штамп-карты, ставит штампы, читает карты и погашает ваучеры. Чтобы ваша система узнавала о событиях, добавьте вебхук — для этого нужен аддон Webhooks & Events.
Можно ли выгрузить данные?
Через API вы читаете карты по своему собственному идентификатору, а вебхуки отправляют события по мере того, как они происходят. В API нет списка всех покупателей — вся база покупателей выгружается через экспорт в админ-панели.
Как API находит карту покупателя?
По вашему собственному идентификатору — ID в CRM, телефону или email, — переданному как external_id. Он хранится на карте и возвращается в каждом вебхуке о ней.
Можно ли подписаться на вебхуки через API?
Нет. Вебхуки добавляются только в админ-панели.
Есть ли у API ограничение частоты запросов?
Нет. Вызовы не ограничиваются ни по количеству, ни по частоте, и ту же карту можно сразу отсканировать снова. Штампы ограничены только Card Operations по тарифу.
Справочник API
Справочник API публичный, вход не нужен: Swagger по адресу https://api.7loc.com/cards-api/docs, файл OpenAPI — по адресу https://api.7loc.com/cards-api/openapi.json. Вызовы идут на https://api.7loc.com/cards-api и требуют API-ключ или логин персонала.
Бизнес с White Label не видит в админ-панели ссылку на справочник API. Его API-ключи и вебхуки работают так же.
Где документация API?
Swagger по адресу https://api.7loc.com/cards-api/docs, публичный, вход не нужен. Файл OpenAPI находится по адресу https://api.7loc.com/cards-api/openapi.json.
Какой базовый адрес у вызовов API?
https://api.7loc.com/cards-api. Для вызовов нужен API-ключ или логин персонала.
В нашей админ-панели White Label нет ссылки на документацию API. Работает ли у нас API?
Да. Бизнес с White Label не видит ссылку на справочник, но его API-ключи и вебхуки работают так же.
Вебхуки

Вебхук добавляется в разделе API и интеграции → Вебхуки → «Добавить вебхук», с URL, который принимает события. В 7Stamp вебхук создаётся для событий штамп-карт. Бизнес может добавить несколько вебхуков, каждый со своим URL.
Для вебхуков нужен аддон Webhooks & Events, $19 в месяц, который доступен только на платных тарифах. При добавлении первого вебхука предлагается его купить; без него вебхук нельзя создать или снова включить. Один аддон держит включённым один вебхук: можно добавить больше, но при каждом обновлении подписки в биллинге выключаются все, кроме самого старого.
Вебхуки отправляют события по мере того, как они происходят, с момента добавления вебхука. Более ранние события не отправляются.
Вебхуки бесплатны?
Нет. Для них нужен аддон Webhooks & Events, $19 в месяц, который доступен только на платных тарифах. Сам API бесплатен.
Я добавил второй вебхук, и он выключился. Почему?
Один аддон Webhooks & Events держит включённым один вебхук. При каждом обновлении подписки в биллинге выключаются все, кроме самого старого.
Отправит ли новый вебхук прошлые события?
Нет. События отправляются с момента добавления вебхука.
События вебхуков
Вебхук получает пятнадцать событий штамп-карт, название которых указано в event_type: SCAN, DELIVERY_INSERT, RECEIPT_SCAN, CARD_JOINED, REWARD_EARNED, VOUCHER_ISSUED, VOUCHER_PACK, ADMIN_VOUCHER_ISSUE, VOUCHER_REDEEMED, LOTTERY_WIN, CARD_CAMPAIGN, BIRTHDAY_GREETING, AUTO_MESSAGE_VOUCHER, CARD_ADDED_TO_WALLET и CARD_REMOVED_FROM_WALLET. Последние два приходят, когда карту добавляют в кошелёк или удаляют из него, с указанием кошелька — Apple или Google.
Скан без штампа, например покупка ниже цены штампа, всё равно отправляет SCAN с нулём добавленных штампов. О призе, выигранном на колесе, сообщает одно событие LOTTERY_WIN, когда колесо прокручено, а не REWARD_EARNED или VOUCHER_ISSUED; колесо, которое ждёт вращения, пока ничего не отправляет.
Отзывы покупателей не являются событиями штамп-карт. Каждый новый отзыв отправляет событие с entity review и action created на те вебхуки, у которых на странице вебхука среди объектов отмечены «Отзывы». Вебхук, добавленный здесь, настроен только на события штамп-карт, поэтому получает отзывы, когда отмечены «Отзывы».
Отправляется ли вебхук, если скан не добавил штамп?
Да. Скан без штампа, например покупка ниже цены штампа, всё равно отправляет SCAN с нулём добавленных штампов.
Какое событие сообщает, что покупатель выиграл на колесе?
LOTTERY_WIN, один раз, когда колесо прокручено. Колесо, которое ждёт вращения, пока ничего не отправляет.
Можно ли узнать, когда покупатель удаляет карту из кошелька?
Да. Добавление карты в кошелёк и её удаление отправляют CARD_ADDED_TO_WALLET и CARD_REMOVED_FROM_WALLET с указанием кошелька — Apple или Google.
Как получать новые отзывы покупателей через вебхук?
Откройте страницу вебхука и отметьте «Отзывы» среди его объектов. После этого каждый новый отзыв приходит с entity review и action created; вебхук, добавленный в разделе «API и интеграции», до тех пор получает только события штамп-карт.
Когда отправляется каждое событие
| Событие | Когда отправляется |
|---|---|
SCAN | Логин персонала сканирует карту: в 7Stamp Scanner, через API или с POS, например Toast. Штампы, снятые в 7Stamp Scanner, приходят как SCAN с отрицательным stamps_added |
DELIVERY_INSERT | Покупатель открывает код штампов, который даёт штампы, — QR, ссылку, сам код или приглашение, созданное через API |
RECEIPT_SCAN | Покупатель сканирует фискальный чек в чат-боте бизнеса, и на карту ставятся штампы; amount — сумма чека |
CARD_JOINED | Покупатель получает новую штамп-карту любым способом, с переданным вами external_id |
REWARD_EARNED | Скан достигает цели с Award |
VOUCHER_ISSUED | Скан достигает цели с ваучером |
LOTTERY_WIN | Колесо Lottery прокручено и даёт приз |
VOUCHER_PACK | Новая карта получает набор ваучеров штамп-карты, все ваучеры одним событием |
ADMIN_VOUCHER_ISSUE | Ваучер выдан напрямую на карту, в админ-панели или через API |
VOUCHER_REDEEMED | Ваучер на карте погашен: в 7Stamp Scanner, через API, на POS Toast или самим покупателем |
CARD_CAMPAIGN | Кампания доходит до карты, один раз на карту, с ваучером кампании, если он есть |
BIRTHDAY_GREETING | Для карты отправлено поздравление с днём рождения, с ваучером на день рождения, если он был выдан |
AUTO_MESSAGE_VOUCHER | Триггер автосообщения начисляет ваучер на карту, независимо от того, дойдёт ли потом до покупателя какой-либо канал |
CARD_ADDED_TO_WALLET | Карту добавили в Apple Wallet или Google Wallet |
CARD_REMOVED_FROM_WALLET | Карту удалили из кошелька |
Каждая цель, которой достигает скан, отправляет собственное событие после события скана, а цель, достигнутая одним сканом дважды за два круга карты, отправляет два. Заполненная карта, начинающая новый круг, — это та же карта, и она не отправляет CARD_JOINED; карта, выпущенная заново после того, как администратор удалил старую, — отправляет. Если при присоединении приходят набор ваучеров и штампы, сначала приходит CARD_JOINED, затем VOUCHER_PACK, затем DELIVERY_INSERT.
Код штампов без штампов не отправляет DELIVERY_INSERT, ваучер, сгенерированный в админ-панели без карты, не отправляет ADMIN_VOUCHER_ISSUE, а повторный вызов API для ваучера, который уже погашен, не отправляет второй VOUCHER_REDEEMED.
Какое событие сообщает, что покупатель достиг цели?
REWARD_EARNED для цели с Award, VOUCHER_ISSUED для цели с ваучером и LOTTERY_WIN для Lottery — каждое отправляется после собственного события скана.
Отправляется ли вебхук при снятии штампов?
Да. Штампы, снятые в 7Stamp Scanner, приходят как SCAN с отрицательным stamps_added.
Чем отличаются VOUCHER_ISSUED и ADMIN_VOUCHER_ISSUE?
VOUCHER_ISSUED приходит, когда скан достигает цели с ваучером. ADMIN_VOUCHER_ISSUE приходит, когда ваучер выдан напрямую на карту — вручную в админ-панели или через API.
Покупатель, который присоединяется по коду штампов, отправляет одно событие или несколько?
Несколько. Сначала приходит CARD_JOINED, затем VOUCHER_PACK, если у штамп-карты есть набор ваучеров, затем DELIVERY_INSERT со штампами.
Получаю ли я событие по каждому сообщению кампании?
CARD_CAMPAIGN отправляется один раз на каждую карту, до которой дошла кампания, с ваучером кампании, если он в ней есть.
Что получает вебхук
У каждого события одинаковое тело JSON: ID события, бизнес и само событие с его типом, штамп-картой, штампами до и после, суммой покупки, ID заказа и external_id, которые передала интеграция, логином персонала, который обслужил покупателя, выданными ваучерами и наградами, а также именем, email, Telegram, телефоном WhatsApp и датой рождения покупателя.
amount — сумма покупки в минимальных единицах валюты (центах): сумма 12.50, переданная со сканом, приходит как 1250. Если у события не было суммы, поле пустое.
ID события есть в теле и в заголовке X-Webhook-Event-Id. Повторная отправка того же события сохраняет его ID, поэтому получатель может отбрасывать повторы. Для URL Make или Zapier событие находится под ключом card_event вместо data.
Какие данные о покупателе передаёт вебхук?
Имя, email, Telegram, телефон WhatsApp и дату рождения, а также штамп-карту, штампы до и после, выданные ваучеры и награды.
В каких единицах amount?
В минимальных единицах валюты (центах). Сумма 12.50, переданная со сканом, приходит как 1250; если у события не было суммы, поле пустое.
Как не обработать одно событие дважды?
Используйте ID события — в теле и в заголовке X-Webhook-Event-Id. Повторная отправка сохраняет тот же ID.
Почему в Make событие находится под card_event?
Для URL Make или Zapier событие находится под ключом card_event вместо data, чтобы их приложения могли его отличить.
Подпись
Каждая доставка подписана. Заголовок X-Webhook-Signature содержит метку времени и HMAC-SHA256 от этой метки времени и исходного тела, вычисленный с секретным ключом вебхука. Секретный ключ показывается и перевыпускается на странице вебхука. Можно также добавить логин и пароль Basic auth.
Как проверить, что вебхук действительно пришёл от 7Stamp?
Вычислите HMAC-SHA256 от метки времени и исходного тела с секретным ключом вебхука и сравните его с заголовком X-Webhook-Signature.
Где найти секретный ключ вебхука?
На странице вебхука, там же его можно перевыпустить.
Можно ли защитить мой эндпоинт паролем?
Да. К вебхуку можно добавить логин и пароль Basic auth в дополнение к подписи.
Неудачные доставки
Доставка, которая не получила ответ 2xx за тридцать секунд, повторяется до десяти раз, и каждое ожидание на четыре секунды дольше предыдущего, поэтому повторы заканчиваются примерно за четыре минуты. При ответе 429 с Retry-After повтор выполняется через указанное время. Первая неудача события создаёт уведомление в админ-панели.
После ста неудачных доставок подряд система блокирует вебхук, и он больше не получает событий. Его страница заранее предупреждает об этом, и на ней есть кнопка «Разблокировать»; одна успешная доставка сбрасывает счётчик.
На странице каждого вебхука есть журнал его доставок с отправленным запросом и полученным ответом. «Отправить повторно» снова отправляет то же событие, только на этот вебхук.
Мой сервер был недоступен. События потеряны?
Каждая доставка повторяется до десяти раз примерно за четыре минуты. После этого откройте журнал вебхука и нажмите «Отправить повторно» для нужных событий.
Почему мой вебхук перестал получать события?
После ста неудачных доставок подряд система его блокирует. Исправьте эндпоинт и нажмите «Разблокировать» на странице вебхука.
Можно ли посмотреть, что было отправлено на мой вебхук?
Да. На странице каждого вебхука есть журнал доставок с отправленным запросом и полученным ответом.
Вкладка «Интеграции»

Вкладка «Интеграции» показывает готовые способы по группам:
- Штампы на вашей кассе — Poster, Toast, «Ваш собственный POS или CRM» и «Не видите своего POS?»;
- Фискальные чеки — SmartKasa;
- Автоматизация — Make, Zapier и Public Swagger.
На каждой карточке указано, нужен ли ей API-ключ. Вкладка предлагает одни и те же карточки во всех странах; по странам ограничены только фискальные чеки.

Бизнес с White Label не видит карточек Make, Zapier и Public Swagger, и ему не предлагаются Poster и инструкции по настройке на 7stamp.com.
Какие POS-системы готовы к подключению?
Poster, а также Toast, когда его включат для платформы, — до тех пор он показывает «Скоро». Другие системы подключаются через API, с карточкой «Ваш собственный POS или CRM».
Ограничены ли интеграции по странам?
Нет. Вкладка предлагает одни и те же карточки во всех странах. По странам ограничены только фискальные чеки.
Почему я не вижу Make и Zapier?
Они не показываются бизнесу с White Label. Его API-ключи и вебхуки работают так же.
Poster
Poster — это наше приложение в маркетплейсе Poster. «Установить в Poster» открывает его страницу, а приложение настраивается с API-ключом логина персонала. Его штампы учитываются как Card Operations этого логина персонала.
Как подключить Poster?
Откройте Интеграции → Poster и выберите «Установить в Poster». Приложение настраивается с API-ключом логина персонала.
Чьи Card Operations расходуют штампы из Poster?
Того логина персонала, чей API-ключ использует приложение.
Нужен ли API-ключ для Poster?
Да, API-ключ логина персонала.
Toast
Toast показывает «Скоро» для каждого бизнеса, пока доступ к Toast не настроен на платформе. Это один переключатель для всей платформы, а не настройка бизнеса; когда он включён, карточка Toast сама содержит настройку.
Каждая локация Toast подключается по своему GUID к одному логину персонала, без API-ключа: бизнес, штамп-карта и тариф этого логина персонала применяются к каждому запросу Toast из этой локации. Локацию можно подключить только к одному логину персонала, и у логина персонала одна локация. Запросы из локации отклоняются, когда она отключена, а также пока её логин персонала выключен или удалён.
Каждому ваучеру можно назначить товар из меню Toast: тогда на POS Toast он становится скидкой на этот товар. Ваучер без товара применяется как нулевая скидка на чек, а подарок кассир выдаёт вручную. Ваучеры погашаются на POS Toast, а колесо, достигнутое оплаченным чеком, прокручивается сразу. Когда Toast отменяет транзакцию, её штампы снимаются, а погашенные по ней ваучеры восстанавливаются.
Гость может присоединиться на киоске Toast или на экране для гостей по номеру телефона или email. Штамп-карта выпускается сразу; от 7Stamp гость ничего не получает, пока не откроет её с тем же телефоном или email.
Почему Toast показывает «Скоро»?
Доступ к Toast — это один переключатель для всей платформы, а не настройка вашего бизнеса. Пока он не включён, подключать нечего.
Как подключается локация Toast?
По её GUID к одному логину персонала, без API-ключа. Штамп-карта и тариф этого логина персонала применяются к каждому запросу из этой локации.
Что происходит со штампами, когда Toast аннулирует чек?
Когда Toast отменяет транзакцию, её штампы снимаются, а погашенные по ней ваучеры восстанавливаются.
SmartKasa

SmartKasa не нужен API-ключ. Это источник чеков в разделе «Сканирование чеков», который добавляется по ID магазина SmartKasa или по коду компании, чтобы охватить все магазины. Покупатели сканируют чек SmartKasa в чат-боте бизнеса, и штампы засчитываются логину персонала этого источника чеков.
SmartKasa — украинская система, а фискальные чеки работают только в Украине, Словакии, Казахстане и Узбекистане.
Нужен ли API-ключ для SmartKasa?
Нет. SmartKasa — это источник чеков в разделе «Сканирование чеков», который добавляется по ID магазина или по коду компании.
Где покупатели сканируют чек SmartKasa?
В чат-боте вашего бизнеса. Штампы засчитываются логину персонала этого источника чеков.
В каких странах работают фискальные чеки?
В Украине, Словакии, Казахстане и Узбекистане.
Make и Zapier

Приложение 7Stamp для Make есть в публичном каталоге приложений Make: найдите 7Stamp поиском в любом сценарии Make или нажмите «Открыть в Make» на вкладке «Интеграции». Нашего приложения для Zapier нет в публичном каталоге Zapier: «Открыть в Zapier» — это приглашение, которое добавляет приложение в собственный аккаунт бизнеса в Zapier. Оба приложения работают с API-ключом логина персонала.
Сценарии Make и Zaps запускаются вебхуками 7Stamp, поэтому триггерам нужен аддон Webhooks & Events. Действиям вроде начисления штампов или выдачи ваучера нужен только API-ключ. Make и Zapier не предлагаются бизнесу с White Label.
Где найти приложение 7Stamp в Make и Zapier?
В Make найдите 7Stamp поиском в любом сценарии — приложение есть в публичном каталоге приложений Make. В Zapier оно пока не публичное, поэтому нажмите «Открыть в Zapier» на вкладке «Интеграции» — приглашение добавит приложение в ваш собственный аккаунт.
Нужен ли для Make и Zapier аддон Webhooks & Events?
Для триггеров — да, потому что сценарии и Zaps запускаются вебхуками 7Stamp. Действиям вроде начисления штампов или выдачи ваучера нужен только API-ключ.
Нужен ли API-ключ для Make или Zapier?
Да. Приложения работают с API-ключом логина персонала.