Automatyzacja

Pracuj dalej tak jak teraz.

Twój PIM, ERP, DAM albo wspólny folder ma już dane i zdjęcia. Wybierz pierwszy pasujący przepis: każdy działa z każdym portalem 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

Który przepis do Ciebie pasuje?

Masz…UżyjPotrzebny kod
plik CSV lub zip pod adresem WWW, na serwerze SFTP lub w zasobniku S3Zaplanowany importbrak
folder, do którego trafiają eksportyobx watchbrak
serwer lub komputer, który nocą uruchamia zadaniacron lub Harmonogram zadańjedna linia
eksporty w repozytorium GitGitHub Actionjeden plik YAML
n8n, Make lub ZapierKroki HTTPbrak (wizualnie)
programistę, który podłączy Twój PIM lub ERPBezpośrednio APItrochę

Jeden format do wszystkiego

Każda metoda publikacji czyta to samo: products.csv z jednym wierszem na rozmiar i zdjęcia o nazwach {style}_{color}_{position}.jpg (model, kolor, pozycja). Gdy to masz, działa każdy przepis poniżej.

products.csv (skrócony)
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
Nazwy plików zdjęć
images/
  KO-1001_NVY_1.jpg     ← style KO-1001, colour NVY, position 1 (front)
  KO-1001_NVY_2.jpg
  KO-1001_NVY_3.jpg

Pełny format importu

Czego potrzebujesz

W panelu administracyjnym otwórz Automatyczne przesyłanie → Klucze dostępu i utwórz nowy klucz. Masz wtedy dwie wartości: adres portalu (OBX_URL) i sam klucz (OBX_TOKEN). Klucz jest pokazywany tylko raz.

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

Daj każdemu systemowi osobny klucz. Wtedy możesz unieważnić jeden, nie psując pozostałych.

1. Zaplanowany import (bez kodu)

W panelu: Automatyczne przesyłanie → Zaplanowane importy → Dodaj zaplanowany import. Wybierz źródło i częstotliwość.

  • Adres WWW (HTTPS): adres pliku products.csv albo archiwum zip z products.csv i zdjęciami. Dane logowania są przechowywane w postaci zaszyfrowanej.
  • SFTP: serwer, użytkownik, hasło lub klucz oraz folder z eksportem.
  • Zasobnik S3: AWS S3, Cloudflare R2, MinIO lub Backblaze: endpoint, zasobnik, folder i klucz tylko do odczytu.

Wybierz „Tylko dodawaj i aktualizuj” albo „Wycofaj też brakujące artykuły”. Druga opcja wycofuje też to, co zniknęło z pliku, ale zatrzymuje się, gdyby miało zniknąć więcej niż połowa marki, więc wadliwy eksport nigdy nie opróżni Twojego katalogu. „Sprawdź połączenie” pokazuje, które pliki zostałyby odczytane.

Narzędzie obx

obx to jeden program dla Windows, macOS i Linuksa. Odczytuje OBX_URL i OBX_TOKEN ze środowiska, przesyła tylko nowe lub zmienione zdjęcia, w razie potrzeby tworzy wersje webowe i czeka, aż portal wszystko przetworzy. Uruchamiaj go tak często, jak chcesz: niezmienione artykuły nic nie kosztują.

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

Kod wyjścia 0 = wszystko w porządku, 2 = gotowe, ale niektóre wiersze miały błędy (są wypisane), 1 = niepowodzenie.

Pobierz obx · obx-go

2. Folder, który publikuje się sam: obx watch

Niech PIM, ERP lub współpracownik zapisuje eksporty w folderze. obx watch publikuje, gdy tylko coś się zmieni, i pomija niezmienione zdjęcia. Uruchom go jako usługę lub w Dockerze:

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 lub Harmonogram zadań Windows

Linux lub 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, jednorazowo)
$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

Zapisz OBX_URL i OBX_TOKEN jako sekrety repozytorium. Tak samo działa to w GitLab CI, Bitbucket i Azure DevOps: zainstaluj obx i uruchom 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 lub Zapier

Użyj zwykłego kroku HTTP Request z nagłówkiem Authorization: Bearer i Twoim kluczem. Każdy krok można bezpiecznie powtórzyć: dwukrotne wysłanie tych samych danych niczego nie zmienia.

Artykuł (na przykład gdy zmieni się w 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}]}]}
Kolor i rozmiar wraz z 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"}
Zdjęcie: najpierw dane, potem sam plik
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>

Portal dla Cloudflare sam nie tworzy wersji internetowych zdjęć. Publikuj tam za pomocą obx albo przez „Importy” w panelu administracyjnym: one tworzą je za Ciebie. Zdjęcia, które trafiają inną drogą, np. z zaplanowanego importu, do tego czasu są pokazywane w oryginalnym rozmiarze.

Wycofanie czegoś
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json

{"status": "unpublished"}

Chcesz dostać sygnał, gdy coś się wydarzy? W panelu dodaj powiadomienie (webhook) o zakończonym imporcie lub nowej prośbie o dostęp i niech uruchamia wyzwalacz w n8n, Make lub Zapier.

6. Bezpośrednio API (dla programistów)

Integracja pamięta, co wysłała ostatnio, i wysyła tylko zmiany, w paczkach. Możesz też wysłać plik CSV bez zmian i pozwolić portalowi go odczytać.

Pomiń zdjęcia, które portal już ma, i wyślij jedną paczkę
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"
Plik CSV i zip ze zdjęciami za jednym razem
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>

Wszystkie szczegóły są w specyfikacji:Ingest API ·przepisy automatyzacji ·SDK Go ·Dla programistów