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 ключове, Webhooks и интеграции.
API ключове

Създава се API ключ под API ключове → Добавете API ключ за едно влизане на персонал. Входът на персонала има най-много един ключ API и не може да бъде избран изключен вход на персонала. Без да можете да избирате вход за персонал, прозорецът за генериране на API ключ предлага да създадете такъв точно там; новото влизане на служители изисква безплатен Staff Seat, а при пълен план прозорецът предлага да добавите място или вместо това да изберете план.
Всяко повикване, направено с ключ API, действа като вход на персонала: достига само до бизнеса на този персонал, подпечатва картата с печат, избрана за него под Автоматично щамповане, и неговите печати се броят като Card Operations на този персонал.
Ключът може да бъде прегледан и копиран отново по всяко време от списъка с ключове API. Може също да се покаже като QR код, за да се сканира в терминал и да се отпечата с името на персонала за влизане.
Как да създам API ключ?
В Настройки → API и интеграции → Ключове API изберете Добавяне на ключ API и изберете Вход за персонал. Всяко влизане на персонал има най-много един ключ API.
Загубих ключа си API. Имам ли нужда от нов?
Не. Ключът може да бъде прегледан и копиран отново по всяко време от списъка с ключове API или показан като QR код.
Коя карта с печат подпечатва API?
Избраният за влизане на персонала на ключа под Автоматично щамповане. Неговите печати се броят като Card Operations на този Staff Login.
Защо не мога да избера вход за персонал за нов ключ?
Изключен Staff Login не може да бъде избран, а Staff Login, който вече има ключ, не може да получи втори. Без да можете да изберете, прозорецът предлага да създадете вход за персонал.
Когато API ключ спре да работи
Ключ API не изтича. Той спира да работи само когато бъде регенериран или изтрит, или когато неговият персонален вход е изключен или изтрит. Нова парола или потребителско име за влизане на персонала не го засяга.
- Regenerate дава на Staff Login нов API ключ; стария веднага спира да работи.
- Delete спира ключа наведнъж. Самото влизане на персонала продължава да работи в 7Stamp Scanner и може да получи нов ключ по-късно.
- Изключването на Staff Login запазва неговия ключ: когато Staff Login се включи отново, същият ключ работи отново.
Ключ API изтича ли?
Не. Той спира да работи само когато бъде регенериран или изтрит, или когато влизането му в персонала е изключено или изтрито.
Промених паролата за влизане на персонала. Имам ли нужда от нов ключ API?
Не. Нова парола или влизане не засяга ключа API.
Включих отново влизането на персонала. Старият ключ API работи ли?
да Изключването на влизане на служители запазва неговия ключ и същият ключ работи отново, след като бъде включен отново.
Какво прави API
Чрез API системата може:
- раздайте карта с печат като връзка или QR;
- добавяне на печати;
- прочетете карта с нейните печати, цели и ваучери;
- издаване на ваучер направо към карта;
- осребрете ваучер чрез неговия код на ваучер;
- съобщение до клиент.
API намира карта на клиент по собствения идентификатор на бизнеса, като CRM ID, телефон или имейл, изпратен като external_id. Идентификаторът се съхранява на картата и се връща във всяка Webhook за нея. API няма обаждане, което изброява клиентите на даден бизнес: цялата клиентска база се изважда само чрез администраторския експорт.
Вместо ключ API, приложението може да влезе с потребителско име и парола за вход на персонала — за устройство, на което касиерът влиза. Ключът API е подходящ за устройство, което работи без надзор. Webhooks се добавят само в администратора; API няма обаждане за абониране за събития или за тяхното изброяване.
API не задава ограничение за честотата на заявките: обажданията не се ограничават по брой или честота и същата карта може да бъде сканирана отново веднага. Това, което ограничава щамповането през него, е Card Operations на плана.
Можем ли да добавим марки от нашия собствен CRM или POS?
Да, чрез API. Той раздава карти с марки, добавя марки, чете карти и изкупува ваучери. За да информирате системата си за събития, добавете Webhook — който се нуждае от добавката Webhooks & Events.
Можем ли да експортираме данни?
Чрез API вие четете карти по вашия собствен идентификатор, а Webhooks изпраща събития, когато се случват. API няма списък с всички клиенти — цялата клиентска база се изважда чрез администраторския експорт.
Как API намира карта на клиент?
Чрез вашия собствен идентификатор — CRM ID, телефон или имейл — изпратен като external_id. Той се съхранява на картата и се връща във всеки Webhook за него.
Мога ли да се абонирам за Webhooks чрез API?
Не. Webhooks се добавят само в администратора.
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 Business не вижда връзка към справката API в администратора. Неговите API ключове и Webhooks работят по същия начин.
Къде е документацията на 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 Business не вижда връзка към препратката, но неговите API ключове и Webhooks работят по същия начин.
Уеб кукички

Добавя се Webhook под API & интеграции → Webhooks → Add webhook, със URL, който получава събитията. В 7Stamp е създадена Webhook за събития на Stamp card. Един бизнес може да добави няколко уебкукички, всяка със собствен URL.
Webhooks се нуждаят от добавката Webhooks & Events, €19 на месец, предлагана само на платени планове. Добавяне на първите предложения за закупуване на Webhook; без него Webhook не може да бъде създаден или включен отново. Една добавка поддържа един Webhook включен: могат да се добавят повече, но всяка актуализация на таксуването на абонамента изключва всички освен най-стария.
Уеб кукичките изпращат събития, както се случват от момента на добавяне на уеб кукичката. По-ранни събития не се изпращат.
Безплатни ли са Webhooks?
Не. Те се нуждаят от добавката Webhooks & Events, €19 на месец, предлагана само на платени планове. Самият API е безплатен.
Добавих втори Webhook и той беше изключен. защо
Една добавка Webhooks & Events поддържа един Webhook включен. Всяка актуализация на таксуването на абонамента изключва всички освен най-стария.
Ще изпрати ли нов Webhook минали събития?
Не. Събитията се изпращат от момента на добавяне на Webhook.
Webhook събития
Уеб кукичката получава петнадесет събития на Stamp card, именувани в 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; колело, което чака да се завърти, все още не изпраща нищо.
Отзивите на клиенти не са събития с карти с печат. Всяка нова рецензия изпраща събитие с обект review и действие created към Webhooks, които имат отметка на Reviews сред своите обекти на страницата на Webhook. Webhook, добавен тук, е настроен само за събития на Stamp card, така че получава рецензии, след като рецензиите бъдат отметнати.
Изпраща ли се Webhook, когато сканирането не добавя печат?
да Сканиране, което не добавя печат, като например покупка под цената на марката, все пак изпраща SCAN с нулеви добавени печати.
Кое събитие ми казва, че клиентът е спечелил на колелото?
LOTTERY_WIN, изпраща се веднъж, когато колелото се завърти. Колело, което чака да бъде завъртяно, още нищо не изпраща.
Мога ли да разбера кога клиентът премахне картата от портфейла си?
Да. Добавянето на картата към портфейл и премахването ѝ изпраща CARD_ADDED_TO_WALLET и CARD_REMOVED_FROM_WALLET, с портфейла, Apple или Google.
Как да получа нови отзиви от клиенти чрез Webhook?
Отворете страницата на Webhook и поставете отметка на Прегледи сред неговите обекти. Всеки нов преглед след това пристига с преглед на обекта и създадено действие; Webhook, добавен под API и интеграции, получава събития на картата Stamp само до тогава.
Когато всяко събитие е изпратено
| Събитие | Изпратено кога |
|---|---|
SCAN | Входът на персонал сканира картата: в 7Stamp Scanner, през API или от POS като Toast. Премахнатите печати в 7Stamp Scanner са SCAN с отрицателен stamps_added |
DELIVERY_INSERT | Клиент отваря Stamp Code, който дава печати — QR, връзка, самия код или покана, направена чрез API |
RECEIPT_SCAN | Клиент сканира фискален бон в чатбота на Бизнеса и той се подпечатва; amount е общата разписка |
CARD_JOINED | Клиент получава нова Stamp карта, независимо от начина, с external_id, който сте преминали |
REWARD_EARNED | Сканирането достига Award цел |
VOUCHER_ISSUED | Едно сканиране достига цел за ваучер |
LOTTERY_WIN | Lottery колело се завърта и дава награда |
VOUCHER_PACK | Нова карта получава пакета ваучери на картата Stamp, всички нейни ваучери в едно събитие |
ADMIN_VOUCHER_ISSUE | Ваучерът се издава директно към карта, в администратора или през API |
VOUCHER_REDEEMED | Ваучер на карта се използва: в 7Stamp Scanner, чрез API, на Toast POS или от купувача |
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, всеки изпратен след собственото събитие на сканирането.
Изпраща ли се Webhook, когато печатите бъдат премахнати?
Да. Пощенските марки, премахнати в 7Stamp Scanner, пристигат като SCAN с отрицателно stamps_added.
Каква е разликата между VOUCHER_ISSUED и ADMIN_VOUCHER_ISSUE?
VOUCHER_ISSUED идва, когато сканирането достигне цел за ваучер. ADMIN_VOUCHER_ISSUE идва, когато ваучер се издаде направо към карта, на ръка в администратора или чрез API.
Клиент, който се присъединява с Stamp Code, изпраща ли едно събитие или няколко?
Няколко. Първо идва CARD_JOINED, след това VOUCHER_PACK, ако Stamp card има пакет ваучери, след това DELIVERY_INSERT с марките.
Получавам ли събитие за всяко съобщение от кампанията?
CARD_CAMPAIGN се изпраща веднъж за всяка карта, достигната от Кампанията, с ваучера на Кампанията, когато носи такъв.
Какво получава Webhook
Всяко събитие има едно и също JSON тяло: идентификатор на събитието, бизнес и събитието с неговия тип, карта с печат, печати преди и след, сумата на покупката, идентификационният номер на поръчката и external_id изпратената интеграция, входът на персонала, който го е обслужил, ваучерите и наградите, които е дал, и името на клиента, имейл, Telegram, WhatsApp телефон и дата на раждане.
amount е сумата на покупката в малки единици (центове): сума от 12,50, изпратена със сканирането, пристига като 1250. Тя е празна, когато събитието няма сума.
Идентификаторът на събитието е в тялото и в заглавката X-Webhook-Event-Id. Повторният опит на същото събитие запазва неговия идентификатор, така че приемникът може да откаже повторенията. За Make или Zapier URL събитието се намира под card_event ключ вместо data.
Какви данни носи Webhook за клиента?
Име, имейл, Telegram, WhatsApp телефон и дата на раждане, заедно с картата с печат, печати преди и след и предоставените ваучери и награди.
В каква единица е сумата?
Във второстепенни единици (центове). Сума от 12,50, изпратена със сканирането, пристига като 1250; той е празен, когато събитието няма сума.
Как да избегна обработката на едно и също събитие два пъти?
Използвайте идентификатора на събитието в тялото и в заглавката X-Webhook-Event-Id. Повторният опит запазва същия идентификатор.
Защо събитието е под card_event в Make?
За Make или Zapier URL събитието се намира под ключа card_event вместо data, така че техните приложения могат да го различат.
Подпис
Всяка доставка е подписана. Заглавката X-Webhook-Signature съдържа клеймо за време и HMAC-SHA256 на това клеймо за време и необработеното тяло, въведено със секретния ключ на Webhook. Тайният ключ се показва и регенерира на страницата на Webhook. Могат да се добавят и потребителско име и парола за основно удостоверяване.
Как да проверя дали Webhook наистина идва от 7Stamp?
Изчислете HMAC-SHA256 на клеймото за време и необработеното тяло с тайния ключ на Webhook и го сравнете със заглавката X-Webhook-Signature.
Къде да намеря тайния ключ на Webhook?
На страницата на Webhook, където също може да бъде регенериран.
Мога ли да защитя крайната си точка с парола?
да Основно потребителско име и парола за удостоверяване могат да бъдат добавени към Webhook върху подписа.
Неуспешни доставки
Доставка, която не получава отговор 2xx в рамките на тридесет секунди, се опитва до десет пъти, като всеки чака четири секунди по-дълго от последния, така че повторните опити приключват в рамките на около четири минути. Отговор 429 с Retry-After се опитва повторно след това време. Първата грешка на събитие поставя известие в администратора.
След сто неуспешни доставки подред Webhook се блокира от системата и не получава повече събития. Страницата му предупреждава преди това и има бутон за деблокиране; една успешна доставка нулира брояча.
Всяка страница на Webhook има дневник на своите доставки, с изпратената заявка и получения отговор. Повторното изпращане изпраща същото събитие отново, само към тази Webhook.
Сървърът ми не работеше. Загубени ли са събитията?
Всяка доставка се опитва до десет пъти в рамките на около четири минути. След това отворете дневника на Webhook и използвайте Resend за събитията, от които се нуждаете.
Защо моята Webhook спря да получава събития?
След сто неуспешни доставки подред се блокира от системата. Коригирайте крайната точка и натиснете Unblock на страницата на Webhook.
Мога ли да видя какво е изпратено до моя Webhook?
да Всяка страница на Webhook има дневник на доставките с изпратената заявка и получения отговор.
Раздел Интеграции

Разделът Интеграции изброява готовите начини по групи:
- Печат на вашата каса — Poster, Toast, вашият собствен POS или CRM и не виждате вашия POS?;
- Фискални бележки — SmartKasa;
- Automation — Make, Zapier и публичен Swagger.
Всяка карта казва дали има нужда от ключ API. Разделът предлага едни и същи карти във всяка държава; само фискалните бележки са ограничени по държава.

White Label Business не вижда карта Make, Zapier или Public Swagger и не се предлага Poster или ръководствата за настройка на 7stamp.com.
Кои POS системи са готови за свързване?
Poster и Toast, след като бъде включен за платформата — дотогава показва Очаквайте скоро. Други системи се свързват чрез API, с вашия собствен POS или CRM.
Интеграциите ограничени ли са по държава?
Не. Разделът предлага едни и същи карти във всяка държава. Само фискалните бонове са ограничени по държава.
Защо не виждам Make и Zapier?
Те не се показват на бизнес White Label. Неговите API ключове и Webhooks работят по същия начин.
Poster
Poster е нашето приложение в Poster пазара. Инсталиране в Poster отваря своя списък и приложението е настроено с ключа API за влизане на персонала. Неговите печати се броят като Card Operations на този Staff Login.
Как да свържа Poster?
Отворете Integrations → Poster и изберете Install in Poster. Приложението е настроено с ключа API за вход на персонала.
Чии Card Operations използват марките Poster?
Тези от персонала Вход, чийто API ключ използва приложението.
Имам ли нужда от API ключ за Poster?
Да, ключът API за вход на персонала.
Toast
Toast показва Очаквайте скоро за всеки бизнес, докато Toast достъпът не бъде настроен на платформата. Това е един ключ за цялата платформа, а не настройка на бизнеса; след като е включена, Toast картата държи самата настройка.
Всяко местоположение на Toast е свързано чрез своя GUID с едно влизане на персонала, без API ключ: този бизнес, карта и план на Staff Login се прилагат към всяка заявка на Toast от местоположението. Едно местоположение може да бъде свързано само с едно влизане на персонала, а влизането на персонала съдържа едно местоположение. Заявките от дадено местоположение се отказват, след като връзката с него е прекъсната или докато влизането на персонала е изключено или изтрито.
Всеки ваучер може да получи Toast продукт от менюто: при Toast POS той става отстъпка за този продукт. Ваучер без такъв се прилага като нулева отстъпка върху чека, а касиерът предава подаръка на ръка. Ваучерите се осребряват на Toast POS и колелото, достигнато от платен чек, се завърта веднага. Когато Toast отмени транзакция, нейните печати се вземат обратно или нейните осребрени ваучери се възстановяват.
Гост може да се присъедини към павилион Toast или към екран, обърнат към гостите, с телефонен номер или имейл. Картата Stamp се издава наведнъж; гостът не получава нищо от 7Stamp, докато не го отвори със същия телефон или имейл.
Защо 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 или използвайте Open in Make в раздела Integrations. Нашето приложение за Zapier не е в публичната директория на Zapier: Open in Zapier е покана, която добавя приложението към собствения Zapier акаунт на Business. И двете приложения работят с ключа API на Staff Login.
Сценариите на Make и Zaps се стартират от 7Stamp Webhooks, така че тригерите се нуждаят от добавката Webhooks & Events. Действия като добавяне на печати или издаване на ваучер се нуждаят само от ключ API. Make и Zapier не се предлагат на White Label бизнес.
Къде да намеря приложението 7Stamp в Make и Zapier?
В Make потърсете 7Stamp във всеки сценарий — приложението е в публичния каталог с приложения на Make. В Zapier то още не е публично, затова използвайте Open in Zapier в раздела Integrations — поканата добавя приложението към вашия собствен акаунт.
Нуждаят ли се Make и Zapier от добавката Webhooks & Events?
Тригерите го правят, защото сценариите и Zaps се стартират от 7Stamp Webhooks. Действия като добавяне на печати или издаване на ваучер се нуждаят само от ключ API.
Имам ли нужда от API ключ за Make или Zapier?
да Приложенията работят с ключа API за вход на персонала.