Synkroniser systemet ditt med en egendefinert kilde

En egendefinert kilde kobler til et system som ikke har noen innebygd kobling: wikien din, saksbehandlingsverktøyet ditt, en database, en eksport fra hvor som helst. Koden din sender dokumenter til Sursa, og Sursa gjør dem om til kort i samlingen og mappene som kilden er satt opp for, med det samme søket, de samme svarene, den samme verifiseringen og de samme tillatelsene som kort fra alle andre kilder.

I motsetning til når du skriver kort direkte, holder en egendefinert kilde rede på hva du har sendt. Ved slutten av en full synkronisering arkiverer Sursa alle dokumenter som du ikke sendte, så slettinger i systemet ditt når fram til Sursa uten ekstra arbeid.

Sett opp kilden

En administrator oppretter kilden i Sursa under Sources → New source → Custom source (kilder, ny kilde, egendefinert kilde) og velger:

• samlingen og eventuelt en mappe for kortene;
• mappemodusen: alle kortene i den valgte mappen, eller undermapper som speiler path for hvert dokument;
• tillatelsene: tillatelsene til samlingen, eller «som i kilden», der hvert dokument oppgir hvem som kan se det.

Kildens side viser ID-en; eksemplene bruker 42.

Velg en nøkkel

Kildenøkkelen er det tryggeste valget for én enkelt integrasjon, særlig en som kjører på en tredjepartsplattform. En organisasjonsnøkkel med import:write passer for en tjeneste som forsyner flere kilder.

Begge nøklene sendes på samme måte, og alle push-operasjonene ligger under /v1/push/sources/{source_id}. Kontroller nøkkelen og tilstanden til kilden 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 ett enkelt dokument ha med en fil på opptil 100 MB i en multipart/form-data-forespørsel: filen i delen file og feltene ovenfor som JSON i delen document. Opplastinger i deler for upload_id og attachments opprettes med en organisasjonsnøkkel som har scopet import:write, og med formålet import_attachment; en kildenøkkel kan ikke opprette dem.

To måter å sende på

Direkte oppdateringer passer for systemer som forteller deg om hver endring, for eksempel en webhook fra helpdesken din eller et steg i Zapier. Send et dokument når det opprettes eller endres, og slett det når det fjernes:

Endringene blir til kort innen omtrent ett minutt; flere endringer på rad behandles samlet.

Synkroniseringer passer for faste eksporter: Du sender alt, eller alt som er endret, og Sursa avstemmer. Resten av denne veiledningen handler om synkroniseringer.

Kjør en full synkronisering

En synkronisering har tre steg: åpne, sende og lukke.

1. Åpne

POST /v1/push/sources/{source_id}/syncs åpner en synkronisering og returnerer nummeret på den:

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 for den første synkroniseringen av kilden og incremental når en synkronisering er fullført. En incremental-synkronisering før noen er fullført, returnerer sources.push_initial_required.
• Bare én synkronisering kan være åpen om gangen: En til returnerer 409 sources.push_sync_open.
• En synkronisering er åpen i max_minutes (60 som standard, opptil 1440). Etter det utløper den: Ingenting arkiveres, og nummeret godtas ikke lenger. Velg en tid med god margin utover det eksporten din tar.

2. Send dokumenter

Send dokumentene i batcher på opptil 500, med nummeret på synkroniseringen. Brødteksten i en batch er på opptil 50 MiB; filer i en batch sendes 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 rekkefølgen 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 gjennomføres hvert dokument i en batch for seg: Ett dårlig dokument stopper ikke de andre.

Dokumenter som ikke er endret siden forrige synkronisering, trenger du ikke sende på nytt. Bekreft dem med ID med POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, opptil 1000 ID-er per forespørsel, slik at den fulle avstemmingen 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. Lukk

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

Lukk med failed hver gang eksporten din stopper halvveis: En complete etter en ufullstendig eksport ville arkivere alle dokumentene du ikke kom til. Gjentar du den samme lukkingen, returneres det samme resultatet.

Etter lukkingen gjør Sursa dokumentene om til kort innen omtrent ett minutt. Kildens side viser hver synkronisering med antallet dokumenter som ble sendt og arkivert, og GET /v1/push/sources/{source_id}/syncs/{sync_number} returnerer de samme tellerne.

Inkrementelle synkroniseringer

Mellom de fulle synkroniseringene sender du bare det som er endret:

1. Åpne med "type": "incremental".
2. Send de endrede dokumentene, og legg ID-ene til de fjernede i deletes (se nedenfor).
3. Lukk med complete_incremental.

Kjør en full synkronisering fra tid til annen, for eksempel ukentlig, for å fange opp det en inkrementell kjøring gikk glipp av.

Slett dokumenter i en batch

En batch kan fjerne dokumenter sammen med dem den skriver. Oppgi ID-ene deres i deletes:

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

Hver slettet ID får sin egen oppføring i results, med result deleted, eller not_found hvis kilden ikke har noe slikt dokument. Det gjør ingen skade å slette den samme ID-en på nytt.

Atomiske batcher

Noen endringer gir bare mening sammen, for eksempel et dokument og dokumentet som erstatter det. Send "atomic": true, så gjennomføres batchen fullstendig eller ikke i det hele tatt: Hvis et dokument ikke består kontrollene, gjennomføres ingenting fra batchen, og svaret er 422 med koden sources.push_batch_rejected og resultatet for hvert dokument i error.details.results: Dokumentene som mislyktes, har error, de andre skipped.

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

Uten atomic gjennomføres en batch dokument for dokument. Bruk atomiske batcher for relaterte endringer og vanlige batcher for masseinnlasting, der ett dårlig dokument ikke skal holde tilbake resten.

Kontroller resultatet for hvert dokument

Svaret på batchen forteller deg hvordan hvert dokument ble skrevet. Selve omgjøringen til kort skjer etterpå, så status kan fortsatt være pending. Slik finner du dokumentene i en synkronisering som ikke ble til kort:

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

Hver oppføring har external_id, title, status, card_id, version og reason, og listen pagineres med cursor. status godtar også pending, processing, indexed og removed.

Du kan også bli varslet i stedet for å spørre: Hendelsene import.sync_completed (en synkronisering er lukket og behandlet, med totalene) og import.document_failed (et dokument ble ikke til et kort, med reason) kommer via webhook og i hendelsesfeeden.

Nye forsøk

• Send en Idempotency-Key med hver POST. En gjentatt batch med samme nøkkel returnerer det første resultatet.
• Selv uten nøkkelen blir et dokument med samme external_id aldri til et kort nummer to: Det er unchanged eller updated.
• Hvis prosessen stopper midt i en synkronisering, åpner du en ny når den gamle har utløpt, eller lukker den gamle med failed hvis du fortsatt har nummeret, og kjører synkroniseringen på nytt.

Grenser

Et dokument over kildens dokumentgrense mislykkes med årsaken limit_reached i en batch; en forespørsel med ett enkelt dokument svarer 409 med koden sources.push_too_many_documents. Hastighetsgrenser gjelder som for alle andre forespørsler; se Hastighetsgrenser og kvoter.

Vanlige feil