Μετάβαση στο περιεχόμενο
Sursa Developers

Γρήγορη εκκίνηση

Αυτός ο οδηγός σας πηγαίνει από το μηδέν σε μια λειτουργική ενσωμάτωση σε πέντε λεπτά: δημιουργείτε ένα κλειδί API, το ελέγχετε, προσθέτετε ένα έγγραφο στη βάση γνώσεων, το βρίσκετε και κάνετε μια ερώτηση γι’ αυτό. Κάθε βήμα είναι ένα αίτημα HTTP. Επιλέξτε τη γλώσσα σας μία φορά σε οποιοδήποτε παράδειγμα· όλα τα παραδείγματα της σελίδας αλλάζουν μαζί.

Τα παραδείγματα με επιλογή γλώσσας χρησιμοποιούν τη διεύθυνση του API αυτής της πύλης: https://api.sursa.com στο cloud της Sursa ή τη διεύθυνση του API της δικής σας εγκατάστασης. Όπου ένα παράδειγμα δείχνει https://api.example.com, βάλτε στη θέση της τη διεύθυνση του API σας. Δείτε τον οδηγό Διεύθυνση του API και περιβάλλοντα, αν δεν είστε βέβαιοι ποια έχετε.

1. Δημιουργήστε ένα κλειδί API

Ένας διαχειριστής του οργανισμού δημιουργεί κλειδιά στη Sursa στο Administration → API keys (διαχείριση, κλειδιά API). Δώστε στο κλειδί ένα όνομα που λέει πού χρησιμοποιείται (για παράδειγμα «Συγχρονισμός CRM»), επιλέξτε τον ρόλο του και, αν θέλετε να το περιορίσετε περισσότερο, τις εμβέλειές του. Το κλειδί μπορεί να κάνει ό,τι μπορεί να κάνει ένας χρήστης με αυτόν τον ρόλο, και όχι περισσότερα από όσα επιτρέπουν οι εμβέλειές του. Για αυτόν τον οδηγό αρκεί ο ρόλος editor.

Το κλειδί εμφανίζεται μία φορά. Φυλάξτε το στον χώρο φύλαξης μυστικών του συστήματός σας και περάστε το στον κώδικά σας μέσω μιας μεταβλητής περιβάλλοντος:

export SURSA_API_KEY="kb_…"

Κάθε αίτημα στέλνει το κλειδί στην κεφαλίδα Authorization ως διακριτικό bearer. Ο οδηγός Κλειδιά API και εμβέλειες εξηγεί τους ρόλους, τις εμβέλειες, τη λήξη και την εναλλαγή.

2. Ρυθμίστε έναν πελάτη

Δεν χρειάζεται καμία βιβλιοθήκη: το API είναι απλό HTTPS και JSON. Τα παραδείγματα αυτού του οδηγού χρησιμοποιούν μια μικρή βοηθητική συνάρτηση σε κάθε γλώσσα. Αντιγράψτε αυτήν της γλώσσας σας· οι επόμενοι οδηγοί χρησιμοποιούν την ίδια. Οι επίσημες βιβλιοθήκες πελάτη αναφέρονται στη σελίδα SDK.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. Ελέγξτε το κλειδί

Το GET /v1/me περιγράφει τον πελάτη που καλεί το API: τον οργανισμό, το κλειδί, τον ρόλο και τις εμβέλειές του, καθώς και το όριο ρυθμού που ισχύει γι’ αυτό. Λειτουργεί με οποιοδήποτε έγκυρο κλειδί, γι’ αυτό είναι το καλύτερο πρώτο αίτημα κάθε ενσωμάτωσης.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

Ένα 401 με τον κωδικό auth.not_authenticated σημαίνει ότι το κλειδί λείπει, έχει ανακληθεί ή έχει πληκτρολογηθεί λάθος· το api_keys.expired σημαίνει ότι έχει λήξει.

4. Βρείτε μια συλλογή

Οι κάρτες βρίσκονται σε συλλογές. Το GET /v1/collections επιστρέφει τη λίστα των συλλογών που βλέπει το κλειδί σας:

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

Σημειώστε το id και το name της συλλογής με την οποία θέλετε να δουλέψετε. Τα παρακάτω παραδείγματα χρησιμοποιούν τη συλλογή 3 με όνομα support.

5. Προσθέστε ένα έγγραφο

Το PUT /v1/cards-by-external-id/{external_id} δημιουργεί μια κάρτα με το δικό σας αναγνωριστικό ή την αντικαθιστά, αν η κάρτα υπάρχει ήδη. Η διπλή εκτέλεση του αιτήματος είναι ασφαλής: τη δεύτερη φορά το περιεχόμενο δεν έχει αλλάξει και η απόκριση είναι skipped με αιτία unchanged. Ως external_id χρησιμοποιήστε το αναγνωριστικό της εγγραφής στο σύστημά σας.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

Το αίτημα επιστρέφει όταν η κάρτα είναι έτοιμη να βρεθεί: 201 με "status": "ready" για μια νέα κάρτα, 200 για μια κάρτα που αντικαταστάθηκε. Το HTML και το απλό κείμενο λειτουργούν με τον ίδιο τρόπο, με "content_type": "html" ή "text". Τα αρχεία (PDF, Word, Excel και άλλα) περνούν από το ίδιο τελικό σημείο ως multipart/form-data· ο οδηγός Εισαγωγή εγγράφων καλύπτει τα αρχεία, τους φακέλους, τα μεταδεδομένα και την εισαγωγή πολλών εγγράφων.

Το POST /v1/search βρίσκει τα αποσπάσματα των καρτών που ταιριάζουν με ένα ερώτημα, με το καλύτερο αποτέλεσμα πρώτο:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

Το collection δέχεται το όνομα της συλλογής. Χωρίς αυτό, η αναζήτηση καλύπτει τη συλλογή με όνομα default.

7. Κάντε μια ερώτηση

Το POST /v1/ask απαντά σε μια ερώτηση σε φυσική γλώσσα και επιστρέφει τις πηγές της απάντησης. Ο Βοηθός AI βρίσκει τη γνώση που χρειάζεται και απαντά μόνο από κάρτες που επιτρέπεται να διαβάζει το κλειδί.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

Όταν δεν βρεθεί τίποτα σχετικό, η απόκριση είναι και πάλι 200, με "empty": "no_hits" και μια σύντομη εξήγηση στο answer. Ο κώδικάς σας αποφασίζει τι θα δείξει στον χρήστη σε αυτή την περίπτωση.

Επόμενα βήματα