Automaatio

Jatka töitä kuten nytkin.

PIM-, ERP- tai DAM-järjestelmässäsi tai jaetussa kansiossa on jo tiedot ja kuvat. Valitse ensimmäinen sopiva ohje: kaikki toimivat jokaisen Open Brand Exchange -portaalin kanssa.

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

Mikä ohje sopii sinulle?

Sinulla on…KäytäKoodia tarvitaan
CSV- tai zip-tiedosto verkko-osoitteessa, SFTP-palvelimella tai S3-säilössäAjastettu tuontiei
kansio, johon viennit tallentuvatobx watchei
palvelin tai tietokone, joka ajaa öisin tehtäviäcron tai Tehtävien ajoitusyksi rivi
vientisi Git-repositoriossaGitHub Actionyksi YAML-tiedosto
n8n, Make tai ZapierHTTP-vaiheetei (visuaalinen)
kehittäjä, joka liittää PIM- tai ERP-järjestelmäsiAPI suoraanvähän

Yksi muoto kaikkeen

Kaikki julkaisutavat lukevat samaa: products.csv, jossa on yksi rivi kokoa kohden, ja kuvat nimettynä {style}_{color}_{position}.jpg (tuotenumero, väri, sijainti). Kun tämä on kunnossa, kaikki alla olevat ohjeet toimivat.

products.csv (lyhennetty)
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
Kuvien tiedostonimet
images/
  KO-1001_NVY_1.jpg     ← style KO-1001, colour NVY, position 1 (front)
  KO-1001_NVY_2.jpg
  KO-1001_NVY_3.jpg

Koko tuontimuoto

Mitä tarvitset

Avaa hallinnasta Automaattinen lataus → Käyttöavaimet ja luo uusi avain. Saat kaksi arvoa: portaalisi osoitteen (OBX_URL) ja itse avaimen (OBX_TOKEN). Avain näytetään vain kerran.

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

Anna jokaiselle järjestelmälle oma avain. Silloin voit perua yhden rikkomatta muita.

1. Ajastettu tuonti (ilman koodia)

Hallinnassa: Automaattinen lataus → Ajastetut tuonnit → Lisää ajastettu tuonti. Valitse lähde ja kuinka usein se ajetaan.

  • Verkko-osoite (HTTPS): products.csv-tiedoston tai products.csv:n ja kuvat sisältävän zipin osoite. Kirjautumistiedot tallennetaan salattuina.
  • SFTP: palvelin, käyttäjä, salasana tai avain sekä vientikansio.
  • S3-säilö: AWS S3, Cloudflare R2, MinIO tai Backblaze: päätepiste, säilö, kansio ja vain luku -avain.

Valitse ”Vain lisää ja päivitä” tai ”Poista myös puuttuvat tuotteet näkyvistä”. Jälkimmäinen poistaa näkyvistä myös sen, mikä katosi tiedostosta, mutta keskeyttää, jos yli puolet brändistä katoaisi, joten viallinen vienti ei koskaan tyhjennä luetteloanne. ”Testaa yhteys” näyttää, mitkä tiedostot luettaisiin.

obx-työkalu

obx on yksi ohjelma Windowsille, macOS:lle ja Linuxille. Se lukee OBX_URL- ja OBX_TOKEN-arvot ympäristöstä, lataa vain uudet tai muuttuneet kuvat, tekee verkkoversiot tarvittaessa ja odottaa, kunnes portaali on käsitellyt kaiken. Aja sitä niin usein kuin haluat: muuttumattomat tuotteet eivät maksa mitään.

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

Paluukoodi 0 = kaikki kunnossa, 2 = valmis, mutta joissakin riveissä oli virheitä (ne listataan), 1 = epäonnistui.

Lataa obx · obx-go

2. Kansio, joka julkaisee itsensä: obx watch

Anna PIM-, ERP-järjestelmän tai kollegan tallentaa viennit kansioon. obx watch julkaisee heti, kun jokin muuttuu, ja ohittaa ennallaan pysyneet kuvat. Aja sitä palveluna tai Dockerilla:

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 tai Windowsin Tehtävien ajoitus

Linux tai 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, kerran)
$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

Tallenna OBX_URL ja OBX_TOKEN repositorion salaisuuksiksi. Sama toimii GitLab CI:ssä, Bitbucketissa ja Azure DevOpsissa: asenna obx ja aja 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 tai Zapier

Käytä tavallista HTTP Request -vaihetta otsakkeella Authorization: Bearer ja avaimellasi. Jokaisen vaiheen voi toistaa turvallisesti: samojen tietojen lähettäminen kahdesti ei muuta mitään.

Tuote (esimerkiksi kun se muuttuu PIM:ssä)
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}]}]}
Väri ja koko EAN-koodeineen
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"}
Kuva: ensin tiedot, sitten itse tiedosto
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>

Portaali Cloudflarelle ei itse tee kuvista verkkoversioita. Julkaise siellä obx-työkalulla tai hallinnan kohdasta ”Tuonnit”: ne tekevät ne puolestasi. Muuta kautta tulevat kuvat, esimerkiksi ajastetusta tuonnista, näytetään siihen asti alkuperäisessä koossa.

Poista jotain näkyvistä
PATCH {OBX_URL}/obx/v1/ingest/products/KO-1001
Authorization: Bearer obxi_…
Content-Type: application/merge-patch+json

{"status": "unpublished"}

Haluatko ilmoituksen, kun jotain tapahtuu? Lisää hallinnassa ilmoitus (webhook) valmistuneesta tuonnista tai uudesta pääsypyynnöstä ja anna sen käynnistää n8n-, Make- tai Zapier-laukaisin.

6. API suoraan (kehittäjille)

Integraatio muistaa, mitä se lähetti viimeksi, ja lähettää vain muutokset erissä. Tai lähetä CSV sellaisenaan ja anna portaalin lukea se.

Ohita kuvat, jotka portaalilla jo on, ja lähetä yksi erä
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 ja zip-kuvat kerralla
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>

Kaikki yksityiskohdat ovat määrittelyssä:Ingest API ·automaatio-ohjeet ·Go-SDK ·Kehittäjille