Automatizácia

Pracujte ďalej tak, ako teraz.

Váš PIM, ERP, DAM alebo zdieľaný priečinok už údaje aj fotografie má. Vyberte prvý návod, ktorý sedí: všetky fungujú s každým portálom 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

Ktorý návod sa vám hodí?

Máte…PoužitePotrebný kód
CSV alebo zip na webovej adrese, serveri SFTP alebo v buckete S3Plánovaný importžiadny
priečinok, kam prichádzajú exportyobx watchžiadny
server alebo PC, ktorý v noci spúšťa úlohycron alebo Plánovač úlohjeden riadok
exporty v repozitári GitGitHub Actionjeden súbor YAML
n8n, Make alebo ZapierKroky HTTPžiadny (vizuálne)
vývojára, ktorý napojí váš PIM alebo ERPPriamo APItrochu

Jeden formát na všetko

Všetky spôsoby publikovania čítajú to isté: products.csv s jedným riadkom na veľkosť a fotky pomenované {style}_{color}_{position}.jpg (model, farba, pozícia). Keď to máte, fungujú všetky návody nižšie.

products.csv (skrátené)
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 súborov 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

Čo potrebujete

V administrácii otvorte Automatické nahrávanie → Prístupové kľúče a vytvorte nový kľúč. Získate dve hodnoty: adresu portálu (OBX_URL) a samotný kľúč (OBX_TOKEN). Kľúč sa zobrazí iba raz.

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

Dajte každému systému vlastný kľúč. Potom môžete jeden zrušiť bez toho, aby ste pokazili ostatné.

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

V administrácii: Automatické nahrávanie → Plánované importy → Pridať plánovaný import. Zvoľte zdroj a ako často sa má spúšťať.

  • Webová adresa (HTTPS): adresa súboru products.csv alebo zipu s products.csv a fotografiami. Prihlasovacie údaje sa ukladajú šifrovane.
  • SFTP: server, používateľ, heslo alebo kľúč a priečinok s exportom.
  • Bucket S3: AWS S3, Cloudflare R2, MinIO alebo Backblaze: endpoint, bucket, priečinok a kľúč iba na čítanie.

Zvoľte „Len pridávať a aktualizovať“ alebo „Stiahnuť z ponuky aj chýbajúci tovar“. Druhá možnosť stiahne aj to, čo zo súboru zmizlo, ale zastaví sa, ak by zmizla viac ako polovica značky, takže chybný export nikdy nevyprázdni váš katalóg. „Otestovať pripojenie“ ukáže, ktoré súbory by sa načítali.

Nástroj obx

obx je jediný program pre Windows, macOS a Linux. Číta OBX_URL a OBX_TOKEN z prostredia, nahráva iba nové alebo zmenené fotografie, podľa potreby vytvára webové verzie a čaká, kým portál všetko nespracuje. Spúšťajte ho, ako často chcete: nezmenené položky nič nestoja.

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šetko v poriadku, 2 = hotovo, ale niektoré riadky mali chyby (sú vypísané), 1 = zlyhalo.

Stiahnuť obx · obx-go

2. Priečinok, ktorý sa publikuje sám: obx watch

Nechajte PIM, ERP alebo kolegu ukladať exporty do priečinka. obx watch publikuje, len čo sa niečo zmení, a preskakuje fotky, ktoré zostali rovnaké. Spustite ho ako službu alebo v Dockeri:

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

Linux alebo 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, raz)
$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 ako tajné hodnoty repozitára. Rovnako to funguje v GitLab CI, Bitbuckete alebo Azure DevOps: nainštalujte obx a spustite 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 alebo Zapier

Použite bežný krok HTTP Request s hlavičkou Authorization: Bearer a vaším kľúčom. Každý krok možno bezpečne opakovať: dvojité odoslanie rovnakých údajov nič nezmení.

Položka (napríklad keď sa zmení 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}]}]}
Farba a veľkosť 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"}
Fotografia: najprv údaje, potom samotný súbor
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 pre Cloudflare sám nevytvára webové verzie fotografií. Publikujte tam pomocou obx alebo cez „Importy“ vo svojej administrácii: tie ich vytvoria za vás. Fotografie, ktoré prídu inak, napríklad plánovaným importom, sa dovtedy zobrazujú v pôvodnej veľkosti.

Stiahnutie niečoho
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json

{"status": "unpublished"}

Chcete dostať správu, keď sa niečo stane? V administrácii pridajte upozornenie (webhook) na dokončený import alebo novú žiadosť o prístup a nechajte ho spustiť trigger v n8n, Make alebo Zapier.

6. Priamo API (pre vývojárov)

Integrácia si pamätá, čo naposledy odoslala, a posiela iba zmeny, v dávkach. Alebo pošlite CSV tak, ako je, a nechajte portál, nech ho načíta.

Preskočiť fotky, ktoré portál už má, a poslať 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 naraz
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šetky podrobnosti sú v špecifikácii:Ingest API ·návody na automatizáciu ·Go SDK ·Pre vývojárov