Партнёрский API продажи билетов

Как это работает

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

1. Живой инвентарь, а не квота. Вы работаете с теми же местами, что и витрина ДСС. Место, проданное на витрине, исчезает у вас немедленно, и наоборот. Заранее выделенных пачек мест не существует; ДСС остаётся мастер-системой статусов.
2. Доступ выдаётся на мероприятие. Вы видите и продаёте только то, на что ДСС выдала грант. Список меняется на стороне ДСС без правок вашего кода.
3. Деньги у вас. Вы принимаете оплату и сами фискализируете чек. Платёжный шлюз ДСС в этом потоке не участвует; payment_info в подтверждении заказа это факт вашего платежа, который ДСС хранит для сверки. Взаиморасчёт между ДСС и партнёром периодический и идёт вне API.
4. Заказ раньше денег, билеты после подтверждения. Заказ запирает места платёжным окном до списания. После списания вы зовёте confirm и получаете билеты: подписанный qr_token и pdf_url на каждый. Писем покупателю ДСС не отправляет, доставка на вашей стороне.
5. Возврат денег делаете вы. ДСС гасит билеты, погашенный не проходит на вход. В первой фазе возврат оформляется обращением к персоналу ДСС, и место после него в продажу не возвращается; освобождение мест появится вместе с ручкой refund во второй фазе.

Заказ, не получивший ни confirm, ни cancel, истекает сам и возвращает места в продажу. Подвисших билетов без денег не бывает по построению.

Если у вас на руках ТЗ СКУП ДСС

Контракт следует разделу 4.2.14 технического задания заказчика и отличается от него в шести местах, каждое ради покупателя или денег: места отдаются посекторно, а не всем залом одним ответом; успешный ответ обёрнут в {"data": …}; ключи идемпотентности partner_booking_id и partner_order_id обязательны; формула подписи зафиксирована проверочным вектором, а не словами; заказ создаётся до списания, а оплата подтверждается отдельным вызовом; гарантированный канал отмены это опрос, вебхуки подключаются позже как ускоритель.

Быстрый старт

Стенд

https://api-sandbox.dss.ndsvs.kz, только HTTPS; ключ pk_sandbox_… и секрет к нему ДСС выдаёт техническому контакту вместе с датой сертификационной сессии (часть сценариев требует оператора ДСС на связи, дата согласуется отдельно)

Продуктив

https://api-dss.ndsvs.kz/api/v1/partners, ключи pk_live_… после сертификации

Транспорт

HTTPS, TLS 1.2 и выше; JSON в UTF-8; имена полей snake_case

Заголовки

X-Api-Key, X-Timestamp, X-Signature на каждом запросе; Content-Type: application/json на POST

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

Каждый запрос подписывается HMAC-SHA256. Строка для подписи собирается из четырёх частей, разделённых одним символом перевода строки (байт 0x0A):

<timestamp>\n<METHOD>\n<uri>\n<body>

Подпись: HMAC-SHA256(key = secret_key, message = canonical), результат в нижнем регистре hex. Секрет это ключ HMAC, а не часть сообщения.

import hmac, hashlib, json, time

def headers(api_key: str, secret: str, method: str, uri: str, body: bytes = b"") -> dict:
    ts = str(int(time.time()))                      # секунды, не миллисекунды
    canonical = f"{ts}\n{method.upper()}\n{uri}\n".encode() + body
    sig = hmac.new(secret.encode(), canonical, hashlib.sha256).hexdigest()
    return {"X-Api-Key": api_key, "X-Timestamp": ts, "X-Signature": sig}

# тело сериализуется ОДИН раз, и отправляются ровно эти байты
body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()

Отсутствующий X-Api-Key отвечает 401 INVALID_API_KEY; любая другая проблема аутентификации, включая timestamp вне окна, отвечает 401 INVALID_SIGNATURE, а details.reason различает signature_mismatch и timestamp_out_of_window, чтобы чинить часы, а не формулу. Отдельного nonce нет намеренно: каждый изменяющий вызов идемпотентен по вашим ключам (Идемпотентность), поэтому повтор запроса внутри окна воспроизводит тот же результат и нового эффекта не создаёт.

Проверочный вектор

Сойдитесь с ним до первого запроса на стенд: расхождение здесь стоит минуты, расхождение на стенде стоит дня переписки.

secret

sandbox_secret_do_not_use_in_prod

X-Timestamp

1790841600

1790841600\nPOST\n/api/v1/partners/bookings\n{"event_id":32,"partner_booking_id":"TKT-BKG-2026-0009871","seats":["seat-AA-A-03-005","seat-AA-A-03-006"],"customer":{"email":"buyer@ticketon.kz"}}

X-Signature: d2b089654f675c25a6f8e3dacce46f5850c7a5a6c62a8a697fcd92e8fc6c5527

1790841600\nGET\n/api/v1/partners/events?date_from=2026-10-01&limit=50\n

X-Signature: d783761a531da8c84c1e6fba1c048f5ebc6cf8c9ac66fe43a7cf060dd95616ca

POST без тела (cancel)

1790841600\nPOST\n/api/v1/partners/orders/7f0e4c6e-2c3b-4f7a-9a1d-3f4b2c1d0e9a/cancel\n

X-Signature: 9733cdf84a9a9e3f7f430807e8ecd990b072cc7390c3aed08e5f351e032868a6

Чеклист перед первым запросом на стенд

• Обе подписи проверочного вектора сошлись на вашей реализации.
• X-Timestamp десятизначный, берётся из синхронизированных часов.
• Тело сериализуется один раз; подписанные байты и отправленные байты это один буфер.
• Клиент читает X-Request-Id из ответа и пишет его в журнал рядом с телом отказа.
• Таймаут клиента около 10 секунд, повтор с нарастающей задержкой на 5xx и на сетевых ошибках.

Общие правила

Успех

{"data": …}; списки дополнительно несут {"meta": {"total", "limit", "offset"}}

Ошибка

{"error": {"code", "message", "details"}}; ветвиться по code, message писать в журнал, а не показывать покупателю

Деньги

целые тенге без копеек; currency всегда KZT

Время

ISO 8601 со смещением, например 2026-10-05T19:00:00+05:00; площадки в UTC+5, но смещение в ответах любое, чаще +00:00: разбирайте ISO 8601 целиком, не подстрокой

Идентификаторы

seat-AA-A-03-007, sector-AA-A, row-AA-A-03 это непрозрачные строки платформы: не разбирать и не собирать самостоятельно; order_id и ticket_id это UUID-строки, номера вида DSS-2026-001042 остаются для переписки с поддержкой

Трассировка

заголовок X-Request-Id (строка до 64 символов из латиницы, цифр, _ и -; UUID подходит) принимается на любом запросе и возвращается тем же заголовком в каждом ответе, включая ошибки; значение вне формата подменяется серверным; по нему ДСС находит запрос у себя

Пагинация

limit до 100 (по умолчанию 50), offset; при опросе изменений с updated_since ответ полный и пагинация не применяется

Неизвестные поля

в теле запроса отвергаются (422 INVALID_PARAMETERS, поле в details); в ответах могут появляться без предупреждения, клиент обязан их пропускать

Ограничение частоты

По умолчанию 100 запросов в минуту на партнёра; боевое значение договорное и согласуется под онсейл заранее, как и срок брони с платёжным окном. Каждый ответ несёт X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (Unix-секунды). Окно фиксированное, одна минута; X-RateLimit-Reset это начало следующего окна. При превышении 429 RATE_LIMIT_EXCEEDED с заголовком Retry-After; договорной потолок одновременных запросов отвечает тем же кодом.

Рекомендуемая каденция чтений: сводку секторов не чаще раза в 10 секунд на мероприятие; места сектора запрашивать, когда пользователь открывает сектор, а не фоном по всем секторам. Доступность в чтениях справочная, истина только за успешной бронью, поэтому частый опрос точности не добавляет.

Справочник ручек

Девять операций. Восемь доступны в первой фазе, refund появляется во второй. Все пути относительно префикса /api/v1/partners. У любой операции возможны 401 (аутентификация) и 429 (лимит), в таблицах ниже они не повторяются; 403 (ACCESS_DENIED, PARTNER_DISABLED) перечислен там, где он возможен.

Состояния брони и заказа

Идемпотентность и повторы

Каждый изменяющий вызов безопасен к повтору, и ключи это ваши же идентификаторы. Оба идентификатора обязаны существовать до вызова и не меняться при повторах.

Повтор ключа с другим телом это не повтор, а конфликт. «Другое тело» для брони это другой event_id или другое множество seats (порядок не важен), для заказа другой booking_id; customer не сравнивается. Конфликт отвечает 409 IDEMPOTENCY_CONFLICT, в details лежат сохранённое и присланное значения поля.

Восстановление после потери ответа

Если ответ на POST /orders потерян и order_id неизвестен, есть два равноценных пути: повторить POST /orders с тем же partner_order_id (вернётся тот же заказ) или прочитать его через GET /orders?partner_order_id=…. Дальше confirm или cancel по полученному order_id. Терять заказы навсегда в этой схеме негде.

Повторы на ошибках сети и 5xx

Повторяйте с нарастающей задержкой; рекомендуемый таймаут клиента 10 секунд. Поскольку каждый изменяющий вызов идемпотентен, повтор после таймаута не создаёт второй брони и второго заказа. Пишите X-Request-Id из ответа рядом с телом отказа: по нему ДСС находит запрос в своих журналах.

Изменения мероприятий

Гарантированный канал с первого дня: опрос. Опрашивайте GET /events?updated_since=… не реже раза в 5 минут. Именно так доезжают отмена, перенос, закрытие продаж и отзыв доступа, и именно на этом канале лежит ваша обязанность остановить продажу и начать возвраты по отменённому мероприятию.

1. Первый запрос делается без updated_since. Из ответа берётся meta.cursor.
2. Первый проход — одной страницей. Просите limit=100 (максимум контракта) и сверьте число записей в data с meta.total; не совпало — повторите запрос. Листать через offset приходится, только если meta.total больше 100, и тогда помните: каждая страница — отдельный запрос, а список между ними может измениться. Отзыв доступа убирает строку, перенос мероприятия меняет её место в порядке (список упорядочен по starts_at), и мероприятие, которое само НЕ менялось, может оказаться на границе страниц и не попасть ни на одну; раз оно не менялось, опрос с updated_since его тоже не вернёт. Поэтому: курсор берите с ПЕРВОЙ страницы — всё, что изменится во время прохода, придёт следующим опросом; выдачу обрабатывайте как идемпотентное обновление (одно мероприятие может прийти дважды); раз в сутки делайте полный проход и сверяйте набор мероприятий со своим.
3. Каждый следующий запрос передаёт этот курсор в updated_since как есть и берёт новый из ответа. Курсор серверный, непрозрачный и URL-безопасный; собственное время сюда не подставляется, часы двух систем расходятся.
4. С updated_since ответ полный: limit и offset игнорируются. Опрос ведётся без фильтров date_from, venue_id, event_type, иначе перенос мероприятия за пределы фильтра пропал бы молча.
5. Изменившееся мероприятие остаётся в выдаче со своим новым состоянием. Исчезновение из списка событием не является.

Вебхуки, вторая фаза

Вебхуки booking_expired, event_updated и event_cancelled подключаются во второй фазе как ускоритель и обязательный опрос не отменяют. ДСС вызывает ваш URL и подписывает запрос той же схемой HMAC с теми же тремя заголовками; uri в канонической строке это полный путь вашего URL без хоста. Доставка не менее одного раза: любой ответ кроме 2xx или таймаут означает повтор с нарастающей задержкой, поэтому обработчик обязан быть идемпотентным по booking_id или event_id. URL для них понадобится позже.

Билеты, QR и PDF

qr_token

JWT в ASCII, около 520–570 символов. Кодировать в байтовом режиме QR с уровнем коррекции M (версия символа 18–20); не усекать и не перекодировать. Между чтениями токен стабилен. Значение null означает, что билет погашен и QR рисовать не нужно.

pdf_url

подписанная ссылка без состояния, действует до окончания мероприятия плюс 30 дней. GET /orders возвращает те же ссылки. Отдавайте её покупателю как ссылку, а не скачивайте PDF пачками со своего сервера: маршрут защищён отдельным лимитом на адрес.

number

номер билета вида DSS-TKT-000061, для поддержки и сверки; номер заказа вида DSS-2026-001042

status

active действителен · used гость прошёл · void погашен (возврат, отмена, инициатива ДСС) · expired мероприятие прошло

Письма покупателю по партнёрскому каналу ДСС не отправляет: доставка билета, QR и PDF на вашей стороне. Покупатель партнёра находится поддержкой ДСС по номеру заказа и по customer.email, поэтому адрес обязателен.

Ошибки

Единый формат: {"error": {"code", "message", "details"}}. Ветвитесь по code, message пишите в журнал: это текст для оператора, а не для покупателя. Неизвестный код обрабатывайте по HTTP-статусу, а не падайте.

Словари

Песочница и сертификация

Стенд открыт: https://api-sandbox.dss.ndsvs.kz, только HTTPS. Ключ pk_sandbox_… и секрет к нему ДСС выдаёт техническому контакту вместе с датой сертификационной сессии: часть сценариев ниже требует оператора ДСС на связи, поэтому дата согласуется отдельно. Вместе с ключами приходят этот документ с OpenAPI-файлом, коллекция Postman, сгенерированная из него, и тестовые мероприятия на стенде, на которых проходятся все сценарии, включая возврат и повторный проход. Нагрузочные прогоны по стенду только по предварительному согласованию: стенд разделяет машину с другими системами. На стенде работают те же фоновые процессы, что на продуктиве (уборка холдов, переходы мероприятий); проход по QR проверяется на настоящей точке прохода стенда контролёром ДСС во время сессии.

API-документация (Scalar) на стенде закрыта паролем, как на продуктиве: схему и это руководство берите только с developers.dss.ndsvs.kz.

Ночной пересев

Каждую ночь с 23:00 до 23:10 UTC (04:00-04:10 по Алматы) стенд недоступен и пересеивается: брони, заказы и билеты предыдущего дня исчезают, многодневные проверки сверки планируйте с учётом этого. Ключ и секрет партнёра при пересеве не меняются: интеграцию переделывать каждое утро не нужно, обновляются только данные. На стенде может быть несколько партнёров одновременно; ключ и секрет у каждого свои, а мероприятия и гранты одинаковы. После пересева на стенде: мероприятие 1 в sales_open с грантом (счастливый путь), мероприятие 2 в sales_open без гранта (сценарий 10 из списка ниже), мероприятие 3 в published с грантом, то есть видно как sales_scheduled (сценарий 25). В каждом зале 960 мест в шести секторах.

Две частые ошибки первого прогона

GET /events/{event_id}/seats отвечает по-разному в двух режимах. Без sector приходит сводка по секторам (ключ sectors, без seats); с sector=<sector_id> приходят места этого сектора (ключ seats, без sectors). Значения sector_id для второго запроса берите из ответа первого.

GET /api/v1/partners/events/32/seats
GET /api/v1/partners/events/32/seats?sector=sector-AA-A

Лимит частоты и потолок незакрытых pending-заказов общие на партнёра, а не на мероприятие и не на экземпляр клиента. Окно лимита частоты восстанавливается само каждую минуту; потолок pending сам не освобождается, слот закрывает только confirm, cancel или истечение платёжного окна. На каждый 429 выдерживайте ровно Retry-After, а не собственный таймаут повтора.

Что нужно от партнёра

1. Подтверждение проверочного вектора, до всего остального.
2. Технический контакт: кто у вас ведёт интеграцию.
3. Две даты: когда ваша разработка готова и когда вы готовы сертифицироваться.
4. Диапазон исходящих адресов, если хотите ограничение по адресу.
5. URL для вебхуков понадобится позже, ко второй фазе.

Сценарии сертификации

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

1. Проверочный вектор HMAC сходится.
2. Счастливый путь: events → seats → bookings → orders → confirm, билеты в ответе. Предусловие: мероприятие с открытыми продажами и грантом; на стенде это мероприятие №1 (см. «Ночной пересев»).
3. Повтор брони с тем же partner_booking_id возвращает ту же бронь, места не удвоены.
4. Повтор заказа с тем же partner_order_id возвращает тот же заказ.
5. Повтор confirm отвечает 200 с теми же билетами.
6. Бронь истекла: BOOKING_EXPIRED, места свободны.
7. Заказ истёк до confirm: ORDER_EXPIRED, и в ту же секунду GET /orders отвечает expired: обе стороны окна дают один ответ.
8. Отказ эквайера: cancel, места свободны немедленно.
9. amount_tenge не равен сумме заказа: 422 с обеими суммами.
10. Мероприятие без гранта: 403, в списке отсутствует. На стенде это мероприятие №2.
11. Превышение лимита частоты: 429 с заголовками. Этот сценарий намеренно исчерпывает общий лимит партнёра: после него дождитесь конца минутного окна (заголовок X-RateLimit-Reset), иначе следующие сценарии получат 429 не по своей вине.
12. Отмена мероприятия видна опросом с updated_since.
13. QR из qr_token проходит на настоящей точке прохода стенда, повторный скан того же билета отвергается кодом ALREADY_USED. Проходится вместе с оператором ДСС на сертификационной сессии: скан делает контролёр ДСС своей учёткой, отдельной демо-точки нет.
14. Потеря ответа: повтор POST /orders и GET /orders?partner_order_id= возвращают тот же заказ, второй не создаётся.
15. Отзыв гранта виден опросом (access: "revoked"), бронь по нему отвечает 403, confirm по живому pending проходит.
16. Бронь сверх предела: BOOKING_LIMIT_EXCEEDED; бронь на sales_paused: SALES_PAUSED.
17. Повтор ключа с другим телом: IDEMPOTENCY_CONFLICT; повтор брони после истечения возвращает её со status: expired и мест не удерживает.
18. confirm после каскада отмены мероприятия: EVENT_CANCELLED.
19. cancel и confirm наперегонки по одному заказу: ровно один из них побеждает, второй отвечает 409.
20. PARTNER_DISABLED посреди потока: новая бронь отвергается, confirm по живому pending проходит.
21. 422 по сумме, затем повтор confirm с верной суммой в окне проходит.
22. Запрос без X-Api-Key и запрос с X-Timestamp вне окна: два разных кода.
23. Ротация секрета: после rotate подписи и старым, и новым секретом принимаются; окно закрывает отдельная команда drop-prev, само оно не закрывается, ДСС сообщает партнёру, когда старый секрет отключён.
24. PENDING_LIMIT_EXCEEDED при превышении потолка незакрытых заказов, повтор после Retry-After. Потолок общий на партнёра и сам не восстанавливается: после сценария отмените созданные заказы через cancel или дождитесь истечения платёжного окна, иначе следующие сценарии получат 429 не по своей вине.
25. Неизвестный sector: 422 с details.sector; бронь на sales_scheduled: SALES_NOT_OPEN. На стенде это мероприятие №3.
26. Гашение билета персоналом ДСС видно в GET /orders и отвергается на точке прохода кодом TICKET_VOID.
27. Перенос мероприятия (starts_at) виден опросом.
28. paid с неполным tickets на намеренно уроненном выпуске: повторное чтение возвращает полный список, денег партнёр не возвращал.
29. Повтор confirm с другим payment_info: 200 с сохранённым первым слепком.
30. Освобождение брони: POST /bookings/{booking_id}/release возвращает места в продажу сразу, повтор отвечает 200, по брони с заказом приходит 409 BOOKING_ALREADY_CONFIRMED.
31. Бронь по сектору: на секторе с sale_mode: "sector" бронь с sector выдаёт запрошенное число мест этого сектора и категории, повтор с тем же ключом возвращает ту же бронь, тот же ключ с другим sector или с seats отвечает IDEMPOTENCY_CONFLICT. Нужен сектор режима sector на стенде; без него сценарий пропускается.
32. Сектор распродан: бронь по сектору на одно место больше остатка отвечает SECTOR_SOLD_OUT с details.available. Нужен сектор режима sector с остатком до 19 мест.

Версии

Добавление полей и кодов ошибок происходит без предупреждения: клиент обязан переживать неизвестные поля и ветвиться по HTTP-статусу на неизвестных кодах. Удаление и переименование только новой версией контракта с уведомлением и окном параллельной работы.