Automatizace

Pracujte dál tak jako dosud.

Váš PIM, ERP, DAM nebo sdílená složka už data i fotografie má. Vyberte první návod, který sedí: všechny fungují s každým portálem 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

Který návod se vám hodí?

Máte…PoužijtePotřebný kód
CSV nebo zip na webové adrese, serveru SFTP nebo v bucketu S3Plánovaný importžádný
složku, kam dorazí exportyobx watchžádný
server nebo PC, který v noci spouští úlohycron nebo Plánovač úlohjeden řádek
exporty v repozitáři GitGitHub Actionjeden soubor YAML
n8n, Make nebo ZapierKroky HTTPžádný (vizuálně)
vývojáře, který napojí váš PIM nebo ERPPřímo APItrochu

Jeden formát pro všechno

Všechny způsoby publikování čtou totéž: products.csv s jedním řádkem na velikost a fotky pojmenované {style}_{color}_{position}.jpg (model, barva, pozice). Jakmile to máte, fungují všechny návody níže.

products.csv (zkráceno)
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
Názvy souborů fotografií
images/
  KO-1001_NVY_1.jpg     ← style KO-1001, colour NVY, position 1 (front)
  KO-1001_NVY_2.jpg
  KO-1001_NVY_3.jpg

Kompletní formát importu

Co potřebujete

V administraci otevřete Automatické nahrávání → Přístupové klíče a vytvořte nový klíč. Získáte dvě hodnoty: adresu portálu (OBX_URL) a samotný klíč (OBX_TOKEN). Klíč se zobrazí jen jednou.

export OBX_URL=https://brands.kestrel.example
export OBX_TOKEN=obxi_…   # admin → Automatic upload → Access keys (shown once)

Dejte každému systému vlastní klíč. Pak můžete jeden zrušit, aniž byste rozbili ostatní.

1. Plánovaný import (bez kódu)

V administraci: Automatické nahrávání → Plánované importy → Přidat plánovaný import. Zvolte zdroj a jak často se má spouštět.

  • Webová adresa (HTTPS): adresa souboru products.csv, nebo zipu s products.csv a fotografiemi. Přihlašovací údaje se ukládají šifrovaně.
  • SFTP: server, uživatel, heslo nebo klíč a složka s exportem.
  • Bucket S3: AWS S3, Cloudflare R2, MinIO nebo Backblaze: endpoint, bucket, složka a klíč jen pro čtení.

Zvolte „Jen přidávat a aktualizovat“ nebo „Stáhnout z nabídky i chybějící artikly“. Druhá možnost stáhne i to, co ze souboru zmizelo, ale zastaví se, pokud by zmizela více než polovina značky, takže vadný export nikdy nevyprázdní váš katalog. „Otestovat připojení“ ukáže, které soubory by se načetly.

Nástroj obx

obx je jediný program pro Windows, macOS a Linux. Čte OBX_URL a OBX_TOKEN z prostředí, nahrává jen nové nebo změněné fotografie, podle potřeby vytváří webové verze a čeká, dokud portál vše nezpracuje. Spouštějte ho, jak často chcete: nezměněné položky nic nestojí.

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

Návratový kód 0 = vše v pořádku, 2 = hotovo, ale některé řádky měly chyby (jsou vypsány), 1 = selhalo.

Stáhnout obx · obx-go

2. Složka, která se publikuje sama: obx watch

Nechte PIM, ERP nebo kolegu ukládat exporty do složky. obx watch publikuje, jakmile se něco změní, a přeskakuje fotky, které zůstaly stejné. Spusťte ho jako službu nebo v Dockeru:

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 nebo Plánovač úloh Windows

Linux nebo 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, jednou)
$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

Uložte OBX_URL a OBX_TOKEN jako tajné hodnoty repozitáře. Stejně to funguje v GitLab CI, Bitbucketu nebo Azure DevOps: nainstalujte obx a spusťte 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 nebo Zapier

Použijte běžný krok HTTP Request s hlavičkou Authorization: Bearer a vaším klíčem. Každý krok lze bezpečně opakovat: dvojí odeslání stejných dat nic nezmění.

Položka (například když se změní v 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}]}]}
Barva a velikost s 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"}
Fotografie: nejdřív údaje, potom samotný soubor
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>

Portál pro Cloudflare sám nevytváří webové verze fotografií. Publikujte tam pomocí obx nebo přes „Importy“ ve své administraci: ty je vytvoří za vás. Fotografie, které přijdou jinak, například plánovaným importem, se do té doby zobrazují v původní velikosti.

Stažení něčeho
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json

{"status": "unpublished"}

Chcete dostat zprávu, když se něco stane? V administraci přidejte oznámení (webhook) na dokončený import nebo novou žádost o přístup a nechte ho spustit trigger v n8n, Make nebo Zapier.

6. Přímo API (pro vývojáře)

Integrace si pamatuje, co naposledy odeslala, a posílá jen změny, v dávkách. Nebo pošlete CSV tak, jak je, a nechte portál, ať ho načte.

Přeskočit fotky, které portál už má, a poslat jednu dávku
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"
CSV a zip s fotkami najednou
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>

Všechny podrobnosti jsou ve specifikaci:Ingest API ·návody na automatizaci ·Go SDK ·Pro vývojáře