birinchishop — Python client for the Birinchi Shop Partner API
Official Python (3.8+) client for the Birinchi Shop Partner API v1 — a COD (cash on delivery) CPA affiliate network in Uzbekistan. Partners promote ready products; the network runs the call center, warehouse and nationwide delivery and pays a fixed amount for every delivered order.
- Standard library only (
urllib), no dependencies; type hints (py.typed) - Every REST endpoint of
/api/v1(offers, links, orders, stats, events, AI insights, Meta ads, webhooks) - Automatic retries for
429 rate_limited,5xxand network errors (GET requests andcreate_orderwith anIdempotency-Key) - Pagination iterators, webhook signature verification, tracking-link builder
API docs: https://birinchishop.uz/api/v1/docs · OpenAPI: https://birinchishop.uz/api/v1/openapi.json · Guide for AI assistants: https://birinchishop.uz/api/v1/guide.md · More examples: https://github.com/Birinchishop/birinchishop-api-examples
Install
pip install birinchishop
Quick start
Create a key in the partner panel (Dashboard → API) with only the scopes you need. The key is a server-side secret: keep it in an environment variable, never in a repository or client-side code.
from birinchishop import Birinchishop
bs = Birinchishop() # reads BSK_KEY from the environment, or Birinchishop("bsk_live_...")
me = bs.get_account()["data"]
print(me["name"], me["balance"], me["currency"])
# Best-selling offers in stock with a good sale rate
for o in bs.list_offers(sort="best_selling", min_sale_rate=25, limit=10, lang="en")["data"]:
print(o["id"], o["name"], o["payout"], o["sale_rate_percent"])
# A tracking link (check my_links first — do not create duplicates)
offer = bs.get_offer(432)["data"]
link = offer["my_links"][0] if offer["my_links"] else bs.create_link(432, name="Instagram reels")["data"]
print(link["url"], link["tracking_url_template"])
Every method returns the API envelope unchanged: {"data": ..., "meta"?: ..., "request_id": ...}.
Method names are the OpenAPI operationIds in snake_case; parameters keep the API's field names.
Orders
# All delivered orders (payout earned), every page
for order in bs.iter_orders(conversion_status="sale", date_from="2026-11-01"):
print(order["id"], order["payout"], (order["tracking"] or {}).get("click_id"))
Submitting an order — read this first
create_ordercreates a REAL order. A call center phones the customer and a courier delivers the product. Use it only for a real customer who asked to order, with their correct phone number. Never send test, sample or fake orders — the account gets blocked. It needs theorders:writescope and an account with at least 3 delivered orders (or admin approval).
res = bs.create_order(
link_id=2001, phone=customer_phone, name=customer_name, region=customer_region,
external_id=lead_id, sub1="reels",
idempotency_key=f"lead-{lead_id}", # same key on retry => same order, never a duplicate
)
print(res["data"]["id"], res["data"]["status"], "(already existed)" if res.get("replayed") else "")
Without idempotency_key the SDK generates one per call, so its own retries are safe.
Errors
from birinchishop import BirinchishopError
try:
bs.create_order(link_id=2001, phone=customer_phone)
except BirinchishopError as e:
if e.code == "duplicate_order": # same phone + offer within 24 h — do not retry
...
elif e.code == "orders_write_not_allowed": # needs 3 delivered orders or admin approval
...
else:
print(e.status, e.code, e.message, e.request_id) # send request_id to support
Attributes: status (HTTP, 0 for network errors), code, message, details, request_id, retry_after.
Client-side codes: network_error, timeout, missing_api_key, invalid_request, http_<status>.
Events and webhooks
Poll the event feed with a cursor:
cursor = load_cursor() # 0 the first time
for ev in bs.iter_events(after=cursor, include_order=True):
print(ev["type"], ev["order_id"], ev["previous_status"], "->", ev["status"], ev["conversion_status"])
cursor = ev["id"]
save_cursor(cursor)
Or receive signed webhooks (kind="json"). Verify X-Birinchishop-Signature on the raw body (Flask example):
import os
from flask import Flask, request, abort
from birinchishop import construct_event, SignatureVerificationError
app = Flask(__name__)
@app.post("/hooks/birinchishop")
def hook():
try:
event = construct_event(request.get_data(), request.headers.get("X-Birinchishop-Signature"),
os.environ["BSK_WEBHOOK_SECRET"])
except SignatureVerificationError:
abort(401)
# Events may arrive twice or out of order: deduplicate by event["id"]. Answer within 10 s.
print(event["type"], event["data"]["order_id"], event["data"]["conversion_status"])
return "ok"
verify_signature(raw_body, header, secret, tolerance=300) returns a bool if you prefer.
Register endpoints with create_webhook(url, kind="json" | "postback", events=[...]) (scope webhooks:manage);
the signing secret is returned once. For S2S postbacks to Keitaro/Binom see
integrations.
from birinchishop import fill_tracking_url
fill_tracking_url(link["tracking_url_template"], click_id="{clickid}", sub1="{campaign_id}")
# https://birinchishop.uz/l/<link>?click_id={clickid}&sub1={campaign_id} (unused sub2..sub5 removed)
All methods
| Method | Endpoint | Scope |
|---|---|---|
get_account() |
GET /me |
account:read |
list_offers(...) / iter_offers(...) |
GET /offers |
offers:read |
get_offer(offer_id, lang=) |
GET /offers/{offer_id} |
offers:read |
list_links(...) / iter_links(...) |
GET /links |
links:read |
get_link(link_id) |
GET /links/{link_id} |
links:read |
create_link(offer_id, name=) |
POST /links |
links:write |
list_orders(...) / iter_orders(...) |
GET /orders |
orders:read |
get_order(order_id) |
GET /orders/{order_id} |
orders:read |
create_order(link_id, phone, ...) |
POST /orders — real order |
orders:write |
get_order_sale_chance(order_id) |
GET /orders/{order_id}/sale-chance |
insights:read |
get_stats(group_by=, date_from=, date_to=, link_id=, offer_id=) |
GET /stats |
stats:read |
list_events(...) / iter_events(...) |
GET /events |
events:read |
get_insights() |
GET /insights |
insights:read |
get_ads_status() |
GET /ads/status |
ads:read |
list_campaigns(period=, include_archived=) |
GET /ads/campaigns |
ads:read |
pause_campaign(id) |
POST /ads/campaigns/{id}/pause (immediate) |
ads:write |
resume_campaign(id) |
POST /ads/campaigns/{id}/resume (partner confirms) |
ads:write |
change_campaign_budget(id, daily_budget, unit=) |
POST /ads/campaigns/{id}/budget (partner confirms) |
ads:write |
get_action(action_id) |
GET /actions/{action_id} |
ads:read |
list_webhooks() |
GET /webhooks |
webhooks:manage |
create_webhook(url, kind=, events=, description=) |
POST /webhooks |
webhooks:manage |
update_webhook(id, url=, events=, description=, is_active=) |
PATCH /webhooks/{id} |
webhooks:manage |
delete_webhook(id) |
DELETE /webhooks/{id} |
webhooks:manage |
test_webhook(id) |
POST /webhooks/{id}/test |
webhooks:manage |
list_webhook_deliveries(id, limit=) |
GET /webhooks/{id}/deliveries |
webhooks:manage |
get_reference() |
GET /reference |
— |
Options: Birinchishop(api_key=None, base_url="https://birinchishop.uz/api/v1", timeout=30.0, max_retries=2, transport=None).
transport lets you plug in your own HTTP stack (e.g. for proxies or tests).
Rules that matter
- Money is integer UZS. Date filters use Asia/Tashkent (UTC+5); timestamps are ISO 8601 UTC.
- Payout is earned only when an order is delivered (
conversion_status == "sale"). - 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.
- Rate limits: 120 requests/minute per key, 30 orders/minute per account.
O'zbekcha. Birinchi Shop hamkorlik API'si uchun rasmiy Python kutubxonasi (faqat standart kutubxona, Python 3.8+).
O'rnatish: pip install birinchishop. Kalitni panelda yarating (Dashboard → API) va faqat serverdagi BSK_KEY muhit o'zgaruvchisida saqlang.
create_order — haqiqiy zakaz: call-center mijozga qo'ng'iroq qiladi. Sinov yoki soxta zakaz yubormang — akkaunt bloklanadi.
Русский. Официальный клиент Python для партнёрского API Birinchi Shop (только стандартная библиотека, Python 3.8+).
Установка: pip install birinchishop. Ключ создаётся в панели (Dashboard → API) и хранится только на сервере (BSK_KEY).
create_order создаёт реальный заказ: колл-центр звонит клиенту. Не отправляйте тестовые или фейковые заказы — аккаунт блокируется.
Registration is free: https://birinchishop.uz/register?utm_source=pypi&utm_campaign=sdk-python · Support: https://t.me/birinchishop_support
License
MIT. Using the API itself is subject to the partner agreement on birinchishop.uz.
Metadata
Release files for birinchishop 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| birinchishop-0.1.0.tar.gz | 22.4 kB | Without provenance | Details for birinchishop-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| birinchishop-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for birinchishop-0.1.0-py3-none-any.whl |
Total release size: 38.1 kB
Release files / birinchishop-0.1.0.tar.gz
| Download URL | birinchishop-0.1.0.tar.gz |
|---|---|
| Size | 22.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14ba07c66b7698b3fc4d667684ccbbd060c0adb5a7f901ca231547f60538c3a2
|
|
BLAKE2b-256 checksum How to use checksums |
715b0febcbbbd0672e8a1ecf865cc066808f10b426c848f82b268a415fbb6baf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / birinchishop-0.1.0-py3-none-any.whl
| Download URL | birinchishop-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
66f4de983611bcfe6653a6efdbe647d57d658d9f94d4b62b99b63933e7d07018
|
|
BLAKE2b-256 checksum How to use checksums |
36137379b51bb8f227509bc6b5a279e3872523f2af07154b2278738bc0a11f8c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for birinchishop 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.