{"openapi":"3.1.0","info":{"title":"NumberCodes Bot Public API","description":"Публичный программный интерфейс и шлюз совместимости SMS-Activate для сервиса виртуальных номеров @NumberCodes_bot.","version":"1.0.0"},"paths":{"/api/v1/operators":{"get":{"tags":["REST API v1"],"summary":"Операторы связи для выбора при покупке","operationId":"list_operators_api_v1_operators_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","maxLength":16,"description":"ID страны (0 - Россия)","default":"0","title":"Country"},"description":"ID страны (0 - Россия)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/rental/tiers":{"get":{"tags":["REST API v1"],"summary":"Сроки аренды и цены для сервиса и страны","description":"Минимальная цена по каждому сроку (instant = 20 минут) среди доступных предложений, с вашей наценкой.","operationId":"rental_tiers_api_v1_rental_tiers_get","parameters":[{"name":"service","in":"query","required":true,"schema":{"type":"string","maxLength":32,"description":"Код сервиса (tg, wa, ...)","title":"Service"},"description":"Код сервиса (tg, wa, ...)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","maxLength":16,"default":"0","title":"Country"}},{"name":"operator","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Operator"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/active":{"get":{"tags":["REST API v1"],"summary":"Активные заказы, ожидающие SMS","operationId":"active_orders_api_v1_orders_active_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/orders/{order_id}/wait":{"get":{"tags":["REST API v1"],"summary":"Ждать SMS по заказу (long polling, до 30 секунд)","description":"Возвращает ответ, как только пришёл код или заказ закрылся; иначе по таймауту (timed_out=true) —\nповторите вызов. Заменяет опрос раз в пару секунд и экономит лимит запросов.","operationId":"wait_for_sms_api_v1_orders__order_id__wait_get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}},{"name":"timeout","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"description":"Сколько секунд ждать код","default":25,"title":"Timeout"},"description":"Сколько секунд ждать код"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/deposits":{"post":{"tags":["REST API v1"],"summary":"Создать счёт на пополнение (CryptoBot или xRocket)","description":"Возвращает ссылку оплаты. Баланс пополнится автоматически после оплаты; статус: ``GET /deposits/{id}``.\nЗаголовок ``Idempotency-Key`` обязателен: повтор с тем же ключом вернёт тот же счёт.","operationId":"create_deposit_api_v1_deposits_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["REST API v1"],"summary":"Последние счета на пополнение","operationId":"list_deposits_api_v1_deposits_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/deposits/{deposit_id}":{"get":{"tags":["REST API v1"],"summary":"Статус счёта (с проверкой оплаты у провайдера)","operationId":"get_deposit_api_v1_deposits__deposit_id__get","parameters":[{"name":"deposit_id","in":"path","required":true,"schema":{"type":"integer","title":"Deposit Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhook":{"get":{"tags":["REST API v1"],"summary":"Текущий webhook аккаунта","operationId":"get_webhook_api_v1_webhook_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"tags":["REST API v1"],"summary":"Задать webhook аккаунта: один адрес на все события","description":"Каждый запрос подписан: заголовок ``X-NumberCodes-Signature: t=<unix>,v1=<hex>``, где\n``hex = HMAC-SHA256(secret, \"<t>.<тело>\")``. Секрет возвращается при создании и при перевыпуске.","operationId":"put_webhook_api_v1_webhook_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["REST API v1"],"summary":"Удалить webhook аккаунта","operationId":"delete_webhook_api_v1_webhook_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/webhook/secret":{"post":{"tags":["REST API v1"],"summary":"Перевыпустить секрет подписи","operationId":"rotate_webhook_secret_api_v1_webhook_secret_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/webhook/test":{"post":{"tags":["REST API v1"],"summary":"Отправить тестовое событие и увидеть ответ вашего сервера","operationId":"test_webhook_api_v1_webhook_test_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/webhook/deliveries":{"get":{"tags":["REST API v1"],"summary":"Журнал доставок webhook","operationId":"webhook_deliveries_api_v1_webhook_deliveries_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhook/deliveries/{delivery_id}/retry":{"post":{"tags":["REST API v1"],"summary":"Повторить доставку вручную","operationId":"retry_webhook_delivery_api_v1_webhook_deliveries__delivery_id__retry_post","parameters":[{"name":"delivery_id","in":"path","required":true,"schema":{"type":"integer","title":"Delivery Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/balance":{"get":{"tags":["REST API v1"],"summary":"Получить баланс аккаунта","description":"Возвращает текущий баланс пользователя в Telegram-боте в долларах USD.","operationId":"get_balance_api_v1_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/services":{"get":{"tags":["REST API v1"],"summary":"Каталог сервисов и цены","description":"Возвращает список поддерживаемых сервисов с актуальными ценами в долларах USD.","operationId":"get_services_api_v1_services_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/countries":{"get":{"tags":["REST API v1"],"summary":"Список доступных стран","description":"Возвращает полный список поддерживаемых стран, их ID и признак популярности.","operationId":"get_countries_api_v1_countries_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/availability":{"get":{"tags":["REST API v1"],"summary":"Проверка наличия и цен в реальном времени","description":"Возвращает живые остатки номеров и актуальные цены с учётом наценки бота.","operationId":"get_availability_api_v1_availability_get","parameters":[{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Код сервиса (tg, wa, ya)","title":"Service"},"description":"Код сервиса (tg, wa, ya)"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ID страны (0 - Россия, 1 - Украина, etc.)","title":"Country"},"description":"ID страны (0 - Россия, 1 - Украина, etc.)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/buy":{"post":{"tags":["REST API v1"],"summary":"Купить номер для SMS","description":"Покупка одного номера для указанного сервиса. Средства списываются с баланса в боте.","operationId":"buy_order_api_v1_orders_buy_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyOrderRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/buy-bulk":{"post":{"tags":["REST API v1"],"summary":"Пакетная покупка номеров (до 20 шт)","description":"Покупка пачки номеров (от 1 до 20) за один вызов с атомарным списанием.","operationId":"buy_orders_bulk_api_v1_orders_buy_bulk_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyBulkOrderRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders":{"get":{"tags":["REST API v1"],"summary":"История заказов с фильтрами и пагинацией","description":"Возвращает список заказов пользователя с пагинацией и статусами.","operationId":"list_orders_api_v1_orders_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Фильтр: waiting_sms, received, cancelled, all","title":"Status"},"description":"Фильтр: waiting_sms, received, cancelled, all"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Номер страницы","default":1,"title":"Page"},"description":"Номер страницы"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Количество на странице","default":20,"title":"Limit"},"description":"Количество на странице"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/{order_id}":{"get":{"tags":["REST API v1"],"summary":"Проверить статус заказа и код","description":"Получить статус заказа, номер телефона и полученный SMS-код.","operationId":"get_order_status_api_v1_orders__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/{order_id}/cancel":{"post":{"tags":["REST API v1"],"summary":"Отменить номер и вернуть средства","description":"Отменяет заказ (если SMS ещё не получено) и возвращает полную стоимость на баланс в боте.","operationId":"cancel_order_api_v1_orders__order_id__cancel_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/{order_id}/finish":{"post":{"tags":["REST API v1"],"summary":"Завершить заказ","description":"Подтвердить успешное завершение работы с номером.","operationId":"finish_order_api_v1_orders__order_id__finish_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/{order_id}/retry":{"post":{"tags":["REST API v1"],"summary":"Запрос повторного SMS","description":"Запросить получение второго SMS для того же номера (если сервис позволяет повторный код).","operationId":"retry_order_sms_api_v1_orders__order_id__retry_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/{order_id}/outbound-call":{"post":{"tags":["REST API v1"],"summary":"Исходящий звонок-подтверждение (Flash-call)","description":"Совершить звонок-сброс с купленного номера на указанный целевой телефон.","operationId":"make_outbound_call_api_v1_orders__order_id__outbound_call_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundCallRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/orders/{order_id}/webhook":{"put":{"tags":["REST API v1"],"summary":"Назначить или обновить Webhook URL для заказа","description":"Установить URL для мгновенной отправки HTTP POST при поступлении SMS по данному заказу.","operationId":"set_order_webhook_api_v1_orders__order_id__webhook_put","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/transactions":{"get":{"tags":["REST API v1"],"summary":"История финансовых транзакций","description":"Возвращает историю списаний и пополнений пользователя.","operationId":"list_transactions_api_v1_transactions_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Номер страницы","default":1,"title":"Page"},"description":"Номер страницы"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Количество на странице","default":20,"title":"Limit"},"description":"Количество на странице"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stubs/handler_api.php":{"get":{"tags":["SMS-Activate Protocol"],"summary":"SMS-Activate Protocol (GET)","description":"Совместимый эндпоинт протокола SMS-Activate/SMSHub для сторонних программ и автореггеров. Поддерживает getBalance, getPrices, getNumbersStatus, getCountries, getOperators, getNumber, getStatus, setStatus.","operationId":"sms_activate_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["SMS-Activate Protocol"],"summary":"SMS-Activate Protocol (POST)","description":"POST-обработчик протокола SMS-Activate/SMSHub с поддержкой передачи параметров в form-data и x-www-form-urlencoded.","operationId":"sms_activate_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/health":{"get":{"tags":["System"],"summary":"Health Check","operationId":"health_check_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"BuyBulkOrderRequest":{"properties":{"service":{"type":"string","title":"Service","description":"Код сервиса (например 'tg', 'wa', 'ya', 'vk')"},"country_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Id","description":"ID страны (по умолчанию '0' — Россия)","default":"0"},"quantity":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Quantity","description":"Количество номеров (от 1 до 20)","default":1},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"Webhook URL для уведомлений о получении SMS"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"Уникальный ключ для предотвращения повторной пакетной покупки"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator","description":"Оператор связи (см. GET /operators), по умолчанию любой"},"rental_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rental Tier","description":"Срок: instant (20 мин), 1h, 24h, 7d, 30d","default":"instant"}},"type":"object","required":["service"],"title":"BuyBulkOrderRequest"},"BuyOrderRequest":{"properties":{"service":{"type":"string","title":"Service","description":"Код сервиса (например 'tg', 'wa', 'ya', 'vk', 'uu')"},"country_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Id","description":"ID страны (по умолчанию '0' — Россия)","default":"0"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"Webhook URL для мгновенных HTTP POST уведомлений о получении SMS"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"Уникальный ключ для предотвращения повторной покупки при дублировании запроса"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operator","description":"Оператор связи (см. GET /operators), по умолчанию любой"},"rental_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rental Tier","description":"Срок: instant (20 мин), 1h, 24h, 7d, 30d (см. GET /rental/tiers)","default":"instant"}},"type":"object","required":["service"],"title":"BuyOrderRequest"},"DepositRequest":{"properties":{"amount":{"anyOf":[{"type":"number","maximum":1000.0,"minimum":1.0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Amount","description":"Сумма в USD (1-1000)"},"provider":{"type":"string","pattern":"^(cryptobot|xrocket)$","title":"Provider","default":"cryptobot"}},"type":"object","required":["amount"],"title":"DepositRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OutboundCallRequest":{"properties":{"target_phone":{"type":"string","title":"Target Phone","description":"Номер телефона для обратного звонка-подтверждения (Flash-call)"}},"type":"object","required":["target_phone"],"title":"OutboundCallRequest"},"UpdateWebhookRequest":{"properties":{"callback_url":{"type":"string","title":"Callback Url","description":"Webhook URL для отправки уведомления при получении SMS"}},"type":"object","required":["callback_url"],"title":"UpdateWebhookRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookRequest":{"properties":{"url":{"type":"string","title":"Url","description":"HTTPS-адрес, который принимает POST с JSON"},"events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Events","description":"Нужные события; пусто = все: sms_received, order_cancelled, rental_finished, rental_expiring, balance_topped_up"}},"type":"object","required":["url"],"title":"WebhookRequest"}}}}