{"openapi": "3.0.3", "info": {"title": "SMS shop API", "version": "1.1.0", "description": "Покупка номеров и получение кодов. Подробная документация: /docs"}, "servers": [{"url": "https://volksms.space"}], "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}}}, "paths": {"/v1/me": {"get": {"tags": ["Аккаунт"], "summary": "Кто я", "description": "Информация о владельце токена: ID аккаунта, баланс, данные токена.", "security": [{"bearerAuth": []}], "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"user_id": 123456789, "balance": 12.5, "token": {"id": 7, "name": "Токен 1", "prefix": "vsk_a1b2c3", "webhook": null}}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/balance": {"get": {"tags": ["Аккаунт"], "summary": "Баланс", "description": "Текущий баланс в долларах. Баланс общий с Telegram-ботом: пополнять его можно в боте.", "security": [{"bearerAuth": []}], "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"balance": 12.5, "currency": "USD"}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/services": {"get": {"tags": ["Каталог"], "summary": "Список сервисов", "description": "Все сервисы, которые можно купить через API, с вашей ценой за один номер (учитываются ваши личные цены/скидки, если они есть). Поле `price` — null, если сервиса сейчас нет в наличии.", "security": [{"bearerAuth": []}], "parameters": [{"name": "search", "in": "query", "required": false, "description": "Часть названия, например `tele`.", "schema": {"type": "string"}}, {"name": "available", "in": "query", "required": false, "description": "`1` — показать только то, что есть в наличии.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"services": [{"id": "tg", "name": "Telegram", "category": "Мессенджеры", "price": 0.45, "in_stock": true}], "count": 1}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/services/{service}": {"get": {"tags": ["Каталог"], "summary": "Один сервис", "description": "Цена и наличие одного сервиса. `{service}` — его `id` из списка или точное название.", "security": [{"bearerAuth": []}], "parameters": [{"name": "service", "in": "path", "required": true, "description": "ID или название сервиса.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"id": "tg", "name": "Telegram", "category": "Мессенджеры", "price": 0.45, "in_stock": true}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/orders": {"post": {"tags": ["Заказы"], "summary": "Купить номер(а)", "description": "Покупает номер и сразу списывает деньги с баланса. Код придёт позже: следите за заказом через `GET /v1/orders/{id}` или подключите вебхук. Если за 20 минут код не пришёл, заказ автоматически отменяется, а деньги возвращаются.\nМожно купить сразу несколько: `quantity` от 1 до 30. Куплено может оказаться меньше запрошенного — за непроданные деньги не списываются (смотрите `bought` и `error` в ответе).", "security": [{"bearerAuth": []}], "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"orders": [{"id": "ord_3f9a1c7b2d4e", "service": "Telegram", "service_id": "tg", "phone": "79991234567", "price": 0.45, "status": "waiting", "codes": [], "code": null, "created_at": 1760000000, "expires_at": 1760001200, "can_cancel": false, "cancel_available_in": 120}], "requested": 1, "bought": 1, "charged": 0.45, "balance": 12.05}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"service": {"type": "string", "description": "ID или название сервиса."}, "quantity": {"type": "integer", "description": "Сколько номеров купить (1–30). По умолчанию 1."}}, "required": ["service"]}, "example": {"service": "tg", "quantity": 1}}}}}, "get": {"tags": ["Заказы"], "summary": "Список заказов", "description": "Ваши заказы, сделанные через API, от новых к старым.", "security": [{"bearerAuth": []}], "parameters": [{"name": "status", "in": "query", "required": false, "description": "Фильтр: `waiting`, `code_received`, `completed`, `cancelled`, `expired`.", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "Сколько вернуть (1–100). По умолчанию 20.", "schema": {"type": "integer"}}, {"name": "offset", "in": "query", "required": false, "description": "Сколько пропустить — для постраничного чтения.", "schema": {"type": "integer"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"orders": [{"id": "ord_3f9a1c7b2d4e", "service": "Telegram", "service_id": "tg", "phone": "79991234567", "price": 0.45, "status": "code_received", "codes": ["48213"], "code": "48213", "created_at": 1760000000, "expires_at": 1760001200, "can_cancel": false, "cancel_available_in": 0}], "count": 1, "limit": 20, "offset": 0}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/orders/{id}": {"get": {"tags": ["Заказы"], "summary": "Статус заказа и код", "description": "Состояние заказа. Когда придёт код, `status` станет `code_received`, а код появится в `code` (и в списке `codes`, если их несколько). Опрашивайте не чаще раза в 3–5 секунд, либо используйте вебхук.", "security": [{"bearerAuth": []}], "parameters": [{"name": "id", "in": "path", "required": true, "description": "ID заказа (`ord_…`).", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"id": "ord_3f9a1c7b2d4e", "service": "Telegram", "service_id": "tg", "phone": "79991234567", "price": 0.45, "status": "code_received", "codes": ["48213"], "code": "48213", "created_at": 1760000000, "expires_at": 1760001200, "can_cancel": false, "cancel_available_in": 0}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/orders/{id}/cancel": {"post": {"tags": ["Заказы"], "summary": "Отменить заказ", "description": "Отменяет заказ, если код ещё не пришёл, и возвращает деньги на баланс. Отмена обычных номеров доступна через 2 минуты после покупки (до этого вернётся ошибка `too_early` с полем `retry_after`).", "security": [{"bearerAuth": []}], "parameters": [{"name": "id", "in": "path", "required": true, "description": "ID заказа.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"id": "ord_3f9a1c7b2d4e", "status": "cancelled", "refunded": 0.45, "balance": 12.5}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/orders/{id}/repeat": {"post": {"tags": ["Заказы"], "summary": "Ждать ещё один код", "description": "Если по номеру уже пришёл код, а нужен ещё один (например, повторная отправка), вызовите этот метод: заказ снова перейдёт в ожидание новых кодов до конца 20 минут с момента покупки. Новый код добавится в `codes`.", "security": [{"bearerAuth": []}], "parameters": [{"name": "id", "in": "path", "required": true, "description": "ID заказа.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"id": "ord_3f9a1c7b2d4e", "service": "Telegram", "service_id": "tg", "phone": "79991234567", "price": 0.45, "status": "code_received", "codes": ["48213"], "code": "48213", "created_at": 1760000000, "expires_at": 1760001200, "can_cancel": false, "cancel_available_in": 0}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/orders/{id}/finish": {"post": {"tags": ["Заказы"], "summary": "Завершить заказ", "description": "Сообщает, что код получен и номер больше не нужен: заказ закрывается (статус `completed`). Освобождает ресурсы, рекомендуется вызывать после получения кода. Если не вызвать — заказ закроется сам к концу срока.", "security": [{"bearerAuth": []}], "parameters": [{"name": "id", "in": "path", "required": true, "description": "ID заказа.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"id": "ord_3f9a1c7b2d4e", "service": "Telegram", "service_id": "tg", "phone": "79991234567", "price": 0.45, "status": "completed", "codes": ["48213"], "code": "48213", "created_at": 1760000000, "expires_at": 1760001200, "can_cancel": false, "cancel_available_in": 0}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/webhook": {"put": {"tags": ["Вебхук"], "summary": "Задать вебхук", "description": "Адрес, на который мы сами отправим POST, когда по заказу придёт код или заказ отменится. Так не нужно постоянно опрашивать статус. В ответе — секрет для проверки подписи (показывается только сейчас). Подробности — в разделе «Вебхуки».", "security": [{"bearerAuth": []}], "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"url": "https://example.com/hooks/sms", "secret": "whsec_3b1f…"}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"url": {"type": "string", "description": "Публичный http(s)-адрес. Адреса внутренних сетей не принимаются."}}, "required": ["url"]}, "example": {"url": "https://example.com/hooks/sms"}}}}}, "delete": {"tags": ["Вебхук"], "summary": "Убрать вебхук", "description": "Отключает отправку уведомлений.", "security": [{"bearerAuth": []}], "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"url": null}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}, "/v1/webhook/test": {"post": {"tags": ["Вебхук"], "summary": "Проверить вебхук", "description": "Отправляет на ваш адрес тестовое событие `ping` и показывает, что ответил ваш сервер.", "security": [{"bearerAuth": []}], "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"example": {"ok": true, "data": {"delivered": true, "http_status": 200}}}}}, "default": {"description": "Ошибка", "content": {"application/json": {"example": {"ok": false, "error": {"code": "unauthorized", "message": "..."}}}}}}}}}}