Sistēmas sinhronizācija ar pielāgotu avotu

Pielāgots avots pievieno sistēmu, kurai nav iebūvēta savienotāja: jūsu wiki, pieteikumu sistēmu, datubāzi, eksportu no jebkurienes. Jūsu kods nosūta dokumentus uz Sursu, un Sursa pārvērš tos par kartītēm kolekcijā un mapēs, kurām avots ir iestatīts, ar tādu pašu meklēšanu, atbildēm, pārbaudi un atļaujām kā kartītēm no jebkura cita avota.

Atšķirībā no kartīšu tiešas rakstīšanas pielāgots avots seko tam, ko esat nosūtījuši. Pilnas sinhronizācijas beigās Sursa arhivē katru dokumentu, kuru nenosūtījāt, tāpēc dzēšana jūsu sistēmā nonāk Sursā bez papildu darba.

Avota iestatīšana

Administrators izveido avotu Sursā sadaļā Sources → New source → Custom source (avoti, jauns avots, pielāgots avots) un izvēlas:

• kolekciju un, ja vajag, mapi tā kartītēm;
• mapju režīmu: visas kartītes izvēlētajā mapē vai apakšmapes, kas atspoguļo katra dokumenta path;
• atļaujas: kolekcijas atļaujas vai „kā avotā“, kur katrs dokuments norāda, kas to drīkst redzēt.

Avota lapā redzams tā ID; piemēros izmantots 42.

Atslēgas izvēle

Avota atslēga ir drošākā izvēle vienai integrācijai, īpaši tādai, kas darbojas trešās puses platformā. Organizācijas atslēga ar import:write der pakalpojumam, kas piegādā datus vairākiem avotiem.

Abas atslēgas sūta vienādi, un visas push operācijas atrodas zem /v1/push/sources/{source_id}. Pārbaudiet atslēgu un avota stāvokli ar 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}

Dokuments

Vienam dokumentam content vietā var būt līdz 100 MB liels fails multipart/form-data pieprasījumā: fails daļā file, iepriekš minētie lauki JSON formātā daļā document. Augšupielādes pa daļām laukiem upload_id un attachments izveido ar organizācijas atslēgu, kurai ir tvērums import:write, un ar mērķi import_attachment; avota atslēga tās izveidot nevar.

Divi nosūtīšanas veidi

Tiešie atjauninājumi der sistēmām, kas ziņo par katru izmaiņu, piemēram, webhook paziņojums no jūsu palīdzības dienesta sistēmas vai solis Zapier platformā. Nosūtiet dokumentu, kad tas tiek izveidots vai mainīts, un dzēsiet to, kad tas tiek noņemts:

Izmaiņas kļūst par kartītēm aptuveni minūtes laikā; vairākas izmaiņas pēc kārtas tiek apstrādātas kopā.

Sinhronizācijas der regulāriem eksportiem: jūs nosūtāt visu vai visu, kas mainījies, un Sursa veic saskaņošanu. Pārējā ceļveža daļa ir par sinhronizācijām.

Pilnas sinhronizācijas izpilde

Sinhronizācijai ir trīs soļi: atvērt, nosūtīt, aizvērt.

1. Atveriet

POST /v1/push/sources/{source_id}/syncs atver sinhronizāciju un atgriež tās numuru:

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 ir initial avota pirmajai sinhronizācijai un incremental, kad kāda sinhronizācija jau ir pabeigta. incremental sinhronizācija pirms pirmās pabeigtās atgriež sources.push_initial_required.
• Vienlaikus var būt atvērta tikai viena sinhronizācija: otrā atgriež 409 sources.push_sync_open.
• Sinhronizācija paliek atvērta max_minutes minūtes (pēc noklusējuma 60, ne vairāk kā 1440). Pēc tam tās derīgums beidzas: nekas netiek arhivēts, un tās numurs vairs netiek pieņemts. Izvēlieties laiku, kas krietni pārsniedz jūsu eksporta ilgumu.

2. Nosūtiet dokumentus

Nosūtiet dokumentus partijās līdz 500 ar sinhronizācijas numuru. Partijas saturs ir līdz 50 MiB; faili partijas iekšienē tiek nodoti kā 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"}}
    ]
  }'

Atbildē ir rezultāts katram dokumentam tādā secībā, kādā tos nosūtījāt:

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

Pēc noklusējuma katrs partijas dokuments tiek piemērots atsevišķi: viens slikts dokuments neaptur pārējos.

Dokumenti, kas kopš pēdējās sinhronizācijas nav mainījušies, nav jānosūta vēlreiz. Apstipriniet tos pēc ID ar POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, līdz 1000 ID vienā pieprasījumā, lai pilnā saskaņošana tos saglabātu:

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. Aizveriet

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close pabeidz sinhronizāciju:

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

Aizveriet ar failed vienmēr, kad jūsu eksports apstājas pusceļā: complete pēc daļēja eksporta arhivētu katru dokumentu, līdz kuram netikāt. Tās pašas aizvēršanas atkārtošana atgriež to pašu rezultātu.

Pēc aizvēršanas Sursa aptuveni minūtes laikā pārvērš dokumentus par kartītēm. Avota lapā redzama katra sinhronizācija ar nosūtīto un arhivēto dokumentu skaitu, un GET /v1/push/sources/{source_id}/syncs/{sync_number} atgriež tos pašus skaitītājus.

Inkrementālas sinhronizācijas

Starp pilnām sinhronizācijām nosūtiet tikai to, kas mainījies:

1. Atveriet ar "type": "incremental".
2. Nosūtiet mainītos dokumentus un noņemto dokumentu ID ievietojiet laukā deletes (sk. tālāk).
3. Aizveriet ar complete_incremental.

Laiku pa laikam, piemēram, reizi nedēļā, palaidiet pilnu sinhronizāciju, lai notvertu visu, ko inkrementālās palaišanas palaida garām.

Dokumentu dzēšana partijā

Partija var noņemt dokumentus kopā ar tiem, ko tā raksta. Uzskaitiet to ID laukā deletes:

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

Katrs dzēstais ID saņem savu ierakstu laukā results ar result deleted vai not_found, ja avotā šāda dokumenta nav. Tā paša ID atkārtota dzēšana nekaitē.

Atomāras partijas

Dažas izmaiņas ir jēgpilnas tikai kopā, piemēram, dokuments un tas, kas to aizstāj. Nosūtiet "atomic": true, un partija tiek piemērota pilnībā vai nemaz: ja kāds dokuments neiztur pārbaudes, nekas no partijas netiek piemērots, un atbilde ir 422 ar kodu sources.push_batch_rejected un katra dokumenta rezultātu laukā error.details.results: dokumentiem, kas neizdevās, ir error, pārējiem – skipped.

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

Bez atomic partija tiek piemērota dokumentu pa dokumentam. Izmantojiet atomāras partijas saistītām izmaiņām un parastas partijas lielapjoma ielādēm, kur viens slikts dokuments nedrīkst aizturēt pārējos.

Katra dokumenta rezultāta pārbaude

Partijas atbilde pasaka, kā katrs dokuments ierakstīts. Pārvēršana par kartīti notiek pēc tam, tāpēc status vēl var būt pending. Lai atrastu sinhronizācijas dokumentus, kas nav kļuvuši par kartītēm:

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

Katram ierakstam ir external_id, title, status, card_id, version un reason, un saraksts tiek dalīts lapās ar cursor. status pieņem arī pending, processing, indexed un removed.

Jūs varat arī saņemt paziņojumu, nevis jautāt paši: notikumi import.sync_completed (sinhronizācija ir aizvērta un apstrādāta, ar tās kopsummām) un import.document_failed (dokuments nav kļuvis par kartīti, ar tā reason) pienāk ar webhook paziņojumiem un notikumu plūsmā.

Atkārtojumi

• Ar katru POST nosūtiet Idempotency-Key. Atkārtota partija ar to pašu atslēgu atgriež pirmo rezultātu.
• Arī bez atslēgas dokuments ar to pašu external_id nekad nekļūst par otru kartīti: tas ir unchanged vai updated.
• Ja process apstājas sinhronizācijas vidū, atveriet jaunu sinhronizāciju pēc vecās derīguma beigām vai aizveriet veco ar failed, ja jums vēl ir tās numurs, un palaidiet sinhronizāciju vēlreiz.

Limiti

Dokuments, kas pārsniedz avota dokumentu limitu, partijā neizdodas ar iemeslu limit_reached; viena dokumenta pieprasījums atgriež 409 ar kodu sources.push_too_many_documents. Pieprasījumu biežuma limiti attiecas tāpat kā uz jebkuru citu pieprasījumu; sk. Pieprasījumu biežuma limiti un kvotas.

Biežākās kļūdas