Sinkronizacija vašeg sustava putem vlastitog izvora

Vlastiti izvor povezuje sustav koji nema ugrađeni konektor: vaš wiki, vaš alat za prijave, bazu podataka, izvoz iz bilo kojeg mjesta. Vaš kod šalje dokumente u Sursu, a Sursa od njih stvara kartice u zbirci i mapama za koje je izvor postavljen, s istim pretraživanjem, odgovorima, provjerom i dopuštenjima kao i kartice iz bilo kojeg drugog izvora.

Za razliku od izravnog zapisivanja kartica, vlastiti izvor prati što ste poslali. Na kraju potpune sinkronizacije Sursa arhivira svaki dokument koji niste poslali, pa brisanja u vašem sustavu stižu u Sursu bez dodatnog rada.

Postavljanje izvora

Administrator stvara izvor u Sursi u Sources → New source → Custom source (izvori, novi izvor, vlastiti izvor) i odabire:

• zbirku i, po želji, mapu za njegove kartice;
• način rada s mapama: sve kartice u odabranoj mapi ili podmape koje zrcale path svakog dokumenta;
• dopuštenja: dopuštenja zbirke ili način zrcaljenja („kao u izvoru”), u kojem svaki dokument navodi tko ga smije vidjeti.

Stranica izvora prikazuje njegov ID; primjeri koriste 42.

Odabir ključa

Ključ izvora najsigurniji je izbor za jednu integraciju, osobito onu koja radi na platformi treće strane. Ključ organizacije s opsegom import:write prikladan je za uslugu koja puni više izvora.

Oba se ključa šalju na isti način, a svaka se operacija slanja (push) nalazi unutar /v1/push/sources/{source_id}. Ključ i stanje izvora provjerite pomoću 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

Umjesto content pojedinačni dokument može nositi datoteku do 100 MB u zahtjevu multipart/form-data: datoteku u dijelu file, a gornja polja kao JSON u dijelu document. Učitavanja u dijelovima za upload_id i attachments stvaraju se ključem organizacije s opsegom import:write i namjenom import_attachment; ključ izvora ne može ih stvoriti.

Dva načina slanja

Izravna ažuriranja prikladna su za sustave koji vas obavještavaju o svakoj promjeni, kao što je webhook iz vašeg sustava za podršku ili korak u Zapieru. Pošaljite dokument kad se stvori ili promijeni, a izbrišite ga kad se ukloni:

Promjene postaju kartice u roku od otprilike jedne minute; više uzastopnih promjena obrađuje se zajedno.

Sinkronizacije su prikladne za redovite izvoze: šaljete sve ili sve što se promijenilo, a Sursa usklađuje stanje. Ostatak ovog vodiča govori o sinkronizacijama.

Potpuna sinkronizacija

Sinkronizacija ima tri koraka: otvaranje, slanje i zatvaranje.

1. Otvorite sinkronizaciju

POST /v1/push/sources/{source_id}/syncs otvara sinkronizaciju i vraća njezin broj:

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 za prvu sinkronizaciju izvora, a incremental nakon što je neka sinkronizacija dovršena. Sinkronizacija incremental prije ijedne dovršene vraća sources.push_initial_required.
• Istodobno može biti otvorena samo jedna sinkronizacija: druga vraća 409 sources.push_sync_open.
• Sinkronizacija ostaje otvorena max_minutes minuta (zadano 60, najviše 1440). Nakon toga istječe: ništa se ne arhivira, a njezin se broj više ne prihvaća. Odaberite vrijeme znatno dulje od trajanja vašeg izvoza.

2. Pošaljite dokumente

Dokumente šaljite u paketima od najviše 500, s brojem sinkronizacije. Tijelo paketa može imati do 50 MiB; datoteke unutar paketa prosljeđuju se kao 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"}}
    ]
  }'

Odgovor sadrži rezultat za svaki dokument, redoslijedom kojim ste ih poslali:

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

Zadano se svaki dokument paketa primjenjuje zasebno: jedan loš dokument ne zaustavlja ostale.

Dokumente koji se nisu promijenili od posljednje sinkronizacije ne morate ponovno slati. Potvrdite ih prema ID-u pomoću POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, do 1000 ID-ova po zahtjevu, kako bi ih potpuno usklađivanje zadržalo:

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. Zatvorite sinkronizaciju

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close završava sinkronizaciju:

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"}'

Zatvorite s failed kad god se vaš izvoz zaustavi na pola puta: complete nakon djelomičnog izvoza arhivirao bi svaki dokument do kojeg niste stigli. Ponavljanje istog zatvaranja vraća isti rezultat.

Nakon zatvaranja Sursa u roku od otprilike jedne minute od dokumenata stvara kartice. Stranica izvora prikazuje svaku sinkronizaciju s brojem poslanih i arhiviranih dokumenata, a GET /v1/push/sources/{source_id}/syncs/{sync_number} vraća iste brojače.

Inkrementalne sinkronizacije

Između potpunih sinkronizacija šaljite samo ono što se promijenilo:

1. Otvorite sinkronizaciju s "type": "incremental".
2. Pošaljite promijenjene dokumente, a ID-ove uklonjenih stavite u deletes (v. u nastavku).
3. Zatvorite s complete_incremental.

S vremena na vrijeme, na primjer jednom tjedno, pokrenite potpunu sinkronizaciju kako biste uhvatili sve što je inkrementalno pokretanje propustilo.

Brisanje dokumenata u paketu

Paket može uklanjati dokumente zajedno s onima koje zapisuje. Navedite njihove ID-ove u deletes:

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

Svaki izbrisani ID dobiva vlastitu stavku u results, s result deleted ili not_found ako izvor nema takav dokument. Ponovno brisanje istog ID-a je bezopasno.

Atomarni paketi

Neke promjene imaju smisla samo zajedno, na primjer dokument i onaj koji ga zamjenjuje. Pošaljite "atomic": true i paket se primjenjuje u cijelosti ili se uopće ne primjenjuje: ako bilo koji dokument ne prođe provjere, ništa se iz paketa ne primjenjuje, a odgovor je 422 s kodom sources.push_batch_rejected i rezultatom svakog dokumenta u error.details.results: dokumenti koji nisu uspjeli imaju error, a ostali skipped.

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

Bez atomic paket se primjenjuje dokument po dokument. Atomarne pakete koristite za povezane promjene, a obične pakete za skupna punjenja, kod kojih jedan loš dokument ne bi smio zadržati ostale.

Provjera rezultata svakog dokumenta

Odgovor na paket govori vam kako je svaki dokument zapisan. Pretvaranje u karticu događa se naknadno, pa status može još biti pending. Da biste pronašli dokumente sinkronizacije koji nisu postali kartice:

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

Svaka stavka ima external_id, title, status, card_id, version i reason, a popis se straniči pomoću cursor. status prima i pending, processing, indexed i removed.

Umjesto da pitate, možete i primati obavijesti: događaji import.sync_completed (sinkronizacija je zatvorena i obrađena, s ukupnim brojevima) i import.document_failed (dokument nije postao kartica, s razlogom reason) stižu putem webhooka i u feedu događaja.

Ponovni pokušaji

• Uz svaki POST pošaljite Idempotency-Key. Ponovljeni paket s istim ključem vraća prvi rezultat.
• Čak i bez ključa dokument s istim external_id nikada ne postaje druga kartica: rezultat je unchanged ili updated.
• Ako se proces zaustavi usred sinkronizacije, otvorite novu nakon što stara istekne ili zatvorite staru s failed ako još imate njezin broj, a zatim ponovno pokrenite sinkronizaciju.

Ograničenja

Dokument iznad ograničenja broja dokumenata izvora u paketu ne uspijeva s razlogom limit_reached; zahtjev s jednim dokumentom vraća 409 s kodom sources.push_too_many_documents. Ograničenja učestalosti primjenjuju se kao i na svaki drugi zahtjev; v. Ograničenja učestalosti i kvote.

Česte pogreške