Автоматизация

Работете както досега.

Вашият PIM, ERP, DAM или споделена папка вече съдържа данните и снимките. Изберете първата подходяща рецепта: всички работят с всеки портал на 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

Коя рецепта ви подхожда?

Имате…ИзползвайтеНужен код
CSV или архив на уеб адрес, SFTP сървър или в S3 хранилищеПланиран импортняма
папка, в която пристигат експортитеobx watchняма
сървър или компютър, който изпълнява задачи през нощтаcron или Планировчик на задачиедин ред
експортите в Git хранилищеGitHub Actionедин YAML файл
n8n, Make или ZapierHTTP стъпкиняма (визуално)
разработчик, който свързва вашия PIM или ERPДиректно APIмалко

Един формат за всичко

Всеки начин на публикуване чете едно и също: products.csv с един ред на размер и снимки с имена {style}_{color}_{position}.jpg (модел, цвят, позиция). Щом имате това, всяка рецепта по-долу работи.

products.csv (съкратено)
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
Имена на файловете със снимки
images/
  KO-1001_NVY_1.jpg     ← style KO-1001, colour NVY, position 1 (front)
  KO-1001_NVY_2.jpg
  KO-1001_NVY_3.jpg

Пълният формат за импорт

Какво ви трябва

В администрацията отворете Автоматично качване → Ключове за достъп и създайте нов ключ. Получавате две стойности: адреса на портала (OBX_URL) и самия ключ (OBX_TOKEN). Ключът се показва само веднъж.

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

Дайте на всяка система собствен ключ. Така можете да отмените един, без да развалите останалите.

1. Планиран импорт (без код)

В администрацията: Автоматично качване → Планирани импортирания → Добави планирано импортиране. Изберете източника и колко често да се изпълнява.

  • Уеб адрес (HTTPS): адресът на products.csv или на архив с products.csv и снимки. Данните за вход се пазят криптирани.
  • SFTP: сървър, потребител, парола или ключ и папката с експорта.
  • S3 хранилище: AWS S3, Cloudflare R2, MinIO или Backblaze: крайна точка, хранилище, папка и ключ само за четене.

Изберете „Само добавяй и обновявай“ или „Оттегли и липсващите артикули“. Второто сваля и това, което е изчезнало от файла, но спира, ако повече от половината от дадена марка би изчезнала, така че повреден експорт никога не изпразва каталога ви. „Тествай връзката“ показва кои файлове ще бъдат прочетени.

Инструментът obx

obx е една програма за Windows, macOS и Linux. Чете OBX_URL и OBX_TOKEN от средата, качва само нови или променени снимки, при нужда създава уеб версиите и изчаква, докато порталът обработи всичко. Пускайте го колкото често искате: непроменените артикули не струват нищо.

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

Код за изход 0 = всичко е наред, 2 = готово, но някои редове имат грешки (изброени са), 1 = неуспех.

Изтеглете obx · obx-go

2. Папка, която се публикува сама: obx watch

Нека вашият PIM, ERP или колега записва експортите в папка. obx watch публикува веднага щом нещо се промени и пропуска снимките, които са останали същите. Пуснете го като услуга или с 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 или Планировчик на задачи в Windows

Linux или 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, еднократно)
$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

Запазете OBX_URL и OBX_TOKEN като тайни на хранилището. Същото работи в GitLab CI, Bitbucket или Azure DevOps: инсталирайте obx и изпълнете 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 или Zapier

Използвайте обикновена стъпка HTTP Request със заглавка Authorization: Bearer и вашия ключ. Всяка стъпка може да се повтори безопасно: двукратното изпращане на едни и същи данни не променя нищо.

Артикул (например когато се промени в 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}]}]}
Цвят и размер, с 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"}
Снимка: първо данните, после самият файл
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>

Портал за Cloudflare не създава сам уеб версии на снимките. Публикувайте там с obx или чрез „Импортиране“ в администрацията: те ги създават вместо вас. Снимките, пристигнали по друг начин, например чрез планиран импорт, дотогава се показват в оригинален размер.

Оттегляне на нещо
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json

{"status": "unpublished"}

Искате известие, когато нещо се случи? В администрацията добавете известие (webhook) за завършен импорт или нова заявка за достъп и нека то стартира тригер в n8n, Make или Zapier.

6. Директно API (за разработчици)

Една интеграция помни какво е изпратила последно и изпраща само промените, на пакети. Или изпратете CSV файла както е и оставете портала да го прочете.

Пропускане на снимките, които порталът вече има, и изпращане на един пакет
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 и архив със снимки наведнъж
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>

Всички подробности са в спецификацията:Ingest API ·рецепти за автоматизация ·Go SDK ·За разработчици