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 systém, ktorý informuje vaše ostatné aplikácie vždy, keď sa niečo zmení vo vašom e-shope. Je to ako „notifikačná služba“, ktorá udržiava vaše skladové, účtovné a marketingové nástroje dokonale synchronizované s vašimi najnovšími dátami.

Pre koho je to určené? Administrátori by si to mali prečítať, aby pochopili rôzne spôsoby, ako môžu ich systémy zostať aktualizované (napr. aktualizácie v reálnom čase vs. periodické aktualizácie). S vaším vývojárom sa budete musieť rozhodnúť, ktorá metóda najlepšie vyhovuje vašim obchodným potrebám – napríklad, potrebujete, aby váš sklad vedel o predaji okamžite, alebo stačí raz za hodinu?

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

  • Presnosť v reálnom čase: Použite „Webhooky“ na aktualizáciu vašich ostatných systémov v priebehu niekoľkých sekúnd od zmeny, čím zaistíte, že vaše skladové zásoby budú vždy správne.
  • Nikdy nezmeškajte aktualizáciu: „Changes API“ funguje ako digitálna stopa, ktorá zaisťuje, že aj keď váš iný systém prejde do režimu offline, dokáže „dohnať“ každú jednu zmenu, ktorú zmeškal.
  • Automatická synchronizácia odstránení: Zabezpečte, aby sa po odstránení Produktu alebo Kategórie na jednom mieste automaticky odstránili všade inde, čím sa zabráni „duchovým“ Produktom na vašej stránke.
  • Prispôsobené upozornenia: Nastavte inteligentné pravidlá, aby ste dostávali upozornenia iba o zmenách, ktoré sú dôležité (napr. „informujte moju marketingovú aplikáciu iba vtedy, keď klesne cena Produktu“).

Prehľad

{productName} ponúka tri metódy na detekciu a sledovanie zmien vo vašich dátach. Každá metóda má iné možnosti a je vhodná pre špecifické prípady použitia.

Výber správnej metódy

  • updatedAt — Jednoduché periodické synchronizácie bez sledovania odstránení
  • Changes API — Kompletná história zmien s periodickým dopytovaním
  • Webhooky — Upozornenia v reálnom čase s automatickým doručením

Porovnanie metód

Porovnajte tri metódy detekcie zmien a vyberte tú najvhodnejšiu pre váš prípad použitia

card: updatedAt
**Výhody**
- Jednoduchá implementácia
- Nízka réžia – používa štandardné filtre dotazov
- Dobré pre periodické synchronizácie (hodinové, denné)

**Obmedzenia**
- Nedetekuje odstránenia
- Vyžaduje periodické dopytovanie
- Môže zmeškať rýchle zmeny, ak je interval periodického dopytovania príliš dlhý

**Najlepšie pre:** Jednoduché integrácie, kde sú odstránenia zriedkavé alebo nie sú kritické
card: Changes API
**Výhody**
- Zaznamenáva všetky operácie (vytvorenie, aktualizácia, odstránenie)
- Sledovanie verzií so sekvenčnými ID
- Spoľahlivé – nezmešká žiadne zmeny
- Dokáže sledovať viacero entít

**Obmedzenia**
- Vyžaduje periodické dopytovanie
- Je potrebné udržiavať posledné ID verzie
- Oneskorenie na základe intervalu periodického dopytovania

**Najlepšie pre:** Robustné integrácie vyžadujúce kompletnú históriu zmien a sledovanie odstránení
card: Webhooky
**Výhody**
- Upozornenia v reálnom čase (do 5 sekúnd)
- Nevyžaduje sa periodické dopytovanie
- Dávkové doručenie (až 100 zmien na webhook)
- Vstavaný mechanizmus opakovania
- Podporuje filtrovanie

**Obmedzenia**
- Vyžaduje verejne prístupný koncový bod
- Musí spracovať spoľahlivosť webhooku
- Zložitejšie nastavenie

**Najlepšie pre:** Integrácie v reálnom čase vyžadujúce okamžitú akciu pri zmenách dát

Metóda 1: Použitie updatedAt [badge:Jednoduché|info]

Sledujte zmeny pomocou poľa časovej pečiatky updatedAt dostupného pre všetky entity

**Dôležité obmedzenie:**
Metóda `updatedAt` nedetekuje odstránenia. Ak potrebujete sledovať odstránené záznamy, použite namiesto toho Changes API alebo Webhooky.

Dotazovanie Produktov aktualizovaných od poslednej synchronizácie

Načítajte všetky Produkty, ktoré boli upravené po konkrétnej časovej pečiatke

GET /c/{companyId}/products?filter=updatedAt > '2025-11-14T10:00:00Z'&limit=100

// Response
{
    "data": [
        {
            "id": "prod-123",
            "name": "Updated Product",
            "price": 99.99,
            "updatedAt": "2025-11-14T10:15:30Z"
        }
        // ... more products
    ]
}

Sledovanie času poslednej synchronizácie (správna metóda)

Uložte časovú pečiatku z posledného načítaného záznamu, aby ste predišli zmeškaniu zmien

// Initialize with a timestamp from your last sync
// For first sync, use a timestamp in the past or null
let lastSyncTime = '2025-01-01T00:00:00Z';

// On each sync
const url = `/c/{companyId}/products?filter=${encodeURIComponent(
    `updatedAt > '${lastSyncTime}'`
)}&limit=100&sort=updatedAt`;

const response = await fetch(url);
const { data } = await response.json();

if (data.length > 0) {
    // Process the changed products
    data.forEach(product => {
        console.log('Updated:', product.id, product.updatedAt);
    });
    
    // ✅ CORRECT: Use updatedAt from the last record
    lastSyncTime = data[data.length - 1].updatedAt;
    
    // ❌ WRONG: Never use new Date().toISOString()
    // This can miss changes due to:
    // - Time between query and new Date() call
    // - Clock skew between client and server
}

⚠️ Kritické: Synchronizácia času

**Nikdy nepoužívajte `new Date().toISOString()` pre lastSyncTime!**

Tento prístup má dva kritické problémy:

1. **Stav pretekov:** Zmeny môžu nastať medzi načítaním dát a volaním `new Date()`, čo spôsobí, že tieto zmeny zmeškáte pri ďalšej synchronizácii.
2. **Časový posun hodín:** Hodiny klienta a servera nemusia byť synchronizované. Ak sú hodiny klienta vpredu, zmeškáte zmeny. Ak sú pozadu, získate duplicitné dáta.

✅ Vždy používajte hodnotu `updatedAt` z posledného záznamu vráteného serverom.

Metóda 2: Použitie Changes API [badge:Kompletné|success]

Sledujte všetky zmeny vrátane odstránení pomocou denníka zmien so sledovaním verzií

Kľúčové výhody
- Zaznamenáva operácie vytvorenia, aktualizácie a odstránenia
- Sekvenčné ID verzií pre spoľahlivé sledovanie
- Dotazovanie viacerých entít v jednej požiadavke
- Žiadna strata dát ani pri dlhých intervaloch periodického dopytovania

Získanie nedávnych zmien pre Produkty

Načítajte všetky zmeny (vrátane odstránení) pre Produkty so sledovaním verzií

GET /c/{companyId}/changes?filter=entity = 'products' and id > 100&limit=100

// Response
{
    "data": [
        {
            "id": 101,  // version number
            "entity": "products",
            "rowId": "prod-123",
            "operation": "update",
            "changeSetId": null,
            "createdAt": "2025-11-14T10:15:30Z"
        },
        {
            "id": 102,
            "entity": "products",
            "rowId": "prod-456",
            "operation": "delete",
            "changeSetId": null,
            "createdAt": "2025-11-14T10:16:45Z"
        }
    ]
}

Periodické dopytovanie zmien so sledovaním verzií

Nepretržite periodicky dopytujte nové zmeny pomocou posledného známeho ID verzie

// Store the last processed version
let lastVersionId = 0;

async function pollForChanges() {
    const filter = encodeURIComponent(
        `entity = 'products' and id > ${lastVersionId}`
    );
    
    const response = await fetch(
        `/c/{companyId}/changes?filter=${filter}&limit=100&sort=id`
    );
    const { data } = await response.json();
    
    if (data.length > 0) {
        // Process changes
        for (const change of data) {
            console.log(
                `Change #${change.id}: ${change.operation} on ${change.rowId}`
            );
            
            if (change.operation === 'delete') {
                // Handle deletion
                console.log('Product deleted:', change.rowId);
            } else {
                // Fetch the updated product
                const product = await fetch(
                    `/c/{companyId}/products/${change.rowId}`
                ).then(r => r.json());
                console.log('Product updated:', product);
            }
        }
        
        // Update last version ID
        lastVersionId = data[data.length - 1].id;
    }
}

// Poll every 30 seconds
setInterval(pollForChanges, 30000);

Získanie zmien pre viaceré entity

Monitorujte zmeny naprieč rôznymi typmi entít

const filter = encodeURIComponent(
    `(entity = 'products' OR entity = 'categories') and id > ${lastVersionId}`
);

const response = await fetch(
    `/c/{companyId}/changes?filter=${filter}&limit=100&sort=id`
);
const { data } = await response.json();

// Group changes by entity
const changesByEntity = data.reduce((acc, change) => {
    if (!acc[change.entity]) acc[change.entity] = [];
    acc[change.entity].push(change);
    return acc;
}, {});

console.log('Products changed:', changesByEntity.products?.length || 0);
console.log('Categories changed:', changesByEntity.categories?.length || 0);

Metóda 3: Použitie Webhookov [badge:V reálnom čase|warning]

Prijímajte automatické upozornenia do 5 sekúnd od akejkoľvek zmeny dát

**Funkcie v reálnom čase**
- Upozornenia doručené do 5 sekúnd od zmien
- Dávkové doručenie (až 100 zmien na webhook)
- Filtrovanie podľa typu entity (konkrétna entita alebo všetky entity)
- Filtrovanie podľa podmienok riadkov (napr. "price > 100")
- Filtrovanie podľa zmenených stĺpcov (napr. ["price", "status"])
- Automatické opakovanie s exponenciálnym oneskorením

Registrácia webhooku pre Produkty

Prijímajte automatické upozornenia pri zmene produktov

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook"
}

// Your webhook endpoint will receive:
{
    "hookId": "hook-123",
    "tenantId": "tenant-789",
    "organisationId": "{companyId}",
    "changeSetId": null,
    "changes": [
        {
            "id": "change-001",
            "entity": "products",
            "operation": "update",
            "rowId": "prod-123",
            "changeSetId": null
        }
    ],
    "timestamp": "2025-11-14T10:30:00.000Z"
}

Príklad obsluhy webhooku

Spracovanie prichádzajúcich upozornení webhooku

// Express.js webhook handler
app.post('/webhooks/products', async (req, res) => {
    const { changes } = req.body;
    
    for (const change of changes) {
        console.log(
            `Webhook: ${change.operation} on ${change.rowId}`
        );
        
        if (change.operation === 'delete') {
            // Handle product deletion
            await deleteProductInMySystem(change.rowId);
        } else {
            // Fetch and process the updated product
            const product = await fetch(
                `https://api.productsync.com/c/{companyId}/products/${change.rowId}`,
                {
                    headers: {
                        'Authorization': 'Bearer YOUR_API_KEY'
                    }
                }
            ).then(r => r.json());
            
            await updateProductInMySystem(product);
        }
    }
    
    // Always respond with 200 to acknowledge receipt
    res.status(200).json({ received: true });
});

Webhook pre konkrétnu entitu

Obmedzte upozornenia na jeden typ entity

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/products",
    "action": "webhook"
}

// Only products changes will trigger this webhook
// Changes to categories, units, etc. will be ignored

Webhook pre všetky entity

Monitorujte všetky zmeny entít v jednom webhooku

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": null,
    "url": "https://your-api.com/webhooks/all-changes",
    "action": "webhook"
}

// This webhook will receive notifications for ALL entity types
// Products, categories, units, customers, orders, etc.

Webhook s filtrom podmienok riadkov

Prijímajte upozornenia iba vtedy, keď riadky zodpovedajú špecifickým podmienkam

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/expensive-products",
    "action": "webhook",
    "filter": "price > 100 AND status = 'active'"
}

// You will only receive webhooks when:
// - The entity is 'products'
// - AND the product price is greater than 100
// - AND the product status is 'active'

Webhook s filtrom stĺpcov

Spustí sa iba vtedy, keď sa zmenia konkrétne stĺpce

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/product-pricing",
    "action": "webhook",
    "columns": ["price", "discount", "tax"]
}

// Webhook only triggers when price, discount, or tax changes
// Changes to name, description, etc. will be ignored

Webhook s kombinovanými filtrami

Skombinujte filtre entít, podmienok riadkov a stĺpcov

POST /c/{companyId}/hooks
Content-Type: application/json

{
    "entity": "products",
    "url": "https://your-api.com/webhooks/premium-product-pricing",
    "action": "webhook",
    "filter": "price > 100",
    "columns": ["price", "status"]
}

// Triple filtering:
// 1. Only 'products' entity
// 2. Only when price > 100
// 3. Only when price or status columns change

** Možnosti filtrovania webhookov**

**1. Filtrovanie entít**

Nastavte `entity` na obmedzenie upozornení na konkrétny typ entity (napr. „products“, „categories“). Použite `null` na prijímanie upozornení pre všetky entity.

**2. Filtrovanie podmienok riadkov**

Použite `filter` s klauzulami `WHERE` podobnými SQL na spustenie webhookov iba vtedy, keď riadky zodpovedajú špecifickým podmienkam (napr. „price > 100 AND status = 'active'“).

**3. Filtrovanie zmien stĺpcov**

Zadajte pole `columns` na spustenie iba vtedy, keď sa zmenili konkrétne stĺpce. Ideálne na monitorovanie aktualizácií cien, zmien stavu atď.

**4. Kombinované filtrovanie**

Skombinujte všetky tri filtre pre presnú kontrolu: typ entity + podmienky riadkov + zmeny stĺpcov. Tým sa minimalizujú zbytočné volania webhookov a spracovanie.

Poznámka: Kompletnú dokumentáciu k webhookom vrátane logiky opakovania, možností filtrovania a príkladov dátovej časti nájdete v [navigate:webhooks.md|Dokumentácii k webhookom].

Osvedčené postupy

Kedy použiť updatedAt

  • Jednoduché integrácie s pravidelnými synchronizáciami (hodinové, denné)
  • Keď sa odstránenia spracúvajú samostatne alebo nie sú potrebné
  • Nízko-frekvenčné aktualizácie dát
  • Rýchle prototypy a MVP

Kedy použiť Changes API

  • Potreba sledovať všetky operácie vrátane odstránení
  • Vytváranie kompletného systému synchronizácie dát
  • Udržiavanie záznamu o zmenách (audit trail)
  • Keď nie je k dispozícii infraštruktúra webhookov
  • Dávkové spracovanie zmien

Kedy použiť Webhooky

  • Potreba aktualizácií dát v reálnom čase alebo takmer v reálnom čase
  • Spúšťanie okamžitých akcií pri zmenách dát
  • Automatická synchronizácia externých systémov
  • Keď môžete udržiavať verejne prístupný koncový bod
  • Vysokofrekvenčné zmeny dát vyžadujúce rýchlu odozvu
**Hybridný prístup:**
Zvážte použitie webhookov pre aktualizácie v reálnom čase a Changes API ako zálohu na zachytenie akýchkoľvek zmeškaných zmien počas výpadkov alebo zlyhaní webhookov. To poskytuje to najlepšie z oboch svetov: aktualizácie v reálnom čase so zaručenou úplnosťou.