Skava Skava / Wiki

Προσαρμοσμένα στοιχεία: API

Ένα API interface είναι ένα φόρμα των οποίων οι γεμάτες τιμές στέλνονται από το Skava ως JSON σε διεύθυνση που καθορίζετε εσείς (το backend σας). Έτσι μπορείτε να συνδέσετε το Skava με ασφάλεια με τα δικά σας συστήματα.

i

Διαχειρίζεστε τα API interfaces στην Webapp κάτω από Custom Elements → εναλλαγή API Interfaces. Η δημιουργία και η επεξεργασία είναι προορισμένη για διαχειριστές εταιρείας· τα εκδοθέντα interfaces μπορούν στη συνέχεια να ενεργοποιηθούν από όλα τα μέλη της εταιρείας.

Ρύθμιση ενός API interface

Ένα interface αποτελείται από πεδία εισαγωγής (τα οποία σχηματίζουν το JSON), τη διεύθυνση προορισμού και την πιστοποίηση.

  1. Δημιουργία πεδίων: Κάθε πεδίο λαμβάνει ένα JSON key. Στα δεξιά βλέπετε ζωντανά την προεπισκόπηση JSON, η οποία αποστέλλεται στο backend σας ακριβώς με αυτόν τον τρόπο.
  2. Διεύθυνση (URL): η διεύθυνση https:// του backend σας. Επιτρέπονται μόνο διευθύνσεις HTTPS και δημόσια προσβάσιμες (βλ. Ασφάλεια παρακάτω).
  3. Μέθοδος: POST (προεπιλογή), PUT, PATCH ή GET. Με GET οι τιμές προστίθενται ως παράμετροι ερωτήματος αντί να αποστέλλονται στο σώμα.
  4. Πιστοποίηση: Ορίστε το όνομα του header (π.χ. Authorization) και το πρόθεμα της τιμής (π.χ. Bearer ), στη συνέχεια αποθηκεύστε το token. Προαιρετικά ορίστε ημερομηνία λήξης.
  5. Πεδία απόκρισης (προαιρετικά): Ορίστε μέσω διαδρομής ποιες τιμές από την απόκριση του backend πρέπει να εμφανίζονται: π.χ. order.id ή items[0].sku.
  6. Ελέγξτε με Ping και Test Request, στη συνέχεια Release.
Skava webapp: Καρτέλα Πεδίων μιας διεπαφής API. Στο πάνω μέρος οι αυτόματα συμπεριλαμβανόμενες τιμές περιεχομένου (όνομα χρήστη, εταιρεία, έργο κ.λπ.), κάτω τα προσαρμοσμένα πεδία με κλειδί JSON, δεξιά η προεπισκόπηση φόρμας και η ζωντανή προεπισκόπηση JSON.
Η καρτέλα Πεδία: κάθε πεδίο λαμβάνει ένα κλειδί JSON. Στο πάνω μέρος, τιμές περιεχομένου όπως χρήστης, εταιρεία και όνομα έργου συμπεριλαμβάνονται αυτόματα. Δεξιά βλέπετε τη φόρμα και το ζωντανό JSON: ακριβώς αυτό που στέλνεται στο backend σας.
Skava webapp: Καρτέλα Endpoint μιας διεπαφής API με πεδία για URL, μέθοδο POST, timeout, κεφαλίδα auth, πρόθεμα τιμής Bearer και το πεδίο εισαγωγής για το κρυπτογραφημένο token.
Η καρτέλα Endpoint: διεύθυνση προορισμού (μόνο HTTPS), μέθοδος, timeout, και κεφαλίδα auth μαζί με πρόθεμα τιμής. Το token αποθηκεύεται κρυπτογραφημένο και δεν παραδίδεται ποτέ στους πελάτες.
Web app της Skava: Καρτέλα Προεπισκόπησης ενός διασυνδέσιμου API. Ένα πεδίο απόκρισης με JSON κλειδί Success έχει ρυθμιστεί, στα δεξιά η προεπισκόπηση του πώς θα φαίνεται το αποτέλεσμα στο chat.
Η καρτέλα Προεπισκόπηση (προαιρετική): ορίστε μέσω διαδρομής ποιες τιμές από την απόκριση του backend θα εμφανίζονται. Στα δεξιά η Skava δημιουργεί την κάρτα αποτελέσματος από αυτές, ακριβώς όπως θα εμφανιστεί αργότερα στο chat.

Αποθήκευση token με ασφάλεια

Το token αποθηκεύεται κρυπτογραφημένο και δεν επιστρέφεται ποτέ στους πελάτες: η εφαρμογή δείχνει μόνο αν έχει οριστεί token και πότε λήγει. Κατά την αποστολή, η Skava το προσθέτει server-side στο ρυθμισμένο header. Αν ορίσετε ημερομηνία λήξης, η Skava απορρίπτει την κλήση μετά τη λήξη και σας ζητά να ανανεώσετε το token.

Δοκιμές: Ping και Αίτημα Δοκιμής

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

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

Web app της Skava: Καρτέλα Δοκιμών μιας διεπαφής API με τα κουμπιά Ping και Δοκιμαστικό αίτημα, το αποτέλεσμα Κατάσταση 200 OK, τον χρόνο απόκρισης και την πλήρη απόκριση JSON από το backend.
Η καρτέλα Δοκιμές: Ping και Δοκιμαστικό αίτημα δίπλα δίπλα. Εδώ με κατάσταση 200, χρόνο απόκρισης και την πλήρη απόκριση του backend σε μορφή JSON.

Σχεδίαση και Έκδοση

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

!

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

Ασφάλεια

i

Για να αποφευχθεί η κακή χρήση της διεπαφής, ισχύουν αυστηροί κανόνες: επιτρέπονται μόνο διευθύνσεις HTTPS και η διεύθυνση πρέπει να δείχνει σε δημόσια διεύθυνση προορισμού : οι εσωτερικές διευθύνσεις (π.χ. localhost, ιδιωτικά δίκτυα ή μεταδεδομένα cloud) απορρίπτονται. Το Skava το ελέγχει σε κάθε κλήση, συνδέεται ακριβώς στη διαπιστευμένη διεύθυνση, δεν ακολουθεί ανακατευθύνσεις και περιορίζει το timeout και το μέγεθος της απάντησης.

Πώς χρησιμοποιεί η ομάδα ένα διασυνδεδεμένο στοιχείο

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

  1. Στη συνομιλία, πατήστε Σύν στο κάτω μέρος και πατήστε το στοιχείο που θέλετε, για παράδειγμα Παραγγελία υλικών.
  2. Συμπληρώστε το έντυπο και πατήστε Αποστολή.
  3. Το αποτέλεσμα εμφανίζεται ως κάρτα στη συνομιλία, ορατό σε όλους τους συμμετέχοντες.
Web app της Skava: συμπληρώσιμο φόρμα της ενέργειας API «Παραγγελία υλικών» με τα πεδία αριθμός άρθρου, περιγραφή, ποσότητα, μονάδα, ημερομηνία παράδοσης και σχόλιο, καθώς και η σημείωση για τις τιμές που συμπεριλαμβάνονται αυτόματα.
Βήμα 3: συμπληρώστε τη φόρμα. Η σημείωση στο κάτω μέρος δείχνει ποιες τιμές συμπεριλαμβάνονται αυτόματα.
Web app της Skava: κάρτα αποτελέσματος της ενέργειας API «Παραγγελία υλικών» στη συνομιλία με κατάσταση 200, οι τιμές που εισήχθησαν και η απάντηση του backend (αριθμός παραγγελίας, κατάσταση, ημερομηνία παράδοσης) καθώς και επεκτάσιμα ακατέργαστα δεδομένα.
Βήμα 4: η κάρτα αποτελέσματος στη συνομιλία, με τις εισόδους και την απάντηση του backend σας.

Αφήστε την AI να δημιουργήσει ένα στοιχείο

Ως διαχειριστής εταιρείας, δεν χρειάζεται να χρησιμοποιήσετε τον επεξεργαστή μόνοι σας. Πείτε στο βοηθό Skava στη συνομιλία, για παράδειγμα «δημιούργησέ μου ένα έντυπο παραγγελίας για τον κατάλογο μου με ποσότητα και διεύθυνση παράδοσης». Δημιουργεί από αυτό ένα σχέδιο, μπορεί να αλλάξει πεδία ένα-ένα αργότερα και γνωρίζει τον κατάλογο προϊόντων που ανεβάσατε: για παραγγελίες προτείνει τον επιλογέα προϊόντων αντί για πεδίο κειμένου για τον κωδικό προϊόντος.

Τι μπορεί επίσης να ορίσει: τελικό σημείο και μέθοδο καθώς και το κοινό («μόνο μέλη εταιρείας» ή «και εξωτερικοί στην ίδια συνομιλία»). Για το κοινό ρωτά πρώτα αντί να το ορίσει απλώς, επειδή καθορίζει ποιος μπορεί να εκτελέσει κάτι από έξω.

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

Ποιος μπορεί να το εκτελέσει

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

Προϊόντα από τον δικό σας κατάλογο

Μόλις ανεβάσετε τον κατάλογο προϊόντων σας, ο κατασκευαστής προσφέρει ένα μπλοκ επιλογής προϊόντων. Δεν υπάρχουν επιλογές συντήρησης: η λίστα είναι ο κατάλογός σας. Ο πελάτης που παραγγέλνει αναζητά σε αυτήν, βλέπει την εικόνα, την ονομασία και τον αριθμό προϊόντος, και το backend σας λαμβάνει τον αριθμό προϊόντος. Η Skava απορρίπτει έναν αριθμό που δεν υπάρχει στον κατάλογό σας. Για την ποσότητα, τοποθετήστε ένα κανονικό πεδίο αριθμού δίπλα σε αυτό.

Ορίστε την κάρτα μόνοι σας

Το backend σας αποφασίζει τι αναγράφεται στην κάρτα. Η Skava ελέγχει μόνο τη δομή, το μέγεθος και την ασφάλεια, ποτέ το νόημα: δεν γνωρίζει ούτε τις καταστάσεις παραγγελίας ούτε τα ονόματα πεδίων. Για να το κάνετε αυτό, απαντήστε με ένα αντικείμενο card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

  • Το v πρέπει να είναι ο ακέραιος 1. Χωρίς αυτό, η απάντηση δεν θεωρείται κάρτα και εφαρμόζεται ο χάρτης αποκρίσεων που έχει οριστεί στο στοιχείο.
  • Το state είναι μόνο χρώμα και εικονίδιο: ok, pending, warn ή error. Ό,τι φέρει νόημα μπαίνει στο status_text ως ελεύθερο κείμενο.
  • Το fields είναι μια λίστα με ετικέτες και τιμές, έως 20 εγγραφές. Οι τιμές που είναι πολύ μεγάλες συντομεύονται αντί να απορρίπτονται, ώστε μια παραγγελία να μην αποτυγχάνει λόγω λεπτομέρειας.

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

Αναφορά κατάστασης αργότερα

Όταν το στοιχείο εκτελείται, η Skava στέλνει δύο επιπλέον τιμές: callback_url και callback_token. Αναφέρετε μια νέα κατάσταση εκεί αργότερα και εμφανίζεται μια νέα κάρτα στη συνομιλία, και στο τηλέφωνο, ενώ κάποιος την κοιτάζει. Η προηγούμενη παραμένει, ώστε να φαίνεται ποια κατάσταση αναφέρθηκε. Στείλτε το ίδιο αντικείμενο card όπως παραπάνω, μέσω POST με το header Authorization: Bearer <callback_token>. Τρεις προαιρετικές τιμές μπαίνουν δίπλα στην κάρτα:

  • seq: ο δικός σας μετρητής. Ένα αναφορά με μικρότερη ή ίση τιμή απορρίπτεται, ώστε δύο αναφορές να μην μπορούν να ξεπεράσουν η μία την άλλη.
  • final: κλείνει την αλληλεπίδραση. Το token γίνεται άκυρο και η κάρτα γίνεται οριστική.
  • notify: ορίστε το σε false για να δημοσιεύεται η κάρτα σιωπηλά, χωρίς αριθμό μη αναγνωσμένων και χωρίς ειδοποίηση. Για ενδιάμεσες βήματα που δεν πρέπει να ξυπνήσουν κανέναν. Χωρίς αυτό, η κάρτα είναι ένα απόλυτα κανονικό μήνυμα.

Μια αλληλεπίδραση μπορεί να δημοσιεύσει το πολύ 50 κάρτες. Η ίδια αναφορά δύο φορές δεν παράγει δεύτερη κάρτα.

Το Skava απαντά με 200 και μια λίστα hints αν κάτι συντομεύτηκε ή απορρίφθηκε, και με 422 αν η κάρτα ήταν μη χρήσιμη. Μια αλληλεπίδραση δέχεται αναφορές για 90 ημέρες.

Τα κάρτες δημοσιεύονται από τον συστηματικό αποστολέα της Skava, όχι από το άτομο που εκτέλεσε το στοιχείο και όχι από λογαριασμό της δικής σας εταιρείας. Το ποιο σύστημα γράφει αναφέρεται στον τίτλο της κάρτας.

Ένα πλήρες παράδειγμα προς αντιγραφή βρίσκεται στο αποθετήριο στο example_order_server/ και εκτελείται στο api.skava.io.

Σχετικά

Θέλετε αντίθετα να δημιουργήσετε ένα πρότυπο εγγράφου προς συμπλήρωση; Δείτε Προσαρμοσμένα Στοιχεία: Έγγραφα.

Συχνές Ερωτήσεις

Τι είναι ένα API interface στο Skava;

Ένα φόρμα των οποίων τα γεμισμένα δεδομένα το Skava στέλνει ως JSON σε διεύθυνση που ορίζετε εσείς (το backend σας): χρήσιμο για τη σύνδεση του Skava με τα δικά σας συστήματα.

Ποιος έχει δικαίωμα να δημιουργεί και να εκτελεί API interfaces;

Η δημιουργία και η επεξεργασία είναι προορισμένες για διαχειριστές εταιρείας. Ένα διατεθειμένο interface μπορεί στη συνέχεια να εκτελεστεί από όλα τα μέλη της εταιρείας.

Ποια είναι η διαφορά μεταξύ "Ping" και "Test Request";

Ping ελέγχει μόνο αν η διεύθυνση είναι προσβάσιμη : χωρίς token και χωρίς δεδομένα. Το Test Request στέλνει δεδομένα δοκιμής συμπεριλαμβανομένου του token και εμφανίζει την πλήρη απάντηση.

Είναι ασφαλές το API token μου;

Ναι. Το token αποθηκεύεται κρυπτογραφημένο και δεν παραδίδεται ποτέ σε πελάτες. Η εφαρμογή δείχνει μόνο αν έχει οριστεί token και πότε λήγει.

Ποιες διευθύνσεις επιτρέπονται ως τελικά σημεία;

Μόνο δημόσια προσβάσιμες διευθύνσεις https://. Εσωτερικοί στόχοι όπως localhost, ιδιωτικά δίκτυα ή μεταδεδομένα cloud απορρίπτονται : αυτό προστατεύει κατά της κατάχρησης της διεπαφής.

Γιατί δεν μπορώ πια να αλλάξω μια διεπαφή που έχει εκδοθεί;

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