API & postbacks: connect your tracker, site or AI assistant

Who it is for

• Media buyers using Keitaro, Binom, Voluum, RedTrack — to see spend and conversions in one place.
• Partners with their own landing page — to send orders from their form straight to the platform.
• Developers — to pull offers, orders and statistics into a bot, CRM or spreadsheet.
• AI assistant users — to let Claude, ChatGPT or another assistant search offers, create links and report results.

Step 1: create an API key

1. Open API & integrations in the partner panel.
2. Create a key, name it (e.g. "Keitaro") and grant only the permissions you need.
3. Optionally restrict the key to your server's IP addresses and set an expiry date.
4. The key is shown once. Store it on your server only — never in website or app code.

Send it as Authorization: Bearer bsk_live_…. You are notified by Telegram whenever a key is created; resetting your password revokes all keys.

Step 2: S2S postback to your tracker

1. Add the click ID to your link: https://birinchishop.uz/l/123?click_id={subid} (Keitaro usually uses {subid}, Binom {clickid}). sub1–sub5 are available for extra labels.
2. Add a postback in the panel with your tracker's URL and our macros, e.g. https://tracker.example.com/postback?subid={click_id}&status={conversion_status}&payout={payout}

Postbacks are sent within seconds of a status change and retried with backoff if your tracker does not answer. The "Test" button sends a sample postback; the delivery log shows every request and response.

Step 3: send orders from your own site

POST /api/v1/orders with your link ID, the customer's phone and name, and optionally your click_id or order number. The order then goes to the call center as usual, and its status comes back via postback, webhook or the events feed.

• Available to partners with at least 3 delivered orders (protection against fake leads).
• One phone number cannot order the same product twice within 24 hours.
• Send an Idempotency-Key header so retries never create duplicates.

Full reference with examples and webhook signature verification code: API documentation · OpenAPI 3.1.

Step 4: connect an AI assistant (MCP)

MCP (Model Context Protocol) endpoint: https://birinchishop.uz/api/v1/mcp. The assistant only sees the tools allowed by the permissions you grant: search offers, offer details, links, orders, statistics, events, and — only if you allow it — creating links or orders.

Claude.ai, ChatGPT (no key): in Claude.ai use Settings → Connectors → Add custom connector; in ChatGPT first turn on Settings → Apps & Connectors → Advanced settings → Developer mode, then Create (Authentication: OAuth). Enter the URL above and press Connect (paid plans of these apps). The Birinchi Shop panel opens: sign in, choose permissions and confirm with your password. The connection appears in Panel → API and can be revoked any time (OAuth 2.1).

Claude Code example (API key):

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

Give an AI assistant a separate, read-only key unless it really must create links.

Security

• Keys are stored only as a hash; they cannot be recovered or viewed by staff.
• Scoped permissions, optional IP allow-list and expiry; one key per integration.
• Customer phone numbers are always masked (last 4 digits) in the API and postbacks.
• Rate limits and a security log of every key creation, revocation and denied request.

FAQ