Automazione
Continua a lavorare come fai ora.
Il tuo PIM, ERP, DAM o una cartella condivisa ha già i dati e le foto. Scegli la prima ricetta adatta: funzionano con qualsiasi portale Open Brand Exchange.
$ 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: exportQuale ricetta fa per te?
| Hai… | Usa | Codice necessario |
|---|---|---|
| un CSV o uno zip su un indirizzo web, un server SFTP o un bucket S3 | Import pianificato | nessuno |
| una cartella dove arrivano gli export | obx watch | nessuno |
| un server o PC che esegue attività di notte | cron o Utilità di pianificazione | una riga |
| i tuoi export in un repository Git | GitHub Action | un file YAML |
| n8n, Make o Zapier | Passaggi HTTP | nessuno (visuale) |
| uno sviluppatore che collega il tuo PIM o ERP | L'API direttamente | un po' |
Un formato per tutto
Ogni modo di pubblicare legge la stessa cosa: un products.csv con una riga per taglia e foto chiamate {style}_{color}_{position}.jpg (modello, colore, posizione). Una volta pronto questo, tutte le ricette qui sotto funzionano.
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.jpgCosa ti serve
Nella tua amministrazione, apri Caricamento automatico → Chiavi di accesso e crea una nuova chiave. Avrai due valori: l'indirizzo del tuo portale (OBX_URL) e la chiave stessa (OBX_TOKEN). La chiave viene mostrata una sola volta.
export OBX_URL=https://brands.kestrel.example
export OBX_TOKEN=obxi_… # admin → Automatic upload → Access keys (shown once)Dai a ogni sistema la sua chiave. Così puoi revocarne una senza bloccare le altre.
1. Import pianificato (senza codice)
Nella tua amministrazione: Caricamento automatico → Importazioni pianificate → Aggiungi importazione pianificata. Scegli la sorgente e ogni quanto deve girare.
- Indirizzo web (HTTPS): l'indirizzo di un products.csv, o di uno zip con products.csv e le foto. Le credenziali sono conservate cifrate.
- SFTP: server, utente, password o chiave, e la cartella con l'export.
- Bucket S3: AWS S3, Cloudflare R2, MinIO o Backblaze: endpoint, bucket, cartella e una chiave di sola lettura.
Scegli «Solo aggiungere e aggiornare» o «Mettere offline anche gli articoli assenti». La seconda opzione mette offline anche ciò che è sparito dal file, ma si ferma se sparisse più della metà di un marchio, così un'esportazione difettosa non svuota mai il tuo catalogo. «Prova la connessione» mostra quali file verrebbero letti.
Lo strumento obx
obx è un unico programma per Windows, macOS e Linux. Legge OBX_URL e OBX_TOKEN dall'ambiente, carica solo foto nuove o modificate, crea le versioni web se serve e aspetta che il portale abbia elaborato tutto. Eseguilo tutte le volte che vuoi: gli articoli invariati non costano nulla.
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 errorsCodice di uscita 0 = tutto ok, 2 = finito ma alcune righe avevano errori (vengono elencate), 1 = non riuscito.
2. Una cartella che si pubblica da sola: obx watch
Lascia che il tuo PIM, ERP o un collega salvi gli export in una cartella. obx watch pubblica appena qualcosa cambia e salta le foto rimaste uguali. Eseguilo come servizio o con 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 o Utilità di pianificazione di Windows
# 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
Salva OBX_URL e OBX_TOKEN come secret del repository. Lo stesso funziona in GitLab CI, Bitbucket o Azure DevOps: installa obx ed esegui obx push.
# .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 o Zapier
Usa un normale passaggio HTTP Request con l'intestazione Authorization: Bearer seguita dalla tua chiave. Ogni passaggio si può ripetere senza problemi: inviare due volte gli stessi dati non cambia nulla.
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>Il Portale per Cloudflare non crea da solo le versioni web delle foto. Lì pubblica con obx o da «Importazioni» nella tua amministrazione: le creano loro per te. Le foto che arrivano in altro modo, per esempio da un'importazione pianificata, fino ad allora sono mostrate nel formato originale.
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json
{"status": "unpublished"}Vuoi un avviso quando succede qualcosa? Nella tua amministrazione aggiungi una notifica (webhook) per un import concluso o una nuova richiesta di accesso, e usala per avviare un trigger in n8n, Make o Zapier.
6. L'API direttamente (per sviluppatori)
Un'integrazione ricorda cosa ha inviato l'ultima volta e invia solo le modifiche, a lotti. Oppure invia il CSV così com'è e lascia che il portale lo legga.
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>Tutti i dettagli sono nella specifica:Ingest API ·ricette di automazione ·SDK Go ·Sviluppatori