Vyzkoušet zdarma
ÚvodPlatformaCeníkOtázkyNápovědaKontakt Kivea FlexiKivea PohodaKivea účetnictvíKivea fakturace Vyzkoušet zdarma

Čo je to?

Poznámka pre administrátora: Toto je vysokorýchlostná „diaľnica“ na presun obrovského množstva dát medzi vaším e-shopom a inými obchodnými systémami (ako je váš sklad alebo účtovný softvér). Je navrhnutá tak, aby efektívne spracovala tisíce alebo dokonca milióny záznamov.

Pre koho je to určené? Administrátori by si to mali prečítať, aby pochopili, ako platforma zostáva synchronizovaná s vašimi ostatnými obchodnými nástrojmi. Zatiaľ čo technické „ako na to“ je pre vašich vývojárov, mali by ste vedieť, že táto funkcia zaisťuje, že vaše skladové zásoby produktov, ceny a objednávky sú vždy aktuálne vo všetkých vašich systémoch.

Kľúčové výhody pre e-shop:

  • Nepriestrelná presnosť dát: Automaticky porovnáva celý váš katalóg produktov a aktualizuje len to, čo sa skutočne zmenilo, čím predchádza chybám v dátach.
  • Rozsiahla synchronizácia: Bez námahy spracuje obrovské súbory (dokonca aj gigabajty), ktoré by štandardné nástroje na import zlyhali.
  • Zjednodušená logika: Namiesto manuálneho sledovania každej malej zmeny môžu vaši vývojári jednoducho poslať „celý obraz“ a nechať náš systém, aby sa postaral o zvyšok.
  • Automatické čistenie: Zabezpečte, aby produkty odstránené z vášho skladového systému boli automaticky skryté alebo odstránené aj z vášho e-shopu.

Čo je Feed API?

Pri synchronizácii dvoch systémov máte dva hlavné prístupy:

card: Klasické API
icon: refresh-cw
Číta dáta cez API, lokálne detekuje zmeny a posiela len modifikácie. Vyžaduje sledovanie zmien a správu stavu na strane klienta.
**Najlepšie pre:**
- Synchronizáciu v reálnom čase
- Časté malé aktualizácie
- Jemné riadenie zmien
card: Feed API
icon: zap
Posiela jeden veľký JSON (aj gigabajty) so všetkými hodnotami. Systém efektívne porovnáva a aktualizuje len skutočné zmeny.
**Najlepšie pre:**
- Synchronizáciu hromadných dát
- Pravidelné úplné synchronizácie
- Jednoduchšiu integračnú logiku

Ako funguje Feed API

1. Efektívne prednačítanie

Systém efektívne prednačíta existujúce dáta na porovnanie pomocou optimalizovaných databázových dotazov.

2. Inteligentné párovanie

Záznamy sa párujú pomocou vyhľadávaní (code:, id:) alebo jedinečných identifikátorov. Dokonca aj položky bez jedinečných ID (ako sú riadkové položky) sa párujú pomocou pravdepodobnostného mechanizmu.

3. Detekcia zmien

Systém porovnáva všetky dáta a identifikuje skutočné zmeny, čím eliminuje falošné rozdiely.

4. Selektívne aktualizácie

Do databázy sa zapisujú len skutočné zmeny, čím sa minimalizuje réžia a udržiavajú sa záznamy o audite.

Základné komponenty

Feed API využíva dva výkonné nástroje: Mapovač a Importér

card: Mapovač
icon: settings
Transformuje externé dátové formáty (XML, JSON, CSV) do interného formátu. Spracováva transformácie Mapovača, dátové transformácie a konverzie typov.
**Kľúčové funkcie:**
- Podpora JSONPath a XPath
- Vyhodnocovanie výrazov
- Rozlíšenie vyhľadávania
- Mapovanie vnorených entít
[navigate:mapper.md|Zobraziť dokumentáciu|book-open]
card: Importér
icon: upload
Spracováva mapované dáta a inteligentne aktualizuje databázu. Spracováva operácie upsert, vymazania a správu vzťahov.
**Kľúčové funkcie:**
- Operácie upsert
- Párovanie založené na vyhľadávaní
- Pravdepodobnostné párovanie
- Dávkové spracovanie
[navigate:imports.md|Zobraziť dokumentáciu|book-open]

Kľúčové direktívy

Základné direktívy pre operácie Feed API

Vyhľadávania (code:, id:, atď.)

Identifikujte záznamy pomocou rôznych typov vyhľadávania namiesto ID databázy.

"category": "code:ELECTRONICS"
"manufacturer": "id:12345"
"customer": "email:john@example.com"

@removeAll

Určuje, či sa majú odstrániť existujúce položky, ktoré nie sú vo feede.

"items": [
  { "code": "ITEM-1", "quantity": 10 }
],
"items@removeAll": true  // Remove items not in feed

Predvolené: true pre režim poľa/objektu, false pre režim zlúčenia

@operation

Explicitne riadi typ operácie pre každý záznam.

{ "@operation": "upsert", "code": "PROD-1", "name": "Product 1" }
{ "@operation": "delete", "code": "PROD-OLD" }
{ "@operation": "create", "name": "New Product" }

Hodnoty: create, update, upsert, delete

@where

Hromadné operácie pomocou klauzúl where pre hromadné aktualizácie alebo vymazania.

{
  "@operation": "update",
  "@where": "category = 'code:OLD_CAT'",
  "category": "code:NEW_CAT"
}

@atomic

Riadi správanie transakcií a spracovanie chýb.

"@atomic": "batch"  // Recommended for large feeds
"@atomic": true     // All-or-nothing
"@atomic": false    // Independent records

Príklad: Feed produktov

Kompletný príklad synchronizácie produktov cez Feed API

1. Zdrojové dáta (externý systém)

{
  "products": [
    {
      "productCode": "WIDGET-001",
      "productName": "Super Widget",
      "price": 99.99,
      "categoryCode": "ELECTRONICS",
      "variants": [
        {
          "sku": "WIDGET-001-RED",
          "color": "Red",
          "stock": 50
        },
        {
          "sku": "WIDGET-001-BLUE",
          "color": "Blue",
          "stock": 30
        }
      ]
    },
    {
      "productCode": "GADGET-002",
      "productName": "Mega Gadget",
      "price": 149.99,
      "categoryCode": "ELECTRONICS"
    }
  ]
}

2. Konfigurácia Mapovača

type JSON

@atomic = "batch"
@language = "en"

products = '$.products[*]' {
    id[code] = 'productCode'
    name = 'productName'
    price = 'price'
    category[code] = 'categoryCode'
    
    variants = 'variants[*]' {
        code = 'sku'
        color = 'color'
        stockQuantity = 'stock'
        @removeAll = "true"
    }
}

3. Výsledný import JSON

{
  "@atomic": "batch",
  "products": [
    {
      "id": "code:WIDGET-001",
      "name": "Super Widget",
      "price": 99.99,
      "category": "code:ELECTRONICS",
      "variants": [
        {
          "code": "WIDGET-001-RED",
          "color": "Red",
          "stockQuantity": 50
        },
        {
          "code": "WIDGET-001-BLUE",
          "color": "Blue",
          "stockQuantity": 30
        }
      ],
      "variants@removeAll": true
    },
    {
      "id": "code:GADGET-002",
      "name": "Mega Gadget",
      "price": 149.99,
      "category": "code:ELECTRONICS"
    }
  ]
}

**Čo sa stane:**
- Produkty sú spárované podľa kódu (`code:WIDGET-001`)
- Kategória je rozlíšená pomocou vyhľadávania (`code:ELECTRONICS`)
- Existujúce varianty, ktoré nie sú vo feede, sú odstránené (`@removeAll: true`)
- Nové varianty sú vytvorené, existujúce sú aktualizované
- Do databázy sa zapisujú len skutočné zmeny
- Spracovanie sa vykonáva v dávkach pre optimálny výkon

Príklad: Feed faktúr

Synchronizácia faktúr s riadkovými položkami

{
  "@atomic": "batch",
  "invoices": [
    {
      "id": "code:INV-2024-001",
      "customer": "code:CUSTOMER-123",
      "issueDate": "2024-01-15",
      "dueDate": "2024-02-15",
      "items": [
        {
          "product": "code:WIDGET-001",
          "quantity": 5,
          "unitPrice": 99.99,
          "description": "Super Widget - Red"
        },
        {
          "product": "code:GADGET-002",
          "quantity": 2,
          "unitPrice": 149.99,
          "description": "Mega Gadget"
        }
      ],
      "items@removeAll": true
    }
  ]
}

**Pravdepodobnostné párovanie:**
Aj keď riadkové položky faktúry zvyčajne nemajú jedinečné identifikátory, systém používa pravdepodobnostný mechanizmus na ich párovanie na základe produktu, množstva a iných polí. To zaisťuje presné aktualizácie bez duplicitných riadkových položiek.

Generovanie feedov

Feed API dokáže generovať aj exporty dát v rôznych formátoch

Feed API môžete použiť nielen na importy, ale aj na generovanie exportov dát:

Export založený na dotazoch

Použite dotazovací jazyk na extrahovanie dát a ich export v rôznych formátoch.

GET /api/products?format=json&export=true

Reverzný Mapovač

Použite mapovače reverzne na transformáciu interných dát späť do externých formátov.

Dopredný Mapovač

Použite dopredné mapovače na generovanie špecializovaných exportných formátov.

Podporované exportné formáty:

JSON, XML, CSV, Excel, PDF, HTML, Vlastné

Osvedčené postupy

  • Používajte dávkový režim pre veľké dátové toky — Nastavte @atomic: "batch" pre optimálny výkon s veľkými súbormi dát.
  • Používajte vyhľadávania namiesto ID databázy — Uprednostnite code:, email: alebo iné obchodné kľúče pre lepšiu prenosnosť.
  • Využite @removeAll pre kompletnú synchronizáciu — Použite @removeAll: true, aby ste zabezpečili odstránenie vymazaných položiek z cieľového systému.
  • Najprv testujte s malými súbormi dát — Overte svoj mapovač a logiku importu s malou podmnožinou pred spracovaním veľkých dátových tokov.
  • Monitorujte výsledky importu — Kontrolujte protokoly importu a hlásenia chýb, aby ste identifikovali a opravili problémy s dátami.

Súvisiaca dokumentácia

[navigate:mapper.md|Dokumentácia mapovača|settings] [navigate:imports.md|Importovací systém|upload] [navigate:query.md|Jazyk dotazov|database]