Birinchishop Partner API

REST API, webhooks, S2S postbacks and an MCP server for partners, ad trackers and AI agents. Version 2026-10-23.

Authentication

Create a key in the partner panel (Dashboard → API). The full key is shown once. Send it on every request:

Authorization: Bearer bsk_live_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys are scoped — grant only what the integration needs — and can be restricted to IP addresses and given an expiry date. Never put a key in a browser, mobile app or public repository; if a key leaks, revoke it in the panel immediately. Keys in URLs are not accepted.

Quick start

1. Find good offers

curl -s "https://birinchishop.uz/api/v1/offers?sort=best_selling&limit=5" \
  -H "Authorization: Bearer $BSK_KEY"

2. Create a tracking link

curl -s -X POST "https://birinchishop.uz/api/v1/links" \
  -H "Authorization: Bearer $BSK_KEY" -H "Content-Type: application/json" \
  -d '{"offer_id": 123, "name": "Instagram reels"}'

Use data.url in your ads. To track conversions in your tracker, use data.tracking_url_template — e.g. https://birinchishop.uz/l/123?click_id={clickid}&sub1={campaign}. Orders placed on that page carry your click_id/sub1..5.

3. Or send orders from your own landing page

curl -s -X POST "https://birinchishop.uz/api/v1/orders" \
  -H "Authorization: Bearer $BSK_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-order-98765" \
  -d '{"link_id": 456, "phone": "+998901234567", "name": "Aziz", "region": "Toshkent", "click_id": "abc123", "external_id": "98765"}'

Every order is real: a call center phones the customer. Requires the orders:write scope and an account with at least 3 delivered orders (or admin approval).

4. Track statuses

# incremental sync
curl -s "https://birinchishop.uz/api/v1/events?after=0&include_order=true" -H "Authorization: Bearer $BSK_KEY"
# then call again with after=<meta.next_cursor>

Business rules

• Customers pay on delivery (cash on delivery). A delivery fee (typically 30,000 UZS) is added to customer_price by the delivery partner.
• Payout is credited only when an order reaches "delivered"; if the status is later reverted, the payout is reversed.
• One phone number cannot order the same offer twice within 24 hours, and at most 3 different offers per 24 hours.
• Customer phone numbers are always masked for partners.
• Submitting orders via API (orders:write) requires at least 3 delivered orders on the account, or admin approval.
• Fake or test orders are forbidden and lead to account blocking.

Endpoints

Base URL: https://birinchishop.uz/api/v1. All responses are JSON: {"data": …, "meta": …, "request_id": "…"}. Money is integer UZS; date filters use Asia/Tashkent; timestamps are ISO 8601 UTC.

Order statuses

conversion_status (for trackers)

Webhooks (signed JSON)

Add a webhook in the panel or via POST /webhooks with "kind": "json". We send order.created and order.status_changed events as a POST. Reply with any 2xx within 10 s; otherwise we retry (1m, 5m, 15m, 1h, 3h, 6h, 12h, 24h). After many consecutive failures the webhook is disabled and you are notified. Events can arrive twice or out of order — deduplicate by id.

POST /your/endpoint
X-Birinchishop-Event: order.status_changed
X-Birinchishop-Event-Id: evt_1042
X-Birinchishop-Timestamp: 1761130000
X-Birinchishop-Signature: t=1761130000,v1=5f1c…

{"id":"evt_1042","type":"order.status_changed","api_version":"2026-10-23",
 "created_at":"2026-10-22T10:00:00.000Z",
 "data":{"id":1042,"order_id":12345,"status":"delivered","previous_status":"shipping",
         "conversion_status":"sale","order":{"id":12345,"payout":50000,"payout_status":"earned", "...": "..."}}}

Verify the signature (Node.js)

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // replay protection
  const expected = crypto.createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}

Python

import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    if abs(time.time() - int(parts['t'])) > 300:
        return False
    expected = hmac.new(secret.encode(), parts['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get('v1', ''))

S2S postbacks (Keitaro, Binom, Voluum, …)

Add a webhook with "kind": "postback". We call your URL with GET on each event, replacing macros (URL-encoded):

{click_id} {sub1} {sub2} {sub3} {sub4} {sub5} {order_id} {external_id} {status} {conversion_status} {payout} {customer_price} {currency} {offer_id} {link_id} {event} {event_id} {timestamp}

https://tracker.example.com/postback?subid={click_id}&status={conversion_status}&payout={payout}&currency={currency}

Map conversion_status in your tracker: lead → lead, approved → approved/hold, sale → sale, rejected → rejected. Payout is earned only on sale.

AI agents (MCP)

An MCP server lets AI assistants (Claude, ChatGPT and others) work with your account in natural language: “find 3 best-selling offers under 300 000 som, create links and report yesterday's results”. Transport: Streamable HTTP (stateless), endpoint https://birinchishop.uz/api/v1/mcp. The agent only sees tools allowed by the granted scopes — grant read-only access unless it must create links or orders.

Claude.ai, ChatGPT and other apps (OAuth — no key needed)

Claude.ai: Settings → Connectors → Add custom connector. ChatGPT: turn on Settings → Apps & Connectors → Advanced settings → Developer mode, then Create with Authentication: OAuth. Use the URL https://birinchishop.uz/api/v1/mcp and press Connect (paid plans of these apps). You will be sent to the Birinchi Shop panel: sign in, choose permissions and confirm with your password (or a Telegram code). The connection appears in Panel → API, where you can revoke it at any time; it is also revoked automatically when your password changes. OAuth 2.1 with PKCE (S256), dynamic client registration and client ID metadata documents are supported; metadata: protected resource, authorization server. OAuth tokens work only on the MCP endpoint (use an API key for REST), access tokens live 1 hour, refresh tokens rotate, a connection lasts up to 180 days.

Claude Code (API key)

claude mcp add --transport http birinchishop https://birinchishop.uz/api/v1/mcp \
  --header "Authorization: Bearer $BSK_KEY"

Generic MCP client config

{
  "mcpServers": {
    "birinchishop": {
      "type": "http",
      "url": "https://birinchishop.uz/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${BSK_KEY}"
      }
    }
  }
}

Human in the loop

Agents can read Meta ad results and pause a campaign immediately (ads:write). Anything that can increase spending — resuming a campaign or changing its budget — is never executed by the agent: it creates a confirmation card that the partner approves in the Telegram bot or the panel (/dashboard/ai); the agent checks the result with get_action.

Prompts and resources

Ready-made prompts appear in the client's prompt menu: daily_review (yesterday's results and today's plan), find_offer, check_campaigns, order_problems. Resources: birinchishop://guide/business (business rules) and birinchishop://account/insights (AI manager overview).

Errors & limits

{"error": {"code": "duplicate_order", "message": "This phone number already has an order for this offer in the last 24 hours"},
 "request_id": "req_Q2x…"}

Branch on error.code. Common codes: invalid_request, unauthorized, key_revoked, key_expired, insufficient_scope, ip_not_allowed, not_found, offer_inactive, out_of_stock, duplicate_order, customer_order_limit, orders_write_not_allowed, daily_order_limit, rate_limited, internal_error. Include request_id when contacting support.

Limits: 120 requests/minute per key; 30 orders/minute per account; 30 failed attempts per 15 minutes per IP. Responses include RateLimit-* headers; on 429 wait and retry.

Machine-readable: /api/v1/openapi.json · /api/v1/reference