Bambuddy InvenTree Sync

Small sidecar service for syncing Bambuddy Archives into InvenTree.

It currently:

creates an InvenTree Part automatically when a printed model is first seen;
creates one InvenTree StockItem for each synced Bambuddy archive;
stores local sync state in SQLite to avoid duplicate stock items;
accepts Bambuddy webhooks and can also backfill existing archives.

The first version intentionally treats one Bambuddy archive as one printed stock item. Later we can add plate parsing, multi-object quantity detection, filament costing, thumbnails, 3MF attachments, and mapping rules.

Setup

Copy .env.example to .env.
Fill in:
- BAMBUDDY_BASE_URL
- BAMBUDDY_API_KEY
- INVENTREE_BASE_URL
- INVENTREE_TOKEN
- INVENTREE_PART_CATEGORY_ID
- INVENTREE_STOCK_LOCATION_ID
Start the service:

docker compose up -d --build

The service listens on http://localhost:8088.

InvenTree IDs

For the first version, use numeric IDs for the target InvenTree part category and stock location. Open the desired category/location in InvenTree and copy the ID from the URL or API response.

Example:

INVENTREE_PART_CATEGORY_ID=12
INVENTREE_STOCK_LOCATION_ID=7

Validate Connectivity

If SERVICE_API_TOKEN is set in .env, pass it as X-Service-Token:

curl.exe -H "X-Service-Token: change-me" http://localhost:8088/validate

Backfill Existing Archives

Run a test with one archive first:

curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/backfill?max_archives=1"

Run full backfill for successful Bambuddy archives:

curl.exe -X POST -H "X-Service-Token: change-me" http://localhost:8088/sync/backfill

The default behavior is SYNC_SUCCESS_ONLY=true, so failed or stopped prints are not imported.

Bambuddy Webhook

In Bambuddy, configure a webhook to:

http://WINDOWS-SERVER-IP:8088/webhooks/bambuddy

If WEBHOOK_SHARED_SECRET is configured, Bambuddy must send this header:

X-Sync-Secret: your-secret

The service expects Bambuddy payloads with event=print_complete and data.archive_id.

Part Matching

The service builds a stable key from:

PART_KEY_FIELDS=filename,name

That key becomes an InvenTree IPN:

BMB-<first-12-sha1-chars>

This means repeat prints of the same file/name reuse the same Part and create new StockItem rows. To change matching behavior later, edit PART_KEY_FIELDS.

Useful Endpoints

GET  /health
GET  /sync/status
GET  /validate
POST /sync/archive/{archive_id}
POST /sync/backfill
POST /webhooks/bambuddy

Manual sync endpoints require X-Service-Token when SERVICE_API_TOKEN is set.

2.7 KiB Raw Blame History