{"openapi": "3.0.3", "info": {"title": "Birgen Seller API", "version": "2", "description": "Server-side product API. Create your individual API key in the Telegram bot. Monetary values are strings.\n\nEvery protected request is signed with X-Api-Key, X-Timestamp, X-Nonce, and X-Signature. Signature: HMAC-SHA256(secret, timestamp + '.' + nonce + '.' + METHOD + '.' + path_with_query + '.' + raw_body).\n\nCreate your key in the bot’s My API section. Keep the secret on your server. Use a new nonce for every attempt; retain the same Idempotency-Key and request body when retrying an order.\n\nFirst get the catalogue and a quote, then send its quote_token when creating the order. If the price increases, get a new quote; if it decreases, the new price applies. available=false means the product cannot be purchased. After a timeout, look up the order by external_order_id.\n\nPROCESSING means wait; DELIVERED provides the product data in delivery_text; REFUNDED means funds were returned; SUPPORT_REQUIRED means contact support. Monetary values are strings. The store calculates RUB amounts at its own rate."}, "servers": [{"url": "https://grinberg.cc"}], "paths": {"/api/v1/health": {"get": {"summary": "Health", "responses": {"200": {"description": "OK"}}}}, "/api/v1/products": {"get": {"summary": "Products", "parameters": [{"name": "X-Api-Key", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Unix seconds"}, {"name": "X-Nonce", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}}, {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, {"name": "currency", "in": "query", "required": false, "schema": {"type": "string", "enum": ["USDT", "RUB"]}}], "responses": {"200": {"description": "Catalogue"}}}}, "/api/v1/balances": {"get": {"summary": "Balances", "parameters": [{"name": "X-Api-Key", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Unix seconds"}, {"name": "X-Nonce", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}}, {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}], "responses": {"200": {"description": "Account balances"}}}}, "/api/v1/quote": {"get": {"summary": "Quote without a debit", "description": "Every protected request is signed with X-Api-Key, X-Timestamp, X-Nonce, and X-Signature. Signature: HMAC-SHA256(secret, timestamp + '.' + nonce + '.' + METHOD + '.' + path_with_query + '.' + raw_body).", "parameters": [{"name": "X-Api-Key", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Unix seconds"}, {"name": "X-Nonce", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}}, {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, {"name": "product_id", "in": "query", "required": true, "schema": {"type": "integer"}}, {"name": "quantity", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1}}, {"name": "currency", "in": "query", "required": false, "schema": {"type": "string", "enum": ["USDT", "RUB"]}}], "responses": {"200": {"description": "Quote", "content": {"application/json": {"example": {"ok": true, "quote": {"product_id": 123, "quantity": 2, "currency": "USDT", "unit_price": "3.09", "total": "6.18", "available": true, "max_quantity": 5, "stock": 7, "quote_token": "example-token"}}}}}}}}, "/api/v1/orders": {"post": {"summary": "Order created", "parameters": [{"name": "X-Api-Key", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Unix seconds"}, {"name": "X-Nonce", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}}, {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 16, "maxLength": 128}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["external_order_id", "product_id", "quantity", "currency", "quote_token"], "properties": {"external_order_id": {"type": "string", "example": "funpay-10069"}, "product_id": {"type": "integer", "example": 123}, "quantity": {"type": "integer", "example": 2}, "currency": {"type": "string", "example": "USDT"}, "quote_token": {"type": "string"}}}}}}, "responses": {"201": {"description": "Order", "content": {"application/json": {"schema": {"type": "object", "required": ["ok", "order"], "properties": {"ok": {"type": "boolean", "example": true}, "order": {"type": "object", "required": ["id", "external_order_id", "status", "amount", "currency", "product", "created_at"], "properties": {"id": {"type": "integer", "example": 10069}, "external_order_id": {"type": "string", "example": "funpay-10069"}, "status": {"type": "string", "enum": ["PROCESSING", "DELIVERED", "REFUNDED", "SUPPORT_REQUIRED"]}, "amount": {"type": "string", "example": "6.18"}, "currency": {"type": "string", "enum": ["USDT", "RUB"]}, "product": {"type": "object", "properties": {"title": {"type": "string"}, "quantity": {"type": "integer"}}}, "created_at": {"type": "string", "format": "date-time"}, "delivered_at": {"type": "string", "nullable": true, "format": "date-time"}, "delivery_text": {"type": "string", "description": "Product delivery; present only when status is DELIVERED"}}}, "idempotent_replay": {"type": "boolean"}}}}}}, "200": {"description": "Order", "content": {"application/json": {"schema": {"type": "object", "required": ["ok", "order"], "properties": {"ok": {"type": "boolean", "example": true}, "order": {"type": "object", "required": ["id", "external_order_id", "status", "amount", "currency", "product", "created_at"], "properties": {"id": {"type": "integer", "example": 10069}, "external_order_id": {"type": "string", "example": "funpay-10069"}, "status": {"type": "string", "enum": ["PROCESSING", "DELIVERED", "REFUNDED", "SUPPORT_REQUIRED"]}, "amount": {"type": "string", "example": "6.18"}, "currency": {"type": "string", "enum": ["USDT", "RUB"]}, "product": {"type": "object", "properties": {"title": {"type": "string"}, "quantity": {"type": "integer"}}}, "created_at": {"type": "string", "format": "date-time"}, "delivered_at": {"type": "string", "nullable": true, "format": "date-time"}, "delivery_text": {"type": "string", "description": "Product delivery; present only when status is DELIVERED"}}}, "idempotent_replay": {"type": "boolean"}}}}}}, "409": {"description": "Get a fresh quote or check the existing order"}}}}, "/api/v1/orders/{order_id}": {"get": {"summary": "Order", "parameters": [{"name": "X-Api-Key", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Unix seconds"}, {"name": "X-Nonce", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}}, {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, {"name": "order_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Order", "content": {"application/json": {"schema": {"type": "object", "required": ["ok", "order"], "properties": {"ok": {"type": "boolean", "example": true}, "order": {"type": "object", "required": ["id", "external_order_id", "status", "amount", "currency", "product", "created_at"], "properties": {"id": {"type": "integer", "example": 10069}, "external_order_id": {"type": "string", "example": "funpay-10069"}, "status": {"type": "string", "enum": ["PROCESSING", "DELIVERED", "REFUNDED", "SUPPORT_REQUIRED"]}, "amount": {"type": "string", "example": "6.18"}, "currency": {"type": "string", "enum": ["USDT", "RUB"]}, "product": {"type": "object", "properties": {"title": {"type": "string"}, "quantity": {"type": "integer"}}}, "created_at": {"type": "string", "format": "date-time"}, "delivered_at": {"type": "string", "nullable": true, "format": "date-time"}, "delivery_text": {"type": "string", "description": "Product delivery; present only when status is DELIVERED"}}}, "idempotent_replay": {"type": "boolean"}}}}}}}}}, "/api/v1/orders/by-external": {"get": {"summary": "Recover an order", "parameters": [{"name": "X-Api-Key", "in": "header", "required": true, "schema": {"type": "string"}}, {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Unix seconds"}, {"name": "X-Nonce", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}}, {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[0-9a-f]{64}$"}}, {"name": "external_order_id", "in": "query", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Order", "content": {"application/json": {"schema": {"type": "object", "required": ["ok", "order"], "properties": {"ok": {"type": "boolean", "example": true}, "order": {"type": "object", "required": ["id", "external_order_id", "status", "amount", "currency", "product", "created_at"], "properties": {"id": {"type": "integer", "example": 10069}, "external_order_id": {"type": "string", "example": "funpay-10069"}, "status": {"type": "string", "enum": ["PROCESSING", "DELIVERED", "REFUNDED", "SUPPORT_REQUIRED"]}, "amount": {"type": "string", "example": "6.18"}, "currency": {"type": "string", "enum": ["USDT", "RUB"]}, "product": {"type": "object", "properties": {"title": {"type": "string"}, "quantity": {"type": "integer"}}}, "created_at": {"type": "string", "format": "date-time"}, "delivered_at": {"type": "string", "nullable": true, "format": "date-time"}, "delivery_text": {"type": "string", "description": "Product delivery; present only when status is DELIVERED"}}}, "idempotent_replay": {"type": "boolean"}}}}}}}}}}}