{"openapi":"3.1.1","info":{"title":"PLATA Integration API","version":"1.0.0","x-contract-updated-at":"2026-11-03","description":"Публичный API интеграций с ролью client. На странице документации работает только локальная демонстрация, без сетевых запросов в API. Примеры вымышлены. fiatRub — целое JSON-число в рублях; *Units — строки, USDT × 10^6. Курс зависит от условий интеграции и фиксируется в заявке. Получите ключ у администратора перед подключением рабочего API."},"servers":[{"url":"https://api.myplata.net/v1","description":"Рабочий API. Локальный playground НЕ отправляет запросы на этот сервер."}],"security":[{"integrationBearer":[]}],"tags":[{"name":"Курс"},{"name":"Заявки"},{"name":"Квитанции"},{"name":"Вебхуки"}],"paths":{"/rate":{"get":{"operationId":"getRate","summary":"Получить курс","description":"Действующий курс RUB за 1 USDT для вашей интеграции.\n\nКлиент определяется по API-ключу. Если согласованы индивидуальные условия, вернётся персональный курс, иначе — общий. Команда PLATA может менять курс в любое время; он действует до следующего изменения. Ответ не кэшируется. Передайте его id как rateId при создании, чтобы защититься от изменения курса между запросами.","tags":["Курс"],"parameters":[],"responses":{"200":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rate"},"example":{"id":"a61a93f0-c4ec-4bad-9587-98b4749e9349","pair":"USDT/RUB","rubPerUsdt":"100.00","updatedAt":"2026-11-03T09:00:00.000Z"}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}},"/orders":{"post":{"operationId":"createOrder","summary":"Создать заявку","description":"Передайте сумму в рублях и адрес, на который клиент получит USDT.\n\nСначала платформа ищет готовые реквизиты с доступным лимитом. Если они найдены, ответ сразу содержит AWAITING_PAYMENT и реквизиты. Иначе вернётся CREATED: заявка ожидает мерчанта. Не отправляйте bank, currency, network или callbackUrl — этих полей в запросе нет.","tags":["Заявки"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"},"example":{"fiatRub":10000,"payoutAddress":"0x1111111111111111111111111111111111111111","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"responses":{"201":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"network":"BSC_USDT","id":"018f6fa2-7b18-4d5f-9d02-5c76a0e2b931","clientId":"99517341-5c92-43b7-a44d-8c531e2ed090","merchantId":"4bd22f46-88ea-4af8-8185-7298362e2839","fiatRub":10000,"clientUnits":"100000000","rate":{"id":"a61a93f0-c4ec-4bad-9587-98b4749e9349","pair":"USDT/RUB","rubPerUsdt":"100.00","updatedAt":"2026-11-03T09:00:00.000Z"},"payoutAddress":"0x1111111111111111111111111111111111111111","status":"AWAITING_PAYMENT","version":2,"requisites":{"account":"DEMO-REQUISITES-NOT-FOR-PAYMENT","bank":"Демонстрационный банк","recipient":"Демо-получатель"},"savedRequisiteId":"f5d66215-0be9-452d-b27b-d97160586f88","paymentExpiresAt":"2026-11-03T09:30:00.000Z","dispute":null}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}},"/orders/{id}":{"get":{"operationId":"getOrder","summary":"Получить заявку","description":"Актуальное состояние, реквизиты и сумма выплаты по вашей заявке.\n\nСохраните id из ответа создания и опрашивайте этот метод. Рекомендуемый интервал — 3–5 секунд с увеличением задержки при ошибках. Внешние webhook сейчас не реализованы. Завершайте опрос на COMPLETED или CANCELLED. transactionHash не входит в объект Order.","tags":["Заявки"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID собственной заявки, полученный при создании."}],"responses":{"200":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"network":"BSC_USDT","id":"018f6fa2-7b18-4d5f-9d02-5c76a0e2b931","clientId":"99517341-5c92-43b7-a44d-8c531e2ed090","merchantId":"4bd22f46-88ea-4af8-8185-7298362e2839","fiatRub":10000,"clientUnits":"100000000","rate":{"id":"a61a93f0-c4ec-4bad-9587-98b4749e9349","pair":"USDT/RUB","rubPerUsdt":"100.00","updatedAt":"2026-11-03T09:00:00.000Z"},"payoutAddress":"0x1111111111111111111111111111111111111111","status":"AWAITING_PAYMENT","version":2,"requisites":{"account":"DEMO-REQUISITES-NOT-FOR-PAYMENT","bank":"Демонстрационный банк","recipient":"Демо-получатель"},"savedRequisiteId":"f5d66215-0be9-452d-b27b-d97160586f88","paymentExpiresAt":"2026-11-03T09:30:00.000Z","dispute":null}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}},"/orders/{id}/receipt":{"post":{"operationId":"uploadReceipt","summary":"Прикрепить квитанцию","description":"Отправьте исходный PDF непосредственно в теле запроса.\n\nContent-Type: application/pdf. Не multipart, не JSON, не base64. До 8 MiB, от 1 до 20 страниц, без шифрования и активного содержимого. Допустимы AWAITING_PAYMENT, PAYMENT_REVIEW и DISPUTED. Один и тот же PDF для этой заявки не создаёт новый документ. До 5 уникальных PDF на заявку. Принятый PDF не подтверждает поступление денег и сам по себе не запускает выплату.","tags":["Квитанции"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID собственной заявки, полученный при создании."}],"requestBody":{"required":true,"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptAccepted"},"example":{"documentId":"1731cafe-cb44-4b82-a690-3cb1c7131111","status":"PAYMENT_REVIEW"}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}},"get":{"operationId":"getReceipt","summary":"Получить квитанцию","description":"Последняя принятая квитанция по заявке в формате PDF.\n\nОтвет — бинарный PDF. По умолчанию Content-Disposition: inline. Добавьте ?download=1 для скачивания как вложения. Это авторизованный запрос: обычная ссылка без Bearer-заголовка не заменяет серверное получение файла.","tags":["Квитанции"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID собственной заявки, полученный при создании."},{"name":"download","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"attachment вместо inline"}],"responses":{"200":{"description":"Последний принятый PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}},"/orders/{id}/history":{"get":{"operationId":"orderHistory","summary":"История заявки","description":"Последовательность изменений заявки, отсортированная по version.\n\nВозвращается JSON-массив без обёртки items. Названия полей здесь используют snake_case. Технические action, request_id, event_id и trace_id могут быть null. Используйте статус заявки для принятия решений, а историю — для объяснения изменений.","tags":["Заявки"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID собственной заявки, полученный при создании."}],"responses":{"200":{"description":"Успешный ответ","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HistoryEvent"}},"example":[{"version":1,"from_status":null,"to_status":"CREATED","occurred_at":"2026-11-03T09:00:00.000Z","action":"create-order","request_id":"917c0421-6123-4e68-b6b3-1f8d92f0b470","event_id":null,"trace_id":null},{"version":2,"from_status":"CREATED","to_status":"AWAITING_PAYMENT","occurred_at":"2026-11-03T09:00:00.000Z","action":"create-order","request_id":"917c0421-6123-4e68-b6b3-1f8d92f0b470","event_id":null,"trace_id":null}]}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}},"/orders/{id}/cancel":{"post":{"operationId":"cancelOrder","summary":"Отменить заявку","description":"Отмена неоплаченной заявки до прикрепления квитанции.\n\nОтмена доступна только в AWAITING_PAYMENT, если квитанция ещё не принята. CREATED, AWAITING_REQUISITES, PAYMENT_REVIEW, DISPUTED и PAYOUT_PENDING этим методом не отменяются. При успехе резерв освобождается. Для повторной отправки используйте исходный requestId.","tags":["Заявки"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"ID собственной заявки, полученный при создании."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Command"},"example":{"requestId":"876867cb-555c-4a38-a930-ecc0c5413168"}}}},"responses":{"201":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"network":"BSC_USDT","id":"018f6fa2-7b18-4d5f-9d02-5c76a0e2b931","clientId":"99517341-5c92-43b7-a44d-8c531e2ed090","merchantId":"4bd22f46-88ea-4af8-8185-7298362e2839","fiatRub":10000,"clientUnits":"100000000","rate":{"id":"a61a93f0-c4ec-4bad-9587-98b4749e9349","pair":"USDT/RUB","rubPerUsdt":"100.00","updatedAt":"2026-11-03T09:00:00.000Z"},"payoutAddress":"0x1111111111111111111111111111111111111111","status":"CANCELLED","version":2,"requisites":{"account":"DEMO-REQUISITES-NOT-FOR-PAYMENT","bank":"Демонстрационный банк","recipient":"Демо-получатель"},"savedRequisiteId":"f5d66215-0be9-452d-b27b-d97160586f88","paymentExpiresAt":"2026-11-03T09:30:00.000Z","dispute":null}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}},"/webhook":{"get":{"operationId":"getWebhook","summary":"Получить настройки вебхука","description":"Адрес уведомлений и состояние подключения вашей интеграции.\n\nЕсли вебхук ещё не настроен, ответ — null. Секрет подписи не возвращается. Настройки принадлежат API-ключу, с которым выполнен запрос.","tags":["Вебхуки"],"parameters":[],"responses":{"200":{"description":"Успешный ответ","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookConfiguration"},{"type":"null"}]},"example":{"id":"6c4bbc53-3228-4c2e-9f4f-4657af693f62","url":"https://receiver.example.com/plata","enabled":true,"updatedAt":"2026-11-03T09:00:00.000Z"}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}},"post":{"operationId":"setWebhook","summary":"Настроить вебхук","description":"Подключите HTTPS-адрес для получения обновлений заявок.\n\nОдин адрес на интеграцию. Передайте все четыре поля. Повтор с тем же requestId и телом безопасен. Изменение настроек отменяет очередь предыдущей конфигурации: новые события будут доставляться по новым условиям. Уже отправляемый запрос может завершиться. Исторические события не отправляются; сверяйте состояние через GET /orders/{id}.","tags":["Вебхуки"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureWebhook"},"example":{"requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470","url":"https://receiver.example.com/plata","secret":"whsec_ddddddddddddddddddddddddddddddddddddddddddd","enabled":true}}}},"responses":{"201":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConfiguration"},"example":{"id":"6c4bbc53-3228-4c2e-9f4f-4657af693f62","url":"https://receiver.example.com/plata","enabled":true,"updatedAt":"2026-11-03T09:00:00.000Z"}}}},"400":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DESTINATION_FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"401":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_KEY_INVALID","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"403":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"FORBIDDEN","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"404":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ORDER_NOT_FOUND","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"409":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"IDEMPOTENCY_CONFLICT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"413":{"description":"Превышен лимит тела; ответ прокси может быть не JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"429":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API_RATE_LIMIT","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"500":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"INTERNAL_ERROR","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}},"503":{"description":"Ошибка запроса или состояния","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"WEBHOOK_DNS_UNAVAILABLE","requestId":"917c0421-6123-4e68-b6b3-1f8d92f0b470"}}}}}}}},"webhooks":{"orderUpdated":{"post":{"summary":"Изменение заявки — POST на адрес вашей интеграции","description":"Подпись HMAC-SHA256 от timestamp + \".\" + eventId + \".\" + rawBody. Любой 2xx подтверждает доставку. При ошибке — повторы до 24 часов, не более 24 попыток. Порядок не гарантируется; используйте data.version, дубликаты определяйте по id.","security":[{"webhookSignature":[]}],"parameters":[{"name":"X-Plata-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Plata-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix-время попытки в секундах; допустимое отклонение при проверке — 300 секунд."},{"name":"X-Plata-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"},"example":{"id":"d6cfd7a4-824f-4b28-8df0-af5771a9884c","type":"order.updated","apiVersion":"v1","createdAt":"2026-11-03T09:05:00.000Z","data":{"network":"BSC_USDT","id":"018f6fa2-7b18-4d5f-9d02-5c76a0e2b931","clientId":"99517341-5c92-43b7-a44d-8c531e2ed090","merchantId":"4bd22f46-88ea-4af8-8185-7298362e2839","fiatRub":10000,"clientUnits":"100000000","rate":{"id":"a61a93f0-c4ec-4bad-9587-98b4749e9349","pair":"USDT/RUB","rubPerUsdt":"100.00","updatedAt":"2026-11-03T09:00:00.000Z"},"payoutAddress":"0x1111111111111111111111111111111111111111","status":"COMPLETED","version":5,"requisites":{"account":"DEMO-REQUISITES-NOT-FOR-PAYMENT","bank":"Демонстрационный банк","recipient":"Демо-получатель"},"savedRequisiteId":"f5d66215-0be9-452d-b27b-d97160586f88","paymentExpiresAt":"2026-11-03T09:30:00.000Z","dispute":null}}}}},"responses":{"200":{"description":"Событие сохранено или уже обработано"},"204":{"description":"Событие сохранено без тела ответа"}}}}},"components":{"securitySchemes":{"webhookSignature":{"type":"apiKey","in":"header","name":"X-Plata-Signature","description":"HMAC-SHA256 с отдельным секретом webhook. Проверяйте timestamp, ID события и исходные байты тела."},"integrationBearer":{"type":"http","scheme":"bearer","description":"Серверный API-ключ plata_live_… с ролью client. Не Telegram initData. Не размещайте его в браузере."}},"schemas":{"WebhookConfiguration":{"type":"object","required":["id","url","enabled","updatedAt"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"enabled":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}}},"ConfigureWebhook":{"type":"object","required":["requestId","url","secret","enabled"],"additionalProperties":false,"properties":{"requestId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","maxLength":2048},"secret":{"type":"string","writeOnly":true,"pattern":"^whsec_[A-Za-z0-9_-]{43}$"},"enabled":{"type":"boolean"}}},"WebhookEvent":{"type":"object","required":["id","type","apiVersion","createdAt","data"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","const":"order.updated"},"apiVersion":{"type":"string","const":"v1"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Order"}}},"Rate":{"type":"object","required":["id","pair","rubPerUsdt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"pair":{"type":"string","const":"USDT/RUB"},"rubPerUsdt":{"type":"string","pattern":"^[0-9]+\\.[0-9]{2}$","example":"100.00","description":"Рублей за 1 USDT. Десятичная строка для точного расчёта."},"updatedAt":{"type":"string","format":"date-time"}}},"CreateOrder":{"type":"object","additionalProperties":false,"required":["fiatRub","payoutAddress","requestId"],"properties":{"fiatRub":{"type":"integer","minimum":1,"maximum":9007199254740991,"example":10000},"rateId":{"type":"string","format":"uuid","description":"Версия курса из GET /rate. При изменении вернётся 409 RATE_CHANGED; заявка не создаётся."},"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Адрес получателя USDT в BSC. Нулевой адрес запрещён. Сервер приводит буквы к нижнему регистру."},"requestId":{"type":"string","format":"uuid"}}},"Command":{"type":"object","additionalProperties":false,"required":["requestId"],"properties":{"requestId":{"type":"string","format":"uuid"}}},"Requisites":{"type":["object","null"],"required":["account","bank","recipient"],"properties":{"account":{"type":"string"},"bank":{"type":"string"},"recipient":{"type":"string"}}},"Dispute":{"type":["object","null"],"required":["orderId","reason","comment","openedBy","openedAt","status","decision","note","resolvedBy","resolvedAt"],"properties":{"orderId":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["PAYMENT_NOT_RECEIVED","AMOUNT_MISMATCH","WRONG_REQUISITES","RECEIPT_ISSUE","OTHER"]},"comment":{"type":"string"},"openedBy":{"type":"string","format":"uuid"},"openedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["OPEN","RESOLVED"]},"decision":{"type":["string","null"],"enum":["CLIENT","MERCHANT",null]},"note":{"type":["string","null"]},"resolvedBy":{"type":["string","null"],"format":"uuid"},"resolvedAt":{"type":["string","null"],"format":"date-time"}}},"Order":{"type":"object","required":["id","clientId","merchantId","fiatRub","clientUnits","rate","payoutAddress","status","version","requisites"],"properties":{"id":{"type":"string","format":"uuid"},"clientId":{"type":"string","format":"uuid"},"merchantId":{"type":["string","null"],"format":"uuid"},"fiatRub":{"type":"integer","minimum":1,"maximum":9007199254740991},"clientUnits":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$","description":"USDT × 10^6, не raw-единицы токена BSC."},"rate":{"$ref":"#/components/schemas/Rate"},"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Адрес получателя USDT в BSC. Нулевой адрес запрещён. Сервер приводит буквы к нижнему регистру."},"status":{"type":"string","enum":["CREATED","AWAITING_REQUISITES","AWAITING_PAYMENT","PAYMENT_REVIEW","DISPUTED","PAYOUT_PENDING","COMPLETED","CANCELLED"]},"version":{"type":"integer","minimum":1},"requisites":{"$ref":"#/components/schemas/Requisites"},"network":{"type":"string","enum":["BSC_USDT","TEST_USDT"]},"savedRequisiteId":{"type":["string","null"],"format":"uuid"},"paymentExpiresAt":{"type":["string","null"],"format":"date-time"},"dispute":{"$ref":"#/components/schemas/Dispute"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Машиночитаемая ошибка. Прокси может вернуть не-JSON при сетевой ошибке."},"requestId":{"type":"string","description":"ID трассировки HTTP-запроса; не ключ идемпотентности команды."}}},"HistoryEvent":{"type":"object","required":["version","from_status","to_status","occurred_at","action","request_id","event_id","trace_id"],"properties":{"version":{"type":"integer"},"from_status":{"type":["string","null"]},"to_status":{"type":"string","enum":["CREATED","AWAITING_REQUISITES","AWAITING_PAYMENT","PAYMENT_REVIEW","DISPUTED","PAYOUT_PENDING","COMPLETED","CANCELLED"]},"occurred_at":{"type":"string","format":"date-time"},"action":{"type":["string","null"]},"request_id":{"type":["string","null"],"format":"uuid"},"event_id":{"type":["string","null"],"format":"uuid"},"trace_id":{"type":["string","null"]}}},"ReceiptAccepted":{"type":"object","required":["documentId","status"],"properties":{"documentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATED","AWAITING_REQUISITES","AWAITING_PAYMENT","PAYMENT_REVIEW","DISPUTED","PAYOUT_PENDING","COMPLETED","CANCELLED"],"description":"Обычно PAYMENT_REVIEW; при открытом споре остаётся DISPUTED. Возможен более поздний статус при конкурентной обработке."}}}}},"externalDocs":{"url":"https://myplata.net/docs/agents.md","description":"Полное руководство для агента"}}