Home-Databases/Aliexpress-Part-DB-orders-pull

Files

T

2026-08-16 03:57:24 +02:00

19 KiB

Raw Permalink Blame History

AliExpress → Part-DB Importer

A two-script toolkit for taking an AliExpress orders.csv export and turning it into a Part-DB v2.15.x inventory with product images automatically attached to each part.

┌─────────────────┐    ┌──────────────────────────┐    ┌─────────────┐
│ orders.csv      │ ─► │ aliexpress_to_partdb.py  │ ─► │ partdb_     │
│ (from AliExpr.) │    │  • renames columns       │    │ import.csv  │
└─────────────────┘    │  • downloads all images  │    └──────┬──────┘
                       │  • writes attachments    │           │
                       │    index                 │      [import via
                       └──────────────────────────┘       Part-DB web UI]
                                                            │
                                                            ▼
                       ┌──────────────────────────┐    ┌─────────────┐
                       │ attach_images_to_        │ ◄──│ parts now   │
                       │   partdb.py              │    │ exist in    │
                       │  • reads index           │    │ Part-DB     │
                       │  • finds each part by    │    └─────────────┘
                       │    name via REST API     │
                       │  • uploads image as      │
                       │    attachment            │
                       └──────────────────────────┘

What's in this package

File	Purpose
`aliexpress_to_partdb.py`	Reads AliExpress `orders.csv`, downloads item images, writes Part-DB-format CSV
`attach_images_to_partdb.py`	Pushes the downloaded images to Part-DB and attaches them via the REST API
`README.md`	This file

Put all three files in the same folder, e.g. C:\Users\Amir\Downloads\aliexpress-import\.

Prerequisites

Python 3.8 or newer — check with python --version
The requests library — install with:
```
pip install requests
```
Part-DB v2.15.x running and accessible (test by opening it in your browser)
A Part-DB API token (see below)
At least one Attachment type defined in Part-DB (e.g. "Image") — see Step 1.5

One-time setup

Step 1: Get an API token in Part-DB

Open Part-DB in your browser, log in
Click your username (top right) → Settings
In the left sidebar, click API tokens
Click + Create new token (or "New")
Give it any name (e.g. importer) and click Save
Copy the token — it looks like tcp_xxxxxxxxxxxxxxxxxxxxxxxxxx
- You won't be able to see it again after this dialog closes
- If you lose it, just create a new one

If the "API tokens" section is missing, your user doesn't have the API permission. If you installed Part-DB yourself you're an admin and already have it; otherwise ask your admin to enable "Miscellaneous → API access" + "Create API tokens" for your user.

Step 1.5 (one-time): Create an "Image" attachment type

Part-DB requires an attachment type to exist before any attachment can be created.

In Part-DB, click Admin in the left sidebar
Click Attachment types
Click + New
Name: Image (or whatever you prefer)
Filetypes: leave blank, or add image/jpeg, image/png for stricter validation
Click Save

Verify it worked:

python attach_images_to_partdb.py --list-attachment-types

You should see your "Image" type listed.

Step 2: Configure the script

Open attach_images_to_partdb.py in any text editor and update the two lines near the top:

DEFAULT_PARTDB_URL = "http://YOUR-PART-DB:PORT"       # e.g. http://192.168.64.80:8085
DEFAULT_PARTDB_TOKEN = "tcp_YOUR_TOKEN_HERE"         # the token you just copied

Security: this file now contains a secret. Treat it like a password. See the Security section at the bottom for the full list of dos and don'ts.

The full workflow (for your first import)

Step A: Export your orders from AliExpress

Go to aliexpress.com → My Orders
Click Export (top-right of the orders table) → choose CSV
Save the file as orders.csv in the same folder as the scripts (e.g. C:\Users\Amir\Downloads\aliexpress-import\orders.csv)

Step B: Run the conversion script

cd C:\Users\Amir\Downloads\aliexpress-import
python aliexpress_to_partdb.py orders.csv

This produces, in the same folder:

partdb_import.csv — the Part-DB-format CSV (one row per item)
partdb_images/ — folder of all downloaded product images
partdb_images/attachments.json — index of which image goes with which part

You should see output like:

Loaded 553 order line(s).
All done.
  CSV written to:   C:\...\partdb_import.csv
  Images stored in: C:\...\partdb_images
  Images downloaded: 553/553 (0 failed)

Step C: Import the CSV into Part-DB

Open Part-DB in your browser
In the left sidebar, click Tools → Import parts (or similar)
Click Choose file → select partdb_import.csv
Important settings in the import wizard:
- ✅ CSV delimiter: , (comma — the script uses standard CSV)
- ✅ Create unknown datastructures: checked (so the "New parts" category and any new suppliers are auto-created)
- Mode: "Create new entries" (default) — see FAQ for re-import behavior
Click through the column mapping. The headers in partdb_import.csv are already named to match Part-DB's import schema, so the auto-map should fill in everything correctly
Click Import / Start import
Wait for the progress bar to finish

⚠️ Watch out for re-imports (see FAQ below). The default "Create" mode will make duplicates if you re-import the same CSV.

Step D: Attach the images

cd C:\Users\Amir\Downloads\aliexpress-import
python attach_images_to_partdb.py

You'll see one line per upload, e.g.:

[   1/553] ENS160 ENS160+AHT21 CARBON Dioxide CO2 e  OK  part 558: attached to part 558
[   2/553] TPS63020 Micro Power Module Automatic Vo  OK  part 559: attached to part 559
...
----------------------------------------------------------------------
Done.
  Uploaded:  553
  Skipped:    0  (already attached)
  No match:   0  (part not found in Part-DB)
  Failed:     0

For ~553 items at 0.15s between calls, expect roughly 1–2 minutes.

The script is idempotent — running it again will skip parts that already have an attachment with the same filename. So you can re-run it anytime without creating duplicates.

Step E: Verify

Open any of the imported parts in Part-DB — the product image should appear in the Attachments tab (and as a thumbnail in the part list if Part-DB auto-set it as the preview, which it usually does).

For future use (when you buy more parts)

The next time you want to import a fresh AliExpress order:

Export the new orders.csv from AliExpress
If the new CSV contains only new parts (no overlap with the old import), you can just re-run Steps B → D above with the new file
If the new CSV might overlap with the old one, read the Re-imports / dedup section in the FAQ below

Optional but recommended: rotate your Part-DB API token periodically to keep it from accumulating exposure. Just delete the old one in Part-DB's API tokens page and paste the new one into the script.

Script 1: `aliexpress_to_partdb.py`

What it does

Reads orders.csv from AliExpress
Maps each row to a Part-DB part using the v2.15.x CSV import schema
Downloads every Item image url to partdb_images/ (upgrades AliExpress's _220x220.jpg thumbnail URLs to full-size, falls back to the thumbnail on 404)
Writes attachments.json mapping each part to its image file(s)
Writes partdb_import.csv ready for the Part-DB import wizard

Run command

cd C:\Users\Amir\Downloads\aliexpress-import
python aliexpress_to_partdb.py orders.csv

Options

python aliexpress_to_partdb.py orders.csv -o my_parts.csv -d ./images
python aliexpress_to_partdb.py orders.csv --no-images       :: CSV only, skip downloads

Customizing the default category

The default category for all imported parts is New parts. To change it (for example to Electronics/Sensors or Imported/2026-Q3):

Open aliexpress_to_partdb.py in a text editor
Find the line near the top:
```
DEFAULT_CATEGORY = "New parts"
```
Change the string to whatever you want
Save the file

The category is auto-created the first time you import, as long as "Create unknown datastructures" is checked in the Part-DB import wizard (see Step C above). Sub-categories use -> as the separator (e.g. Imported -> 2026 -> Q3).

Output files

File	Contents
`partdb_import.csv`	The CSV you upload to Part-DB's import wizard
`partdb_images/<part-name>_<idx>.jpg`	One image per part, full size when available
`partdb_images/attachments.json`	Index: row → part name → image file path. Used by script 2

Script 2: `attach_images_to_partdb.py`

What it does

Reads attachments.json from script 1
For each entry, queries Part-DB for a part with the matching name
Auto-picks an attachment type whose name looks like "Image" / "Photo" / etc., or falls back to the first available type
Uploads the image as a PartAttachment
Skips parts that already have an attachment with the same filename (idempotent — safe to re-run)

Run command (just run it)

cd C:\Users\Amir\Downloads\aliexpress-import
python attach_images_to_partdb.py

The URL and token are read from the DEFAULT_PARTDB_URL and DEFAULT_PARTDB_TOKEN constants at the top of the file. Override with env vars (recommended for shared machines) or CLI flags (see below).

Options

:: Show all flags
python attach_images_to_partdb.py --help

:: Override the URL/token (e.g. for a different Part-DB instance)
python attach_images_to_partdb.py --url http://localhost:8000 --token tcp_xxx

:: Test with the first 3 entries, no changes made
python attach_images_to_partdb.py --limit 3 --dry-run

:: Run for real, only on the first 50
python attach_images_to_partdb.py --limit 50

:: List all attachment types in your Part-DB (useful for picking one)
python attach_images_to_partdb.py --list-attachment-types

:: Force a specific attachment type
python attach_images_to_partdb.py --attachment-type /api/attachment_types/1

:: Skip TLS verification (self-signed certs)
python attach_images_to_partdb.py --insecure

Using env vars instead of editing the file (more secure)

set PARTDB_URL=http://192.168.64.80:8085
set PARTDB_TOKEN=tcp_xxxxxxxx
python attach_images_to_partdb.py

In PowerShell:

$env:PARTDB_URL = "http://192.168.64.80:8085"
$env:PARTDB_TOKEN = "tcp_xxxxxxxx"
python attach_images_to_partdb.py

FAQ

When I re-import the same CSV, does it skip existing parts?

No, by default Part-DB will create duplicates. The CSV importer's default mode is "Create new entries" — it does not check for existing parts.

For the AliExpress use case (one big import, plus small future imports of new items), this is rarely a problem because the new orders contain different parts. But if you ever need to re-import the same file (or a file that overlaps with an old one), do one of these:

Option 1 — Use the import wizard's matching mode

In the Part-DB import wizard, look for a "Mode" or "Match existing parts" option:

Create (default) — always creates new parts → duplicates
Update — updates matching parts, leaves the rest alone
Skip — skips any part that already matches

If available, pick Update or Skip and choose the match key (usually name works, but manufacturer_product_number is more reliable for electronics).

Option 2 — Delete duplicates manually after import

After the import, in the Part-DB parts list, sort by name, find the duplicates, select all → Delete. Tedious but works.

Option 3 — Import to a temporary category, then move

Import into a unique category (e.g. Incoming/2026-08-15), then manually move parts to their final categories. Anything that was already in the final categories will now appear twice, which is easy to spot.

The image script says "no attachment types defined"

You skipped Step 1.5 or your Part-DB has no attachment types at all. Fix:

python attach_images_to_partdb.py --list-attachment-types

If it prints nothing, go to Admin → Attachment types in Part-DB's web UI and create at least one (recommended name: Image).

The image script says "401 Unauthorized"

Token is wrong, expired, or your user lacks API permission.

Open Part-DB → User menu → Settings → API tokens → create a new one
Paste it into DEFAULT_PARTDB_TOKEN in the script (or set PARTDB_TOKEN env var)
If the API tokens section is missing, ask your admin to grant "Miscellaneous → API access" + "Create API tokens" to your user

The image script says "no match in Part-DB" for some rows

Either:

You skipped Step C (CSV import) — the parts aren't in Part-DB yet
The part name in Part-DB differs slightly from what's in the CSV (e.g. truncated, case-different, or with extra characters)
You're looking at parts in a different Part-DB instance

The first one is most common. Run Step C, then re-run the image script — it will skip already-uploaded ones and pick up where it left off.

The connection fails / "cannot reach Part-DB"

Make sure http://YOUR-PART-DB:PORT opens in your browser first
If Part-DB is on HTTPS, change DEFAULT_PARTDB_URL to start with https:// and possibly add --insecure if you have a self-signed cert
If Part-DB is on a different machine, check the firewall / port forwarding

Can I import other vendors (LCSC, Mouser, Digi-Key)?

The CSV format from other vendors is different. To support them you'd need a new conversion script. The aliexpress_to_partdb.py script has the AliExpress header names hard-coded near the top — you'd write a parallel script with a different AE = {...} mapping. Happy to help if you need this.

How do I move all my AliExpress parts to a different category later?

In Part-DB, go to the part list, filter by category = "New parts", select all → Edit → change the category. Or use the Part-DB REST API for bulk moves.

Troubleshooting checklist

Symptom	Likely cause	Fix
`File invalid. Please check that you have selected the right format!` in Part-DB import	CSV column names don't match Part-DB's schema	Re-run `aliexpress_to_partdb.py`; the current version uses the verified 2.15.x column names
`must be one of Orderdetail[] (string given)`	Old script version used `orderdetails` as a flat column	Use the latest `aliexpress_to_partdb.py` from this package
`KeyError: 'ordernumber'` at script startup	Old script version	Use the latest version from this package
`DeprecationWarning: 'maxsplit' is passed as positional argument`	Old script version (cosmetic)	Update to the latest version
Image script: `no attachment types`	Skipped Step 1.5	See this FAQ entry
Image script: `no match in Part-DB`	Skipped CSV import step, or names differ	Run Step C first, or check Part-DB web UI
Image script: `401 Unauthorized`	Bad/expired token, or no API permission	Recreate token in Part-DB; check user has API permission
Image script: `SSL: CERTIFICATE_VERIFY_FAILED`	Self-signed HTTPS cert	Add `--insecure` flag
Some images fail to download (`404 Client Error`)	Seller removed the image from AliExpress CDN	Script falls back to the thumbnail; if even that fails, the part is created without an image — you can attach a manual photo later

Security

This package handles an API token that grants access to your Part-DB under your user account. Please:

✅ Do:

Keep the script folder on your local machine only
Use a fresh token dedicated to this purpose
Treat the file like a password — it should not leak
Rotate (delete + recreate) the token periodically
If you ever share your screen / codebase, blank the DEFAULT_PARTDB_TOKEN line first
For a "cleaner" approach, use the PARTDB_TOKEN env var instead of baking it into the file

❌ Don't:

Commit the folder to git (add a .gitignore containing *.py if you must)
Sync the folder to cloud backups (OneDrive, Dropbox, Google Drive, iCloud) without first removing the token
Share the folder publicly
Re-use the same token for other applications
Leave the file on a USB stick you might lose

If your token leaks

In Part-DB: User menu → Settings → API tokens → delete the leaked one
Create a new token and paste it into the script
Check Part-DB's audit log for unexpected activity
Done — the new token works immediately

Files at a glance

aliexpress-import\
├── README.md                          ← you are here
├── aliexpress_to_partdb.py            ← script 1: CSV + image downloader
├── attach_images_to_partdb.py         ← script 2: REST API uploader
├── orders.csv                         ← (your input) AliExpress export
├── partdb_import.csv                  ← (output) Part-DB-ready CSV
└── partdb_images\                     ← (output) downloaded images
    ├── ENS160_ENS160+AHT21_..._1.jpg
    ├── TPS63020_Micro_Power_..._2.jpg
    ├── …
    └── attachments.json               ← (output) image index for script 2

Quick reference card

Task	Command
Convert CSV + download images	`python aliexpress_to_partdb.py orders.csv`
Skip image download (CSV only)	`python aliexpress_to_partdb.py orders.csv --no-images`
Import to Part-DB	Use web UI: Tools → Import parts → upload `partdb_import.csv`
Attach all images	`python attach_images_to_partdb.py`
Test 3 images first	`python attach_images_to_partdb.py --limit 3 --dry-run`
List attachment types	`python attach_images_to_partdb.py --list-attachment-types`
Show all flags	`python attach_images_to_partdb.py --help`

Version notes

Tested with:

AliExpress CSV export (as of mid-2026)
Part-DB v2.15.0
Python 3.10 / 3.11 on Windows 10/11

If Part-DB changes its CSV schema in a future version, you may need to update the column names in PARTDB_COLUMNS near the top of aliexpress_to_partdb.py. Check the official docs: https://docs.part-db.de/usage/import_export.html

19 KiB Raw Permalink Blame History Unescape Escape

AliExpress → Part-DB Importer

What's in this package

Prerequisites

One-time setup

Step 1: Get an API token in Part-DB

Step 1.5 (one-time): Create an "Image" attachment type

Step 2: Configure the script

The full workflow (for your first import)

Step A: Export your orders from AliExpress

Step B: Run the conversion script

Step C: Import the CSV into Part-DB

Step D: Attach the images

Step E: Verify

For future use (when you buy more parts)

Script 1: aliexpress_to_partdb.py

What it does

Run command

Options

Customizing the default category

Output files

Script 2: attach_images_to_partdb.py

What it does

Run command (just run it)

Options

Using env vars instead of editing the file (more secure)

FAQ

When I re-import the same CSV, does it skip existing parts?

The image script says "no attachment types defined"

The image script says "401 Unauthorized"

The image script says "no match in Part-DB" for some rows

The connection fails / "cannot reach Part-DB"

Can I import other vendors (LCSC, Mouser, Digi-Key)?

How do I move all my AliExpress parts to a different category later?

Troubleshooting checklist

Security

If your token leaks

Files at a glance

Quick reference card

Version notes

19 KiB

Raw Permalink Blame History

Script 1: `aliexpress_to_partdb.py`

Script 2: `attach_images_to_partdb.py`