repsapi

Official Python client for the RepsApi.pl API: parcel tracking, warehouse QC photos, product lookup, agent links, shipping estimates and haul calculations.

• Sync (RepsApi) and async (AsyncRepsApi) clients, e.g. for discord.py bots.
• Typed responses (TypedDict), so your editor completes every field.
• Retries network errors, 5xx answers and short rate limits on its own.
• One dependency: httpx. Python 3.9+.

Install

pip install repsapi

Quick start

Create an API key in the dashboard and put it in the REPSAPI_KEY environment variable (or pass it as api_key).

from repsapi import RepsApi

with RepsApi() as api:  # reads REPSAPI_KEY
    parcel = api.tracking("YT2530998211074512")
    if parcel["summary"]:
        print(parcel["summary"]["status_en"])

    item = api.lookup("https://weidian.com/item.html?itemID=7779617259", currency="PLN")
    print(item["title_en"], item.get("price_local"))

Async:

import asyncio
from repsapi import AsyncRepsApi

async def main():
    async with AsyncRepsApi() as api:
        qc = await api.qc(platform="weidian", id="7779617259")
        print(qc["total_photos"])

asyncio.run(main())

Responses are the API's JSON as plain dicts. Field-by-field descriptions are in the documentation.

Methods

Every method also takes timeout= (seconds) and max_retries=.

# the same product on two agents
links = api.convert("https://detail.1688.com/offer/678091425228.html", agents=["kakobuy", "cnfans"])
print(links["agents"]["kakobuy"])

# shipping lines for a 1.2 kg parcel to Poland, priced in PLN
estimate = api.shipping_estimate("PL", weight=1200, currency="PLN")
print(estimate["cheapest"])

# a whole haul
haul = api.haul(
    [
        {"url": "https://weidian.com/item.html?itemID=7779617259", "quantity": 2},
        {"url": "https://detail.1688.com/offer/678091425228.html"},
    ],
    "PL",
    currency="PLN",
)
print(haul["totals"].get("local"))

Errors

Every error extends RepsApiError. Errors from the API extend APIError and carry status, type (the API's error type), message and details (extra fields such as allowed).

from repsapi import RateLimitError, UnprocessableEntityError

try:
    api.lookup(link)
except RateLimitError as err:
    print("Quota used up, resets", err.reset_at)
except UnprocessableEntityError:
    print("That isn't a product link.")

Retries, timeouts and limits

• Network errors and 500/502/503/504 answers are retried twice with a growing pause (max_retries).
• A 429 is retried after its Retry-After when that is at most 60 s (max_retry_wait); a used-up daily quota raises RateLimitError at once.
• Failed calls don't count toward your quota, so retries cost nothing.
• Timeouts: 60 s, hauls and link-based shipping estimates 180 s (timeout).
• api.rate_limit holds the per-minute limit from the last response that carried one.
• The client never follows redirects, so your key is never sent anywhere but base_url, and base_url must be https://. repr(api) never shows the key.

api = RepsApi(api_key="rk_live_...", timeout=30, max_retries=3)

Changelog

0.1.2 (2026-10-25): QC batches have sku_en / sku_pl - the variant name in English and Polish when the warehouse wrote it in Chinese. No runtime changes.

0.1.1 (2026-10-14): ServiceName includes "shipping" - health() now reports the shipping calculator. No runtime changes.

0.1.0 (2026-10-14): first release. The full list is in CHANGELOG.md in the source distribution.

Links

• Documentation: https://repsapi.pl/docs
• Status: https://repsapi.pl/status
• Discord: https://discord.gg/repsapi

License

MIT