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.

Terminal
$ 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
publish.ymlGitHub Action
# .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: export

Quale ricetta fa per te?

Hai…UsaCodice necessario
un CSV o uno zip su un indirizzo web, un server SFTP o un bucket S3Import pianificatonessuno
una cartella dove arrivano gli exportobx watchnessuno
un server o PC che esegue attività di nottecron o Utilità di pianificazioneuna riga
i tuoi export in un repository GitGitHub Actionun file YAML
n8n, Make o ZapierPassaggi HTTPnessuno (visuale)
uno sviluppatore che collega il tuo PIM o ERPL'API direttamenteun 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.

products.csv (abbreviato)
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,2000100101025
Nomi dei file delle foto
images/
  KO-1001_NVY_1.jpg     ← style KO-1001, colour NVY, position 1 (front)
  KO-1001_NVY_2.jpg
  KO-1001_NVY_3.jpg

Il formato di import completo

Cosa 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 errors

Codice di uscita 0 = tutto ok, 2 = finito ma alcune righe avevano errori (vengono elencate), 1 = non riuscito.

Scarica obx · obx-go

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/outbox
Docker
docker run -d --restart unless-stopped \
  -e OBX_URL -e OBX_TOKEN \
  -v /data/outbox:/outbox \
  ghcr.io/openbrandexchange/obx watch /outbox

3. cron o Utilità di pianificazione di Windows

Linux o macOS
# 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
Windows (PowerShell, una volta)
$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/images

5. 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.

Articolo (per esempio quando cambia nel PIM)
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}]}]}
Colore e taglia, con il suo EAN
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"}
Foto: prima i dati, poi il file
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.

Ritirare qualcosa
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.

Saltare le foto che il portale ha già, poi inviare un lotto
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"
Un CSV e uno zip di foto in un colpo solo
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