Автоматизация
Работете както досега.
Вашият PIM, ERP, DAM или споделена папка вече съдържа данните и снимките. Изберете първата подходяща рецепта: всички работят с всеки портал на Open Brand Exchange.
$ 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# .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 или Zapier | HTTP стъпки | няма (визуално) |
| разработчик, който свързва вашия PIM или ERP | Директно API | малко |
Един формат за всичко
Всеки начин на публикуване чете едно и също: products.csv с един ред на размер и снимки с имена {style}_{color}_{position}.jpg (модел, цвят, позиция). Щом имате това, всяка рецепта по-долу работи.
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,2000100101025images/
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 = неуспех.
2. Папка, която се публикува сама: obx watch
Нека вашият PIM, ERP или колега записва експортите в папка. obx watch публикува веднага щом нещо се промени и пропуска снимките, които са останали същите. Пуснете го като услуга или с Docker:
obx watch /data/outboxdocker run -d --restart unless-stopped \
-e OBX_URL -e OBX_TOKEN \
-v /data/outbox:/outbox \
ghcr.io/openbrandexchange/obx watch /outbox3. cron или Планировчик на задачи в Windows
# 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$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/images5. n8n, Make или Zapier
Използвайте обикновена стъпка HTTP Request със заглавка Authorization: Bearer и вашия ключ. Всяка стъпка може да се повтори безопасно: двукратното изпращане на едни и същи данни не променя нищо.
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}]}]}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"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 ·За разработчици