Настройка
1
Включите торговлю для ключа
Перейдите в API-профиль и переключите тумблер buying для нужного ключа. До этого каждый вызов
POST /v1/orders будет возвращать 403 trading_not_enabled.2
Привяжите аккаунт Steam и trade URL
Ордера доставляются напрямую в Steam, поэтому в профиле должны быть привязаны Steam-аккаунт и действующий trade URL. Без этого API возвращает
400 steam_account_required.3
Пополните баланс CSBoard
Покупки списываются с вашего существующего баланса CSBoard. Пополняйте его на сайте — через сам API нет пути оплаты картой или криптовалютой.
4
Найдите листинги для покупки
Запросите
GET /v1/listings, чтобы найти предметы и собрать их поля id. Каждое значение id в ответе — это стабильная ссылка, которую вы передаёте непосредственно в эндпоинт ордеров.5
Разместите ордер
Отправьте POST со списком ID листингов в
/v1/orders. Включите max_price_usd и Idempotency-Key — оба подробно объясняются ниже.Защита от перерасхода
Вам всегда списывается актуальная цена в момент исполнения, а не цена, которую вы видели при просмотре листингов. Рынки движутся — листинг, который вы получили 30 секунд назад, мог быть перевыставлен по более высокой цене к моменту исполнения ордера. Используйтеmax_price_usd как потолок общей суммы. Списание атомарно: если на момент исполнения актуальная сумма превышает ваш потолок, весь ордер отклоняется с 409 price_moved — ничего не списывается и ни один предмет не передаётся.
Если цена изменилась и вы получили 400, в теле ответа есть current_total_usd, чтобы вы могли решить, перепосылать ли запрос с более высоким потолком или прервать сделку:
Идемпотентность
Сетевые сбои случаются. Без идемпотентности повтор после таймаута может купить один и тот же предмет дважды. Чтобы этого избежать, отправляйте уникальный заголовокIdempotency-Key с каждым запросом ордера.
- Сохраните один ключ на заказ. Успешный ответ доступен для повтора из кэша до 24 часов. После сетевого таймаута сначала проверьте исходный заказ.
- Также можно передать
idempotency_keyв теле запроса вместо заголовка; эффект одинаковый. - Используйте UUID v4, сгенерированный на каждую попытку ордера, а не на каждый повтор.
Пример ответа
Новый ордер возвращает201 с деталями ордера (повтор с тем же Idempotency-Key возвращает 200 с тем же телом):
Доставка
В ответе ордера есть полеdelivery на уровне всего ордера и expected_minutes, когда мы можем оценить срок:
instant— доставка ботом; трейд-оффер придёт на ваш Steam trade URL в течение нескольких минут.pending— трейд ещё должен отправить продавец или поставщик.
delivery и tradable_at листинга до покупки. Следите за ордером через GET /v1/orders/{id}, где видны hold и hold_until, и забирайте его через POST /v1/orders/{id}/claim или настройку autoclaim.
В GET /v1/orders/{id} есть и delivery_type. Заказ manual отправляет человек, это может занять до 12 часов; delivery_deadline_at показывает, когда у продавца кончается время, после чего заказ отменяется и деньги возвращаются автоматически. Чтобы не ждать, отмените его через POST /v1/orders/{id}/cancel спустя 31 минуту.
Если заказ не выполнен
Если заказ закончился статусомfailed или cancelled, деньги за него уже вернулись — квитанция лежит в refund. Причину объясняют три поля:
fail_reason— код для ветвления логики, напримерrecipient_inventory_privateилиlisting_gone. Незнакомый код обрабатывайте какunavailable.fail_side— кто должен действовать.recipient: исправьте Steam-аккаунт или trade URL получателя и купите заново.sellerилиmarket: купите другой листинг, а приmarket_unavailableповторите чуть позже.buyer: заказ отменили вы.fail_message— одно предложение, которое можно показать как есть.
null. Все коды перечислены в разделе «Почему заказ не выполнен».