Synchronizace vašeho systému přes vlastní zdroj

Vlastní zdroj připojí systém, pro který neexistuje vestavěný konektor: vaši wiki, nástroj pro tikety, databázi, export odkudkoli. Váš kód odesílá dokumenty do Sursy a Sursa z nich vytváří karty v kolekci a složkách, pro které je zdroj nastaven, se stejným vyhledáváním, odpověďmi, ověřováním a oprávněními jako u karet z jakéhokoli jiného zdroje.

Na rozdíl od přímého zápisu karet si vlastní zdroj pamatuje, co už dostal. Na konci úplné synchronizace Sursa archivuje každý dokument, který v ní nebyl odeslán, takže se smazání ve vašem systému do Sursy dostanou bez další práce.

Nastavení zdroje

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

• kolekci a případně složku pro jeho karty;
• režim složek: všechny karty ve zvolené složce, nebo podsložky, které kopírují path každého dokumentu;
• oprávnění: oprávnění kolekce, nebo „jako ve zdroji“, kdy každý dokument uvádí, kdo ho smí vidět.

Stránka zdroje zobrazuje jeho ID; ukázky používají 42.

Výběr klíče

Klíč zdroje je nejbezpečnější volbou pro jednu integraci, zvlášť pro takovou, která běží na platformě třetí strany. Klíč organizace s import:write se hodí pro službu, která zásobuje několik zdrojů.

Oba klíče se odesílají stejně a všechny operace push leží pod /v1/push/sources/{source_id}. Klíč a stav zdroje zkontrolujete pomocí 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

Místo content může jeden dokument v požadavku multipart/form-data nést soubor do velikosti 100 MB: soubor v části file, pole uvedená výše jako JSON v části document. Nahrávání po částech pro upload_id a attachments se vytvářejí klíčem organizace s rozsahem import:write a s účelem import_attachment; klíč zdroje je vytvořit nemůže.

Dva způsoby odesílání

Přímé aktualizace se hodí pro systémy, které vás informují o každé změně, například webhookem z vašeho helpdesku nebo krokem v Zapieru. Dokument odešlete, když vznikne nebo se změní, a smažte ho, když je odstraněn:

Ze změn se stanou karty zhruba do minuty; několik změn za sebou se zpracuje společně.

Synchronizace se hodí pro pravidelné exporty: odešlete všechno nebo všechno, co se změnilo, a Sursa data sesouhlasí. Zbytek tohoto návodu se věnuje synchronizacím.

Úplná synchronizace

Synchronizace má tři kroky: otevřít, odeslat, uzavřít.

1. Otevřete synchronizaci

POST /v1/push/sources/{source_id}/syncs otevře synchronizaci a vrátí 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 pro první synchronizaci zdroje a incremental, jakmile se některá synchronizace dokončila. Synchronizace incremental před první dokončenou vrátí sources.push_initial_required.
• Najednou může být otevřená jen jedna synchronizace: druhá vrátí 409 sources.push_sync_open.
• Synchronizace zůstává otevřená max_minutes (výchozí 60, nejvýše 1440). Poté vyprší: nic se nearchivuje a její číslo se už nepřijímá. Zvolte dobu s dostatečnou rezervou delší, než trvá váš export.

2. Odešlete dokumenty

Dokumenty posílejte v dávkách nejvýše po 500 s číslem synchronizace. Tělo dávky má nejvýše 50 MiB; soubory v dávce se předávají jako 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"}}
    ]
  }'

Odpověď obsahuje výsledek pro každý dokument ve stejném pořadí, v jakém byly odeslány:

{
  "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…"}
  ]
}

Ve výchozím nastavení se každý dokument dávky použije samostatně: jeden chybný dokument nezastaví ostatní.

Dokumenty, které se od poslední synchronizace nezměnily, není nutné posílat znovu. Potvrďte je podle identifikátoru pomocí POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, až 1000 identifikátorů na požadavek, aby je úplné sesouhlasení 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. Uzavřete synchronizaci

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close synchronizaci 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"}'

Kdykoli se váš export zastaví v polovině, uzavřete synchronizaci s failed: complete po neúplném exportu by archivoval každý dokument, ke kterému se export nedostal. Opakované stejné uzavření vrátí stejný výsledek.

Po uzavření Sursa z dokumentů vytvoří karty zhruba do minuty. Stránka zdroje ukazuje každou synchronizaci s počtem odeslaných a archivovaných dokumentů a GET /v1/push/sources/{source_id}/syncs/{sync_number} vrací stejné počty.

Přírůstkové synchronizace

Mezi úplnými synchronizacemi odesílejte jen to, co se změnilo:

1. Otevřete synchronizaci s "type": "incremental".
2. Odešlete změněné dokumenty a identifikátory odstraněných vložte do deletes (viz níže).
3. Uzavřete synchronizaci s complete_incremental.

Čas od času, například jednou týdně, spusťte úplnou synchronizaci, aby se zachytilo vše, co přírůstkový běh vynechal.

Mazání dokumentů v dávce

Dávka může spolu s dokumenty, které zapisuje, i dokumenty odstraňovat. Jejich 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ý smazaný identifikátor dostane v results vlastní položku s result deleted, nebo not_found, pokud zdroj takový dokument nemá. Opakované smazání stejného identifikátoru nic nepokazí.

Atomické dávky

Některé změny mají smysl jen společně, například dokument a dokument, který ho nahrazuje. Odešlete "atomic": true a dávka se použije buď celá, nebo vůbec: pokud kterýkoli dokument neprojde kontrolami, nepoužije se nic z dávky a odpověď je 422 s kódem sources.push_batch_rejected a výsledkem každého dokumentu v error.details.results: dokumenty, které selhaly, mají error, ostatní skipped.

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

Bez atomic se dávka použije dokument po dokumentu. Atomické dávky používejte pro související změny a běžné dávky pro hromadná načtení, kde jeden chybný dokument nemá zdržet ostatní.

Kontrola výsledku každého dokumentu

Odpověď na dávku vám řekne, jak byl každý dokument zapsán. Vytvoření karty proběhne až potom, takže status může být ještě pending. Dokumenty synchronizace, ze kterých se karty nestaly, najdete 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 seznam se stránkuje pomocí cursor. status přijímá také pending, processing, indexed a removed.

Místo dotazování se můžete nechat informovat: události import.sync_completed (synchronizace je uzavřená a zpracovaná, se svými součty) a import.document_failed (z dokumentu se nestala karta, s jeho reason) přicházejí webhookem i v kanálu událostí.

Opakování

• S každým POST odesílejte Idempotency-Key. Opakovaná dávka se stejným klíčem vrátí první výsledek.
• I bez klíče se z dokumentu se stejným external_id nikdy nestane druhá karta: je unchanged nebo updated.
• Pokud se proces zastaví uprostřed synchronizace, otevřete po vypršení staré synchronizace novou, nebo starou uzavřete s failed, pokud ještě znáte její číslo, a synchronizaci spusťte znovu.

Limity

Dokument nad limitem dokumentů zdroje selže v dávce s důvodem limit_reached; na požadavek s jediným dokumentem přijde odpověď 409 s kódem sources.push_too_many_documents. Limity četnosti platí stejně jako pro jakýkoli jiný požadavek; viz Limity četnosti a kvóty.

Časté chyby