Synchronizuj swój system przez własne źródło

Własne źródło łączy system, który nie ma wbudowanego konektora: Twoją wiki, system zgłoszeń, bazę danych, eksport z dowolnego miejsca. Twój kod wysyła dokumenty do Sursy, a Sursa zamienia je w karty w kolekcji i folderach, dla których skonfigurowano źródło, z takim samym wyszukiwaniem, odpowiedziami, weryfikacją i uprawnieniami jak w przypadku kart z każdego innego źródła.

W odróżnieniu od bezpośredniego zapisu kart własne źródło śledzi, co zostało wysłane. Na koniec pełnej synchronizacji Sursa archiwizuje każdy dokument, którego nie wysłano, więc usunięcia w Twoim systemie docierają do Sursy bez dodatkowej pracy.

Skonfiguruj źródło

Administrator tworzy źródło w Sursie w sekcji Sources → New source → Custom source (źródła → nowe źródło → własne źródło) i wybiera:

• kolekcję i opcjonalnie folder dla kart źródła;
• tryb folderów: wszystkie karty w wybranym folderze albo podfoldery odwzorowujące path każdego dokumentu;
• uprawnienia: uprawnienia kolekcji albo „jak w źródle”, gdzie każdy dokument wymienia, kto może go widzieć.

Strona źródła pokazuje jego ID; przykłady używają 42.

Wybierz klucz

Klucz źródła to najbezpieczniejszy wybór dla pojedynczej integracji, zwłaszcza działającej na platformie zewnętrznej. Klucz organizacji z import:write pasuje do usługi, która zasila kilka źródeł.

Oba klucze wysyła się w ten sam sposób, a wszystkie operacje push znajdują się pod /v1/push/sources/{source_id}. Sprawdź klucz i stan źródła za pomocą 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}

Dokument

Zamiast content pojedynczy dokument może zawierać plik do 100 MB w żądaniu multipart/form-data: plik w części file, a powyższe pola jako JSON w części document. Przesyłania w częściach dla upload_id i attachments tworzy się kluczem organizacji, który ma zakres import:write, z przeznaczeniem import_attachment; klucz źródła nie może ich tworzyć.

Dwa sposoby wysyłania

Bezpośrednie aktualizacje pasują do systemów, które informują o każdej zmianie, np. webhook z Twojego systemu pomocy technicznej lub krok w Zapier. Wysyłaj dokument, gdy zostanie utworzony lub zmieniony, i usuwaj go, gdy zniknie z Twojego systemu:

Zmiany stają się kartami w ciągu około minuty; kilka kolejnych zmian jest przetwarzanych razem.

Synchronizacje pasują do regularnych eksportów: wysyłasz wszystko lub wszystko, co się zmieniło, a Sursa uzgadnia stan. Dalsza część przewodnika dotyczy synchronizacji.

Uruchom pełną synchronizację

Synchronizacja ma trzy kroki: otwarcie, wysyłanie, zamknięcie.

1. Otwórz

POST /v1/push/sources/{source_id}/syncs otwiera synchronizację i zwraca jej 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 ma wartość initial przy pierwszej synchronizacji źródła i incremental po zakończeniu którejkolwiek synchronizacji. Synchronizacja incremental przed pierwszą zakończoną zwraca sources.push_initial_required.
• Naraz może być otwarta tylko jedna synchronizacja: druga zwraca 409 sources.push_sync_open.
• Synchronizacja pozostaje otwarta przez max_minutes (domyślnie 60, maksymalnie 1440). Potem wygasa: nic nie jest archiwizowane, a jej numer przestaje być akceptowany. Wybierz czas wyraźnie dłuższy niż czas trwania eksportu.

2. Wyślij dokumenty

Wysyłaj dokumenty w pakietach do 500 z numerem synchronizacji. Treść pakietu może mieć do 50 MiB; pliki w pakiecie przekazuje się jako 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"}}
    ]
  }'

Odpowiedź zawiera wynik dla każdego dokumentu, w kolejności wysłania:

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

Domyślnie każdy dokument pakietu jest stosowany osobno: jeden błędny dokument nie zatrzymuje pozostałych.

Dokumentów, które nie zmieniły się od ostatniej synchronizacji, nie trzeba wysyłać ponownie. Potwierdź je według identyfikatora za pomocą POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, do 1000 identyfikatorów na żądanie, aby pełne uzgadnianie je zachowało:

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

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close kończy synchronizację:

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

Zamykaj z failed zawsze, gdy eksport zatrzyma się w połowie: complete po częściowym eksporcie zarchiwizowałoby każdy dokument, do którego eksport nie dotarł. Powtórzenie tego samego zamknięcia zwraca ten sam wynik.

Po zamknięciu Sursa w ciągu około minuty zamienia dokumenty w karty. Strona źródła pokazuje każdą synchronizację z liczbą wysłanych i zarchiwizowanych dokumentów, a GET /v1/push/sources/{source_id}/syncs/{sync_number} zwraca te same liczniki.

Synchronizacje przyrostowe

Między pełnymi synchronizacjami wysyłaj tylko to, co się zmieniło:

1. Otwórz synchronizację z "type": "incremental".
2. Wyślij zmienione dokumenty, a identyfikatory usuniętych umieść w deletes (poniżej).
3. Zamknij synchronizację z complete_incremental.

Od czasu do czasu, np. co tydzień, uruchamiaj pełną synchronizację, aby wyłapać wszystko, co pominęło uruchomienie przyrostowe.

Usuwaj dokumenty w pakiecie

Pakiet może usuwać dokumenty razem z tymi, które zapisuje. Wymień ich identyfikatory w deletes:

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

Każdy usunięty identyfikator otrzymuje własny wpis w results, z result równym deleted lub not_found, jeśli źródło nie ma takiego dokumentu. Ponowne usunięcie tego samego identyfikatora jest nieszkodliwe.

Pakiety atomowe

Niektóre zmiany mają sens tylko razem, np. dokument i ten, który go zastępuje. Wyślij "atomic": true, a pakiet zostanie zastosowany w całości albo wcale: jeśli którykolwiek dokument nie przejdzie kontroli, nic z pakietu nie zostanie zastosowane, a odpowiedź to 422 z kodem sources.push_batch_rejected i wynikiem każdego dokumentu w error.details.results: dokumenty, które nie przeszły kontroli, mają error, a pozostałe skipped.

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

Bez atomic pakiet jest stosowany dokument po dokumencie. Używaj pakietów atomowych do powiązanych zmian, a zwykłych pakietów do ładowań masowych, w których jeden błędny dokument nie powinien wstrzymywać reszty.

Sprawdź wynik każdego dokumentu

Odpowiedź pakietu informuje, jak każdy dokument został zapisany. Zamiana w kartę następuje później, więc status może jeszcze mieć wartość pending. Aby znaleźć dokumenty synchronizacji, które nie stały się kartami:

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

Każdy wpis ma external_id, title, status, card_id, version i reason, a lista jest stronicowana za pomocą cursor. status przyjmuje też pending, processing, indexed i removed.

Możesz też otrzymywać powiadomienia, zamiast pytać: zdarzenia import.sync_completed (synchronizacja została zamknięta i przetworzona, z jej sumami) i import.document_failed (dokument nie stał się kartą, z jego reason) przychodzą przez webhook i w kanale zdarzeń.

Ponowienia

• Wysyłaj Idempotency-Key z każdym żądaniem POST. Powtórzony pakiet z tym samym kluczem zwraca pierwszy wynik.
• Nawet bez klucza dokument z tym samym external_id nigdy nie stanie się drugą kartą: ma wynik unchanged lub updated.
• Jeśli proces zatrzyma się w trakcie synchronizacji, otwórz nową po wygaśnięciu starej albo zamknij starą z failed, jeśli nadal znasz jej numer, i uruchom synchronizację ponownie.

Limity

Dokument przekraczający limit dokumentów źródła kończy się w pakiecie błędem z przyczyną limit_reached; na żądanie z pojedynczym dokumentem API odpowiada 409 z kodem sources.push_too_many_documents. Limity częstotliwości obowiązują tak samo jak przy każdym innym żądaniu; zob. Limity częstotliwości i przydziały.

Typowe błędy