{ "openapi": "3.1.0", "info": { "title": "AdaptGroup Shop API", "version": "0.1.0", "description": "API for Telegram Stars, Telegram Premium, game/account topups and digital codes.\n\n**Base URL:** `https://shop-api.adaptgroup.pro`\n\nSend `X-Api-Key` in the header and `api_key_id` in every JSON request. All endpoints use POST. All amounts are in USD. Limit: 100 requests per 60 seconds per integration across all endpoints.\n\nCatalog prices include the platform markup. Do not send a price when buying: the current amount is charged to the integration balance.\n\nDocumentation is published ahead of the public rollout. End-to-end production testing is pending. Examples use illustrative IDs and prices; they are not live catalog offers.\n\n[Download OpenAPI (EN)](/openapi/shop.json) · [OpenAPI (RU)](/openapi/shop.ru.json)", "contact": { "name": "AdaptGroup", "url": "https://t.me/adapt_support", "email": "support@adaptgroup.org" } }, "paths": { "/balance/check": { "post": { "tags": [ "Balance" ], "summary": "Check balance", "operationId": "checkBalance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRequest" }, "examples": { "balance": { "summary": "Balance", "value": { "api_key_id": 1 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceCheckResponse" }, "examples": { "balance": { "summary": "Balance", "value": { "success": true, "api_key_id": 1, "balance": "25.0000", "currency": "USD", "balance_updated_at": "2026-09-26T12:00:00" } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the current balance of your integration, not a cached price estimate. The balance is in USD." } }, "/modules/list": { "post": { "tags": [ "Catalog" ], "summary": "List modules", "operationId": "listModules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRequest" }, "examples": { "modules": { "summary": "Modules", "value": { "api_key_id": 1 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModulesResponse" }, "examples": { "modules": { "summary": "Modules", "value": { "success": true, "currency": "USD", "modules": { "stars": { "price_per_star_usd": "0.0150" }, "tg_premium": { "nominals": [ { "months": 3, "price_usd": "12.0000" }, { "months": 6, "price_usd": "16.0000" }, { "months": 12, "price_usd": "29.0000" } ] }, "topups": { "items_count": 10, "nominals_count": 50 }, "codes": { "items_count": 8, "nominals_count": 20 } } } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists Stars and Premium prices and the catalog counts for topups and codes. A null price means unavailable. Amounts and IDs in examples are illustrative." } }, "/catalog/list": { "post": { "tags": [ "Catalog" ], "summary": "List products", "operationId": "listCatalog", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogListRequest" }, "examples": { "topups": { "summary": "Topups", "value": { "api_key_id": 1, "module": "topups", "query": "Example", "limit": 50, "offset": 0 } }, "codes": { "summary": "Codes", "value": { "api_key_id": 1, "module": "codes", "limit": 50, "offset": 0 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogListResponse" }, "examples": { "catalog": { "summary": "Product list", "value": { "success": true, "items": [ { "id": 10, "name": "Example Game", "description": "Game account top-ups", "image_url": null, "nominals_count": 2 } ], "total_count": 1, "limit": 50, "offset": 0 } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Lists active catalog products for topups or codes. To obtain denominations and prices, use /catalog/details. Not used for Stars or Premium." } }, "/catalog/details": { "post": { "tags": [ "Catalog" ], "summary": "Product details", "operationId": "getCatalogItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogDetailsRequest" }, "examples": { "topups": { "summary": "Topups", "value": { "api_key_id": 1, "module": "topups", "item_id": 10 } }, "codes": { "summary": "Codes", "value": { "api_key_id": 1, "module": "codes", "item_id": 20 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogDetailsResponse" }, "examples": { "item": { "summary": "Product and nominals", "value": { "success": true, "currency": "USD", "item": { "id": 10, "name": "Example Game", "description": "Game account top-ups", "image_url": null, "nominals_count": 2, "nominals": [ { "id": 11, "name": "60 credits", "price_usd": "0.9800", "available": true }, { "id": 13, "name": "300 credits", "price_usd": null, "available": false } ] } } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "404": { "description": "Product, nominal or order not found in the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the product and its active nominals with your API prices per unit. An unavailable price may be null with available=false. Retrieve the chosen nominal's input_fields via /catalog/nominal." } }, "/catalog/nominal": { "post": { "tags": [ "Catalog" ], "summary": "Nominal details", "operationId": "getCatalogNominal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNominalRequest" }, "examples": { "topups": { "summary": "Topups", "value": { "api_key_id": 1, "module": "topups", "item_id": 10, "nominal_id": 11 } }, "codes": { "summary": "Codes", "value": { "api_key_id": 1, "module": "codes", "item_id": 20, "nominal_id": 12 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNominalResponse" }, "examples": { "topups": { "summary": "Topups", "value": { "success": true, "currency": "USD", "nominal": { "id": 11, "item_id": 10, "name": "60 credits", "price_usd": "0.9800", "available": true, "input_fields": [ { "key": "playerId", "label": "UID", "type": "input", "required": true, "options": [] }, { "key": "server", "label": "Server", "type": "select", "required": true, "options": [ { "key": "eu", "label": "Europe" }, { "key": "asia", "label": "Asia" } ] } ] } } }, "codes": { "summary": "Codes", "value": { "success": true, "currency": "USD", "nominal": { "id": 12, "item_id": 20, "name": "Gift code", "price_usd": "0.9800", "available": true, "input_fields": [] } } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "404": { "description": "Product, nominal or order not found in the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Invalid upstream response or recipient verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Catalog or recipient verification timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the selected nominal's price, availability and current recipient fields, including server choices. IDs belong to AdaptGroup. Field names in the example are illustrative: always use the actual input_fields keys and options. Codes have no recipient fields." } }, "/orders/quote": { "post": { "tags": [ "Orders" ], "summary": "Calculate price", "operationId": "quoteOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StarsQuoteRequest" }, { "$ref": "#/components/schemas/PremiumQuoteRequest" }, { "$ref": "#/components/schemas/CatalogQuoteRequest" } ], "discriminator": { "propertyName": "module", "mapping": { "stars": "#/components/schemas/StarsQuoteRequest", "tg_premium": "#/components/schemas/PremiumQuoteRequest", "topups": "#/components/schemas/CatalogQuoteRequest", "codes": "#/components/schemas/CatalogQuoteRequest" } }, "title": "Data" }, "examples": { "stars": { "summary": "Telegram Stars", "value": { "api_key_id": 1, "module": "stars", "stars_amount": 50 } }, "premium": { "summary": "Telegram Premium", "value": { "api_key_id": 1, "module": "tg_premium", "months": 3 } }, "topups": { "summary": "Topups", "value": { "api_key_id": 1, "module": "topups", "nominal_id": 11, "quantity": 1 } }, "codes": { "summary": "Codes", "value": { "api_key_id": 1, "module": "codes", "nominal_id": 12, "quantity": 1 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderQuoteResponse" }, "examples": { "quote": { "summary": "Total price", "value": { "success": true, "module": "codes", "amount_usd": "0.9800", "currency": "USD" } } } } } }, "400": { "description": "Request cannot be fulfilled (for example insufficient balance, invalid recipient or unavailable nominal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "404": { "description": "Product, nominal or order not found in the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Invalid upstream response or recipient verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Catalog or recipient verification timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Calculates the current total in USD without checking the integration balance, reserving stock or creating an order. The quote does not lock the price. Do not send a price to /orders/create: it recalculates and charges the current amount." } }, "/orders/create": { "post": { "tags": [ "Orders" ], "summary": "Create order", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StarsCreateRequest" }, { "$ref": "#/components/schemas/PremiumCreateRequest" }, { "$ref": "#/components/schemas/TopupsCreateRequest" }, { "$ref": "#/components/schemas/CodesCreateRequest" } ], "discriminator": { "propertyName": "module", "mapping": { "stars": "#/components/schemas/StarsCreateRequest", "tg_premium": "#/components/schemas/PremiumCreateRequest", "topups": "#/components/schemas/TopupsCreateRequest", "codes": "#/components/schemas/CodesCreateRequest" } }, "title": "Data" }, "examples": { "stars": { "summary": "Telegram Stars", "value": { "api_key_id": 1, "module": "stars", "stars_amount": 50, "username": "example_user", "api_user_id": "customer-789", "partner_order_id": "order-456" } }, "premium": { "summary": "Telegram Premium", "value": { "api_key_id": 1, "module": "tg_premium", "months": 3, "username": "example_user", "api_user_id": "customer-789", "partner_order_id": "order-456" } }, "topups": { "summary": "Topups", "value": { "api_key_id": 1, "module": "topups", "nominal_id": 11, "quantity": 1, "recipient_data": { "playerId": "123456789", "server": "eu" }, "api_user_id": "customer-789", "partner_order_id": "order-456" } }, "codes": { "summary": "Codes", "value": { "api_key_id": 1, "module": "codes", "nominal_id": 12, "quantity": 1, "api_user_id": "customer-789", "partner_order_id": "order-456" } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateResponse" }, "examples": { "processing": { "summary": "Accepted for processing", "value": { "success": true, "order_id": 125, "partner_order_id": "order-456", "status": "processing", "amount_usd": "0.9800", "currency": "USD" } }, "completed": { "summary": "Completed", "value": { "success": true, "order_id": 125, "partner_order_id": "order-456", "status": "completed", "amount_usd": "0.9800", "currency": "USD" } }, "review": { "summary": "Result not confirmed", "value": { "success": false, "order_id": 125, "partner_order_id": "order-456", "status": "review", "amount_usd": "0.9800", "currency": "USD" } }, "refunded": { "summary": "Refunded", "value": { "success": false, "order_id": 125, "partner_order_id": "order-456", "status": "refunded", "amount_usd": "0.9800", "currency": "USD" } } } } } }, "400": { "description": "Request cannot be fulfilled (for example insufficient balance, invalid recipient or unavailable nominal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Insufficient balance" } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "404": { "description": "Product, nominal or order not found in the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Invalid upstream response or recipient verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable or creation result uncertain. If detail is an object with order_id, check /orders/status; do not repeat the purchase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreationUnavailable" }, "examples": { "unavailable": { "summary": "Unavailable", "value": { "detail": "Order creation unavailable" } }, "uncertain": { "summary": "Uncertain result", "value": { "detail": { "message": "Order creation result unknown; check order status", "order_id": 125, "partner_order_id": "order-456" } } } } } } }, "504": { "description": "Catalog or recipient verification timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a separate purchase on every call and charges the current price. Choose exactly one module request variant. api_user_id identifies your customer; optional partner_order_id links the order to your system but does not deduplicate requests. There is no request_id or client price field. HTTP 200 with processing means accepted, not delivered. Read status even when success=false: review is an uncertain result, refunded means funds were returned. Use /orders/status or final webhooks for the outcome and codes. Never automatically repeat this request after a timeout or uncertain result; see Purchase flow." } }, "/orders/status": { "post": { "tags": [ "Orders" ], "summary": "Order status", "operationId": "getOrderStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusRequest" }, "examples": { "status": { "summary": "Order status", "value": { "api_key_id": 1, "order_id": 125 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusResponse" }, "examples": { "completed": { "summary": "Completed", "value": { "success": true, "order": { "order_id": 125, "partner_order_id": "order-456", "api_user_id": "customer-789", "module": "codes", "nominal_id": 12, "quantity": 1, "stars_amount": null, "months": null, "amount_usd": "0.9800", "currency": "USD", "status": "completed", "created_at": "2026-09-26T12:00:00", "updated_at": "2026-09-26T12:00:05", "completed_at": "2026-09-26T12:00:05", "recipient_data": {}, "codes": [ { "content": "EXAMPLE-CODE", "number": null, "pin": null } ] } } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "404": { "description": "Product, nominal or order not found in the requested scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the saved status and result of an order belonging to this integration. success=true means the lookup succeeded, not that the order completed. Codes are returned only for completed codes orders. This request never starts another purchase." } }, "/orders/list": { "post": { "tags": [ "Orders" ], "summary": "Order history", "operationId": "listOrders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListRequest" }, "examples": { "all": { "summary": "All orders", "value": { "api_key_id": 1, "limit": 50, "offset": 0 } }, "filtered": { "summary": "With filters", "value": { "api_key_id": 1, "module": "codes", "status": "completed", "api_user_id": "customer-789", "partner_order_id": "order-456", "date_from": "2026-09-01T00:00:00Z", "date_to": "2026-09-30T23:59:59Z", "limit": 50, "offset": 0 } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" }, "examples": { "orders": { "summary": "Order history", "value": { "success": true, "orders": [ { "order_id": 125, "partner_order_id": "order-456", "api_user_id": "customer-789", "module": "codes", "nominal_id": 12, "quantity": 1, "stars_amount": null, "months": null, "amount_usd": "0.9800", "currency": "USD", "status": "completed", "created_at": "2026-09-26T12:00:00", "updated_at": "2026-09-26T12:00:05", "completed_at": "2026-09-26T12:00:05" } ], "total_count": 1, "limit": 50, "offset": 0 } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns orders of this integration, newest first by created_at and order ID. Filters are combined. api_user_id and partner_order_id are exact matches; multiple orders can have the same partner_order_id. Date bounds are inclusive and interpreted in UTC. Issued codes and recipient data are available via /orders/status, not this list." } }, "/recipient/check": { "post": { "tags": [ "Recipients" ], "summary": "Check recipient", "operationId": "checkRecipient", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StarsRecipientRequest" }, { "$ref": "#/components/schemas/PremiumRecipientRequest" }, { "$ref": "#/components/schemas/TopupsRecipientRequest" } ], "discriminator": { "propertyName": "module", "mapping": { "stars": "#/components/schemas/StarsRecipientRequest", "tg_premium": "#/components/schemas/PremiumRecipientRequest", "topups": "#/components/schemas/TopupsRecipientRequest" } }, "title": "Data" }, "examples": { "stars": { "summary": "Telegram Stars", "value": { "api_key_id": 1, "module": "stars", "username": "example_user", "stars_amount": 50 } }, "premium": { "summary": "Telegram Premium", "value": { "api_key_id": 1, "module": "tg_premium", "username": "example_user", "months": 3 } }, "topups": { "summary": "Topups", "value": { "api_key_id": 1, "module": "topups", "nominal_id": 11, "recipient_data": { "playerId": "123456789", "server": "eu" } } } } } } }, "responses": { "200": { "description": "Operation result; inspect success and status/valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientCheckResponse" }, "examples": { "valid": { "summary": "Recipient verified", "value": { "success": true, "valid": true, "supported": true, "code": "recipient_valid", "retryable": false, "message": "Recipient verified", "username": "example_user", "display_name": "Example User" } }, "invalid": { "summary": "Recipient not found", "value": { "success": true, "valid": false, "supported": true, "code": "recipient_not_found", "retryable": false, "message": "Recipient not found", "username": null, "display_name": null } }, "unsupported": { "summary": "Verification not supported", "value": { "success": true, "valid": false, "supported": false, "code": "validation_unsupported", "retryable": false, "message": "Recipient verification is not supported for this product", "username": null, "display_name": null } }, "unavailable": { "summary": "Verification unavailable", "value": { "success": false, "valid": false, "supported": null, "code": "recipient_check_unavailable", "retryable": true, "message": "Recipient verification temporarily unavailable", "username": null, "display_name": null } } } } } }, "401": { "description": "Missing/invalid API key, wrong integration ID or inactive integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Invalid api_key or api_key_id" } } } }, "422": { "description": "Request validation failed, including unknown fields or an invalid module variant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Integration rate limit exceeded: 100 requests per 60 seconds across all public endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "Too many requests" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Invalid upstream response or recipient verification response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service or data temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Catalog or recipient verification timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Checks a Telegram username or topup recipient without creating an order or charging the balance. Codes require no recipient check. HTTP 200 may contain valid=false or success=false: inspect all result flags. For topups, validation_unsupported with success=true and supported=false permits purchasing but does not verify the recipient. The purchase checks the recipient again." } } }, "components": { "schemas": { "ApiRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id" ], "title": "ApiRequest", "description": "Request JSON. Unknown fields are rejected." }, "BalanceCheckResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "api_key_id": { "type": "integer", "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "balance": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "description": "Current integration balance in USD, serialized as a decimal string." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." }, "balance_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Last balance change in UTC; null if unavailable. Timestamps may have no timezone suffix." } }, "type": "object", "required": [ "success", "api_key_id", "balance" ], "title": "BalanceCheckResponse" }, "CatalogDetailsRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "enum": [ "topups", "codes" ], "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "item_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Product ID returned by /catalog/list. It is not a nominal ID." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "item_id" ], "title": "CatalogDetailsRequest", "description": "Request JSON. Unknown fields are rejected." }, "CatalogDetailsResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." }, "item": { "$ref": "#/components/schemas/CatalogItemDetails", "description": "Product with its active nominals." } }, "type": "object", "required": [ "success", "item" ], "title": "CatalogDetailsResponse" }, "CatalogItem": { "properties": { "id": { "type": "integer", "description": "AdaptGroup identifier of this item." }, "name": { "type": "string", "description": "Catalog name set by the administrator." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Catalog description, or null." }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Absolute product image URL, or null." }, "nominals_count": { "type": "integer", "description": "Number of active nominals in the catalog; not the stock quantity." } }, "type": "object", "required": [ "id", "name", "description", "image_url", "nominals_count" ], "title": "CatalogItem" }, "CatalogItemDetails": { "properties": { "id": { "type": "integer", "description": "AdaptGroup identifier of this item." }, "name": { "type": "string", "description": "Catalog name set by the administrator." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Catalog description, or null." }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Absolute product image URL, or null." }, "nominals_count": { "type": "integer", "description": "Number of active nominals in the catalog; not the stock quantity." }, "nominals": { "items": { "$ref": "#/components/schemas/NominalSummary" }, "type": "array", "description": "Available denominations or subscription durations." } }, "type": "object", "required": [ "id", "name", "description", "image_url", "nominals_count", "nominals" ], "title": "CatalogItemDetails" }, "CatalogListRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "enum": [ "topups", "codes" ], "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "query": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "description": "Case-insensitive search by product name. Empty or whitespace-only means no filter." }, "limit": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "description": "Page size, 1–200; default 50." }, "offset": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "description": "Number of records to skip; default 0." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module" ], "title": "CatalogListRequest", "description": "Request JSON. Unknown fields are rejected." }, "CatalogListResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "items": { "items": { "$ref": "#/components/schemas/CatalogItem" }, "type": "array", "description": "Products matching the filters." }, "total_count": { "type": "integer", "description": "Total number of records matching the filters before pagination." }, "limit": { "type": "integer", "description": "Page size, 1–200; default 50." }, "offset": { "type": "integer", "description": "Number of records to skip; default 0." } }, "type": "object", "required": [ "success", "items", "total_count", "limit", "offset" ], "title": "CatalogListResponse" }, "CatalogModule": { "properties": { "items_count": { "type": "integer", "description": "Number of active catalog products." }, "nominals_count": { "type": "integer", "description": "Number of active nominals in the catalog; not the stock quantity." } }, "type": "object", "required": [ "items_count", "nominals_count" ], "title": "CatalogModule" }, "CatalogNominal": { "properties": { "id": { "type": "integer", "description": "AdaptGroup identifier of this item." }, "name": { "type": "string", "description": "Catalog name set by the administrator." }, "price_usd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your API price for one nominal unit in USD, including the platform markup. Null if unavailable." }, "available": { "type": "boolean", "description": "Whether the nominal is currently available. Availability is checked again when purchasing." }, "item_id": { "type": "integer", "description": "Product ID returned by /catalog/list. It is not a nominal ID." }, "input_fields": { "items": { "$ref": "#/components/schemas/RecipientField" }, "type": "array", "description": "Fields to collect for this nominal. Empty for codes. Retrieve the selected nominal's current fields before checking or buying." } }, "type": "object", "required": [ "id", "name", "price_usd", "available", "item_id", "input_fields" ], "title": "CatalogNominal" }, "CatalogNominalRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "enum": [ "topups", "codes" ], "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "item_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Product ID returned by /catalog/list. It is not a nominal ID." }, "nominal_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "item_id", "nominal_id" ], "title": "CatalogNominalRequest", "description": "Request JSON. Unknown fields are rejected." }, "CatalogNominalResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." }, "nominal": { "$ref": "#/components/schemas/CatalogNominal", "description": "Selected nominal with price and recipient fields." } }, "type": "object", "required": [ "success", "nominal" ], "title": "CatalogNominalResponse" }, "CatalogQuoteRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "enum": [ "topups", "codes" ], "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "nominal_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." }, "quantity": { "type": "integer", "maximum": 2147483647, "minimum": 1, "default": 1, "description": "Number of nominal units. For topups/codes, defaults to 1. The effective limit may depend on the nominal and available stock. Stars/Premium orders store quantity=1; use stars_amount/months for their value." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "nominal_id" ], "title": "CatalogQuoteRequest", "description": "Request JSON. Unknown fields are rejected." }, "CodesCreateRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "codes", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "nominal_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." }, "quantity": { "type": "integer", "maximum": 2147483647, "minimum": 1, "default": 1, "description": "Number of nominal units. For topups/codes, defaults to 1. The effective limit may depend on the nominal and available stock. Stars/Premium orders store quantity=1; use stars_amount/months for their value." }, "api_user_id": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S", "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "partner_order_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "nominal_id", "api_user_id" ], "title": "CodesCreateRequest", "description": "Request JSON. Unknown fields are rejected." }, "ComplianceInfo": { "properties": { "paymentMethod": { "type": "string", "enum": [ "credit_card", "debit_card", "digital_wallet", "bank_transfer", "crypto", "other" ], "description": "Payment method used by your customer." }, "playerIp": { "type": "string", "format": "ipvanyaddress", "description": "Customer's actual IPv4 or IPv6 address. Do not substitute your server's address." }, "sellerName": { "type": "string", "maxLength": 85, "minLength": 1, "pattern": "\\S", "description": "Seller name, 1–85 characters; a whitespace-only value is not accepted." } }, "additionalProperties": false, "type": "object", "required": [ "paymentMethod", "playerIp", "sellerName" ], "title": "ComplianceInfo" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "description": "Error details. Validation errors return an array; most other errors return a string." } }, "type": "object", "title": "HTTPValidationError" }, "Modules": { "properties": { "stars": { "$ref": "#/components/schemas/StarsModule", "description": "Telegram Stars." }, "tg_premium": { "$ref": "#/components/schemas/PremiumModule", "description": "Telegram Premium." }, "topups": { "$ref": "#/components/schemas/CatalogModule", "description": "Game/account topups." }, "codes": { "$ref": "#/components/schemas/CatalogModule", "description": "Digital codes." } }, "type": "object", "required": [ "stars", "tg_premium", "topups", "codes" ], "title": "Modules" }, "ModulesResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." }, "modules": { "$ref": "#/components/schemas/Modules", "description": "The four supported modules: stars, tg_premium, topups and codes." } }, "type": "object", "required": [ "success", "modules" ], "title": "ModulesResponse" }, "NominalSummary": { "properties": { "id": { "type": "integer", "description": "AdaptGroup identifier of this item." }, "name": { "type": "string", "description": "Catalog name set by the administrator." }, "price_usd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your API price for one nominal unit in USD, including the platform markup. Null if unavailable." }, "available": { "type": "boolean", "description": "Whether the nominal is currently available. Availability is checked again when purchasing." } }, "type": "object", "required": [ "id", "name", "price_usd", "available" ], "title": "NominalSummary" }, "OrderCode": { "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Issued code content if present." }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Issued card number if present." }, "pin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Issued PIN if present." } }, "type": "object", "title": "OrderCode" }, "OrderCreateResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "order_id": { "type": "integer", "description": "AdaptGroup order ID. Use it to retrieve the result without creating another purchase." }, "partner_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "status": { "type": "string", "description": "Order status. Current purchase flow uses review, processing, completed and refunded; pending and failed are also accepted by history filters. See Purchase flow." }, "amount_usd": { "type": "string", "description": "Total price in USD as a decimal string. A quote is indicative; an order contains the amount actually charged." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." } }, "type": "object", "required": [ "success", "order_id", "partner_order_id", "status", "amount_usd" ], "title": "OrderCreateResponse" }, "OrderDetails": { "properties": { "order_id": { "type": "integer", "description": "AdaptGroup order ID. Use it to retrieve the result without creating another purchase." }, "partner_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "api_user_id": { "type": "string", "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "module": { "type": "string", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "nominal_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." }, "quantity": { "type": "integer", "description": "Number of nominal units. For topups/codes, defaults to 1. The effective limit may depend on the nominal and available stock. Stars/Premium orders store quantity=1; use stars_amount/months for their value." }, "stars_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of Telegram Stars: an integer from 50 to 100000." }, "months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Telegram Premium subscription duration: 3, 6 or 12 months." }, "amount_usd": { "type": "string", "description": "Total price in USD as a decimal string. A quote is indicative; an order contains the amount actually charged." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." }, "status": { "type": "string", "description": "Order status. Current purchase flow uses review, processing, completed and refunded; pending and failed are also accepted by history filters. See Purchase flow." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time in UTC. The response may omit the timezone suffix." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Last change in UTC, or null." }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Completion or refund time in UTC, or null." }, "recipient_data": { "additionalProperties": { "type": "string" }, "type": "object", "description": "String key/value pairs from the selected nominal's input_fields. Send option.key, not its label. Preserve key spelling and case. Do not send this field for codes." }, "codes": { "items": { "$ref": "#/components/schemas/OrderCode" }, "type": "array", "description": "Issued codes for a completed codes order only; otherwise an empty array. Each code may contain content, number and/or pin." } }, "type": "object", "required": [ "order_id", "partner_order_id", "api_user_id", "module", "nominal_id", "quantity", "stars_amount", "months", "amount_usd", "status", "created_at", "updated_at", "completed_at", "recipient_data", "codes" ], "title": "OrderDetails" }, "OrderListRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "anyOf": [ { "type": "string", "maxLength": 20, "minLength": 1 }, { "type": "null" } ], "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "refunded", "review" ] }, { "type": "null" } ], "description": "Order status. Current purchase flow uses review, processing, completed and refunded; pending and failed are also accepted by history filters. See Purchase flow." }, "api_user_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "partner_order_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "date_from": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Inclusive lower bound for order creation time. ISO 8601; offsets are converted to UTC. A value without an offset is treated as UTC." }, "date_to": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Inclusive upper bound for order creation time. Must not precede date_from." }, "limit": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "description": "Page size, 1–200; default 50." }, "offset": { "type": "integer", "maximum": 9223372036854775807, "minimum": 0, "default": 0, "description": "Number of records to skip; default 0." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id" ], "title": "OrderListRequest", "description": "Request JSON. Unknown fields are rejected." }, "OrderListResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "orders": { "items": { "$ref": "#/components/schemas/OrderSummary" }, "type": "array", "description": "Orders of this integration, newest first. Issued codes are not included; use /orders/status." }, "total_count": { "type": "integer", "description": "Total number of records matching the filters before pagination." }, "limit": { "type": "integer", "description": "Page size, 1–200; default 50." }, "offset": { "type": "integer", "description": "Number of records to skip; default 0." } }, "type": "object", "required": [ "success", "orders", "total_count", "limit", "offset" ], "title": "OrderListResponse" }, "OrderQuoteResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "module": { "type": "string", "enum": [ "stars", "tg_premium", "topups", "codes" ], "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "amount_usd": { "type": "string", "description": "Total price in USD as a decimal string. A quote is indicative; an order contains the amount actually charged." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." } }, "type": "object", "required": [ "success", "module", "amount_usd" ], "title": "OrderQuoteResponse" }, "OrderStatusRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "order_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "AdaptGroup order ID. Use it to retrieve the result without creating another purchase." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "order_id" ], "title": "OrderStatusRequest", "description": "Request JSON. Unknown fields are rejected." }, "OrderStatusResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "order": { "$ref": "#/components/schemas/OrderDetails", "description": "Saved order and its result belonging to this integration." } }, "type": "object", "required": [ "success", "order" ], "title": "OrderStatusResponse" }, "OrderSummary": { "properties": { "order_id": { "type": "integer", "description": "AdaptGroup order ID. Use it to retrieve the result without creating another purchase." }, "partner_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "api_user_id": { "type": "string", "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "module": { "type": "string", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "nominal_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." }, "quantity": { "type": "integer", "description": "Number of nominal units. For topups/codes, defaults to 1. The effective limit may depend on the nominal and available stock. Stars/Premium orders store quantity=1; use stars_amount/months for their value." }, "stars_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of Telegram Stars: an integer from 50 to 100000." }, "months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Telegram Premium subscription duration: 3, 6 or 12 months." }, "amount_usd": { "type": "string", "description": "Total price in USD as a decimal string. A quote is indicative; an order contains the amount actually charged." }, "currency": { "type": "string", "const": "USD", "default": "USD", "description": "All prices and balances use USD." }, "status": { "type": "string", "description": "Order status. Current purchase flow uses review, processing, completed and refunded; pending and failed are also accepted by history filters. See Purchase flow." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time in UTC. The response may omit the timezone suffix." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Last change in UTC, or null." }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Completion or refund time in UTC, or null." } }, "type": "object", "required": [ "order_id", "partner_order_id", "api_user_id", "module", "nominal_id", "quantity", "stars_amount", "months", "amount_usd", "status", "created_at", "updated_at", "completed_at" ], "title": "OrderSummary" }, "PremiumCreateRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "tg_premium", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "months": { "type": "integer", "enum": [ 3, 6, 12 ], "description": "Telegram Premium subscription duration: 3, 6 or 12 months." }, "api_user_id": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S", "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "partner_order_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "username": { "type": "string", "minLength": 1, "description": "Recipient's public Telegram username; an initial @ is accepted. Do not pass a numeric Telegram ID." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "months", "api_user_id", "username" ], "title": "PremiumCreateRequest", "description": "Request JSON. Unknown fields are rejected." }, "PremiumModule": { "properties": { "nominals": { "items": { "$ref": "#/components/schemas/PremiumNominal" }, "type": "array", "description": "Available denominations or subscription durations." } }, "type": "object", "required": [ "nominals" ], "title": "PremiumModule" }, "PremiumNominal": { "properties": { "months": { "type": "integer", "enum": [ 3, 6, 12 ], "description": "Telegram Premium subscription duration: 3, 6 or 12 months." }, "price_usd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your API price for one nominal unit in USD, including the platform markup. Null if unavailable." } }, "type": "object", "required": [ "months", "price_usd" ], "title": "PremiumNominal" }, "PremiumQuoteRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "tg_premium", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "months": { "type": "integer", "enum": [ 3, 6, 12 ], "description": "Telegram Premium subscription duration: 3, 6 or 12 months." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "months" ], "title": "PremiumQuoteRequest", "description": "Request JSON. Unknown fields are rejected." }, "PremiumRecipientRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "tg_premium", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "username": { "type": "string", "minLength": 1, "description": "Recipient's public Telegram username; an initial @ is accepted. Do not pass a numeric Telegram ID." }, "months": { "type": "integer", "enum": [ 3, 6, 12 ], "description": "Telegram Premium subscription duration: 3, 6 or 12 months." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "username", "months" ], "title": "PremiumRecipientRequest", "description": "Request JSON. Unknown fields are rejected." }, "RecipientCheckResponse": { "properties": { "success": { "type": "boolean", "description": "Result of this operation. See the endpoint description: HTTP 200 does not always mean the purchase is complete." }, "valid": { "type": "boolean", "description": "Whether the recipient was verified. Check together with success, supported and code." }, "supported": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether recipient verification is supported. For topups, false with code=validation_unsupported is not proof that the recipient is invalid." }, "code": { "type": "string", "description": "Machine-readable recipient-check result. See the response examples and Purchase flow." }, "retryable": { "type": "boolean", "description": "Whether this recipient check can be retried. This flag never authorizes replaying /orders/create." }, "message": { "type": "string", "description": "Human-readable result message. Do not use it instead of code for application logic." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized Telegram username if available; otherwise null." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient display name if available; otherwise null." } }, "type": "object", "required": [ "success", "valid", "code", "retryable", "message" ], "title": "RecipientCheckResponse" }, "RecipientField": { "properties": { "key": { "type": "string", "description": "Machine-readable field or option key to use in recipient_data; preserve case." }, "label": { "type": "string", "description": "Display label. Do not use the label instead of the key." }, "type": { "type": "string", "enum": [ "input", "select", "radio", "check" ], "description": "Input control: input, select, radio or check. All recipient_data values are strings; for choices send one option.key, not an array." }, "required": { "type": "boolean", "description": "Whether the recipient field must be filled in." }, "options": { "items": { "$ref": "#/components/schemas/RecipientOption" }, "type": "array", "description": "Available choices. Send the selected option's key as a string." } }, "type": "object", "required": [ "key", "label", "type", "required", "options" ], "title": "RecipientField" }, "RecipientOption": { "properties": { "key": { "type": "string", "description": "Machine-readable field or option key to use in recipient_data; preserve case." }, "label": { "type": "string", "description": "Display label. Do not use the label instead of the key." } }, "type": "object", "required": [ "key", "label" ], "title": "RecipientOption" }, "StarsCreateRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "stars", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "stars_amount": { "type": "integer", "maximum": 100000, "minimum": 50, "description": "Number of Telegram Stars: an integer from 50 to 100000." }, "api_user_id": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S", "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "partner_order_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "username": { "type": "string", "minLength": 1, "description": "Recipient's public Telegram username; an initial @ is accepted. Do not pass a numeric Telegram ID." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "stars_amount", "api_user_id", "username" ], "title": "StarsCreateRequest", "description": "Request JSON. Unknown fields are rejected." }, "StarsModule": { "properties": { "price_per_star_usd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your API price for one Telegram Star in USD. Null if no valid price is configured." } }, "type": "object", "required": [ "price_per_star_usd" ], "title": "StarsModule" }, "StarsQuoteRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "stars", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "stars_amount": { "type": "integer", "maximum": 100000, "minimum": 50, "description": "Number of Telegram Stars: an integer from 50 to 100000." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "stars_amount" ], "title": "StarsQuoteRequest", "description": "Request JSON. Unknown fields are rejected." }, "StarsRecipientRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "stars", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "username": { "type": "string", "minLength": 1, "description": "Recipient's public Telegram username; an initial @ is accepted. Do not pass a numeric Telegram ID." }, "stars_amount": { "type": "integer", "maximum": 100000, "minimum": 50, "description": "Number of Telegram Stars: an integer from 50 to 100000." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "username", "stars_amount" ], "title": "StarsRecipientRequest", "description": "Request JSON. Unknown fields are rejected." }, "TopupsCreateRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "topups", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "nominal_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." }, "quantity": { "type": "integer", "maximum": 2147483647, "minimum": 1, "default": 1, "description": "Number of nominal units. For topups/codes, defaults to 1. The effective limit may depend on the nominal and available stock. Stars/Premium orders store quantity=1; use stars_amount/months for their value." }, "api_user_id": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S", "description": "Your customer's ID as a non-blank string (1–255 characters). This is not required to be a Telegram ID." }, "partner_order_id": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "description": "Optional order ID in your system, returned unchanged and usable as an exact history filter. It is not unique and does not prevent repeated purchases." }, "recipient_data": { "additionalProperties": { "type": "string" }, "type": "object", "description": "String key/value pairs from the selected nominal's input_fields. Send option.key, not its label. Preserve key spelling and case. Do not send this field for codes." }, "compliance_info": { "anyOf": [ { "$ref": "#/components/schemas/ComplianceInfo" }, { "type": "null" } ], "description": "Optional purchase compliance details for nominals that accept them. Not required by default; do not send for other nominals. An unsupported nominal returns HTTP 400. Does not replace recipient_data." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "nominal_id", "api_user_id", "recipient_data" ], "title": "TopupsCreateRequest", "description": "Request JSON. Unknown fields are rejected." }, "TopupsRecipientRequest": { "properties": { "api_key_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "Integration ID from the dashboard. Send it in the JSON body of every request." }, "module": { "type": "string", "const": "topups", "description": "Module identifier. Choose the matching request variant; fields of other modules must not be sent." }, "nominal_id": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "description": "AdaptGroup nominal ID, not a product ID. Use the ID returned by /catalog/details or /catalog/nominal." }, "recipient_data": { "additionalProperties": { "type": "string" }, "type": "object", "description": "String key/value pairs from the selected nominal's input_fields. Send option.key, not its label. Preserve key spelling and case. Do not send this field for codes." } }, "additionalProperties": false, "type": "object", "required": [ "api_key_id", "module", "nominal_id", "recipient_data" ], "title": "TopupsRecipientRequest", "description": "Request JSON. Unknown fields are rejected." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "description": "Location of the invalid field." }, "msg": { "type": "string", "description": "Validation error message." }, "type": { "type": "string", "description": "Machine-readable validation error type." } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ErrorResponse": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string", "description": "Error description." } } }, "OrderCreationUnavailable": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "message", "order_id", "partner_order_id" ], "properties": { "message": { "type": "string" }, "order_id": { "type": "integer" }, "partner_order_id": { "type": [ "string", "null" ] } } } ] } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key from integration settings in the dashboard. Keep it in your server-side code." } } }, "servers": [ { "url": "https://shop-api.adaptgroup.pro", "description": "Shop API" } ], "tags": [ { "name": "Catalog", "description": "Modules, products, nominal prices and recipient fields." }, { "name": "Recipients", "description": "Recipient checks without a purchase." }, { "name": "Orders", "description": "Price calculation, purchase and order results." }, { "name": "Balance", "description": "Current integration balance." } ], "security": [ { "ApiKeyAuth": [] } ] }