Synchronizujte svoj systém cez vlastný zdroj

Vlastný zdroj pripojí systém, ktorý nemá vstavaný konektor: vašu wiki, nástroj na tikety, databázu, export odkiaľkoľvek. Váš kód odosiela dokumenty do Sursy a Sursa z nich vytvára karty v kolekcii a priečinkoch, pre ktoré je zdroj nastavený, s rovnakým vyhľadávaním, odpoveďami, overovaním a oprávneniami ako karty z akéhokoľvek iného zdroja.

Na rozdiel od priameho zápisu kariet si vlastný zdroj pamätá, čo ste odoslali. Na konci úplnej synchronizácie Sursa archivuje každý dokument, ktorý ste neodoslali, takže vymazania vo vašom systéme sa do Sursy dostanú bez práce navyše.

Nastavte zdroj

Administrátor vytvorí zdroj v Surse v časti Sources → New source → Custom source (zdroje → nový zdroj → vlastný zdroj) a zvolí:

• kolekciu a voliteľne priečinok pre jeho karty;
• režim priečinkov: všetky karty vo zvolenom priečinku, alebo podpriečinky, ktoré kopírujú path každého dokumentu;
• oprávnenia: oprávnenia kolekcie, alebo „ako v zdroji“, keď každý dokument uvádza, kto ho smie vidieť.

Stránka zdroja ukazuje jeho ID; ukážky používajú 42.

Vyberte kľúč

Kľúč zdroja je najbezpečnejšia voľba pre jednu integráciu, najmä pre takú, ktorá beží na platforme tretej strany. Kľúč organizácie s import:write sa hodí pre službu, ktorá zásobuje niekoľko zdrojov.

Oba kľúče sa posielajú rovnako a všetky operácie push sú pod /v1/push/sources/{source_id}. Kľúč a stav zdroja overíte cez GET /v1/push/sources/{source_id}:

curl https://api.sursa.com/v1/push/sources/42 \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

{"source_id": 42, "name": "Helpdesk articles", "documents": 1840, "open_sync": null}

Dokument

Namiesto content môže jeden dokument v požiadavke multipart/form-data niesť súbor s veľkosťou najviac 100 MB: súbor v časti file, polia uvedené vyššie ako JSON v časti document. Nahrávania po častiach pre upload_id a attachments sa vytvárajú kľúčom organizácie s rozsahom import:write a účelom import_attachment; kľúč zdroja ich vytvoriť nemôže.

Dva spôsoby odosielania

Priame aktualizácie sa hodia pre systémy, ktoré vám oznamujú každú zmenu, napríklad webhook z vášho helpdesku alebo krok v Zapieri. Dokument odošlite, keď sa vytvorí alebo zmení, a vymažte ho, keď sa odstráni:

Zmeny sa premenia na karty približne do minúty; niekoľko zmien za sebou sa spracuje spolu.

Synchronizácie sa hodia pre pravidelné exporty: odošlete všetko alebo všetko, čo sa zmenilo, a Sursa údaje zosúladí. Zvyšok tohto návodu sa venuje synchronizáciám.

Spustite úplnú synchronizáciu

Synchronizácia má tri kroky: otvoriť, odoslať, uzavrieť.

1. Otvorte

POST /v1/push/sources/{source_id}/syncs otvorí synchronizáciu a vráti jej číslo:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"type": "initial", "max_minutes": 180}'

{"sync_number": 7, "type": "initial", "status": "open", "opened_at": "2026-10-24T02:00:00Z",
 "expires_at": "2026-10-24T05:00:00Z", "pushed": 0, "removed": 0}

• type je initial pri prvej synchronizácii zdroja a incremental, keď už niektorá synchronizácia skončila. Synchronizácia incremental pred prvou dokončenou vráti sources.push_initial_required.
• Naraz môže byť otvorená len jedna synchronizácia: druhá vráti 409 sources.push_sync_open.
• Synchronizácia zostane otvorená max_minutes (predvolene 60, najviac 1440). Potom vyprší: nič sa nearchivuje a jej číslo sa už neprijíma. Zvoľte čas s dostatočnou rezervou nad trvaním vášho exportu.

2. Odošlite dokumenty

Dokumenty posielajte v dávkach po najviac 500 spolu s číslom synchronizácie. Telo dávky má najviac 50 MiB; súbory v dávke sa odovzdávajú ako upload_id.

curl -X POST https://api.sursa.com/v1/push/sources/42/documents/batch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-7-batch-1" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_number": 7,
    "documents": [
      {"external_id": "faq-shipping", "title": "Shipping", "content_type": "markdown",
       "content": "# Shipping\n\nWe ship worldwide within 5 days.", "path": ["Support"]},
      {"external_id": "faq-refunds", "title": "Refunds", "content_type": "html",
       "content": "<p>Refunds take 14 days.</p>", "path": ["Support", "Billing"],
       "permissions": {"groups": ["Support"]}, "metadata": {"article_id": "1042"}}
    ]
  }'

Odpoveď obsahuje výsledok pre každý dokument v poradí, v akom ste ich odoslali:

{
  "results": [
    {"external_id": "faq-shipping", "result": "unchanged", "status": "indexed", "card_id": "8c1d…", "version": "5e0f…"},
    {"external_id": "faq-refunds", "result": "updated", "status": "pending", "card_id": "3f2c…", "version": "a91b…"}
  ]
}

Predvolene sa každý dokument dávky spracuje samostatne: jeden chybný dokument nezastaví ostatné.

Dokumenty, ktoré sa od poslednej synchronizácie nezmenili, netreba posielať znova. Potvrďte ich podľa identifikátora cez POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, najviac 1000 identifikátorov v jednej požiadavke, aby ich úplné zosúladenie zachovalo:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/touch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ids": ["faq-contact", "faq-hours"]}'

3. Uzavrite

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close synchronizáciu ukončí:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/close \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'

Kedykoľvek sa váš export zastaví v polovici, uzavrite synchronizáciu s failed: uzavretie s complete po čiastočnom exporte by archivovalo každý dokument, ku ktorému ste sa nedostali. Opakované rovnaké uzavretie vráti rovnaký výsledok.

Po uzavretí Sursa premení dokumenty na karty približne do minúty. Stránka zdroja ukazuje každú synchronizáciu s počtom odoslaných a archivovaných dokumentov a GET /v1/push/sources/{source_id}/syncs/{sync_number} vracia tie isté počítadlá.

Prírastkové synchronizácie

Medzi úplnými synchronizáciami posielajte len to, čo sa zmenilo:

1. Otvorte synchronizáciu s "type": "incremental".
2. Odošlite zmenené dokumenty a identifikátory odstránených vložte do deletes (pozri nižšie).
3. Uzavrite s complete_incremental.

Z času na čas, napríklad raz týždenne, spustite úplnú synchronizáciu, aby ste zachytili všetko, čo prírastkový beh vynechal.

Vymazanie dokumentov v dávke

Dávka môže odstrániť dokumenty spolu s tými, ktoré zapisuje. Ich identifikátory uveďte v deletes:

{
  "sync_number": 8,
  "documents": [{"external_id": "faq-shipping", "title": "Shipping", "content": "…"}],
  "deletes": ["faq-old-returns", "faq-fax"]
}

Každý vymazaný identifikátor dostane vlastnú položku v results s result deleted alebo not_found, ak zdroj taký dokument nemá. Opätovné vymazanie toho istého identifikátora neuškodí.

Atomické dávky

Niektoré zmeny dávajú zmysel len spolu, napríklad dokument a ten, ktorý ho nahrádza. Odošlite "atomic": true a dávka sa premietne celá, alebo vôbec: ak niektorý dokument neprejde kontrolami, z dávky sa nepremietne nič a odpoveď je 422 s kódom sources.push_batch_rejected a výsledkom každého dokumentu v error.details.results: dokumenty, ktoré zlyhali, majú error, ostatné skipped.

{"sync_number": 8, "atomic": true, "documents": […], "deletes": ["faq-old-returns"]}

Bez atomic sa dávka spracúva dokument po dokumente. Atomické dávky používajte pre súvisiace zmeny a bežné dávky pre hromadné načítania, kde jeden chybný dokument nemá zdržať ostatné.

Kontrola výsledku každého dokumentu

Odpoveď na dávku vám povie, ako sa každý dokument zapísal. Premena na kartu prebieha až potom, takže status môže byť ešte pending. Dokumenty synchronizácie, z ktorých sa nestali karty, nájdete takto:

curl "https://api.sursa.com/v1/push/sources/42/syncs/7/documents?status=failed" \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

Každá položka má external_id, title, status, card_id, version a reason a zoznam sa stránkuje cez cursor. status prijíma aj pending, processing, indexed a removed.

Namiesto pýtania sa môžete nechať aj upozorniť: udalosti import.sync_completed (synchronizácia je uzavretá a spracovaná, so súčtami) a import.document_failed (dokument sa nestal kartou, s jeho reason) prichádzajú cez webhook aj do kanála udalostí.

Opakovania

• S každým POST odošlite Idempotency-Key. Opakovaná dávka s rovnakým kľúčom vráti prvý výsledok.
• Aj bez kľúča sa dokument s rovnakým external_id nikdy nestane druhou kartou: je unchanged alebo updated.
• Ak sa proces zastaví uprostred synchronizácie, otvorte novú, keď stará vyprší, alebo starú uzavrite s failed, ak ešte poznáte jej číslo, a synchronizáciu spustite znova.

Limity

Dokument nad limitom dokumentov zdroja v dávke zlyhá s dôvodom limit_reached; požiadavka s jedným dokumentom vráti 409 s kódom sources.push_too_many_documents. Limity frekvencie platia ako pri každej inej požiadavke; pozri Limity frekvencie a kvóty.

Bežné chyby