3.1.1. Огляд інстанцій#

3.1.1.1. Про цей підручник#

У цьому підручнику описано, як обробляти платежі за допомогою внутрішнього інтерфейсу GNU Taler. Аудиторією цього підручника є розробники торговельних підприємств (наприклад, веб-магазинів), які працюють над інтеграцією GNU Taler з інтерфейсом користувача і бек-офісом, що працює з персоналом.

У цьому розділі пояснюються деякі базові поняття. У другому розділі ви дізнаєтеся, як здійснювати основні платежі.

Ця версія підручника містить приклади для Python3. Вона використовує бібліотеку requests для HTTP-запитів. Також доступні версії для інших мов/середовищ.

Якщо ви хочете подивитися на прості, працюючі приклади, перегляньте ці:

  • Торговець есеями <https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/blog>, який продає окремі розділи книги.

  • Сторінка пожертви, яка приймає пожертви на програмні проекти та видає квитанції про пожертви.

  • Плагін WooCommerce, який є комплексною інтеграцією у веб-магазин, включаючи бізнес-процес повернення коштів.

3.1.1.2. Огляд архітектури#

Стек програмного забезпечення Taler для торговця складається з таких основних компонентів:

  • Фронтенд, який взаємодіє з браузером клієнта. Фронтенд дозволяє клієнту створити кошик і оформити замовлення. Після оплати він запускає відповідну бізнес-логіку для виконання замовлення. Цей компонент не входить до складу Taler, але передбачається, що він існує у продавця. Цей підручник описує, як розробити фронтенд для Taler.

  • Платіжний бекенд, специфічний для Талера, який полегшує фронтенду обробку фінансових транзакцій з Талером. У цьому посібнику ви будете використовувати загальнодоступний бекенд у пісочниці. Для промислового використання ви повинні або створити власний бекенд, або попросити когось зробити це за вас.

Наступне зображення ілюструє різні взаємодії цих ключових компонентів:

../../_images/arch-api.png

Бекенд забезпечує підтримку криптографічного протоколу, зберігає специфічну для Талера фінансову інформацію та взаємодіє з біржею GNU Taler через Інтернет. Фронтенд отримує доступ до бекенду через RESTful API. В результаті, фронтенд ніколи не повинен безпосередньо спілкуватися з біржею, а також не має справи з конфіденційними даними. Зокрема, ключі підпису продавця та інформація про банківські рахунки інкапсульовані в бекенді Taler.

Деяка функціональність бекенду («публічний інтерфейс») доступна безпосередньо браузеру клієнта. У HTTP API всі приватні кінцеві точки (для бек-офісу) мають префікс /private/. Цей підручник зосереджується на кінцевих точках /private/. Публічний інтерфейс використовується безпосередньо гаманцем і не має відношення до продавця (за винятком того, що API має бути відкритим).

3.1.1.3. Бекенд публічної пісочниці та автентифікація#

Те, як фронтенд аутентифікується в бекенді Taler, залежить від конфігурації. Дивіться Руководство оператора бекенда торговельного терміналу.

Бекенд публічної пісочниці https://backend.demo.taler.net/instances/sandbox/ використовує ключ API в заголовку Authorization. Значення цього заголовка має бути Bearer secret-token:sandbox для публічного бекенду пісочниці.

>>> import requests
>>> requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders",
...              headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Якщо повертається код статусу HTTP, відмінний від 200, це означає, що щось пішло не так. Вам слід з’ясувати, в чому проблема, перш ніж продовжувати роботу з цим підручником.

Бекенд пісочниці https://backend.demo.taler.net/instances/sandbox/ використовує KUDOS як уявну валюту. Монети, деноміновані в KUDOS, можна виводити з https://bank.demo.taler.net/.

3.1.1.4. Торговельні екземпляри#

Один сервер внутрішнього інтерфейсу продавця Taler може використовуватися декількома продавцями, які є окремими бізнес-суб’єктами. Кожному з цих окремих суб’єктів господарювання призначається екземпляр продавця, який ідентифікується за допомогою алфавітно-цифрового ідентифікатора екземпляра. Якщо ідентифікатор екземпляра не вказано, буде використано ідентифікатор admin.

На сайті https://backend.demo.taler.net/ налаштовані наступні екземпляри мерчантів:

Примітка

Це вигадані торговці, які використовуються для наших демонстрацій і не пов’язані з відповідними проектами і не схвалені ними офіційно.

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

3.1.1.5. Відеоуроки#

На цій сторінці міститься вся документація до відеоуроку, що знайомить з API продавця Taler.

3.1.1.5.1. Відео#

3.1.1.5.2. Вимоги#

Необхідно для цієї серії уроків:

  • Бекенд торговця Талером
    Для зручності ми рекомендуємо використовувати https://backend.demo.taler.net/instances/sandbox/.
  • Примірник гаманця Taler
    Інструкції з налаштування доступні на сайті https://wallet.taler.net, хоча вони не є обов’язковими для цього посібника.
  • Програмне забезпечення для управління REST API або відповідні навички програмування
    У цій серії відео ми будемо використовувати безкоштовне програмне забезпечення Insomnia, яке можна завантажити за посиланням https://insomnia.rest.
    Як вступ, це відео покаже, як експортувати робочий код з підготовлених запитів в Insomnia на Python (або будь-якій іншій підтримуваній мові) і виконати їх, але це не буде продемонстровано в наступних уроках.

3.1.1.5.3. Повідомлення про демонстраційний бекенд#

Для цього посібника ми наполегливо рекомендуємо використовувати демо-сервіс для продавців Taler https://backend.demo.taler.net/instances/sandbox/.

Ключ доступу: sandbox.

3.1.1.5.4. Інформація про секретний токен#

Секретний токен відповідає документу RFC 8959. Ви можете дізнатися більше про нього тут: https://datatracker.ietf.org/doc/html/rfc8959. Майте на увазі, що це токен на пред’явника, і в заголовку авторизації потрібно вказати його.

Ваш заголовок авторизації повинен виглядати так:
Авторизація: Секретний токен пред’явника:<ключ доступу>

3.1.1.5.5. Більше навчальних посібників#

Щоб переглянути додаткові навчальні матеріали, ви можете переглянути цей сайт або перейти на https://docs.taler.net, щоб отримати найновішу документацію про сервіси Taler.