Automatisierung
Arbeiten Sie weiter wie bisher.
Ihr PIM, ERP, DAM oder ein gemeinsamer Ordner hat die Daten und Fotos bereits. Wählen Sie das erste Rezept, das passt: Alle funktionieren mit jedem Open-Brand-Exchange-Portal.
$ obx push ./export
Publishing to brands.kestrel.example (Kestrel, Kestrel Trail)
images: 27 checked, 3 uploaded (4.2 MB) in 3s
Done: rows: 40, images: 27 → new: 2 · updated: 3 · unchanged: 35# .github/workflows/publish.yml
on:
push:
paths: ["export/**"]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: openbrandexchange/obx-go/push-action@v0
with:
url: ${{ secrets.OBX_URL }}
token: ${{ secrets.OBX_TOKEN }}
folder: exportWelches Rezept passt zu Ihnen?
| Sie haben … | Verwenden Sie | Code nötig |
|---|---|---|
| eine CSV- oder ZIP-Datei auf einer Webadresse, einem SFTP-Server oder S3-Bucket | Geplanter Import | nein |
| einen Ordner, in dem Exporte landen | obx watch | nein |
| einen Server oder PC, der nachts Aufgaben ausführt | cron oder Aufgabenplanung | eine Zeile |
| Ihre Exporte in einem Git-Repository | GitHub Action | eine YAML-Datei |
| n8n, Make oder Zapier | HTTP-Schritte | nein (visuell) |
| einen Entwickler, der Ihr PIM oder ERP anbindet | Die API direkt | ein wenig |
Ein Format für alles
Jeder Weg liest dasselbe: eine products.csv mit einer Zeile pro Größe und Fotos mit dem Namen {style}_{color}_{position}.jpg (Artikelnummer, Farbe, Position). Sobald Sie das haben, funktioniert jedes Rezept unten.
brand,style_number,name:en,name:nl,item_type,season,materials,color_code,color_name:en,size,gtin
Kestrel,KO-1001,Merino Crew Sweater,Merino trui met ronde hals,sweater,AW26,main: 100% merino_wool,NVY,Navy,S,2000100101018
Kestrel,KO-1001,Merino Crew Sweater,Merino trui met ronde hals,sweater,AW26,main: 100% merino_wool,NVY,Navy,M,2000100101025images/
KO-1001_NVY_1.jpg ← style KO-1001, colour NVY, position 1 (front)
KO-1001_NVY_2.jpg
KO-1001_NVY_3.jpgWas Sie brauchen
Öffnen Sie in Ihrer Verwaltung „Automatischer Upload → Zugangsschlüssel“ und erstellen Sie einen neuen Schlüssel. Dann haben Sie zwei Werte: die Adresse Ihres Portals (OBX_URL) und den Schlüssel selbst (OBX_TOKEN). Der Schlüssel wird nur einmal angezeigt.
export OBX_URL=https://brands.kestrel.example
export OBX_TOKEN=obxi_… # admin → Automatic upload → Access keys (shown once)Geben Sie jedem System einen eigenen Schlüssel. Dann können Sie einen widerrufen, ohne die anderen zu stören.
1. Geplanter Import (ohne Code)
In Ihrer Verwaltung: Automatischer Upload → Geplante Importe → Geplanten Import hinzufügen. Wählen Sie die Quelle und wie oft er laufen soll.
- Webadresse (HTTPS): die Adresse einer products.csv oder einer ZIP-Datei mit products.csv und Fotos. Zugangsdaten werden verschlüsselt gespeichert.
- SFTP: Server, Benutzer, Passwort oder Schlüssel und der Ordner mit dem Export.
- S3-Bucket: AWS S3, Cloudflare R2, MinIO oder Backblaze: Endpunkt, Bucket, Ordner und ein Nur-Lese-Schlüssel.
Wählen Sie „Nur hinzufügen und aktualisieren“ oder „Fehlende Artikel auch offline nehmen“. Die zweite Option nimmt auch offline, was aus der Datei verschwunden ist, bricht aber ab, wenn mehr als die Hälfte einer Marke verschwinden würde, damit ein fehlerhafter Export nie Ihren Katalog leert. „Verbindung testen“ zeigt, welche Dateien gelesen würden.
Das obx-Tool
obx ist ein einzelnes Programm für Windows, macOS und Linux. Es liest OBX_URL und OBX_TOKEN aus der Umgebung, lädt nur neue oder geänderte Fotos hoch, erstellt bei Bedarf die Webversionen und wartet, bis Ihr Portal alles verarbeitet hat. Führen Sie es so oft aus, wie Sie möchten: Unveränderte Artikel kosten nichts.
obx info # check the token, see limits and brands
obx push --csv products.csv --images ./images # publish a CSV and a folder (or zip) of images
obx push --package export.zip # the same, as one zip
obx push --csv products.csv --images ./images --mirror # also take offline what is no longer in the file
obx push --csv products.csv --images ./images --dry-run # only check, change nothing
obx watch ./outbox # keep publishing whatever lands in a folder
obx status # recent jobs and their errorsExit-Code 0 = alles gut, 2 = fertig, aber einige Zeilen hatten Fehler (sie werden aufgelistet), 1 = fehlgeschlagen.
2. Ein Ordner, der sich selbst veröffentlicht: obx watch
Lassen Sie Ihr PIM, ERP oder einen Kollegen Exporte in einem Ordner ablegen. obx watch veröffentlicht, sobald sich etwas ändert, und überspringt unveränderte Fotos. Als Dienst ausführen oder mit Docker:
obx watch /data/outboxdocker run -d --restart unless-stopped \
-e OBX_URL -e OBX_TOKEN \
-v /data/outbox:/outbox \
ghcr.io/openbrandexchange/obx watch /outbox3. cron oder Windows-Aufgabenplanung
# crontab -e: every night at 02:30
30 2 * * * OBX_URL=https://brands.kestrel.example OBX_TOKEN=obxi_… /usr/local/bin/obx push --csv /exports/products.csv --images /exports/images >> /var/log/obx.log 2>&1$action = New-ScheduledTaskAction -Execute "C:\Tools\obx.exe" -Argument "push --csv D:\Export\products.csv --images D:\Export\images"
$trigger = New-ScheduledTaskTrigger -Daily -At 2:30am
[Environment]::SetEnvironmentVariable("OBX_URL", "https://brands.kestrel.example", "Machine")
[Environment]::SetEnvironmentVariable("OBX_TOKEN", "obxi_…", "Machine")
Register-ScheduledTask -TaskName "Publish to OBX" -Action $action -Trigger $trigger -User "SYSTEM"4. GitHub Action
Hinterlegen Sie OBX_URL und OBX_TOKEN als Repository-Secrets. Das funktioniert genauso in GitLab CI, Bitbucket oder Azure DevOps: obx installieren und obx push ausführen.
# .github/workflows/publish.yml (secrets: OBX_URL, OBX_TOKEN)
name: Publish product content
on:
push:
branches: [main]
paths: ["export/**"]
schedule:
- cron: "30 2 * * *"
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install obx
run: |
curl -fsSL https://github.com/openbrandexchange/obx-go/releases/latest/download/obx_linux_amd64.tar.gz | tar -xz obx
sudo mv obx /usr/local/bin/
- name: Publish
env:
OBX_URL: ${{ secrets.OBX_URL }}
OBX_TOKEN: ${{ secrets.OBX_TOKEN }}
run: obx push --csv export/products.csv --assets-csv export/assets.csv --images export/images5. n8n, Make oder Zapier
Verwenden Sie einen normalen HTTP-Request-Schritt mit dem Header Authorization: Bearer und Ihrem Schlüssel. Jeder Schritt darf wiederholt werden: Dieselben Daten zweimal zu senden ändert nichts.
PUT {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/json
{"style_number": "KO-1001",
"name": {"en": "Merino Crew Sweater", "nl": "Merino trui met ronde hals"},
"item_type": "sweater", "season": "AW26",
"materials": [{"part": "main", "fibers": [{"fiber": "merino_wool", "percentage": 100}]}]}PUT {OBX_URL}/obx/v1/ingest/variants/2000100101025
Authorization: Bearer obxi_…
Content-Type: application/json
{"product_external_id": "KO-1001", "gtin": "2000100101025",
"color": {"code": "NVY", "name": {"en": "Navy"}}, "size": "M"}PUT {OBX_URL}/obx/v1/ingest/assets/KO-1001_NVY_1
Authorization: Bearer obxi_…
Content-Type: application/json
{"product_external_id": "KO-1001", "color_code": "NVY",
"role": "packshot", "view": "front", "position": 1}
PUT {OBX_URL}/obx/v1/ingest/assets/KO-1001_NVY_1/files/original
Authorization: Bearer obxi_…
Content-Type: image/jpeg
<the image file as binary body>Das Portal für Cloudflare erstellt selbst keine Webversionen von Fotos. Veröffentlichen Sie dort mit obx oder über „Importe“ in Ihrer Verwaltung: Die erstellen sie für Sie. Fotos, die auf anderem Weg ankommen, etwa über einen geplanten Import, werden bis dahin in Originalgröße gezeigt.
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json
{"status": "unpublished"}Sie möchten Bescheid bekommen, wenn etwas passiert? Richten Sie in Ihrer Verwaltung eine Benachrichtigung (Webhook) für einen abgeschlossenen Import oder eine neue Zugangsanfrage ein und lassen Sie damit einen Trigger in n8n, Make oder Zapier starten.
6. Die API direkt (für Entwickler)
Eine Anbindung merkt sich, was sie zuletzt gesendet hat, und schickt nur Änderungen, in Stapeln. Oder senden Sie die CSV so, wie sie ist, und lassen Sie das Portal sie einlesen.
URL="$OBX_URL/obx/v1/ingest"; AUTH="Authorization: Bearer $OBX_TOKEN"
# 1. Upload only the images the node does not have yet (addressed by sha256).
for f in images/*.jpg; do
sha=$(shasum -a 256 "$f" | cut -d' ' -f1)
curl -sf -I -H "$AUTH" "$URL/blobs/$sha" >/dev/null || \
curl -sf -X PUT -H "$AUTH" -H 'Content-Type: image/jpeg' --data-binary @"$f" "$URL/blobs/$sha"
done
# 2. One batch of up to 1000 operations (NDJSON), processed in order.
cat > batch.ndjson <<'EOF'
{"op":"upsert","kind":"product","external_id":"KO-1001","data":{"style_number":"KO-1001","name":{"en":"Merino Crew Sweater"}}}
{"op":"upsert","kind":"variant","external_id":"2000100101025","data":{"product_external_id":"KO-1001","gtin":"2000100101025","color":{"code":"NVY"},"size":"M"}}
{"op":"unpublish","kind":"product","external_id":"KO-0999"}
EOF
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/x-ndjson' \
-H "Idempotency-Key: nightly-$(date +%F)" --data-binary @batch.ndjson "$URL/batch"curl -s -X POST -H "Authorization: Bearer $OBX_TOKEN" \
-F [email protected] -F [email protected] \
-F 'options={"mode":"upsert"};type=application/json' \
"$OBX_URL/obx/v1/ingest/imports" # returns a job; poll $OBX_URL/obx/v1/ingest/jobs/<id>Alle Details stehen in der Spezifikation:Ingest API ·Automatisierungsrezepte ·Go-SDK ·Entwickler