Sistemos sinchronizavimas per pasirinktinį šaltinį

Pasirinktinis šaltinis prijungia sistemą, kuri neturi integruotos jungties: jūsų wiki, užklausų valdymo įrankį, duomenų bazę, eksportą iš bet kur. Jūsų kodas siunčia dokumentus į Sursą, o Sursa paverčia juos kortelėmis tame rinkinyje ir aplankuose, kuriems nustatytas šaltinis, – su ta pačia paieška, atsakymais, tikrinimu ir leidimais kaip bet kurio kito šaltinio kortelės.

Kitaip nei tiesioginis kortelių rašymas, pasirinktinis šaltinis seka, ką išsiuntėte. Visiškos sinchronizacijos pabaigoje Sursa archyvuoja kiekvieną dokumentą, kurio neišsiuntėte, todėl ištrynimai jūsų sistemoje pasiekia Sursą be papildomo darbo.

Šaltinio nustatymas

Administratorius sukuria šaltinį Sursoje, skiltyje Sources → New source → Custom source (šaltiniai, naujas šaltinis, pasirinktinis šaltinis), ir pasirenka:

• rinkinį ir, jei reikia, aplanką jo kortelėms;
• aplankų režimą: visos kortelės pasirinktame aplanke arba poaplankiai, atkartojantys kiekvieno dokumento path;
• leidimus: rinkinio leidimai arba „kaip šaltinyje“ – tada kiekvienas dokumentas nurodo, kas gali jį matyti.

Šaltinio puslapyje rodomas jo ID; pavyzdžiuose naudojamas 42.

Rakto pasirinkimas

Šaltinio raktas – saugiausias pasirinkimas vienai integracijai, ypač tokiai, kuri veikia trečiosios šalies platformoje. Organizacijos raktas su import:write tinka paslaugai, kuri pildo kelis šaltinius.

Abu raktai siunčiami vienodai, o visos push operacijos yra po /v1/push/sources/{source_id}. Raktą ir šaltinio būseną patikrinkite operacija 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}

Dokumentas

Vietoj content vienas dokumentas multipart/form-data užklausoje gali perduoti iki 100 MB failą: failas – dalyje file, aukščiau nurodyti laukai JSON formatu – dalyje document. Įkėlimai dalimis, skirti upload_id ir attachments, kuriami su organizacijos raktu, turinčiu apimtį import:write, ir paskirtimi import_attachment; šaltinio raktas jų sukurti negali.

Du siuntimo būdai

Tiesioginiai atnaujinimai tinka sistemoms, kurios praneša apie kiekvieną pakeitimą, pavyzdžiui, jūsų pagalbos tarnybos sistemos webhook pranešimas ar žingsnis Zapier platformoje. Siųskite dokumentą, kai jis sukuriamas ar pakeičiamas, ir ištrinkite, kai jis pašalinamas:

Pakeitimai tampa kortelėmis maždaug per minutę; keli pakeitimai iš eilės apdorojami kartu.

Sinchronizacijos tinka reguliariems eksportams: siunčiate viską arba viską, kas pasikeitė, o Sursa suderina. Toliau ši instrukcija aprašo sinchronizacijas.

Visiška sinchronizacija

Sinchronizacija turi tris žingsnius: atidaryti, siųsti, uždaryti.

1. Atidarykite

POST /v1/push/sources/{source_id}/syncs atidaro sinchronizaciją ir grąžina jos numerį:

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 yra initial pirmajai šaltinio sinchronizacijai ir incremental, kai jau yra užbaigta sinchronizacija. incremental sinchronizacija prieš bet kurią užbaigtą grąžina sources.push_initial_required.
• Vienu metu gali būti atidaryta tik viena sinchronizacija: antroji grąžina 409 sources.push_sync_open.
• Sinchronizacija lieka atidaryta max_minutes (numatytoji reikšmė – 60, daugiausia 1440). Po to jos galiojimas baigiasi: niekas nearchyvuojama, o jos numeris nebepriimamas. Pasirinkite laiką, gerokai ilgesnį už jūsų eksporto trukmę.

2. Siųskite dokumentus

Siųskite dokumentus partijomis iki 500, su sinchronizacijos numeriu. Partijos turinys – iki 50 MiB; failai partijoje perduodami kaip 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"}}
    ]
  }'

Atsake pateikiamas kiekvieno dokumento rezultatas ta tvarka, kuria juos išsiuntėte:

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

Pagal numatytuosius nustatymus kiekvienas partijos dokumentas taikomas atskirai: vienas blogas dokumentas nesustabdo kitų.

Dokumentų, kurie nuo paskutinės sinchronizacijos nepasikeitė, siųsti iš naujo nereikia. Patvirtinkite juos pagal ID operacija POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, iki 1000 ID vienoje užklausoje, kad visiškas suderinimas juos išsaugotų:

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. Uždarykite

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close užbaigia sinchronizaciją:

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

Kai eksportas nutrūksta pusiaukelėje, visada uždarykite su failed: complete po dalinio eksporto archyvuotų kiekvieną dokumentą, kurio nespėjote išsiųsti. Pakartojus tą patį uždarymą, grąžinamas tas pats rezultatas.

Po uždarymo Sursa maždaug per minutę paverčia dokumentus kortelėmis. Šaltinio puslapyje rodoma kiekviena sinchronizacija su išsiųstų ir archyvuotų dokumentų skaičiumi, o GET /v1/push/sources/{source_id}/syncs/{sync_number} grąžina tuos pačius skaitiklius.

Inkrementinės sinchronizacijos

Tarp visiškų sinchronizacijų siųskite tik tai, kas pasikeitė:

1. Atidarykite su "type": "incremental".
2. Išsiųskite pasikeitusius dokumentus, o pašalintųjų ID įrašykite į deletes (žr. toliau).
3. Uždarykite su complete_incremental.

Retkarčiais, pavyzdžiui, kas savaitę, paleiskite visišką sinchronizaciją, kad pagautumėte tai, ką praleido inkrementinis paleidimas.

Dokumentų trynimas partijoje

Partija gali pašalinti dokumentus kartu su tais, kuriuos rašo. Jų ID išvardykite lauke deletes:

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

Kiekvienas ištrintas ID gauna savo įrašą lauke results su result deleted arba not_found, jei šaltinis tokio dokumento neturi. Ištrinti tą patį ID dar kartą nekenksminga.

Atominės partijos

Kai kurie pakeitimai prasmingi tik kartu, pavyzdžiui, dokumentas ir jį pakeičiantis dokumentas. Siųskite "atomic": true, ir partija bus pritaikyta visa arba visai nepritaikyta: jei kuris nors dokumentas nepraeina patikrų, nieko iš partijos nepritaikoma, o atsakas yra 422 su kodu sources.push_batch_rejected ir kiekvieno dokumento rezultatu lauke error.details.results: nepavykę dokumentai turi error, kiti – skipped.

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

Be atomic partija taikoma dokumentas po dokumento. Atomines partijas naudokite susijusiems pakeitimams, o įprastas partijas – masiniams įkėlimams, kur vienas blogas dokumentas neturėtų sulaikyti kitų.

Kiekvieno dokumento rezultato patikra

Partijos atsakas nurodo, kaip buvo įrašytas kiekvienas dokumentas. Kortele dokumentas tampa vėliau, todėl status dar gali būti pending. Kad rastumėte sinchronizacijos dokumentus, kurie netapo kortelėmis:

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

Kiekvienas įrašas turi external_id, title, status, card_id, version ir reason, o sąrašas skaidomas puslapiais su cursor. status taip pat priima pending, processing, indexed ir removed.

Užuot klausus, galite gauti pranešimus: įvykiai import.sync_completed (sinchronizacija uždaryta ir apdorota, su suvestiniais skaičiais) ir import.document_failed (dokumentas netapo kortele, su jo reason) ateina webhook pranešimais ir yra įvykių juostoje.

Pakartojimai

• Su kiekviena POST užklausa siųskite Idempotency-Key. Pakartota partija su tuo pačiu raktu grąžina pirmąjį rezultatą.
• Net be rakto dokumentas su tuo pačiu external_id niekada netampa antra kortele: jis yra unchanged arba updated.
• Jei procesas sustoja sinchronizacijos viduryje, atidarykite naują, kai senosios galiojimas baigsis, arba, jei dar turite senosios numerį, uždarykite ją su failed ir paleiskite sinchronizaciją iš naujo.

Limitai

Dokumentas, viršijantis šaltinio dokumentų limitą, partijoje nepavyksta su priežastimi limit_reached; vieno dokumento užklausa grąžina 409 su kodu sources.push_too_many_documents. Užklausų dažnio limitai taikomi kaip ir bet kuriai kitai užklausai; žr. Užklausų dažnio limitai ir kvotos.

Dažnos klaidos