148 lines
4.0 KiB
Markdown
148 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```env
|
|
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`:
|
|
|
|
```powershell
|
|
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/validate
|
|
```
|
|
|
|
## Backfill Existing Archives
|
|
|
|
Run a test with one archive first:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```text
|
|
http://WINDOWS-SERVER-IP:8088/webhooks/bambuddy
|
|
```
|
|
|
|
If `WEBHOOK_SHARED_SECRET` is configured, Bambuddy must send this header:
|
|
|
|
```text
|
|
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:
|
|
|
|
```env
|
|
PART_KEY_FIELDS=filename,name
|
|
```
|
|
|
|
That key becomes an InvenTree IPN:
|
|
|
|
```text
|
|
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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```text
|
|
<INVENTREE_WEB_URL or INVENTREE_BASE_URL>/web/part/<part_id>/
|
|
```
|
|
|
|
Existing non-InvenTree external links are preserved unless:
|
|
|
|
```env
|
|
OVERWRITE_ARCHIVE_EXTERNAL_LINK=true
|
|
```
|
|
|
|
## Useful Endpoints
|
|
|
|
```text
|
|
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.
|