Публичный контракт интеграции

CircleLoyal Partners API

Один проверяемый протокол для начислений, списаний, Circle ID и ежедневных recap-сценариев. Начинаем в shadow-режиме, сверяем события и включаем live только после согласованных лимитов.

Схема подписи Проверить подпись Пример события OpenAPI JSON

Статус запуска

Партнёр видит, что уже готово, а что подключается через пилот

Это публичная карта готовности: она снижает риск неверных ожиданий и помогает технической команде партнёра быстро понять следующий шаг.

stable

Публичный контракт

Страница API, OpenAPI JSON, HMAC-заголовки, canonical payload и privacy-ограничения готовы для технической оценки.

stable

Локальная проверка подписи

Sandbox считает hash, payload и подпись в браузере, а server verifier сверяет публичный test vector без боевых секретов.

pilot

Shadow-интеграция

Первые партнёры подключаются через ручное согласование сценария, отдельный ключ, лимиты и сверку duplicate/replay.

planned

Self-serve кабинет

Автоматическая заявка, выдача тестовых ключей, changelog-подписка и статус live-окружения остаются следующим этапом.

Подпись запроса

Каждый запрос подписывается сервером партнёра

Секрет хранится только на backend-стороне партнёра. В браузер, чат, query string и клиентский JavaScript он не попадает.

X-Circle-Key-Id

идентификатор активного ключа партнёра

X-Circle-Timestamp

Unix-время в секундах; окно проверки — 5 минут

X-Circle-Nonce

одноразовая строка 16–100 символов, защищает от replay

Idempotency-Key

стабильный ключ операции; повтор с другим payload вернёт конфликт

X-Circle-Mode

shadow для сверки без боевого эффекта или live для включённого контура

X-Circle-Signature

v1=base64url(HMAC-SHA256(secret, canonicalPayload))

Canonical payload

METHOD
/v1/partners/shelterz/events
1736539200
nonce-4cbb33a5b1f24f0c
booking-stay-completed:stz-94817
sha256(rawBodyHex)

Подпись

X-Circle-Signature: v1=base64url(
  HMAC_SHA256(partnerSecret, canonicalPayload)
)

Локальный sandbox подписи

Проверьте canonical payload до подключения backend

Это демонстрационный расчёт в браузере: данные не отправляются на CircleLoyal, не сохраняются в хранилище сайта и не попадают в URL. Используйте только тестовый секрет.

МетодTimestamp

Request target

NonceIdempotency-Key

Тестовый секретRaw body

Расчёт выполняется только в вашем браузере. Не вводите боевой секрет.

Результат

SHA-256 body—Canonical payload

Нажмите «Рассчитать подпись»

X-Circle-Signature—

Signature test vector

Эталон для backend-команды партнёра

Если партнёрский сервер считает тот же hash и `X-Circle-Signature` на этих тестовых данных, базовая HMAC-реализация совпадает с контрактом CircleLoyal. Это не боевой ключ и не доступ к API.

Входные данные

method: POST
requestTarget: /v1/partners/shelterz/events
timestamp: 1736539200
nonce: nonce-4cbb33a5b1f24f0c
Idempotency-Key: booking-stay-completed:stz-demo
test signing key: circleloyal-demo-signing-key
raw body: {"ok":true}

Canonical payload

POST
/v1/partners/shelterz/events
1736539200
nonce-4cbb33a5b1f24f0c
booking-stay-completed:stz-demo
4062edaf750fb8074e7e83e0c9028c94e32468a8b6f1614774328ef045150f93

Ожидаемый результат

sha256(rawBody): 4062edaf750fb8074e7e83e0c9028c94e32468a8b6f1614774328ef045150f93
X-Circle-Signature: v1=EP98y55_1CtXBuqxnNr6eK0S3LqWEwQfr9mksGcI74Y

Server verifier

Отправьте те же поля и свою подпись. Endpoint не принимает боевые секреты и не связан с live-ключами партнёров.

method: POST
url: /api/partners/signature-test
success: { "verified": true }

Endpoints

Минимальный набор для пилота

Публичная документация показывает контур. Боевой набор методов и ключей выдаётся только после согласованного пилота и проверки безопасности.

POST/v1/partners/{partner}/events

События начислений и статусов

Бронирование, завершённое проживание, отмена, возврат или одобренное задание. Сервер сохраняет событие в inbox и возвращает duplicate только при точном повторе payload.

GET/v1/partners/{partner}/accounts/by-external-user/{externalUserId}/projection

Проекция баланса пользователя

Партнёр получает только связанную проекцию Circle: баланс, уровень и безопасные статусы, без паролей и платёжных данных.

POST/v1/partners/shelterz/redemptions/{quote|reserve|apply|release|refund}

Списание и возврат CIRCLE

Контур бронирования поддерживает предварительный расчёт, резерв, применение, освобождение и возврат с идемпотентностью и TTL резерва.

GET/v1/partners/{partner}/accounts/by-external-user/{externalUserId}/daily-recap

Краткий итог дня

Показывает пользователю понятный итог начислений, прогресса и следующих действий внутри партнёрского сервиса.

Пример события

Событие описывает факт, а не обещание награды

CircleLoyal проверяет схему, подпись, источник, статус, уникальность и правила экономики перед начислением или расчётом.

{
  "schema_version": 1,
  "event_id": "stz_evt_20260911_0001",
  "event_type": "booking.stay_completed",
  "occurred_at": "2026-09-11T09:00:00.000Z",
  "partner_id": "shelterz",
  "subject": {
    "external_user_id": "7421",
    "referral_code": "CIRCLE2026"
  },
  "booking": {
    "external_booking_id": "stz-booking-94817",
    "public_booking_id": "94817",
    "currency": "RUB",
    "gross_amount_minor": 1800000,
    "discount_amount_minor": 0,
    "circle_spent_minor": 0,
    "net_cash_paid_minor": 1800000,
    "arrival_at": "2026-09-08T14:00:00.000Z",
    "departure_at": "2026-09-11T10:00:00.000Z",
    "location": {
      "city_name": "Москва",
      "country_code": "RU"
    }
  },
  "facts": {
    "payment_status": "settled",
    "stay_status": "completed"
  },
  "supersedes_event_id": null
}

Shadow → live

Порядок запуска

Выбираем один сценарий: начисление, списание, SSO или ежедневный recap.
Выдаём отдельный ключ и включаем shadow-режим для сверки без влияния на баланс.
Проверяем подписи, nonce, idempotency, повторы, отмены, возвраты и ошибки сети.
Фиксируем KPI и лимиты, затем включаем live только для согласованной аудитории.

Минимизация данных

Что нельзя отправлять

пароли, reset-токены и одноразовые коды пользователя
полные номера карт, CVV, банковские реквизиты и платёжные токены
лишние паспортные данные, адреса и контактные поля, не нужные для события
API-секреты в чатах, URL, логах браузера или клиентском JavaScript

Integration checklist

Что партнёр готовит до первого shadow-запуска

Выбрать один measurable-сценарий: начисление за факт, SSO, списание CIRCLE или daily recap.
Согласовать минимальный payload без лишних персональных данных и без платёжных секретов.
Подписывать запросы только backend-сервером партнёра; клиентский JavaScript не хранит ключи.
Проверить timestamp, nonce, idempotency, повтор payload, конфликт payload и сетевой retry.
Запустить shadow-режим на ограниченной аудитории и сравнить отчёты до включения live.

API changelog

Последние изменения контракта

2026-09-11-r323Server verifier для test vectorДобавлен публичный endpoint /api/partners/signature-test: он проверяет только тестовую подпись и запрещает secret/token/password поля.

2026-09-11-r322Эталон подписи для backendДобавлен фиксированный HMAC test vector: входные данные, sha256(rawBody), canonical payload и ожидаемый X-Circle-Signature.

2026-09-11-r321Статус API, checklist и changelogСтраница теперь явно показывает, какие части партнёрского контура готовы, какие идут через pilot и что ещё не заявлено как self-serve.

2026-09-11-r320Локальный sandbox подписиДобавлен расчёт SHA-256, canonical payload и X-Circle-Signature без сетевых запросов и без сохранения секретов.

2026-09-11-r319OpenAPI 3.1Опубликован машинно-читаемый контракт для событий, проекций аккаунта, recap и списаний CIRCLE.

Готовы сверить первый сценарий?

Начните с одного события и измеримого KPI

Собрать заявку на пилот