API Documentation

ELITE TOOLS STORE runs on one API that both the website and the Telegram bot communicate with.

Base URL

https://api.elitetoolz.store/api

Authentication

Protected endpoints require the header x-storefront-key with the shared storefront secret. Requests without it are rejected.

Format

All requests and responses are JSON. Successful responses include ok: true.

Catalogue

Public product data. The bot is the single source of truth for products, prices and stock.

GET/storefront/productspublic

Full product list in bot row order: id, name, price, stock, inStock, description, warranty, buyUrl.

Payments

Wallet top-ups and order payments are verified on-chain or through Binance Pay before anything is delivered.

GET/storefront/payment-configkey required

Active wallet addresses: BEP-20, TRC-20, Binance Pay and bank transfer details.

POST/storefront/verify-paymentkey required

Verifies a transaction. Returns verified, amount, received, alreadyUsed and a reason on failure.

{ "network": "bep20" | "trc20" | "binance", "txHash": "0x…", "amount": 12.5 }

POST/storefront/pay-sessionkey required

Creates a card checkout session and returns the payment URL.

{ "reference": "ETS-1234", "email": "…", "name": "…", "amountUsd": 10, "successUrl": "…", "cancelUrl": "…" }

GET/storefront/pay-session/:sessionIdkey required

Reads a card session back: ok, paid, amount, reference.

Delivery & activations

Credentials leave the bot only after a payment is confirmed.

POST/storefront/deliverkey required

Delivers a paid order: supplier products are bought live from the supplier, others come from real bot stock. Idempotent per idempotencyKey (a retry returns the same items). Returns ok, delivered, items (exactly quantity), source (supplier|stock), reference, quantity, supplierOrderId, idempotent, partial, retryable, reason.

{ "productId": "ABF0431B", "quantity": 1, "reference": "ETS-ABCDE23456", "itemId": "uuid", "idempotencyKey": "ETS-ABCDE23456:uuid", "priceUsd": 9.99 }

POST/storefront/activationkey required

Queues a Canva or Surfshark activation for a website purchase.

{ "request_id": "…", "reference": "ETS-1234", "type": "canva" | "surfshark", "value": "user@gmail.com" }

Wallet bridge

While a Telegram account is linked, the bot wallet and the website wallet spend as one pot. Nothing is ever merged.

GET/storefront/wallet?telegram_id=123key required

Current bot wallet balance for a linked customer.

POST/storefront/wallet/debitkey required

Takes money out of the bot wallet for a website purchase.

{ "telegram_id": 123, "amount": 5, "note": "Order ETS-1234" }

Orders

So website order history shows bot purchases too.

GET/storefront/orders?telegram_id=123key required

All purchases a linked Telegram customer made inside the bot.

GET/storefront/order-lookup?reference=ETS-1234key required

Looks up one order by reference for public order tracking.

POST/storefront/notifykey required

Sends a live admin notification into Telegram with optional approve / reject / deliver buttons.

{ "title": "…", "body": "…", "action": { "kind": "order", "id": "…", "actions": ["approve"] } }

Errors

401 — missing or wrong x-storefront-key.
404 — unknown product, order or session.
409 — transaction already used for another payment.
503 — supplier or payment provider temporarily unavailable.