Συγχρονισμός του συστήματός σας με μια προσαρμοσμένη πηγή

Μια προσαρμοσμένη πηγή συνδέει ένα σύστημα που δεν έχει ενσωματωμένο σύνδεσμο (connector): το wiki σας, το εργαλείο αιτημάτων υποστήριξης, μια βάση δεδομένων, μια εξαγωγή από οπουδήποτε. Ο κώδικάς σας αποστέλλει έγγραφα στη Sursa, και η Sursa τα μετατρέπει σε κάρτες στη συλλογή και στους φακέλους για τους οποίους έχει ρυθμιστεί η πηγή, με την ίδια αναζήτηση, τις ίδιες απαντήσεις, την ίδια επαλήθευση και τα ίδια δικαιώματα όπως οι κάρτες από οποιαδήποτε άλλη πηγή.

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

Ρύθμιση της πηγής

Ένας διαχειριστής δημιουργεί την πηγή στη Sursa στο Sources → New source → Custom source (πηγές, νέα πηγή, προσαρμοσμένη πηγή) και επιλέγει:

• τη συλλογή και, προαιρετικά, έναν φάκελο για τις κάρτες της·
• τη λειτουργία φακέλων: όλες οι κάρτες στον επιλεγμένο φάκελο ή υποφάκελοι που αντιγράφουν τη δομή του path κάθε εγγράφου·
• τα δικαιώματα: τα δικαιώματα της συλλογής ή «όπως στην πηγή», όπου κάθε έγγραφο αναφέρει ποιος μπορεί να το δει.

Η σελίδα της πηγής δείχνει το ID της· τα παραδείγματα χρησιμοποιούν το 42.

Επιλογή κλειδιού

Το κλειδί πηγής είναι η πιο ασφαλής επιλογή για μία ενσωμάτωση, ιδίως για μια ενσωμάτωση που εκτελείται σε πλατφόρμα τρίτων. Ένα κλειδί του οργανισμού με import:write ταιριάζει σε μια υπηρεσία που τροφοδοτεί πολλές πηγές.

Και τα δύο κλειδιά στέλνονται με τον ίδιο τρόπο, και κάθε τελικό σημείο αποστολής βρίσκεται κάτω από το /v1/push/sources/{source_id}. Ελέγξτε το κλειδί και την κατάσταση της πηγής με το 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}

Το έγγραφο

Αντί για content, ένα μεμονωμένο έγγραφο μπορεί να φέρει ένα αρχείο έως 100 MB σε ένα αίτημα multipart/form-data: το αρχείο στο τμήμα file και τα παραπάνω πεδία ως JSON στο τμήμα document. Οι μεταφορτώσεις σε τμήματα για τα upload_id και attachments δημιουργούνται με ένα κλειδί του οργανισμού που έχει την εμβέλεια import:write και με σκοπό import_attachment· ένα κλειδί πηγής δεν μπορεί να τις δημιουργήσει.

Δύο τρόποι αποστολής

Οι άμεσες ενημερώσεις ταιριάζουν σε συστήματα που σας ειδοποιούν για κάθε αλλαγή, όπως ένα webhook από το σύστημα υποστήριξης ή ένα βήμα στο Zapier. Στείλτε ένα έγγραφο όταν δημιουργείται ή αλλάζει και διαγράψτε το όταν αφαιρείται:

Οι αλλαγές γίνονται κάρτες μέσα σε περίπου ένα λεπτό· πολλές διαδοχικές αλλαγές επεξεργάζονται μαζί.

Οι συγχρονισμοί ταιριάζουν σε τακτικές εξαγωγές: στέλνετε τα πάντα ή ό,τι άλλαξε, και η Sursa κάνει τη συμφωνία δεδομένων. Ο υπόλοιπος οδηγός αφορά τους συγχρονισμούς.

Εκτέλεση πλήρους συγχρονισμού

Ένας συγχρονισμός έχει τρία βήματα: άνοιγμα, αποστολή, κλείσιμο.

1. Ανοίξτε τον συγχρονισμό

Το POST /v1/push/sources/{source_id}/syncs ανοίγει έναν συγχρονισμό και επιστρέφει τον αριθμό του:

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 είναι initial για τον πρώτο συγχρονισμό της πηγής και incremental αφού ολοκληρωθεί ένας συγχρονισμός. Ένας συγχρονισμός incremental πριν από οποιονδήποτε ολοκληρωμένο επιστρέφει sources.push_initial_required.
• Μόνο ένας συγχρονισμός μπορεί να είναι ανοιχτός κάθε φορά: ένας δεύτερος επιστρέφει 409 sources.push_sync_open.
• Ένας συγχρονισμός μένει ανοιχτός για max_minutes (60 από προεπιλογή, έως 1440). Μετά λήγει: τίποτα δεν αρχειοθετείται και ο αριθμός του δεν γίνεται πια δεκτός. Επιλέξτε έναν χρόνο αρκετά μεγαλύτερο από όσο διαρκεί η εξαγωγή σας.

2. Αποστείλετε τα έγγραφα

Στείλτε τα έγγραφα σε παρτίδες έως 500, με τον αριθμό του συγχρονισμού. Το σώμα μιας παρτίδας είναι έως 50 MiB· τα αρχεία μέσα σε μια παρτίδα περνούν ως 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"}}
    ]
  }'

Η απόκριση έχει ένα αποτέλεσμα για κάθε έγγραφο, με τη σειρά που τα στείλατε:

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

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

Τα έγγραφα που δεν άλλαξαν από τον τελευταίο συγχρονισμό δεν χρειάζεται να σταλούν ξανά. Επιβεβαιώστε τα με βάση το αναγνωριστικό με το POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, έως 1000 αναγνωριστικά ανά αίτημα, ώστε η πλήρης συμφωνία να τα διατηρήσει:

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. Κλείστε τον συγχρονισμό

Το POST /v1/push/sources/{source_id}/syncs/{sync_number}/close ολοκληρώνει τον συγχρονισμό:

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

Κλείνετε με failed κάθε φορά που η εξαγωγή σας σταματά στη μέση: ένα complete μετά από μερική εξαγωγή θα αρχειοθετούσε κάθε έγγραφο που δεν προλάβατε να στείλετε. Η επανάληψη του ίδιου κλεισίματος επιστρέφει το ίδιο αποτέλεσμα.

Μετά το κλείσιμο, η Sursa μετατρέπει τα έγγραφα σε κάρτες μέσα σε περίπου ένα λεπτό. Η σελίδα της πηγής δείχνει κάθε συγχρονισμό με τον αριθμό των εγγράφων που στάλθηκαν και αρχειοθετήθηκαν, και το GET /v1/push/sources/{source_id}/syncs/{sync_number} επιστρέφει τους ίδιους μετρητές.

Επαυξητικοί συγχρονισμοί

Ανάμεσα στους πλήρεις συγχρονισμούς, στέλνετε μόνο ό,τι άλλαξε:

1. Ανοίξτε με "type": "incremental".
2. Στείλτε τα έγγραφα που άλλαξαν και βάλτε τα αναγνωριστικά όσων αφαιρέθηκαν στο deletes (παρακάτω).
3. Κλείστε με complete_incremental.

Εκτελείτε κατά διαστήματα έναν πλήρη συγχρονισμό, για παράδειγμα κάθε εβδομάδα, για να πιάσετε ό,τι ξέφυγε από μια επαυξητική εκτέλεση.

Διαγραφή εγγράφων σε παρτίδα

Μια παρτίδα μπορεί να αφαιρεί έγγραφα μαζί με εκείνα που γράφει. Απαριθμήστε τα αναγνωριστικά τους στο deletes:

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

Κάθε αναγνωριστικό που διαγράφεται παίρνει τη δική του καταχώριση στο results, με result ίσο με deleted ή not_found, αν η πηγή δεν έχει τέτοιο έγγραφο. Η εκ νέου διαγραφή του ίδιου αναγνωριστικού δεν βλάπτει.

Ατομικές παρτίδες

Ορισμένες αλλαγές έχουν νόημα μόνο μαζί, για παράδειγμα ένα έγγραφο και εκείνο που το αντικαθιστά. Στείλτε "atomic": true, και η παρτίδα εφαρμόζεται ολόκληρη ή καθόλου: αν οποιοδήποτε έγγραφο αποτύχει στους ελέγχους, δεν εφαρμόζεται τίποτα από την παρτίδα, και η απόκριση είναι 422 με τον κωδικό sources.push_batch_rejected και το αποτέλεσμα κάθε εγγράφου στο error.details.results: τα έγγραφα που απέτυχαν έχουν error, τα υπόλοιπα skipped.

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

Χωρίς atomic, μια παρτίδα εφαρμόζεται έγγραφο προς έγγραφο. Χρησιμοποιείτε ατομικές παρτίδες για αλληλένδετες αλλαγές και κανονικές παρτίδες για μαζικές φορτώσεις, όπου ένα προβληματικό έγγραφο δεν πρέπει να καθυστερεί τα υπόλοιπα.

Έλεγχος του αποτελέσματος κάθε εγγράφου

Η απόκριση της παρτίδας σας λέει πώς γράφτηκε κάθε έγγραφο. Η μετατροπή του σε κάρτα γίνεται αργότερα, οπότε το status μπορεί να είναι ακόμη pending. Για να βρείτε τα έγγραφα ενός συγχρονισμού που δεν έγιναν κάρτες:

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

Κάθε καταχώριση έχει external_id, title, status, card_id, version και reason, και η λίστα σελιδοποιείται με cursor. Το status δέχεται επίσης pending, processing, indexed και removed.

Μπορείτε επίσης να λαμβάνετε ειδοποιήσεις αντί να ρωτάτε: τα συμβάντα import.sync_completed (ένας συγχρονισμός έκλεισε και επεξεργάστηκε, με τα σύνολά του) και import.document_failed (ένα έγγραφο δεν έγινε κάρτα, με το reason του) φτάνουν μέσω webhook και στην τροφοδοσία συμβάντων.

Επαναλήψεις

• Στέλνετε ένα Idempotency-Key με κάθε POST. Μια επαναλαμβανόμενη παρτίδα με το ίδιο κλειδί επιστρέφει το πρώτο αποτέλεσμα.
• Ακόμη και χωρίς το κλειδί, ένα έγγραφο με το ίδιο external_id δεν γίνεται ποτέ δεύτερη κάρτα: είναι unchanged ή updated.
• Αν η διεργασία σταματήσει στη μέση ενός συγχρονισμού, ανοίξτε νέο αφού λήξει ο παλιός ή κλείστε τον παλιό με failed, αν έχετε ακόμη τον αριθμό του, και εκτελέστε ξανά τον συγχρονισμό.

Όρια

Ένα έγγραφο πάνω από το όριο εγγράφων της πηγής αποτυγχάνει σε μια παρτίδα με αιτία limit_reached· ένα αίτημα με ένα μόνο έγγραφο απαντά 409 με τον κωδικό sources.push_too_many_documents. Τα όρια ρυθμού ισχύουν όπως σε κάθε άλλο αίτημα· δείτε τον οδηγό Όρια ρυθμού και ποσοστώσεις.

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