Використання API Passtastic | Passtastic Help
Passtastic
Explore
Product
Loyalty app
Pricing
Use Cases
Customer Stories
Help
No account yet? Sign up free

Використання API Passtastic

Що дає вам API

API Passtastic підключає ваші власні системи — індивідуальну POS-систему, CRM, внутрішній застосунок — безпосередньо до вашої програми лояльності. За його допомогою ви можете:

  • Реєструвати клієнтів і видавати картки wallet зі свого власного процесу реєстрації
  • Додавати штампи чи бали та перевіряти баланс клієнта зі своєї каси чи бек-офісу
  • Отримувати сповіщення в реальному часі за допомогою вебхуків — замість постійних запитів до API, Passtastic одразу надсилає подію у вашу систему в момент, коли щось відбувається (клієнт реєструється, нагороду використано, і не тільки)
  • Використовувати клієнтів, яких ви вже маєте — якщо когось, кого реєструє ваша система, вже зареєстровано через вашу сторінку реєстрації, Passtastic розпізнає цю особу за електронною поштою чи телефоном і додає ваш референс до картки, яку вона вже має, замість видачі другої

Це рішення для бізнесів, які створюють індивідуальну інтеграцію. Якщо вам потрібне просто готове підключення, перегляньте Підключіть Square POS або POS-системи та інтеграції — без написання коду.

Доступ до API входить до пакета Підключіть касову систему. Пакет ввімкнений на час 14-денного безкоштовного пробного періоду й оплачується за кожну локацію; див. Ціни. Без пакета розділ API та вебхуки в Налаштуваннях підкаже, як його додати.

Створіть API-ключ

1. Відкрийте Налаштування, потім API та вебхуки (у розділі Бізнес).

2. На вкладці API-ключі натисніть Створити тестовий ключ, щоб спробувати без ризику, або Створити робочий ключ, коли будете готові підключити реальних клієнтів.

3. Вкажіть назву ключа, щоб пізніше знати, для чого він (напр. «продакшн CRM»).

4. Ваш новий ключ буде показано один раз, у вікні Ваш новий API-ключ (для тестового ключа — Ваш новий тестовий ключ). Скопіюйте його зараз — повторно побачити його буде неможливо. Натисніть Скопіювати або Показати, щоб спершу переглянути його.

Ставтеся до цього ключа як до пароля. Будь-хто, хто його має, може діяти від імені вашого акаунта через API.

5. Зберігайте ключ у безпечному місці у своїй системі (змінна середовища, менеджер секретів) і надсилайте його як заголовок автентифікації з кожним запитом — точний формат наведено в технічній документації нижче.

Створювати або відкликати API-ключі можуть лише адміністратори.

Спочатку спробуйте з тестовим ключем

Тестові ключі працюють на будь-якому тарифі, зокрема під час пробного періоду — оновлення тарифу не потрібне. Тестові клієнти отримують справжню картку wallet із позначкою TEST і автоматично видаляються через 30 днів — прибирати вручну нічого не потрібно.

Пройдіть Quickstart у технічній документації з вашим тестовим ключем — він покроково показує, як зареєструвати тестового клієнта і додати картку на власний телефон, ще до того, як буде залучено жодного реального клієнта.

Коли ваша інтеграція запрацює від початку до кінця, поверніться до API та вебхуки і натисніть Створити робочий ключ, щоб перейти на реальних клієнтів. Робочі ключі входять до пакета Підключіть касову систему.

Загубили ключ або підозрюєте витік?

Ключі повторно не показуються після створення. Якщо ви загубили ключ або підозрюєте, що він став відомий стороннім, відкрийте API-ключі та натисніть біля нього Відкликати — це одразу зупинить його дію — а потім створіть новий і оновіть свою інтеграцію.

Налаштуйте вебхук

Вебхуки дозволяють вашій системі реагувати в момент, коли щось відбувається у Passtastic, без потреби постійно опитувати API.

1. На вкладці Вебхуки натисніть Додати ендпоінт.

2. Введіть URL ендпоінту — адресу у вашій власній системі, яка отримає подію (напр. `https://ваша-система.com/hook`).

3. У розділі Події оберіть, які події отримувати:

  • Клієнта зареєстровано
  • Баланс оновлено
  • Рівень змінено
  • Нагороду використано
  • Картку прострочено
  • Картку поновлено

4. Збережіть. Ваш секрет підпису буде показано один раз, у вікні Секрет підпису — скопіюйте його зараз. Використовуйте його, щоб перевірити, що запит вебхука дійсно надійшов від Passtastic (технічна документація пояснює, як перевірити підпис).

Створювати або редагувати вебхуки можуть лише адміністратори.

Кожен ендпоінт вебхука показує свої останні доставки, тож ви можете перевірити, чи виклик пройшов успішно, чи ні, і повторити невдалу доставку, щойно ваша система знову запрацює, не чекаючи наступної події.

Редагування або вимкнення вебхука

Відкрийте ендпоінт і натисніть Редагувати, щоб змінити URL або події, або встановіть статус Вимкнено, щоб призупинити доставки, не видаляючи його. Натисніть Видалити, щоб прибрати його остаточно.

Де знайти повну технічну документацію

Цей посібник охоплює частину роботи в панелі — створення ключів і вебхуків. Ендпоінти, формати запитів/відповідей, заголовки автентифікації, коди помилок і приклади коду шукайте в повній документації API, або перейдіть одразу до довідника API, щоб побачити схему запиту/відповіді кожного ендпоінта. Ви також можете відкрити обидва посилання будь-коли — Читати документацію API і Довідник API — вгорі сторінки API та вебхуки: довідник API відкривається в новій вкладці.

Поширені запитання

Чи потрібна мені POS-система, щоб користуватися API?
Ні. API призначений для підключення ваших власних систем — індивідуальної POS-системи, CRM або застосунку. Якщо ви віддаєте перевагу готовому підключенню, перегляньте Підключіть Square POS або POS-системи та інтеграції.
Чи створить моя інтеграція дублікати клієнтів?
Ні. Коли ваша система реєструє когось, Passtastic спершу перевіряє, чи цей клієнт вже існує у вашому акаунті — за референсом, який надсилає ваша система, потім за електронною поштою, потім за телефоном. Якщо так, вона пов'язує ваш референс із наявною карткою замість видачі другої, тож штампи й бали цього клієнта залишаються на місці. Якщо два клієнти мають однакову електронну пошту чи телефон, Passtastic не намагається вгадати між ними — вона повертає помилку, що називає обох, і ваш розробник зможе вибрати потрібного.
Чи може моя система дізнатися, коли закінчується термін дії картки клієнта?
Так. Якщо ваша картка має строк дії (Термін дії картки у розділі Деталі картки на вкладці Налаштування програми), позначте у вебхуку Картку прострочено та Картку поновлено: ваша система дізнається, коли термін дії картки закінчується та коли її поновлюють, зокрема коли ви поновлюєте її в Passtastic. Ваш розробник також може отримати дату закінчення картки кожного клієнта й поновити картку з вашої системи. Щоб випробувати це до того, як закінчиться строк дії справжньої картки, тестовий ключ може одразу завершити строк дії картки тестового клієнта. Подробиці — у документації API.
Чи включено доступ до API у мій план?
Так, з пакетом Підключіть касову систему: API, вебхуки та робочі ключі входять до нього. Пакет ввімкнений на час 14-денного безкоштовного пробного періоду й оплачується за кожну локацію; див. Ціни. Без пакета API та вебхуки показує API для розробників з кнопкою Додати за. Якщо ви приберете пакет, API та вебхуки буде призупинено, а нічого не видаляється. Ви на попередньому плані? Ваш план зберігає те, що входило; див. Плани, ліміти та як оновити підписку. Тестові ключі працюють на кожному плані.
Де знайти ID картки?
Відкрийте вкладку Поділитися програми. У розділі Поділитися в Соціальних Мережах або на Сайті ви побачите її посилання: частина після `/get-pass/` — це ID картки. Не копіюйте ID з адреси сторінки програми, бо він може бути іншим. Ваш розробник також може отримати список усіх ваших карток та їхніх ID через API (`GET /api/v1/cards`).
Мій розробник отримує «Missing scope(s): cards:read». Що робити?
Ключ створено ще до того, як API навчився показувати список карток. Створіть новий ключ (API-ключі → Створити ключ), передайте його розробнику, а потім відкличте старий кнопкою Відкликати.
Хто може керувати API-ключами та вебхуками?
Лише адміністратори. Редактори та переглядачі не побачать можливості створити, редагувати чи відкликати ключ або вебхук.
Чи можу я мати більше одного API-ключа?
Так — створюйте окремий ключ для кожної системи чи середовища (напр. один для CRM, інший для тестового середовища), щоб мати змогу відкликати один без впливу на інші.
Вебхук перестав отримувати події — що сталося?
Відкрийте ендпоінт і перевірте останні доставки, щоб дізнатися причину збою (напр. ваш сервер повернув помилку або перевищив час очікування). Виправте проблему на своєму боці, а потім натисніть Повторити біля невдалої доставки, щоб надіслати її ще раз.