Контракты
Два контракта, один смысл
Запись — пять операций о фактах. Чтение — кабинет партнёра по токену. Первоисточники лежат в репозиториях, здесь только карта.
Факты
| Операция | Когда вызывается |
|---|---|
claim | клиент зарегистрировался по коду партнёра |
member | участник появился и известно, от кого он |
order | клиент оплатил |
refund | клиенту вернули деньги |
partner-link | нужна ссылка партнёра |
Правило одно и главное: eventId уникален навсегда, повтор с тем же идентификатором не должен давать второе начисление.
Схема и правила:spec/README.md, сама схема — spec/partna-facts.v1.json.
Чтение кабинета
GET /v1/portal/me, /me/invited,/me/payouts — по заголовкуAuthorization: Bearer <токен>, без cookie и без ключа тенанта. Поэтому кабинет работает с любого домена.
Описание полей и кодов ошибок:docs/portal-api.md.
Совместимость
- добавлять необязательные поля и новые операции — можно;
- удалять и переименовывать поля, менять смысл сумм и единицы — нельзя;
- суммы всегда в минорных единицах:
500000— это 5 000,00 ₽; - лишние поля в ответах сохраняются: клиент обязан их игнорировать.
Как это держится
Схема фактов генерируется из обработчиков моста, а не пишется руками: расхождение видно в пайплайне. Одинаковые примеры — golden-кейсы — гоняют и HTTP-, и локальный адаптер, чтобы две реализации не разъехались.