Увоз докумената

Овај водич показује како да своје документе унесете у платформу Sursa помоћу API интерфејса за картице: неколико докумената из скрипте или све документе неког система кроз редован посао. Сваки документ постаје картица у колекцији. Људи је проналазе у претрази, асистент одговара на основу ње, а она има власника, ознаке, проверу и дозволе као и свака друга картица.

Потребан вам је API кључ са опсегом cards:write и улогом која може да уписује у циљну колекцију (editor или admin). Примери користе помоћну функцију из водича Брзи почетак.

Избор праве операције

За све што увозите више пута користите external_id. Тако је сваки увоз поновљив: поновно покретање ажурира картице које је креирао уместо да додаје копије.

Креирање или замена картице по вашем идентификатору

PUT /v1/cards-by-external-id/{external_id} прима ID записа у вашем систему. Ако ниједна картица нема овај external_id, операција креира нову (201). Ако га нека картица има, замењује садржај и детаље те картице (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"}
  }'

Шта се дешава при понављању:

• Садржај се није променио: не прави се нова верзија. Одговор је 200 са "status": "skipped" и "reason": "unchanged". Понављање захтева је увек безбедно, чак и без Idempotency-Key.
• Садржај се променио: картица добија нову верзију и поново се индексира. Њен наслов, ознаке, власник, категорија и metadata добијају вредности које сте послали; metadata се замењује у целини.
• Колекција и фолдер примењују се само када се картица креира. Да бисте касније преместили картицу, измените је помоћу PATCH /v1/cards/{card_id}.

Нова верзија уклања проверу картице, као и свака измена садржаја: верификатор је поново потврђује.

Формати текста

Са чекањем на картицу или без њега

Подразумевано се захтев враћа када је картица спремна да буде пронађена, са "status": "ready" и картицом у card. То траје од делића секунде за кратак текст до минут или више за дугачак фајл.

За масовни увоз пошаљите "async": true. Одговор стиже одмах, са "status": "queued" и послом индексирања у job (са његовим job_id). Проверите посао помоћу GET /v1/jobs/{job_id} или пратите све послове у GET /v1/jobs/stream. Посао се завршава са status done, error или canceled.

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

Отпремање фајла

Фајлови се шаљу у захтеву multipart/form-data, у пољу file. Sursa чита PDF, Word, Excel, PowerPoint, OpenDocument табеле, CSV, Markdown, HTML, AsciiDoc, имејл (.eml), обичан текст и уобичајене формате слика. Проверава да ли се име фајла, пријављени тип и садржај слажу, а неслагање одбија са 415.

Да бисте креирали или заменили картицу са фајлом по сопственом идентификатору, пошаљите фајл на исту операцију 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"}'

У обрасцу је tags стринг са вредностима раздвојеним зарезима, а metadata JSON објекат записан као стринг. Нова картица без title добија име фајла као наслов.

Да бисте фајл додали једном, без сопственог идентификатора, користите POST /v1/cards са истим обрасцем и Idempotency-Key. Отпремање фајла који колекција већ има враћа "status": "skipped" са "duplicate": true и card_id постојеће картице, осим ако проследите external_id.

Величину једног фајла ограничава инсталација (подразумевано 200 MB). За веће фајлове или за непоуздане мреже прво отпремите фајл у деловима.

Замена садржаја картице

Када већ имате идентификатор картице у платформи Sursa, PUT /v1/cards/{card_id}/content замењује њен текст или фајл и задржава све остало: власника, ознаке, верификаторе, интервал провере и ручно постављену категорију.

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

• Исти садржај поново враћа "status": "skipped" са "reason": "unchanged".
• Картица која се управо индексира враћа 409 са кодом cards.indexing_in_progress. Покушајте поново за неколико секунди.
• Картица која потиче из извора, на пример из конектора или сопственог извора, мења се само у свом извору: cards.managed_by_source.
• Кључ мора да има право да види целу картицу; делимично видљива картица враћа cards.content_whole_access.

Увоз много докумената

Петља кроз ваше записе са PUT /v1/cards-by-external-id/… је најједноставнији масовни увоз, а безбедно је можете зауставити и поново покренути у било ком тренутку. Да би увоз био брз и у складу са ограничењем учесталости:

1. Пошаљите "async": true, како би се сваки захтев вратио чим картица уђе у ред.
2. Покрените неколико захтева паралелно (од 4 до 8) и успорите када заглавље RateLimit покаже да је преостало мало захтева. Погледајте Ограничења учесталости и квоте.
3. На 429 сачекајте Retry-After; на мрежну грешку или 5xx поновите исти захтев. Понављања не праве штету.
4. Забележите external_id сваког записа који се заврши грешком и на крају поново покушајте са тим записима.

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;
}

За ZIP архиву фајлова POST /v1/cards/archive једним захтевом претвара сваки подржани фајл у њој у картицу. Одмах одговара планом (који фајлови постају картице, а који се прескачу и зашто) и послом; GET /v1/archives/{job_id} извештава о резултату.

Проналажење и уклањање увезених картица

• Прочитајте картицу по свом идентификатору помоћу GET /v1/cards-by-external-id/{external_id}.
• Наведите картице једног увоза помоћу филтера метаподатака: GET /v1/cards?metadata[source]=helpdesk. Погледајте Метаподаци.
• Обришите картицу помоћу DELETE /v1/cards/{card_id}.

Честе грешке