Создание заказов

3.1.3. Создание заказов#

На этой странице собрана вся документация к видеоуроку, в котором рассказывается о создании простого заказа через API и проверке его статуса.

3.1.3.1. Видео#

3.1.3.2. Требования#

Требуется для этой серии уроков:

  • Бэкэнд для торговых предприятий Taler
    Если вам нужна помощь в использовании бэкенда торговца в первый раз, вы можете посмотреть учебник Taler merchant introduction.
  • Экземпляр кошелька Taler
    Инструкции по настройке доступны на сайте https://wallet.taler.net.
  • Знание программного обеспечения для управления REST API или соответствующие навыки программирования
    В этой серии видео мы будем использовать бесплатное программное обеспечение Insomnia, доступное для загрузки на сайте https://insomnia.rest.

3.1.3.3. Уведомление о демонстрационном бэкэнде#

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

3.1.3.4. Обработка торговых платежей#

  1. Создание заказа на оплату

Платежи в Taler осуществляются на основе заказа, который представляет собой машиночитаемое описание бизнес-операции, за которую должен быть произведен платеж. Прежде чем принимать платежи в Taler в качестве продавца, вы должны создать такой заказ.

Это делается путем отправки JSON-объекта в конечную точку API бэкенда /private/orders. Внутри поля order должны быть указаны как минимум следующие поля:

  • сумма: Сумма к оплате, в виде строки в формате CURRENCY:DECIMAL_VALUE, например EUR:10 для 10 евро или KUDOS:1.5 для 1.5 KUDOS.

  • ummary: Человекочитаемое резюме о том, что представляет собой платеж. Резюме должно быть достаточно коротким, чтобы поместиться в заголовки, хотя жестких ограничений нет.

  • fulfillment_url: URL-адрес, который будет отображаться после завершения платежа. Для цифровых товаров это должна быть страница, на которой отображается купленный товар. При успешной оплате кошелек автоматически добавляет order_id в качестве параметра запроса, а также ession_sig для платежей, привязанных к сессии (об этом ниже).

Заказы могут содержать гораздо больше полей, см. раздел Формат заказа Taler. При размещении заказа вы можете указать дополнительные детали, такие как переопределение срока возврата и инструкции по управлению запасами. Они требуются редко и не рассматриваются в этом руководстве; за подробностями обращайтесь к справочному руководству.

Минимальный фрагмент Python для создания заказа будет выглядеть следующим образом:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Бэкэнд заполнит некоторые детали, отсутствующие в заказе, например, адрес инстанса продавца. Полная информация называется условиями договора.

Примечание

В приведенном выше запросе отключено использование токенов требований путем установки опции create_token в значение false. Если вам нужны токены утверждений, вы должны изменить код для построения URI taler://pay/, приведенного ниже, чтобы включить токен утверждения.

После успешного POST запроса к /private/orders будет возвращен JSON, содержащий только поле order_id со строкой, представляющей ID заказа. Если вы также получите токен утверждения, проверьте, что вы использовали запрос, как описано выше.

Вместе с инстансом торговца, идентификатор заказа однозначно идентифицирует заказ в бэкенде торговца. Используя идентификатор заказа, вы можете тривиально построить соответствующий URI taler://pay/, который должен быть предоставлен кошельку. Пусть example.com - это доменное имя, к которому доступны публичные конечные точки экземпляра. Тогда URI оплаты Taler - это просто taler://pay/example.com/$ORDER_ID/, где $ORDER_ID должен быть заменен на ID возвращенного ордера.

Вы можете поместить URI taler:// в качестве целевой ссылки, чтобы открыть кошелек Taler через схему taler://, или поместить его в QR-код. Однако для веб-магазина проще всего просто перенаправить браузер на страницу https://example.com/orders/$ORDER_ID. На этой странице будет запущен кошелек Taler. Здесь бэкэнд генерирует правильную логику для запуска кошелька, поддерживая различные типы существующих кошельков Taler. Вместо того чтобы создавать указанный выше URL вручную, его также можно получить, проверив статус платежа, как описано в следующем разделе.

При ручном создании этого URL убедитесь, что вы указали токен утверждения (если он не был отключен) и если бэкэнд работает без TLS, используйте taler+http:// (обратите внимание, что последнее поддерживается только кошельками, работающими в режиме отладки).

Примечание

Тривиальный способ получить правильный payment_redirect_url - проверить статус платежа (см. ниже). Так что если вы все еще не знаете, как его построить, вы можете просто попросить бэкенд сделать это за вас. Однако в продакшене вам, вероятно, стоит создать его вручную и избежать лишних запросов к бэкенду.

  1. Проверка статуса платежа и запрос на оплату

Учитывая идентификатор заказа, статус платежа можно проверить с помощью конечной точки /private/orders/$ORDER_ID. Если платеж еще не завершен клиентом, /private/orders/$ORDER_ID передаст фронтенду URL (под именем payment_redirect_url), который запустит кошелек клиента для выполнения платежа. По сути, это URL https://example.com/orders/$ORDER_ID, о котором мы говорили выше.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Если поле order_status в ответе имеет значение paid, вы не получите payment_redirect_url, а вместо этого получите информацию о статусе платежа, включая:

  • contract_terms: Полные условия контракта по заказу.

  • refunded: true, если за эту покупку был произведен (возможно, частичный) возврат средств.

  • Возвращенная_сумма: Сумма, которая была возвращена

После того как фронтенд подтвердил, что платеж прошел успешно, ему обычно нужно запустить бизнес-логику для продавца, чтобы выполнить его обязательства по договору.

Примечание

Вам не нужно постоянно делать запросы, чтобы заметить изменения в статусе транзакции заказа. Конечные точки поддерживают длительный опрос, просто укажите в параметре запроса timeout_ms, сколько времени вы хотите ждать, пока статус заказа не изменится на paid.

3.1.3.5. Другие учебники#

Для просмотра дополнительных руководств вы можете просмотреть этот сайт или зайти на https://docs.taler.net, чтобы получить самую свежую документацию по сервисам Taler.