Zapier, Make και n8n

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

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

Αποστολή εγγραφών ως κάρτες

Δημιουργήστε μια προσαρμοσμένη πηγή στη Sursa (Sources → New source → Custom source) και μετά ένα κλειδί γι’ αυτήν στη σελίδα της πηγής, στην ενότητα API keys. Το κλειδί ξεκινά με kbsrc_ και μπορεί μόνο να γράφει έγγραφα σε αυτή την πηγή, γι’ αυτό είναι το σωστό κλειδί για να αποθηκευτεί σε μια πλατφόρμα τρίτων.

Η συνηθισμένη ρύθμιση είναι «όταν μια εγγραφή δημιουργείται ή ενημερώνεται στο X, στείλ’ τη στη Sursa»:

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

• Αντιστοιχίστε στο external_id ένα σταθερό αναγνωριστικό της εγγραφής, ποτέ μια ώρα ή έναν αριθμό εκτέλεσης. Τότε, αν στείλετε ξανά την ίδια εγγραφή, ενημερώνεται η ίδια κάρτα, και ένα βήμα που επαναλαμβάνεται δεν βλάπτει: η απόκριση είναι unchanged.
• Για ένα έναυσμα «η εγγραφή διαγράφηκε», προσθέστε μια δεύτερη ροή εργασιών με μέθοδο DELETE και URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Δοκιμάστε τη σύνδεση με GET https://api.example.com/v1/push/sources/42 και την ίδια κεφαλίδα Authorization. Επιστρέφει το όνομα της πηγής και τον αριθμό των εγγράφων της.

Τα πεδία του εγγράφου είναι τα ίδια όπως στον κώδικα.

Zapier

Χρησιμοποιήστε το Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: απενεργοποιημένο. Data: το παραπάνω JSON, με πεδία που εισάγονται από το έναυσμα.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Χρησιμοποιήστε τη μονάδα HTTP → Make a request:

• Method POST, URL όπως παραπάνω, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: το παραπάνω JSON με αντιστοιχισμένες τιμές.
• Ενεργοποιήστε το Parse response, για να χρησιμοποιήσετε το result (created, updated, unchanged) σε επόμενες μονάδες.
• Για να στείλετε ένα αρχείο, επιλέξτε Body type Multipart/form-data με ένα πεδίο file (το αρχείο από μια προηγούμενη μονάδα) και ένα πεδίο κειμένου document που περιέχει τα πεδία JSON χωρίς το content.

n8n

Χρησιμοποιήστε τον κόμβο HTTP Request:

• Method POST, URL όπως παραπάνω.
• Authentication Generic Credential Type → Header Auth, με όνομα Authorization και τιμή Bearer kbsrc_….
• Send Body ενεργοποιημένο, Body Content Type JSON, πεδία αντιστοιχισμένα με εκφράσεις όπως {{ $json.id }}.

Για μια προγραμματισμένη πλήρη εξαγωγή, συνδέστε διαδοχικά τρεις κόμβους HTTP Request: ανοίξτε έναν συγχρονισμό (POST …/syncs με {"type": "initial"} την πρώτη φορά και {"type": "incremental"} στη συνέχεια), αποστείλετε τα στοιχεία και κλείστε τον συγχρονισμό με {"status": "complete"}. Το n8n εκτελεί έναν κόμβο μία φορά ανά στοιχείο· για να στέλνετε λιγότερα αιτήματα, ομαδοποιήστε τα στοιχεία με έναν κόμβο Aggregate και στείλτε τα στο …/documents/batch ως {"sync_number": …, "documents": [...]}.

Ερώτηση μέσα σε μια ροή εργασιών

Μια ροή εργασιών μπορεί να ρωτήσει τη Sursa και να χρησιμοποιήσει την απάντηση: να συντάξει ένα προσχέδιο απάντησης σε ένα αίτημα υποστήριξης, να εμπλουτίσει μια εγγραφή στο CRM, να δημοσιεύσει μια απάντηση σε ένα κανάλι συνομιλίας. Χρησιμοποιήστε ένα κλειδί API του οργανισμού με την εμβέλεια ask και έναν ρόλο που βλέπει τις σωστές συλλογές.

Η απόκριση έχει την απάντηση στο answer (Markdown) και τις πηγές της στο sources, την καθεμία με doc_name. Όταν η βάση γνώσεων δεν έχει τίποτα για την ερώτηση, ορίζεται το empty (για παράδειγμα no_hits): προσθέστε ένα βήμα φίλτρου, ώστε η ροή εργασιών να μη δημοσιεύει κενή απάντηση. Δείτε τον οδηγό Δημιουργία bot ερωτήσεων και απαντήσεων.

Οι απαντήσεις μπορεί να χρειαστούν αρκετά δευτερόλεπτα. Αν το βήμα HTTP της πλατφόρμας έχει μικρό προεπιλεγμένο χρονικό όριο, αυξήστε το σε τουλάχιστον 60 δευτερόλεπτα.

Εκκίνηση ροής εργασιών από συμβάν της Sursa

Κάθε πλατφόρμα μπορεί να λαμβάνει webhooks:

1. Δημιουργήστε το έναυσμα και αντιγράψτε τη διεύθυνση HTTPS που σας δίνει.
2. Στη Sursa, καταχωρίστε ένα webhook με αυτή τη διεύθυνση και τα συμβάντα που θέλετε, στο Administration → Integrations → Webhooks and API ή με το POST /v1/webhooks.
3. Στείλτε ένα δοκιμαστικό συμβάν από τη σελίδα του webhook και αντιστοιχίστε τα πεδία του συμβάντος (type, data.card.title, …) στα επόμενα βήματα.

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

• Στο n8n, προσθέστε έναν κόμβο Code μετά τον κόμβο Webhook με τον κώδικα επαλήθευσης υπογραφής για Node.js από τον οδηγό Λήψη webhooks και ενεργοποιήστε την επιλογή ακατέργαστου σώματος του κόμβου Webhook, ώστε να είναι διαθέσιμα τα ακριβή byte.
• Στο Zapier και στο Make, όπου η πρόσβαση στο ακατέργαστο σώμα είναι δυσκολότερη, τουλάχιστον κρατήστε τη διεύθυνση μυστική, φιλτράρετε με βάση το type και διαβάστε ξανά το αντικείμενο από το API πριν ενεργήσετε.

Οι επαναλήψεις και τα διπλότυπα ισχύουν για τις πλατφόρμες όπως για κάθε παραλήπτη: φιλτράρετε με βάση το id του συμβάντος, αν μια διπλή εκτέλεση θα ήταν επιβλαβής.

Συμβουλές

• Σε 429, αφήστε την αυτόματη επανάληψη της πλατφόρμας να περιμένει όσα δευτερόλεπτα λέει το Retry-After. Προτιμάτε παρτίδες για μεγάλες εξαγωγές.
• Οι πλατφόρμες καταγράφουν κάθε αίτημα και κάθε απόκριση. Μη βάζετε ποτέ ένα κλειδί μέσα σε URL και προτιμάτε το κλειδί kbsrc_ όπου η ροή εργασιών μόνο γράφει έγγραφα.
• Αν ένα βήμα αποτυγχάνει με 401 sources.push_key_invalid, ελέγξτε ότι το ID της πηγής στη διεύθυνση URL αντιστοιχεί στο κλειδί.