Uvoz dokumenata

Ovaj vodič pokazuje kako svoje dokumente unijeti u Sursu pomoću API-ja kartica: nekoliko dokumenata iz skripte ili sve dokumente nekog sustava putem redovitog posla. Svaki dokument postaje kartica u zbirci. Ljudi je pronalaze pretraživanjem, asistent odgovara na temelju nje, a ima vlasnika, oznake, provjeru i dopuštenja kao i svaka druga kartica.

Potreban vam je API ključ s opsegom cards:write i ulogom koja može pisati u ciljnu zbirku (editor ili admin). Primjeri koriste pomoćnu funkciju iz vodiča Brzi početak.

Odabir prave operacije

Za sve što uvozite više puta koristite external_id. On svaki uvoz čini ponovljivim: ponovno pokretanje ažurira kartice koje je stvorio umjesto da dodaje kopije.

Stvaranje ili zamjena kartice prema vašem ID-u

PUT /v1/cards-by-external-id/{external_id} prima ID zapisa u vašem sustavu. Ako nijedna kartica nema taj external_id, stvara novu (201). Ako ga neka kartica ima, zamjenjuje sadržaj i pojedinosti kartice (200).

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/kb-article-1042 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "folder_id": "0f8e2d7c-4b6a-4e1f-9c3d-2a5b8e7f1c40",
    "title": "Returning a damaged item",
    "content_type": "html",
    "body": "<h2>Damaged items</h2><p>Send a photo within 7 days and we ship a replacement.</p>",
    "tags": ["returns", "shipping"],
    "metadata": {"source": "helpdesk", "article_id": "1042"}
  }'

Što se događa pri ponavljanju:

• Sadržaj se nije promijenio: ne stvara se nova verzija. Odgovor je 200 s "status": "skipped" i "reason": "unchanged". Ponavljanje zahtjeva uvijek je sigurno, čak i bez Idempotency-Key.
• Sadržaj se promijenio: kartica dobiva novu verziju i ponovno se indeksira. Njezin naslov, oznake, vlasnik, kategorija i metadata preuzimaju vrijednosti koje ste poslali; metadata se zamjenjuje u cjelini.
• Zbirka i mapa primjenjuju se samo pri stvaranju kartice. Da biste karticu kasnije premjestili, promijenite je pomoću PATCH /v1/cards/{card_id}.

Nova verzija uklanja provjeru kartice, kao i svaka promjena sadržaja: provjeravatelj je ponovno potvrđuje.

Formati teksta

Čekati karticu ili ne

Zadano zahtjev vraća odgovor kad je kartica spremna za pronalaženje, s "status": "ready" i karticom u card. To traje od djelića sekunde za kratak tekst do minute ili više za dugu datoteku.

Za skupne uvoze pošaljite "async": true. Odgovor stiže odmah, s "status": "queued" i poslom indeksiranja u job (s njegovim job_id). Posao provjerite pomoću GET /v1/jobs/{job_id} ili pratite sve poslove u GET /v1/jobs/stream. Posao završava sa status done, error ili canceled.

curl https://api.sursa.com/v1/jobs/48213 \
  -H "Authorization: Bearer $SURSA_API_KEY"

Učitavanje datoteke

Datoteke idu u zahtjevu multipart/form-data, u polju file. Sursa čita PDF, Word, Excel, PowerPoint, proračunske tablice OpenDocument, CSV, Markdown, HTML, AsciiDoc, e-poštu (.eml), običan tekst i uobičajene formate slika. Provjerava podudaraju li se ime datoteke, prijavljena vrsta i sadržaj, a nepodudaranje odbija s 415.

Da biste stvorili ili zamijenili karticu s datotekom prema vlastitom ID-u, pošaljite datoteku na isti PUT /v1/cards-by-external-id/{external_id}:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/handbook-2026 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -F "file=@employee-handbook.pdf" \
  -F "collection_id=3" \
  -F "tags=hr,policies" \
  -F 'metadata={"owner_team":"people"}'

U obrascu je tags niz znakova odvojenih zarezima, a metadata JSON objekt zapisan kao niz znakova. Nova kartica bez title dobiva ime datoteke kao naslov.

Da biste datoteku dodali jednom, bez vlastitog ID-a, koristite POST /v1/cards s istim obrascem i Idempotency-Key. Učitavanje datoteke koju zbirka već ima vraća "status": "skipped" uz "duplicate": true i postojeći card_id, osim ako proslijedite external_id.

Veličinu jedne datoteke ograničava instalacija (zadano 200 MB). Veće datoteke, ili datoteke na nepouzdanim mrežama, najprije učitajte u dijelovima.

Zamjena sadržaja kartice

Kad već imate ID kartice u Sursi, PUT /v1/cards/{card_id}/content zamjenjuje njezin tekst ili datoteku i zadržava sve ostalo: vlasnika, oznake, provjeravatelje, interval provjere i ručno postavljenu kategoriju.

curl -X PUT https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60/content \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "markdown", "body": "# Refund policy\n\nRefunds are processed within 10 days."}'

• Ponovno isti sadržaj vraća "status": "skipped" uz "reason": "unchanged".
• Kartica koja se upravo indeksira vraća 409 s kodom cards.indexing_in_progress. Pokušajte ponovno za nekoliko sekundi.
• Kartica koja potječe iz izvora, kao što je konektor ili vlastiti izvor, mijenja se samo u svojem izvoru: cards.managed_by_source.
• Ključ mora smjeti vidjeti cijelu karticu; djelomično vidljiva kartica vraća cards.content_whole_access.

Uvoz velikog broja dokumenata

Petlja po vašim zapisima s PUT /v1/cards-by-external-id/… najjednostavniji je skupni uvoz, a sigurno ju je zaustaviti i ponovno pokrenuti u bilo kojem trenutku. Da bi bila brza i poštovala ograničenje učestalosti:

1. Pošaljite "async": true, kako bi svaki zahtjev vratio odgovor čim kartica uđe u red čekanja.
2. Pokrenite nekoliko zahtjeva paralelno (od 4 do 8) i usporite kad zaglavlje RateLimit pokaže da je preostalo malo zahtjeva. V. Ograničenja učestalosti i kvote.
3. Pri 429 pričekajte koliko navodi Retry-After; pri mrežnoj pogrešci ili 5xx ponovite isti zahtjev. Ponavljanja su bezopasna.
4. Zabilježite external_id svakog zapisa koji završi pogreškom i na kraju ponovno pokušajte s njima.

import { api } from "./sursa.mjs";

async function importAll(records, concurrency = 6) {
  const failed = [];
  const queue = [...records];
  async function worker() {
    for (let record = queue.shift(); record; record = queue.shift()) {
      try {
        await api("PUT", `/v1/cards-by-external-id/${encodeURIComponent(record.id)}`, {
          collection_id: 3,
          title: record.title,
          content_type: "html",
          body: record.html,
          metadata: { source: "helpdesk" },
          async: true,
        });
      } catch (error) {
        failed.push({ id: record.id, error: String(error) });
      }
    }
  }
  await Promise.all(Array.from({ length: concurrency }, worker));
  return failed;
}

Za ZIP arhivu datoteka POST /v1/cards/archive jednim zahtjevom pretvara svaku podržanu datoteku u njoj u karticu. Odmah odgovara planom (koje datoteke postaju kartice, a koje se preskaču i zašto) i poslom; GET /v1/archives/{job_id} izvješćuje o rezultatu.

Pronalaženje i uklanjanje uvezenih kartica

• Karticu prema vašem ID-u pročitajte pomoću GET /v1/cards-by-external-id/{external_id}.
• Kartice jednog uvoza popišite filtrom metapodataka: GET /v1/cards?metadata[source]=helpdesk. V. Metapodaci.
• Karticu izbrišite pomoću DELETE /v1/cards/{card_id}.

Česte pogreške