Skip to content

opastorello/AcBuyClient

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
docs
docs
 
 
scripts
scripts
 
 
src/acbuy
src/acbuy
 
 
tests
tests
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

AcBuy Client

Complete Python suite to talk to the encrypted AcBuy API (acbuy.com). It includes a library and a CLI (acbuy), handles transport encryption, captcha, token cache, product URL parsing, and exposes dozens of endpoints ready for terminal usage or automation.

The project mirrors the real web UI flow: it downloads the AES key from the site JS bundle, encrypts/decrypts bodies, RSA-encrypts the password, and keeps headers consistent (Lang, Accept-Language, Currency, Device). Everything is encapsulated so you only pass credentials and JSON.

Main blocks:

  • Login with captcha (OCR or manual) and configurable retries (ACBUY_MAX_LOGIN_ATTEMPTS)
  • Local token cache validated via JWT exp
  • Payload encryption/decryption (AES-ECB + PKCS7) and RSA password encryption on login
  • Product URL parser (1688/Taobao/Goofish) to extract IDs/SKU and build calls from links
  • CLI with dozens of commands, JSON support via --params (GET) and --payload (POST/PUT/DELETE)

Quick start

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

export ACBUY_EMAIL="you@example.com"
export ACBUY_PASSWORD="your_password"

acbuy login
acbuy user-info

Optional:

acbuy login --manual
acbuy clear-cache

Table of contents

Overview

This project is designed to:

  • Encapsulate all encryption required by the API
  • Perform login with captcha (OCR or manual)
  • Reuse token via local cache
  • Expose a clear CLI with grouped commands
  • Allow parameters via JSON (--params / --payload)
  • Extract data from URLs (1688 / Taobao / Goofish)

Project structure and code docs

Each file has function/argument documentation in docs/CODE_REFERENCE.md. Summary of core modules:

Main files in src/acbuy:

  • client.py

    • AcBuyClient: main API entry point.
    • Composes service mixins and exposes all get_*, post_*, put_* and delete_* methods.
    • Centralizes encryption/decryption and auth headers via a shared base.

  • services/

    • Smaller mixins split by feature (e.g., user_profile, user_cart, payment_wallet, order_list, product_catalog, resource_task, logistics_catalog, marketing_report, storage_package).
    • Each mixin groups closely related endpoints to keep classes focused.

  • crypto.py

    • fetch_aes_key: downloads the main JS bundle and extracts the AES key.
    • AESCipher: AES encrypt/decrypt with PKCS7.
    • rsa_encrypt: RSA-encrypts the password.

  • http.py

    • build_session: creates a requests.Session with retries and default headers.

  • config.py

    • Settings: configuration values from environment variables.
    • Current defaults: pt, pt-PT, BRL.

  • cache.py

    • load_token, save_token, clear_cache.
    • Validates expiration via JWT.

  • captcha.py

    • Saves captcha to cache.
    • OcrCaptchaSolver: OCR using OpenCV + Tesseract.

  • cli.py

    • Main CLI (acbuy).
    • Maps commands -> client methods.
    • Supports --params, --payload, --url.

  • url_parser.py

    • URL parser for 1688/Taobao/Goofish.
    • Extracts itemId, goodsId, source, sku, skuId.

Encryption and decryption (detailed)

See the technical article in docs/CRYPTOGRAPHY.md (AES key bootstrap, AES-ECB+PKCS7, RSA on login, wire format, and Python examples).

Quick snippet to decrypt any encrypted body from Burp/DevTools:

from acbuy.client import AcBuyClient
from acbuy.config import Settings

client = AcBuyClient(Settings.from_env())  # fetches AES key from the site
print(client.aes.decrypt("yp3ye9cuklb/W94I..."))  # Base64 ciphertext from the body

Installation

Requirements:

  • Python 3.9+
  • (Optional) OCR via Tesseract installed on your system. Without it, use acbuy login --manual.
    • macOS (Homebrew): brew install tesseract
    • Debian/Ubuntu: sudo apt-get install tesseract-ocr
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

Credentials

export ACBUY_EMAIL="you@example.com"
export ACBUY_PASSWORD="your_password"

Variables (defaults)

Variable Default Notes
ACBUY_BASE_URL https://www.acbuy.com Site/API base
ACBUY_LANG pt Lang header
ACBUY_ACCEPT_LANGUAGE pt-PT Accept-Language header
ACBUY_CURRENCY BRL Currency header
ACBUY_DEVICE pc Device header
ACBUY_TIMEOUT 15 Timeout (seconds)
ACBUY_MAX_LOGIN_ATTEMPTS 10 Max attempts for login/captcha
ACBUY_TOKEN_MARGIN 60 JWT exp margin (seconds)
ACBUY_CACHE_DIR ~/.cache/acbuy Cache folder (token + captcha)
ACBUY_REGISTER_COUNTRY_CODE BR Country code for registration
ACBUY_REGISTER_COUNTRY 巴西 Country name for registration
ACBUY_REGISTER_LANGUAGE pt Language sent on registration
ACBUY_INVITE_CODE AC244922609 Optional invite code
ACBUY_INVITE_SOURCE TB Invite source (TB, etc.)
ACBUY_PROMOTER_CODE `` Optional promoter code

CLI overrides

The options below override the corresponding environment variables:

  • --email, --password
  • --base-url
  • --timeout
  • --max-attempts
  • --cache-dir

For registration (acbuy register), if you do not pass explicit flags, the CLI uses defaults from ACBUY_REGISTER_COUNTRY_CODE, ACBUY_REGISTER_COUNTRY, ACBUY_REGISTER_LANGUAGE, ACBUY_INVITE_CODE, ACBUY_INVITE_SOURCE, and ACBUY_PROMOTER_CODE.

How it works

1) HTTP session

  • The client builds a requests.Session with automatic retries.
  • Default headers are pinned (Accept, Content-Type, Lang, Currency, Device, X-Encrypted).
  • A random User-Agent is chosen per session.

2) AES key

  • The AES key is extracted from the site JS bundle.
  • The client fetches https://www.acbuy.com/, finds the main JS, and captures the embedded AES key.
  • This key encrypts request bodies and decrypts responses.

3) Encryption

  • Payloads are AES-ECB encrypted with PKCS7 padding.
  • The password is RSA-encrypted with the public key from the API.
  • Responses are decrypted automatically.
  • Technical details in docs/CRYPTOGRAPHY.md.

4) Captcha

  • Captcha is fetched via endpoint, decrypted, and saved to ACBUY_CACHE_DIR/captcha.png.
  • OCR attempts to solve (OpenCV + pytesseract).
  • If OCR fails, manual mode asks for captcha on the terminal.
  • In manual mode, wrong captcha is retried up to ACBUY_MAX_LOGIN_ATTEMPTS.

5) Token cache

  • Token is saved to ACBUY_CACHE_DIR/auth_cache.json (default: ~/.cache/acbuy/auth_cache.json).
  • Cache is validated via JWT exp and a safety margin (ACBUY_TOKEN_MARGIN).
  • With a valid token, no new login is required.

Authentication and cache

Login

  • acbuy login performs login, prints the token, and saves it in cache.
  • acbuy login --manual forces manual captcha (with retries up to ACBUY_MAX_LOGIN_ATTEMPTS).
  • acbuy captcha downloads a captcha and saves it to ACBUY_CACHE_DIR/captcha.png (useful for inspection).

Token cache

  • Token is stored at ACBUY_CACHE_DIR/auth_cache.json (default: ~/.cache/acbuy/auth_cache.json).
  • acbuy clear-cache removes only the token (does not delete captcha.png).
  • To force a fresh login even with a valid token: acbuy login --no-cache.
  • Use clear-cache when you want to switch accounts or ensure a brand-new token.

When token is missing

If you run a command without being authenticated, the CLI exits and asks you to run acbuy login.

CLI

Basic syntax

acbuy <command> [--params '{...}'] [--payload '{...}'] [--url "..."]

Common options

  • --params: JSON object for query string (GET only)
  • --payload: JSON object for body (POST/PUT/DELETE)
  • --url: product URL to extract fields (only for some commands)
  • --manual: force manual captcha (login and register)
  • --no-cache: do not use cached token (non-login commands will exit asking for acbuy login)
  • --base-url, --timeout, --max-attempts, --cache-dir, --verbose

Precedence rules

  • If --url and --params/--payload are used together, JSON overrides values extracted from the URL.

JSON tips for the terminal

  • Use single quotes in the shell to avoid JSON being interpreted.
  • Avoid ending JSON with . or ; (if it happens, the CLI tries to strip it automatically).
acbuy issue-detail-list --params '{"pageNum":1,"pageSize":10,"status":0}'
acbuy user-tags-put --payload '{"id":8753,"name":"VIP","bgColor":"#FF8F1F","comment":"Tag edited"}'

Registration (register)

  • acbuy register follows the same captcha flow as login (OCR by default; --manual to type). If the API returns a token, it is saved automatically.
  • Default registration values (country, invite code, language) come from ACBUY_REGISTER_*, ACBUY_INVITE_*, ACBUY_PROMOTER_CODE.
  • Activation (if the platform requires a code): use register-active with --payload.

Examples:

acbuy register --manual --country-code BR --register-country "巴西" --invite-code AC244922609
acbuy register-active --payload '{"code":"1234","userId":"405414802","account":"email@example.com"}'

Product URLs (--url)

The parser understands 1688, Taobao and Goofish URLs. It attempts to extract:

  • itemId
  • goodsId
  • source (TB or AL)
  • sku
  • skuId

Mapping:

  • 1688: /offer/<id>.html -> itemId=<id>, source=AL, goodsId=AL<id>
  • Taobao: ?id=<id> -> itemId=<id>, source=TB, goodsId=TB<id>
  • Goofish: only itemId (does not produce goodsId)

Commands that support --url:

  • product-item-detail
  • product-item-photos
  • product-item-match
  • product-measure
  • item-logistics-data
  • product-post-fee
  • collect-is-collect
  • browsing-history-add

Limitation:

  • Goofish URLs are supported only by product-item-match.

Examples:

acbuy product-item-detail --url "https://item.taobao.com/item.htm?id=xxxxxxxxxxxx"
acbuy product-item-photos --url "https://detail.1688.com/offer/xxxxxxxxxxxx.html"
acbuy product-item-match --url "https://www.goofish.com/item?id=xxxxxxxxxxxx"

Endpoints with required parameters

Some endpoints fail without correct parameters. The CLI validates this and reports missing keys (e.g., Missing required --params: ...).

acbuy payment-channel-list --params '{"country":"CN","orderNo":"ZE02353003730"}'
acbuy payment-fee --params '{"channelId":100,"orderNo":"ZE02353003730","currency":"USD"}'

Practical examples (with args)

User / profile:

acbuy user-info
acbuy login-history
acbuy address-list
acbuy user-tags
acbuy user-tags-post --payload '{"name":"VIP","bgColor":"#07B9B9","comment":"Notes"}'
acbuy user-tags-put --payload '{"id":8749,"name":"VIP","bgColor":"#FF8F1F","comment":"Tag edited"}'
acbuy user-tags-delete --tag-id 8749

Notes:

  • For user-tags-post and user-tags-put, userId is auto-filled via user-info if missing in the payload.
  • If user-tags-post returns "duplicate information", use user-tags-put to edit or user-tags-delete to remove.

Registration:

acbuy register --manual --country-code BR --register-country "巴西" --register-email new@example.com --register-password "password123" --no-apply-token
acbuy register-active --payload '{"code":"1234","userId":"405414802","account":"email@example.com"}'

Cart:

acbuy cart-list
acbuy cart-add --payload '{"itemId":"625214050696","quantity":1}'
acbuy cart-edit --payload '{"cartId":"123","quantity":2}'   # quantity maps to goodsNum automatically
acbuy cart-selected-remove --payload '{"cartIds":["123","456"]}'

Note: the cart API requires multiple fields (storeId, goodsAttr, prices). The examples above only work if the payload includes the fields that the web UI sends; use a Burp export as reference or build the payload from product data (sku, store, price) to avoid 500s.

Orders:

acbuy user-order-list --payload '{"page":1,"pageSize":20}'
acbuy item-status-count --payload '{}'
acbuy order-count --payload '{}'
acbuy item-logistics-data --url "https://item.taobao.com/item.htm?id=625214050696"

Payments:

acbuy wallet-balance
acbuy payment-channel-list --params '{"country":"CN","orderNo":"ZE02353003730"}'
acbuy payment-fee --params '{"channelId":100,"orderNo":"ZE02353003730","currency":"USD"}'

Products:

acbuy product-item-detail --url "https://item.taobao.com/item.htm?id=625214050696"
acbuy product-item-photos --url "https://detail.1688.com/offer/570423754750.html"
acbuy product-measure --params '{"spuIds":"TB625214050696"}'
acbuy product-post-fee --payload '{"goodsId":"TB625214050696"}'

Resources:

acbuy activity-detail --params '{"id":3211908173210603,"lang":"pt"}'
acbuy issue-detail-list --params '{"pageNum":1,"pageSize":10,"status":0}'

Captcha:

acbuy login --manual
acbuy captcha

Examples by command (detailed)

Note: the payloads below are basic examples. Some endpoints require additional fields depending on account type, order, or context.

Authentication

acbuy register --manual
acbuy login
acbuy login --manual
acbuy captcha
acbuy register-active --payload '{"code":"1234","userId":"405414802","account":"email@example.com"}'

In manual mode, if the captcha is incorrect, the CLI retries up to ACBUY_MAX_LOGIN_ATTEMPTS (for login and register).

  • acbuy register accepts --register-email/--register-password (to avoid reusing the login env vars) and --no-apply-token to prevent overwriting the current token.
acbuy clear-cache

User

acbuy user-info
acbuy login-history
acbuy address-list
acbuy member-config-list
acbuy user-tags
acbuy user-tags-post --payload '{"name":"VIP","bgColor":"#07B9B9","comment":"Notes"}'
acbuy user-tags-put --payload '{"id":8749,"name":"VIP","bgColor":"#FF8F1F","comment":"Tag edited"}'
acbuy user-tags-delete --tag-id 8749
acbuy bill-address-detail
acbuy bill-address-post --payload '{"name":"John","country":"BR","city":"Lisbon","address":"Street X, 123"}'
acbuy browsing-history-list --params '{"pageNum":1,"pageSize":10}'
acbuy browsing-history-add --url "https://item.taobao.com/item.htm?id=625214050696"
acbuy address-add --payload '{"firstName":"John","country":"BR","countryCode":"BR","city":"Sao Paulo"}'
acbuy address-edit --payload '{"id":237770,"firstName":"John","countryCode":"BR"}'
acbuy address-remove --payload '{"id":237770}'
acbuy user-info-edit --payload '{"userId":244922609,"userName":"AC244922609"}'

Note: in user-tags-post and user-tags-put, userId is auto-filled via user-info if missing in the payload. To update a tag, the payload must include id. If user-tags-post returns "duplicate information", change name or use user-tags-put/user-tags-delete.

Cart

acbuy cart-list
acbuy cart-nums
acbuy cart-add --payload '{"itemId":"625214050696","quantity":1}'
acbuy cart-edit --payload '{"cartId":"123","quantity":2}'
acbuy cart-buy --payload '{"cartIds":["123","456"]}'
acbuy cart-selected-remove --payload '{"cartIds":["123","456"]}'

Orders

acbuy user-order-list --payload '{"page":1,"pageSize":20}'
acbuy item-status-count --payload '{}'
acbuy order-count --payload '{}'
acbuy order-pending-list --payload '{"page":1,"pageSize":20}'
acbuy order-item-steps --payload '{"orderNo":"ZE02353003730"}'
acbuy order-delete --payload '{"orderNo":"ZE02353003730"}'
acbuy order-advance-payment --payload '{"orderNo":"ZE02353003730"}'
acbuy order-wait-pay-cancel --payload '{"orderNo":"ZE02353003730"}'
acbuy item-logistics-data --url "https://item.taobao.com/item.htm?id=625214050696"

Payments

acbuy wallet-balance
acbuy wallet-check-pwd
acbuy payment-channel-list --params '{"country":"CN","orderNo":"ZE02353003730"}'
acbuy payment-fee --params '{"channelId":100,"orderNo":"ZE02353003730","currency":"USD"}'
acbuy payment-order --payload '{"orderNo":"ZE02353003730","channelId":100}'
acbuy exchange-rate --params '{"currency":"USD"}'
acbuy exchange-rate-actual --params '{"currency":"USD"}'
acbuy balance-detail-list --params '{"pageNum":1,"pageSize":10}'
acbuy business-type-list
acbuy discount-list --payload '{"pageNum":1,"pageSize":10}'
acbuy recharge-create --payload '{"currency":"BRL","amount":"100.00","originalAmount":100}'

Logistics

acbuy country-alphabet
acbuy express-list --params '{"status":1}'
acbuy logistics-mail-limit
acbuy logistics-linecount --payload '{"countryCode":"CN","weight":1.2}'
acbuy logistics-notice-query --payload '{"orderNo":"ZE02353003730"}'

Marketing

acbuy marketing-bills --params '{"pageNum":1,"pageSize":10}'
acbuy marketing-invite-records --params '{"pageNum":1,"pageSize":10}'
acbuy marketing-level-conf
acbuy marketing-promoter-info
acbuy marketing-settle-packages --params '{"pageNum":1,"pageSize":10}'
acbuy marketing-withdrawals --params '{"pageNum":1,"pageSize":10}'
acbuy marketing-withdraw-bank

Resources

acbuy task-count
acbuy user-task-list --params '{"pageNum":1,"pageSize":10}'
acbuy issue-detail-list --params '{"pageNum":1,"pageSize":10,"status":0}'
acbuy issue-detail-exchange-coupon --payload '{"issueId":"123"}'
acbuy resource-code-list --params '{"hotStatus":1,"pageSize":1000}'
acbuy msg-notice-list
acbuy activity-list --params '{"lang":"en"}'
acbuy activity-detail --params '{"id":3211908173210603,"lang":"en"}'
acbuy advert-page --params '{"position":"top","page":"index"}'
acbuy doc-category --doc-id 111
acbuy doc-category-tree --params '{"lang":"en","status":1}'
acbuy country-state-list --payload '{"countryCode":"CN"}'

Storage

acbuy increment-list
acbuy package-list --params '{"pageNum":1,"pageSize":10}'
acbuy preview-item-list --params '{"pageNum":1,"pageSize":10}'
acbuy pack-rewards-user-list --payload '{"pageNum":1,"pageSize":10}'

Products

acbuy category-recommend
acbuy product-item-detail --url "https://item.taobao.com/item.htm?id=625214050696"
acbuy product-item-photos --url "https://detail.1688.com/offer/570423754750.html"
acbuy product-item-match --url "https://www.goofish.com/item?id=995060882159"
acbuy product-measure --params '{"spuIds":"TB625214050696"}'
acbuy product-post-fee --payload '{"goodsId":"TB625214050696"}'

Letters

acbuy letter-list --params '{"pageNum":1,"pageSize":10}'
acbuy letter-counts
acbuy letter-batch-read --letter-id 678071941673434 --payload '{}'

Collections

acbuy collect-list --params '{"pageNum":1,"pageSize":10}'
acbuy store-collect-list --params '{"pageNum":1,"pageSize":10}'
acbuy collect-is-collect --payload '{"goodsId":"TB625214050696"}'

Command groups

Authentication

  • register, register-active, login, captcha, clear-cache

User

  • user-info, login-history, address-list, member-config-list, user-tags, user-tags-post, user-tags-put, user-tags-delete, bill-address-detail, bill-address-post, address-add, address-edit, address-remove, user-info-edit, browsing-history-list, browsing-history-add

Cart

  • cart-list, cart-nums, cart-add, cart-edit, cart-buy, cart-selected-remove

Orders

  • user-order-list, item-status-count, order-count, order-pending-list, order-item-steps, order-delete, order-advance-payment, order-wait-pay-cancel, item-logistics-data

Payments

  • wallet-balance, wallet-check-pwd, payment-channel-list, payment-fee, payment-order, recharge-create, exchange-rate, exchange-rate-actual, balance-detail-list, business-type-list, discount-list

Logistics

  • country-alphabet, express-list, logistics-mail-limit, logistics-linecount, logistics-notice-query

Marketing

  • marketing-bills, marketing-invite-records, marketing-level-conf, marketing-promoter-info, marketing-settle-packages, marketing-withdrawals, marketing-withdraw-bank

Resources

  • task-count, user-task-list, issue-detail-list, issue-detail-exchange-coupon, resource-code-list, msg-notice-list, activity-list, activity-detail, advert-page, doc-category, doc-category-tree, country-state-list

Storage

  • increment-list, package-list, preview-item-list, pack-rewards-user-list

Products

  • category-recommend, product-item-detail, product-item-photos, product-item-match, product-measure, product-post-fee

Letters

  • letter-list, letter-counts, letter-batch-read

Collections

  • collect-list, store-collect-list, collect-is-collect

Full list

acbuy --help

Library usage (Python)

Simple example:

from acbuy.client import AcBuyClient
from acbuy.config import Settings

settings = Settings.from_env()
client = AcBuyClient(settings=settings)

# Manual login if needed
client.login(settings.email, settings.password, use_ocr=False)

info = client.get_user_info()
print(info)

Troubleshooting

  • "Not authenticated": run acbuy login first.
  • OCR failed: use acbuy login --manual.
  • "Invalid JSON for --params/--payload": check shell quoting and remove trailing punctuation (e.g., .).
  • 500 without message: usually missing required --params.
  • "Add failed, duplicate information": duplicate tag name; use user-tags-put to edit or user-tags-delete to remove.
  • Order endpoints (advance/delete/wait-pay-cancel) depend on order state; if orderNo is not in the expected stage, the API returns 500.
  • Tesseract not found: install it or use manual mode.

Tests

source .venv/bin/activate
pip install -e .[dev]
python -m pytest

Support scripts

  • scripts/check_endpoints.py: validates client endpoints. Use ACBUY_EMAIL and ACBUY_PASSWORD and, optionally, samples (ACBUY_SAMPLE_GOODS_ID, ACBUY_SAMPLE_ITEM_ID, ACBUY_SAMPLE_ORDER_NO, ACBUY_SAMPLE_CHANNEL_ID, ACBUY_SAMPLE_LETTER_ID, ACBUY_SAMPLE_CART_ID). Options:
    • --include-writes to include endpoints that mutate state (cart, orders, tags, payments).
    • --fail-on-skip to fail if any endpoint is skipped due to missing samples.
  • Extra env vars for full payloads: ACBUY_RICH_GOODS_ID, ACBUY_RICH_ITEM_ID, ACBUY_RICH_SOURCE, ACBUY_RICH_SKU_ID (defaults use the 1688 item from the export). By default, cart add/edit/remove flows are disabled; enable with ACBUY_ENABLE_CART_OPS=1 if you want to exercise these endpoints against a real cart.
  • scripts/burp_diff.py: compares a Burp XML export (like the provided model) with paths implemented in src/acbuy (client + services/), listing missing and extra endpoints.
  • scripts/parse_burp_xml.py: reads a Burp XML export, identifies method/path, extracts payload, and tries to decrypt request/response (encrypted field) using the AES key loaded from the site. Options:
    • --base-url to override base URL (default: ACBUY_BASE_URL or https://www.acbuy.com)
    • --limit N to show only the first N items
    • --no-decrypt to skip decryption

Recommendation: use Burp exports with Base64 (export-base64-encode.xml) as the default, because they preserve the encrypted body exactly as it reaches the client and speed up analysis/decryption.

About

Complete Python suite to talk to the encrypted AcBuy API

Topics

python cryptography webscraping acbuy

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Languages