⌁
API key
48 alphanumeric characters. The key remains available under My account until you regenerate it.
01
ACCESS
Authentication
Every API request requires your personal key in the X-API-Key header. Keep it private and use it only from your backend.
◇
Server-side only
Never expose the key in frontend code, mobile apps or public repositories.
Request header
X-API-Key: YOUR_API_KEY02
FIRST REQUEST
Quick start
Request the live catalog in seconds. Replace the placeholder with your API key.
curl "https://api.goribucshop.com/api/v2/catalog" \
-H "X-API-Key: YOUR_API_KEY"import requests
response = requests.get(
"https://api.goribucshop.com/api/v2/catalog",
headers={"X-API-Key": "YOUR_API_KEY"},
timeout=15,
)
response.raise_for_status()
print(response.json())GET
/api/v2/catalogReturns every GORIB product with its public SKU, price and live availability.
Response
skustringStable GORIB product code.
fulfillmentstringinstant_code, automatic or assisted.
recipient_typestringWhich recipient value the order requires.
price_usdstringUnit price in USD with three decimal places.
stockinteger | nullFinite code stock, or null for non-stock products.
200 OK
[
{
"sku": "GORIB-STARS",
"name": "GORIB Stars",
"category": "services/telegram/stars",
"fulfillment": "automatic",
"recipient_type": "telegram_recipient",
"price_usd": "0.015",
"available": true,
"stock": null,
"min_quantity": 50,
"max_quantity": 9000
}
]GET
/api/v2/profileReturns account details and available balance.
Use this endpoint to
- Display the current balance
- Confirm account identity
- Read the masked API key hint
200 OK
{
"telegram_id": 123456789,
"username": "username",
"language": "en",
"balance_usd": "250.000",
"api_key_hint": "Ab12••••Xy90"
}POST
/api/v2/ordersCreates one protected order for any SKU in the unified catalog.
Idempotency required
Send a unique Idempotency-Key for every checkout attempt. Retrying the same request is safe and will not create a duplicate charge.
Headers
X-API-KeyrequiredYour private API key.
Idempotency-KeyrequiredUnique value, 8–100 letters, numbers or hyphens.
JSON body
skurequiredPublic GORIB SKU from the catalog.
quantityrequiredMust be inside the product’s current limits.
recipientconditionalRequired only when recipient_type is not none.
Request
curl -X POST \
"https://api.goribucshop.com/api/v2/orders" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Idempotency-Key: checkout-8f31a2c4" \
-H "Content-Type: application/json" \
-d '{"sku":"GORIB-STARS","quantity":100,"recipient":"username"}'200 OK
{
"order_id": "GORIB-DIGITAL-550e8400-e29b-41d4-a716-446655440000",
"sku": "GORIB-STARS", "status": "processing", "quantity": 100,
"unit_price_usd": "0.015", "total_price_usd": "1.500",
"balance_usd": "248.500", "codes": [],
"status_url": "/api/v2/orders/GORIB-DIGITAL-550e8400-e29b-41d4-a716-446655440000"
}GET
/api/v2/orders/{order_id}Returns the current result, item statuses and any delivered customer codes.
Create order→Poll status URL→Receive final result
Private order scope
An API key can read only orders created by the same account. Internal processing details are never included.
POST
/api/v2/api-key/rotateInvalidates the current key and issues a new one.
Update integrations
The new key remains available under My account. The previous key stops working immediately.
03
REFERENCE
Error handling
StatusMeaningAction
400Invalid request or quantityValidate parameters
401Missing or invalid API keyCheck authentication
402Insufficient balanceAdd funds and retry
409Idempotency conflictUse a new unique key
422Product unavailableRefresh the catalog
04
GOOD PRACTICE
Security checklist
Treat your API key like a password. Rotate it immediately if it may have been exposed.
- Keep credentials in environment variables or a secret manager
- Use a new idempotency key for each checkout
- Set request timeouts and log order IDs
- Never publish delivered codes in application logs