Synka ditt system med en egen källa

En egen källa ansluter ett system som saknar inbyggd connector: din wiki, ditt ärendehanteringsverktyg, en databas, en export från var som helst. Din kod skickar dokument till Sursa, och Sursa gör om dem till kort i den samling och de mappar som källan är konfigurerad för, med samma sökning, svar, verifiering och behörigheter som kort från vilken annan källa som helst.

Till skillnad från när du skriver kort direkt håller en egen källa reda på vad du har skickat. I slutet av en fullständig synkning arkiverar Sursa varje dokument som du inte skickade, så att borttagningar i ditt system når Sursa utan extra arbete.

Konfigurera källan

En administratör skapar källan i Sursa under Sources → New source → Custom source och väljer:

• samlingen och, om så önskas, en mapp för källans kort;
• mappläget: alla kort i den valda mappen, eller undermappar som speglar varje dokuments path;
• behörigheterna: samlingens behörigheter, eller ”som i källan”, där varje dokument anger vem som får se det.

Källans sida visar dess id; exemplen använder 42.

Välj en nyckel

Källnyckeln är det säkraste valet för en enskild integration, särskilt en som körs på en extern plattform. En organisationsnyckel med import:write passar en tjänst som matar flera källor.

Båda nycklarna skickas på samma sätt, och alla push-slutpunkter ligger under /v1/push/sources/{source_id}. Kontrollera nyckeln och källans tillstånd 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 stället för content kan ett enskilt dokument bära en fil på upp till 100 MB i ett multipart/form-data-anrop: filen i delen file, fälten ovan som JSON i delen document. Uppladdningar i delar för upload_id och attachments skapas med en organisationsnyckel som har omfånget import:write och syftet import_attachment; en källnyckel kan inte skapa dem.

Två sätt att skicka

Direkta uppdateringar passar system som meddelar dig om varje ändring, till exempel en webhook från ditt helpdesksystem eller ett steg i Zapier. Skicka ett dokument när det skapas eller ändras, och ta bort det när det tas bort:

Ändringar blir kort inom ungefär en minut; flera ändringar i rad bearbetas tillsammans.

Synkningar passar regelbundna exporter: du skickar allt, eller allt som har ändrats, och Sursa stämmer av. Resten av den här guiden handlar om synkningar.

Kör en fullständig synkning

En synkning har tre steg: öppna, skicka, stäng.

1. Öppna

POST /v1/push/sources/{source_id}/syncs öppnar en synkning och returnerar dess 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 är initial för källans första synkning och incremental när en synkning har slutförts. En incremental-synkning före den första slutförda returnerar sources.push_initial_required.
• Bara en synkning kan vara öppen åt gången: en andra returnerar 409 sources.push_sync_open.
• En synkning är öppen i max_minutes (60 som standard, upp till 1440). Därefter går den ut: inget arkiveras och dess nummer godtas inte längre. Välj en tid som med god marginal är längre än din export tar.

2. Skicka dokument

Skicka dokumenten i batchar om högst 500, med synkningens nummer. En batchs brödtext är högst 50 MiB; filer i en batch skickas 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 ett resultat för varje dokument, i den ordning som du skickade 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 tillämpas varje dokument i en batch för sig: ett felaktigt dokument stoppar inte de andra.

Dokument som inte har ändrats sedan den senaste synkningen behöver inte skickas igen. Bekräfta dem med id med POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, upp till 1000 id per anrop, så att den fullständiga avstämningen behåller 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. Stäng

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close avslutar synkningen:

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

Stäng med failed så fort din export stannar halvvägs: en complete efter en ofullständig export skulle arkivera varje dokument som du inte hann skicka. Upprepar du samma stängning returneras samma resultat.

Efter stängningen gör Sursa om dokumenten till kort inom ungefär en minut. Källans sida visar varje synkning med antalet skickade och arkiverade dokument, och GET /v1/push/sources/{source_id}/syncs/{sync_number} returnerar samma räknare.

Inkrementella synkningar

Mellan de fullständiga synkningarna skickar du bara det som har ändrats:

1. Öppna med "type": "incremental".
2. Skicka de ändrade dokumenten och lägg id:n för borttagna dokument i deletes (nedan).
3. Stäng med complete_incremental.

Kör en fullständig synkning då och då, till exempel varje vecka, för att fånga upp sådant som en inkrementell körning missade.

Ta bort dokument i en batch

En batch kan ta bort dokument samtidigt som den skriver andra. Lista deras id i deletes:

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

Varje borttaget id får en egen post i results, med result deleted, eller not_found om källan inte har något sådant dokument. Det gör ingen skada att ta bort samma id igen.

Atomiska batchar

Vissa ändringar är bara meningsfulla tillsammans, till exempel ett dokument och det som ersätter det. Skicka "atomic": true, så tillämpas batchen helt eller inte alls: om något dokument inte klarar kontrollerna tillämpas inget i batchen, och svaret är 422 med koden sources.push_batch_rejected och resultatet för varje dokument i error.details.results: de dokument som misslyckades har error, de övriga skipped.

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

Utan atomic tillämpas en batch dokument för dokument. Använd atomiska batchar för relaterade ändringar och vanliga batchar för massinläsningar, där ett felaktigt dokument inte ska hålla tillbaka resten.

Kontrollera resultatet för varje dokument

Batchsvaret talar om hur varje dokument skrevs. Omvandlingen till ett kort sker efteråt, så status kan fortfarande vara pending. Så hittar du de dokument i en synkning som inte blev kort:

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

Varje post har external_id, title, status, card_id, version och reason, och listan delas in i sidor med cursor. status tar också emot pending, processing, indexed och removed.

Du kan också få besked i stället för att fråga: händelserna import.sync_completed (en synkning är stängd och bearbetad, med sina summor) och import.document_failed (ett dokument blev inte ett kort, med sin reason) kommer via webhook och i händelseflödet.

Nya försök

• Skicka en Idempotency-Key med varje POST. En upprepad batch med samma nyckel returnerar det första resultatet.
• Även utan nyckeln blir ett dokument med samma external_id aldrig ett andra kort: det är unchanged eller updated.
• Om processen stannar mitt i en synkning öppnar du en ny när den gamla har gått ut, eller stänger den gamla med failed om du fortfarande har dess nummer, och kör synkningen igen.

Gränser

Ett dokument utöver källans gräns för antalet dokument misslyckas med orsaken limit_reached i en batch; ett anrop med ett enda dokument svarar 409 med koden sources.push_too_many_documents. Hastighetsbegränsningar gäller som för alla andra anrop; se Hastighetsbegränsningar och kvoter.

Vanliga fel