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

1. Copy .env.example to .env.
2. Fill in:
   • BAMBUDDY_BASE_URL
   • BAMBUDDY_API_KEY
   • INVENTREE_BASE_URL
   • INVENTREE_TOKEN
   • INVENTREE_PART_CATEGORY_ID
   • INVENTREE_STOCK_LOCATION_ID
3. 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"

When SYNC_SUCCESS_ONLY=true, max_archives counts import attempts. Archives that are still printing or already failed are skipped and do not consume the limit.

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.

InvenTree Part Parameters

For each synced Part, the service updates these InvenTree parameters when matching parameter templates exist:

• Weight: filament weight per printed item in grams. If a Bambuddy archive has quantity=2, the total filament weight is divided by 2.
• PrintTime: print duration from Bambuddy. The visible value is formatted as 1h 6m 1s; data_numeric stores the duration in seconds.

InvenTree Part Images

When SYNC_PART_IMAGES=true, the service downloads the Bambuddy archive thumbnail and uploads it to the InvenTree Part.image field.

By default, existing InvenTree part images are preserved:

OVERWRITE_PART_IMAGES=false

Set OVERWRITE_PART_IMAGES=true if Bambuddy thumbnails should replace existing part images.

Bambuddy External Links

When SYNC_ARCHIVE_EXTERNAL_LINK=true, the service writes the InvenTree part page URL into Bambuddy archive external_url.

The default link format is:

<INVENTREE_WEB_URL or INVENTREE_BASE_URL>/web/part/<part_id>/

Existing non-InvenTree external links are preserved unless:

OVERWRITE_ARCHIVE_EXTERNAL_LINK=true

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.