Synkronisér dit system med en brugerdefineret kilde

En brugerdefineret kilde forbinder et system, der ikke har en indbygget connector: din wiki, dit ticketsystem, en database, en eksport fra et hvilket som helst sted. Din kode sender dokumenter til Sursa, og Sursa gør dem til kort i den samling og de mapper, som kilden er sat op til, med den samme søgning, de samme svar, den samme verificering og de samme tilladelser som kort fra enhver anden kilde.

I modsætning til at skrive kort direkte holder en brugerdefineret kilde styr på, hvad du har sendt. Ved afslutningen af en fuld synkronisering arkiverer Sursa alle dokumenter, som du ikke sendte, så sletninger i dit system når frem til Sursa uden ekstra arbejde.

Sæt kilden op

En administrator opretter kilden i Sursa under Sources → New source → Custom source (kilder, ny kilde, brugerdefineret kilde) og vælger:

• samlingen og eventuelt en mappe til kildens kort;
• mappetilstanden: alle kort i den valgte mappe eller undermapper, der afspejler hvert dokuments path;
• tilladelserne: samlingens tilladelser eller »som i kilden«, hvor hvert dokument angiver, hvem der må se det.

Kildens side viser dens id; eksemplerne bruger 42.

Vælg en nøgle

Kildenøglen er det sikreste valg til en enkelt integration, især en, der kører på en tredjepartsplatform. En organisationsnøgle med import:write passer til en tjeneste, der forsyner flere kilder.

Begge nøgler sendes på samme måde, og alle push-operationer ligger under /v1/push/sources/{source_id}. Kontrollér nøglen og kildens tilstand med 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}

Dokumentet

I stedet for content kan et enkelt dokument have en fil på op til 100 MB i en multipart/form-data-anmodning: filen i delen file og felterne ovenfor som JSON i delen document. Uploads i dele til upload_id og attachments oprettes med en organisationsnøgle, der har scopet import:write og formålet import_attachment; en kildenøgle kan ikke oprette dem.

To måder at sende på

Direkte opdateringer passer til systemer, der fortæller dig om hver ændring, fx en webhook fra dit helpdesk-system eller et trin i Zapier. Send et dokument, når det oprettes eller ændres, og slet det, når det fjernes:

Ændringer bliver til kort inden for cirka et minut; flere ændringer i træk behandles samlet.

Synkroniseringer passer til faste eksporter: Du sender alt eller alt, der er ændret, og Sursa afstemmer. Resten af denne vejledning handler om synkroniseringer.

Kør en fuld synkronisering

En synkronisering har tre trin: åbne, sende og lukke.

1. Åbn

POST /v1/push/sources/{source_id}/syncs åbner en synkronisering og returnerer dens nummer:

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 er initial ved kildens første synkronisering og incremental, når en synkronisering er gennemført. En incremental-synkronisering før den første gennemførte returnerer sources.push_initial_required.
• Der kan kun være én åben synkronisering ad gangen: En synkronisering mere returnerer 409 sources.push_sync_open.
• En synkronisering forbliver åben i max_minutes (som standard 60, op til 1440). Derefter udløber den: Intet arkiveres, og dens nummer accepteres ikke længere. Vælg en tid, der er et godt stykke længere, end din eksport tager.

2. Send dokumenter

Send dokumenterne i batches på op til 500 med synkroniseringens nummer. En batchs brødtekst er op til 50 MiB; filer i en batch angives som 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"}}
    ]
  }'

Svaret har et resultat for hvert dokument i den rækkefølge, du sendte dem:

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

Som standard behandles hvert dokument i en batch for sig: Ét dårligt dokument stopper ikke de andre.

Dokumenter, der ikke er ændret siden den sidste synkronisering, behøver ikke sendes igen. Bekræft dem efter id med POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, op til 1000 id’er pr. anmodning, så den fulde afstemning beholder dem:

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

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close afslutter synkroniseringen:

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

Luk med failed, når din eksport stopper halvvejs: Et complete efter en delvis eksport ville arkivere alle de dokumenter, du ikke nåede til. Gentager du den samme lukning, returneres det samme resultat.

Efter lukningen gør Sursa dokumenterne til kort inden for cirka et minut. Kildens side viser hver synkronisering med antallet af sendte og arkiverede dokumenter, og GET /v1/push/sources/{source_id}/syncs/{sync_number} returnerer de samme tællere.

Inkrementelle synkroniseringer

Mellem fulde synkroniseringer sender du kun det, der er ændret:

1. Åbn med "type": "incremental".
2. Send de ændrede dokumenter, og sæt id’erne for de fjernede i deletes (se nedenfor).
3. Luk med complete_incremental.

Kør en fuld synkronisering en gang imellem, fx ugentligt, for at fange det, som en inkrementel kørsel har overset.

Slet dokumenter i en batch

En batch kan fjerne dokumenter sammen med dem, den skriver. Angiv deres id’er i deletes:

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

Hvert slettet id får sin egen post i results med result deleted eller not_found, hvis kilden ikke har et sådant dokument. Det gør ingen skade at slette det samme id igen.

Atomare batches

Nogle ændringer giver kun mening sammen, fx et dokument og det dokument, der erstatter det. Send "atomic": true, så anvendes batchen helt eller slet ikke: Består et dokument ikke kontrollen, anvendes intet fra batchen, og svaret er 422 med koden sources.push_batch_rejected og resultatet for hvert dokument i error.details.results: De dokumenter, der mislykkedes, har error, de andre skipped.

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

Uden atomic anvendes en batch dokument for dokument. Brug atomare batches til relaterede ændringer og almindelige batches til masseindlæsninger, hvor ét dårligt dokument ikke skal holde resten tilbage.

Kontrollér resultatet for hvert dokument

Batchsvaret fortæller dig, hvordan hvert dokument blev skrevet. Omdannelsen til et kort sker bagefter, så status kan stadig være pending. Sådan finder du de dokumenter i en synkronisering, der ikke blev til kort:

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

Hver post har external_id, title, status, card_id, version og reason, og listen inddeles i sider med cursor. status accepterer også pending, processing, indexed og removed.

Du kan også få besked i stedet for at spørge: Hændelserne import.sync_completed (en synkronisering er lukket og behandlet, med totaler) og import.document_failed (et dokument blev ikke til et kort, med dets reason) kommer via webhook og i hændelsesfeedet.

Nye forsøg

• Send en Idempotency-Key med hver POST. En gentaget batch med samme nøgle returnerer det første resultat.
• Selv uden nøglen bliver et dokument med samme external_id aldrig til et kort mere: Det er unchanged eller updated.
• Stopper processen midt i en synkronisering, så åbn en ny, når den gamle er udløbet, eller luk den gamle med failed, hvis du stadig har dens nummer, og kør synkroniseringen igen.

Grænser

Et dokument ud over kildens grænse for dokumenter mislykkes med årsagen limit_reached i en batch; en anmodning med et enkelt dokument returnerer 409 med koden sources.push_too_many_documents. Hastighedsgrænser gælder som for enhver anden anmodning; se Hastighedsgrænser og kvoter.

Almindelige fejl