YUNIT SL
YUNIT SL
Senior Hands on Delivery
English Deutsch Català Русский

Merchant integration guide

Интеграция для merchants

Технический обзор для merchants, использующих YUNIT как identity provider, consent manager и PII vault для разовых выдач клиентских данных.

Открыть портал Обзор для consumer

Prerequisites для onboarding merchant

  • Каждый merchant работает в собственном tenant и получает OAuth-клиент для backend-сервиса или middleware POS.
  • Merchant должен зарегистрировать redirect URI, callback endpoints и операционные контакты до начала тестов или production rollout.
  • Доступные scopes заранее определяются политикой, чтобы merchant не мог запрашивать поля вне разрешённого каталога.

Каталог scopes и модель запроса

Запрос согласия включает merchant, терминал или исходный канал, деловую цель и точный список запрашиваемых полей. Модель построена так, чтобы клиент видел понятный и конкретный запрос.

Поля обрабатываются как заранее определённые scopes, например `name`, `billing_address` и `tax_number`, а ответ содержит только те значения, которые были одобрены в рамках данного запроса.

Жизненный цикл запроса согласия

  • POS создаёт запрос, связывает его с текущей операцией и ожидает разрешения статуса согласия.
  • Сканирование QR-кода Wallet разрешает consumer token, после чего YUNIT запускает OTP-подтверждение и экран одобрения.
  • После разрешения merchant получает краткоживущий authorization code, который обменивается на access token для чтения одобренных данных.
  • Если клиент отказал, если запрос истёк или если токен больше не действителен, запрос завершается без данных, и POS должен создать новый запрос.

Поведение callback, polling и expiry

Для надёжности POS интеграция может сочетать серверный callback и polling статуса, пока касса ждёт исход. Это уменьшает зависимость от одного механизма доставки.

Запросы имеют короткое время жизни, authorization codes тоже быстро истекают, а access tokens должны жить ровно столько, чтобы завершить непосредственное чтение данных.

Ожидания по безопасности и аудиту

  • Backend merchant должен логировать запрос, исход и деловую цель, не сохраняя больше персональных данных, чем действительно необходимо.
  • Redirect URI и OAuth credentials нужно вести по окружениям, с ротацией и операционными контролями поддержки.
  • Любые поля, возвращённые YUNIT, должны трактоваться как данные для этой конкретной транзакции, а не как постоянный доступ для будущих обращений.
  • Операционные команды должны уметь показать, зачем был запрошен каждый scope и как обрабатывались истёкшие или отклонённые запросы.

Последовательность интеграции merchant

  1. Step 1 Подготовьте tenant merchant, зарегистрируйте redirect URI и выпустите OAuth credentials для backend POS или middleware.
  2. Step 2 Создайте запрос согласия с нужными scopes, ссылкой на цель и контекстом POS-сессии.
  3. Step 3 Отсканируйте QR из Wallet, чтобы YUNIT разрешил wallet token и запустил OTP-подтверждение.
  4. Step 4 Получите краткоживущий authorization code после одобрения и обменяйте его на access token.
  5. Step 5 Считайте только одобренные данные, завершите merchant-операцию и сохраните audit trail запроса.

Пример запроса согласия

curl -H "Authorization: Bearer POS_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/consent-requests \
  -d '{
    "merchant_id": "restaurant-abc",
    "terminal_id": "pos-03",
    "purpose": "Invoice #12345",
    "scopes": ["name", "billing_address", "tax_number"],
    "callback_url": "https://merchant.example.com/yunit/callback"
  }'

Обмен authorization code

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/token \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_req_9f8d",
    "redirect_uri": "https://merchant.example.com/yunit/callback"
  }'

Пример чтения одобренных данных

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET "https://api.yunit.tech/oauth/consent-requests/auth_req_9f8d/data"

Операционные заметки

  • Используйте callback вместе с polling, чтобы POS оставался устойчивым при задержке одного из каналов доставки.
  • Каждое одобрение является разовым consent. Для нового запроса требуется новое одобрение даже для того же merchant.
  • Authorization codes и access tokens должны быть короткоживущими и ограниченными конкретным одобренным запросом.
  • Логи merchant должны хранить request IDs, scopes, purpose references и итоговые статусы без лишнего хранения PII.