API a integrace

Nastavení → API a integrace má tři karty: Klíče API, Webhooky a Integrace.
API a klíče API jsou zdarma na každém plánu, včetně Free Forever; žádný doplněk pro API neexistuje. Razítka udělená přes API jsou Card Operations jako všechna ostatní, takže se zastaví, když se Card Operations plánu vyčerpají. Placenou částí jsou webhooky, viz níže.
Stojí API něco navíc?
Ne. API a klíče API jsou zdarma na každém plánu, včetně Free Forever. Razítka udělená přes něj jsou Card Operations jako všechna ostatní.
Mohu API používat na Free Forever?
Ano. Když se Card Operations plánu vyčerpají, razítka přes API se zastaví jako všechna ostatní.
Kde je nastavení API?
V Nastavení → API a integrace, se třemi kartami — Klíče API, Webhooky a Integrace.
Klíče API

Klíč API se vytváří v Klíče API → Přidat klíč API pro jeden login zaměstnance. Login zaměstnance má nejvýše jeden klíč API a vypnutý login zaměstnance nelze vybrat. Když není žádný login zaměstnance k výběru, okno Generovat klíč API nabídne jeho vytvoření přímo na místě; nový login zaměstnance vyžaduje volný Staff Seat a při plném plánu okno místo toho nabídne přidat místo nebo vybrat plán.
Každé volání s klíčem API jedná jako jeho login zaměstnance: dosáhne jen na firmu tohoto loginu zaměstnance, uděluje razítka na razítkovou kartu, která je pro něj vybrána v části Automatické udělování razítek, a jeho razítka se počítají jako Card Operations tohoto loginu zaměstnance.
Klíč lze kdykoli znovu zobrazit a zkopírovat ze seznamu klíčů API. Lze ho také zobrazit jako QR kód, aby se dal naskenovat do terminálu, a vytisknout se jménem loginu zaměstnance.
Jak vytvořím klíč API?
V Nastavení → API a integrace → Klíče API zvolte Přidat klíč API a vyberte login zaměstnance. Každý login zaměstnance má nejvýše jeden klíč API.
Ztratil jsem klíč API. Potřebuji nový?
Ne. Klíč lze kdykoli znovu zobrazit a zkopírovat ze seznamu klíčů API nebo ho zobrazit jako QR kód.
Kterou razítkovou kartu volání API orazítkují?
Tu, která je pro login zaměstnance daného klíče vybrána v části Automatické udělování razítek. Její razítka se počítají jako Card Operations tohoto loginu zaměstnance.
Proč nemohu pro nový klíč vybrat login zaměstnance?
Vypnutý login zaměstnance nelze vybrat a login zaměstnance, který už klíč má, nemůže dostat druhý. Když není co vybrat, okno nabídne vytvoření loginu zaměstnance.
Kdy klíč API přestane fungovat
Platnost klíče API nevyprší. Přestane fungovat jen tehdy, když je přegenerován nebo smazán, nebo když je jeho login zaměstnance vypnut nebo smazán. Nové heslo nebo login pro login zaměstnance ho neovlivní.
- Regenerovat dá loginu zaměstnance nový klíč API; starý okamžitě přestane fungovat.
- Vymazat klíč okamžitě zastaví. Samotný login zaměstnance dál funguje v 7Stamp Scanner a může později dostat nový klíč.
- Vypnutí loginu zaměstnance jeho klíč ponechá: když je login zaměstnance znovu zapnut, stejný klíč opět funguje.
Vyprší platnost klíče API?
Ne. Přestane fungovat jen tehdy, když je přegenerován nebo smazán, nebo když je jeho login zaměstnance vypnut nebo smazán.
Změnil jsem heslo loginu zaměstnance. Potřebuji nový klíč API?
Ne. Nové heslo ani login klíč API neovlivní.
Znovu jsem zapnul login zaměstnance. Funguje jeho starý klíč API?
Ano. Vypnutí loginu zaměstnance jeho klíč ponechá a stejný klíč znovu funguje, jakmile je login opět zapnutý.
Co API umí
Přes API systém může:
- vydat razítkovou kartu jako odkaz nebo QR;
- přidat razítka;
- přečíst kartu s jejími razítky, cíli a poukazy;
- vydat poukaz přímo na kartu;
- uplatnit poukaz podle jeho kódu poukazu;
- poslat zprávu kupujícímu.
API najde kartu kupujícího podle vlastního identifikátoru firmy, například ID v CRM, telefonu nebo e-mailu, odeslaného jako external_id. Identifikátor se uloží na kartě a vrací se v každém webhooku o ní. API nemá žádné volání, které by vypsalo kupující firmy: celá základna kupujících se vynáší jen přes export v administraci.
Místo klíče API se aplikace může přihlásit přihlašovacím jménem a heslem loginu zaměstnance — pro zařízení, ke kterému se přihlašuje pokladní. Klíč API se hodí pro zařízení, které běží bez obsluhy. Webhooky se přidávají jen v administraci; API nemá žádné volání pro přihlášení k odběru událostí ani pro jejich výpis.
API nestanovuje žádný limit počtu požadavků: volání nejsou omezena počtem ani frekvencí a stejnou kartu lze hned znovu naskenovat. Udělování razítek přes něj omezují Card Operations plánu.
Můžeme přidávat razítka z vlastního CRM nebo POS?
Ano, přes API. Vydává razítkové karty, přidává razítka, čte karty a uplatňuje poukazy. Aby byl váš systém informován o událostech, přidejte webhook — ten vyžaduje doplněk Webhooks & Events.
Můžeme data exportovat?
Přes API čtete karty podle vlastního identifikátoru a webhooky posílají události, jakmile nastanou. API nemá seznam všech kupujících — celá základna kupujících se vynáší přes export v administraci.
Jak API najde kartu kupujícího?
Podle vašeho vlastního identifikátoru — ID v CRM, telefonu nebo e-mailu — odeslaného jako external_id. Uloží se na kartě a vrací se v každém webhooku o ní.
Mohu se k webhookům přihlásit přes API?
Ne. Webhooky se přidávají jen v administraci.
Má API omezení počtu požadavků?
Ne. Volání nejsou omezena počtem ani frekvencí a stejnou kartu lze hned znovu naskenovat. Udělování razítek omezují jen Card Operations plánu.
Reference API
Reference API je veřejná a nevyžaduje přihlášení: Swagger na https://api.7loc.com/cards-api/docs, se souborem OpenAPI na https://api.7loc.com/cards-api/openapi.json. Volání jdou na https://api.7loc.com/cards-api a vyžadují klíč API nebo login zaměstnance.
Firma s White Label v administraci nevidí odkaz na referenci API. Její klíče API a webhooky fungují stejně.
Kde je dokumentace API?
Swagger na https://api.7loc.com/cards-api/docs, veřejný, bez nutnosti přihlášení. Soubor OpenAPI je na https://api.7loc.com/cards-api/openapi.json.
Jaká je základní adresa pro volání API?
https://api.7loc.com/cards-api. Volání vyžadují klíč API nebo login zaměstnance.
Naše administrace White Label nemá odkaz na dokumentaci API. Funguje pro nás API?
Ano. Firma s White Label nevidí odkaz na referenci, ale její klíče API a webhooky fungují stejně.
Webhooky

Webhook se přidává v API a integrace → Webhooky → Přidat webhook, s URL, která události přijímá. V 7Stamp se webhook vytváří pro události razítkových karet. Firma může přidat několik webhooků, každý s vlastní URL.
Webhooky vyžadují doplněk Webhooks & Events, €19 měsíčně, nabízený jen na placených plánech. Přidání prvního webhooku nabídne jeho koupi; bez něj nelze webhook vytvořit ani znovu zapnout. Jeden doplněk udrží zapnutý jeden webhook: lze přidat další, ale každá fakturační aktualizace předplatného vypne všechny kromě nejstaršího.
Webhooky posílají události, jakmile nastanou, od okamžiku přidání webhooku. Dřívější události se neposílají.
Jsou webhooky zdarma?
Ne. Vyžadují doplněk Webhooks & Events, €19 měsíčně, nabízený jen na placených plánech. Samotné API je zdarma.
Přidal jsem druhý webhook a byl vypnut. Proč?
Jeden doplněk Webhooks & Events udrží zapnutý jeden webhook. Každá fakturační aktualizace předplatného vypne všechny kromě nejstaršího.
Pošle nový webhook minulé události?
Ne. Události se posílají od okamžiku přidání webhooku.
Události webhooků
Webhook dostává patnáct událostí razítkových karet, pojmenovaných v 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 a CARD_REMOVED_FROM_WALLET. Poslední dvě přicházejí, když je karta přidána do peněženky nebo z ní odstraněna, s peněženkou, Apple nebo Google.
Skenování, které nepřidá žádné razítko, například nákup pod cenou razítka, přesto odešle SCAN s nulou přidaných razítek. Výhru na kole oznámí jedna událost LOTTERY_WIN při roztočení kola, ne REWARD_EARNED ani VOUCHER_ISSUED; kolo čekající na roztočení zatím nic neposílá.
Recenze kupujících nejsou události razítkových karet. Každá nová recenze odešle událost s entitou review a akcí created webhookům, které mají na stránce webhooku mezi objekty zaškrtnuté Recenze. Webhook přidaný zde je nastaven jen na události razítkových karet, takže recenze dostává, jakmile jsou Recenze zaškrtnuté.
Odešle se webhook, když skenování nepřidá žádné razítko?
Ano. Skenování, které nepřidá žádné razítko, například nákup pod cenou razítka, přesto odešle SCAN s nulou přidaných razítek.
Která událost mi řekne, že kupující vyhrál na kole?
LOTTERY_WIN, odeslaná jednou při roztočení kola. Kolo čekající na roztočení zatím nic neposílá.
Poznám, když kupující odstraní kartu ze své peněženky?
Ano. Přidání karty do peněženky a její odstranění odešlou CARD_ADDED_TO_WALLET a CARD_REMOVED_FROM_WALLET, s peněženkou, Apple nebo Google.
Jak dostanu nové recenze kupujících přes webhook?
Otevřete stránku webhooku a mezi jeho objekty zaškrtněte Recenze. Každá nová recenze pak dorazí s entitou review a akcí created; webhook přidaný v API a integrace do té doby dostává jen události razítkových karet.
Kdy se která událost odesílá
| Událost | Odesílá se, když |
|---|---|
SCAN | Login zaměstnance naskenuje kartu: v 7Stamp Scanner, přes API nebo z POS, například Toast. Razítka odebraná v 7Stamp Scanner jsou SCAN se záporným stamps_added |
DELIVERY_INSERT | Kupující otevře kód razítka, který dává razítka — QR, odkaz, samotný kód nebo pozvánku vytvořenou přes API |
RECEIPT_SCAN | Kupující naskenuje fiskální účtenku v chatbotovi firmy a dostane razítko; amount je součet účtenky |
CARD_JOINED | Kupující dostane novou razítkovou kartu, jakoukoli cestou, s external_id, které jste předali |
REWARD_EARNED | Skenování dosáhne cíle Award |
VOUCHER_ISSUED | Skenování dosáhne cíle s poukazem |
LOTTERY_WIN | Kolo Lottery se roztočí a dá výhru |
VOUCHER_PACK | Nová karta dostane balíček poukazů razítkové karty, všechny jeho poukazy v jedné události |
ADMIN_VOUCHER_ISSUE | Poukaz je vydán přímo na kartu, v administraci nebo přes API |
VOUCHER_REDEEMED | Poukaz na kartě je uplatněn: v 7Stamp Scanner, přes API, na POS Toast nebo kupujícím |
CARD_CAMPAIGN | Kampaň dorazí na kartu, jednou za kartu, s poukazem kampaně, pokud nějaký má |
BIRTHDAY_GREETING | Pro kartu odejde narozeninové přání, s narozeninovým poukazem, pokud byl vydán |
AUTO_MESSAGE_VOUCHER | Spouštěč automatické zprávy vloží poukaz na kartu, bez ohledu na to, zda pak některý kanál kupujícího zastihne |
CARD_ADDED_TO_WALLET | Karta je přidána do Apple Wallet nebo Google Wallet |
CARD_REMOVED_FROM_WALLET | Karta je odstraněna z peněženky |
Každý cíl, kterého skenování dosáhne, odešle vlastní událost po události skenování, a cíl dosažený jedním skenováním dvakrát, přes dvě kola karty, odešle dvě. Plná karta, která začíná nové kolo, je stejná karta a CARD_JOINED neodešle; karta vydaná znovu poté, co administrátor smazal starou, ano. Když připojení přinese balíček poukazů a razítka, přijde nejprve CARD_JOINED, pak VOUCHER_PACK a pak DELIVERY_INSERT.
Kód razítka bez razítek neodešle DELIVERY_INSERT, poukaz vygenerovaný v administraci bez karty neodešle ADMIN_VOUCHER_ISSUE a opakované volání API pro poukaz, který už uplatnilo, neodešle druhou VOUCHER_REDEEMED.
Která událost mi řekne, že kupující dosáhl cíle?
REWARD_EARNED pro cíl Award, VOUCHER_ISSUED pro cíl s poukazem a LOTTERY_WIN pro Lottery, každá odeslaná po vlastní události skenování.
Odešle se webhook, když jsou razítka odebrána?
Ano. Razítka odebraná v 7Stamp Scanner dorazí jako SCAN se záporným stamps_added.
Jaký je rozdíl mezi VOUCHER_ISSUED a ADMIN_VOUCHER_ISSUE?
VOUCHER_ISSUED přijde, když skenování dosáhne cíle s poukazem. ADMIN_VOUCHER_ISSUE přijde, když je poukaz vydán přímo na kartu, ručně v administraci nebo přes API.
Odešle kupující, který se připojí s kódem razítka, jednu událost, nebo několik?
Několik. Nejprve přijde CARD_JOINED, pak VOUCHER_PACK, pokud má razítková karta balíček poukazů, a pak DELIVERY_INSERT s razítky.
Dostanu událost za každou zprávu kampaně?
CARD_CAMPAIGN se odešle jednou za každou kartu, na kterou kampaň dorazí, s poukazem kampaně, pokud ho nese.
Co webhook dostává
Každá událost má stejné tělo JSON: ID události, firmu a událost s jejím typem, razítkovou kartou, razítky před a po, částkou nákupu, ID objednávky a external_id, které integrace odeslala, loginem zaměstnance, který ji obsloužil, poukazy a odměnami, které dala, a jménem, e-mailem, Telegram, telefonem WhatsApp a datem narození kupujícího.
amount je částka nákupu v nejmenších jednotkách měny (centech): částka 12.50 odeslaná se skenováním dorazí jako 1250. Je prázdná, když událost žádnou částku neměla.
ID události je v těle a v hlavičce X-Webhook-Event-Id. Opakované odeslání stejné události si ponechá své ID, takže příjemce může opakování zahodit. U URL od Make nebo Zapier je událost pod klíčem card_event místo data.
Jaká data o kupujícím webhook nese?
Jméno, e-mail, Telegram, telefon WhatsApp a datum narození, spolu s razítkovou kartou, razítky před a po a vydanými poukazy a odměnami.
V jaké jednotce je amount?
V nejmenších jednotkách měny (centech). Částka 12.50 odeslaná se skenováním dorazí jako 1250; je prázdná, když událost žádnou částku neměla.
Jak se vyhnu zpracování stejné události dvakrát?
Použijte ID události, v těle a v hlavičce X-Webhook-Event-Id. Opakované odeslání si ponechá stejné ID.
Proč je v Make událost pod card_event?
U URL od Make nebo Zapier je událost pod klíčem card_event místo data, aby ji jejich aplikace rozlišily.
Podpis
Každé doručení je podepsané. Hlavička X-Webhook-Signature obsahuje časové razítko a HMAC-SHA256 z tohoto časového razítka a nezpracovaného těla, s klíčem v podobě tajného klíče webhooku. Tajný klíč se zobrazuje a přegenerovává na stránce webhooku. Lze přidat i přihlašovací jméno a heslo Basic auth.
Jak ověřím, že webhook opravdu pochází od 7Stamp?
Spočítejte HMAC-SHA256 z časového razítka a nezpracovaného těla s tajným klíčem webhooku a porovnejte ho s hlavičkou X-Webhook-Signature.
Kde najdu tajný klíč webhooku?
Na stránce webhooku, kde ho lze také přegenerovat.
Mohu svůj endpoint chránit heslem?
Ano. K webhooku lze kromě podpisu přidat přihlašovací jméno a heslo Basic auth.
Neúspěšná doručení
Doručení, které do třiceti sekund nedostane odpověď 2xx, se opakuje až desetkrát, přičemž každé čekání je o čtyři sekundy delší než předchozí, takže opakování skončí zhruba do čtyř minut. Odpověď 429 s Retry-After se zopakuje po uplynutí této doby. První selhání události vloží do administrace oznámení.
Po stovce neúspěšných doručení za sebou systém webhook zablokuje a ten už nedostává žádné události. Jeho stránka na to předem upozorní a má tlačítko Odblokovat; jedno úspěšné doručení počítadlo vynuluje.
Stránka každého webhooku má deník jeho doručení s odeslaným požadavkem a přijatou odpovědí. Odeslat znovu pošle stejnou událost znovu, jen tomuto webhooku.
Můj server byl nedostupný. Jsou události ztraceny?
Každé doručení se opakuje až desetkrát během zhruba čtyř minut. Potom otevřete deník webhooku a u potřebných událostí použijte Odeslat znovu.
Proč můj webhook přestal dostávat události?
Po stovce neúspěšných doručení za sebou ho systém zablokuje. Opravte endpoint a na stránce webhooku stiskněte Odblokovat.
Mohu vidět, co bylo mému webhooku odesláno?
Ano. Stránka každého webhooku má deník doručení s odeslaným požadavkem a přijatou odpovědí.
Karta Integrace

Karta Integrace uvádí hotové cesty podle skupin:
- Razítko u pokladny — Poster, Toast, Váš vlastní POS nebo CRM a Nevidíte svůj POS?;
- Fiskální doklady — SmartKasa;
- Automatizace — Make, Zapier a Public Swagger.
Každá dlaždice uvádí, zda potřebuje klíč API. Karta nabízí stejné dlaždice v každé zemi; podle země jsou omezeny jen fiskální účtenky.

Firma s White Label nevidí dlaždice Make, Zapier ani Public Swagger a nenabízí se jí Poster ani návody k nastavení na 7stamp.com.
Které systémy POS jsou připraveny k připojení?
Poster a Toast, jakmile je zapnut pro platformu — do té doby ukazuje Již brzy. Ostatní systémy se připojují přes API, pomocí Váš vlastní POS nebo CRM.
Jsou integrace omezeny podle země?
Ne. Karta nabízí stejné dlaždice v každé zemi. Podle země jsou omezeny jen fiskální účtenky.
Proč nevidím Make a Zapier?
Nezobrazují se firmě s White Label. Její klíče API a webhooky fungují stejně.
Poster
Poster je naše aplikace v tržišti Poster. Instalovat v Poster otevře její stránku a aplikace se nastavuje klíčem API loginu zaměstnance. Její razítka se počítají jako Card Operations tohoto loginu zaměstnance.
Jak připojím Poster?
Otevřete Integrace → Poster a zvolte Instalovat v Poster. Aplikace se nastavuje klíčem API loginu zaměstnance.
Čí Card Operations spotřebovávají razítka z Poster?
Ty loginu zaměstnance, jehož klíč API aplikace používá.
Potřebuji pro Poster klíč API?
Ano, klíč API loginu zaměstnance.
Toast
Toast ukazuje Již brzy pro každou firmu, dokud není na platformě nastaven přístup k Toast. Je to jeden přepínač pro celou platformu, ne nastavení firmy; jakmile je zapnutý, dlaždice Toast obsahuje samotné nastavení.
Každá provozovna Toast se připojuje svým GUID k jednomu loginu zaměstnance, bez klíče API: firma, razítková karta a plán tohoto loginu zaměstnance platí pro každý požadavek Toast z provozovny. Provozovnu lze připojit jen k jednomu loginu zaměstnance a login zaměstnance má jednu provozovnu. Požadavky z provozovny jsou odmítnuty, jakmile je odpojena, nebo dokud je její login zaměstnance vypnutý či smazaný.
Každému poukazu lze přiřadit produkt z menu Toast: na POS Toast se pak stane slevou na tento produkt. Poukaz bez produktu se uplatní jako nulová sleva na účet a pokladní předá dárek ručně. Poukazy se uplatňují na POS Toast a kolo, kterého bylo dosaženo zaplaceným účtem, se roztočí okamžitě. Když Toast vrátí transakci, její razítka se odeberou nebo se její uplatněné poukazy obnoví.
Host se může připojit na kiosku Toast nebo na obrazovce pro hosty telefonním číslem nebo e-mailem. Razítková karta se vydá okamžitě; host od 7Stamp nic nedostane, dokud ji neotevře se stejným telefonem nebo e-mailem.
Proč Toast ukazuje Již brzy?
Přístup k Toast je jeden přepínač pro celou platformu, ne nastavení vaší firmy. Dokud není zapnutý, není co připojit.
Jak se připojuje provozovna Toast?
Svým GUID k jednomu loginu zaměstnance, bez klíče API. Razítková karta a plán tohoto loginu zaměstnance platí pro každý požadavek z provozovny.
Co se stane s razítky, když Toast stornuje účet?
Když Toast vrátí transakci, její razítka se odeberou nebo se její uplatněné poukazy obnoví.
SmartKasa

SmartKasa nepotřebuje klíč API. Je to zdroj účtenek ve Skenování účtenek, přidaný podle ID prodejny SmartKasa nebo podle kódu společnosti, aby pokryl všechny prodejny. Kupující skenují účtenku SmartKasa v chatbotovi firmy a razítka jdou na login zaměstnance daného zdroje účtenek.
SmartKasa je ukrajinská a fiskální účtenky fungují jen na Ukrajině, na Slovensku, v Kazachstánu a v Uzbekistánu.
Potřebuji pro SmartKasa klíč API?
Ne. SmartKasa je zdroj účtenek ve Skenování účtenek, přidaný podle ID prodejny nebo podle kódu společnosti.
Kde kupující skenují účtenku SmartKasa?
V chatbotovi vaší firmy. Razítka jdou na login zaměstnance daného zdroje účtenek.
Ve kterých zemích fiskální účtenky fungují?
Na Ukrajině, na Slovensku, v Kazachstánu a v Uzbekistánu.
Make a Zapier

Aplikace 7Stamp pro Make je ve veřejném katalogu aplikací Make: vyhledejte 7Stamp v libovolném scénáři Make, nebo na kartě Integrace použijte „Použijte 7Stamp na Make“. Naše aplikace pro Zapier není ve veřejném katalogu Zapier: „Použijte 7Stamp na Zapieru“ je pozvánka, která přidá aplikaci do vlastního účtu firmy v Zapier. Obě aplikace pracují s klíčem API loginu zaměstnance.
Scénáře Make a Zapy spouštějí webhooky 7Stamp, takže triggery vyžadují doplněk Webhooks & Events. Akce jako přidání razítek nebo vydání poukazu potřebují jen klíč API. Make a Zapier se firmě s White Label nenabízejí.
Kde najdu aplikaci 7Stamp v Make a Zapier?
V Make vyhledejte 7Stamp v libovolném scénáři — aplikace je ve veřejném katalogu aplikací Make. V Zapier zatím veřejná není, proto na kartě Integrace použijte „Použijte 7Stamp na Zapieru“ — pozvánka přidá aplikaci do vašeho vlastního účtu.
Potřebují Make a Zapier doplněk Webhooks & Events?
Triggery ano, protože scénáře a Zapy spouštějí webhooky 7Stamp. Akce jako přidání razítek nebo vydání poukazu potřebují jen klíč API.
Potřebuji pro Make nebo Zapier klíč API?
Ano. Aplikace pracují s klíčem API loginu zaměstnance.