Εισαγωγή εγγράφων

Αυτός ο οδηγός δείχνει πώς βάζετε τα έγγραφά σας στη Sursa με το API καρτών: λίγα έγγραφα από ένα σενάριο ή όλα τα έγγραφα ενός συστήματος μέσω μιας τακτικής εργασίας. Κάθε έγγραφο γίνεται μια κάρτα σε μια συλλογή. Οι άνθρωποι τη βρίσκουν στην αναζήτηση, ο Βοηθός AI απαντά με βάση αυτήν, και έχει υπεύθυνο, ετικέτες, επαλήθευση και δικαιώματα όπως κάθε άλλη κάρτα.

Χρειάζεστε ένα κλειδί API με την εμβέλεια cards:write και έναν ρόλο που μπορεί να γράφει στη συλλογή-στόχο (editor ή admin). Τα παραδείγματα χρησιμοποιούν τη βοηθητική συνάρτηση από τη Γρήγορη εκκίνηση.

Επιλογή του σωστού τελικού σημείου

Για ό,τι εισάγετε περισσότερες από μία φορές, χρησιμοποιήστε το external_id. Κάνει κάθε εισαγωγή επαναλήψιμη: μια νέα εκτέλεση ενημερώνει τις κάρτες που δημιούργησε, αντί να προσθέτει αντίγραφα.

Δημιουργία ή αντικατάσταση κάρτας με το δικό σας αναγνωριστικό

Το PUT /v1/cards-by-external-id/{external_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, e-mail (.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 από προεπιλογή). Για μεγαλύτερα αρχεία ή για αναξιόπιστα δίκτυα, μεταφορτώστε πρώτα το αρχείο σε τμήματα.

Αντικατάσταση του περιεχομένου μιας κάρτας

Όταν έχετε ήδη το ID μιας κάρτας στη 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. Επαναλάβετε σε λίγα δευτερόλεπτα.
• Μια κάρτα που προέρχεται από μια πηγή, όπως έναν σύνδεσμο (connector) ή μια προσαρμοσμένη πηγή, αλλάζει μόνο στην πηγή της: 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}.

Συνήθη σφάλματα