Skava Skava / Wiki

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

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

i

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

Ρύθμιση μιας διεπαφής API

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

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

Ασφαλής αποθήκευση token

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

Δοκιμή: Ping και Test Request

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

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

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

Σχέδιο και Έκδοση

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

!

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

Ασφάλεια

i

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

Πώς το ομάδα χρησιμοποιεί μια εκδοθείσα διεπαφή

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

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

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

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

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

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

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

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

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

Μόλις ανεβάσετε τον κατάλογο των άρθρων σας, ο δημιουργός προσφέρει ένα μπλοκ επιλογής προϊόντος. Δεν υπάρχουν επιλογές συντήρησης: η λίστα είναι ο κατάλογός σας. Το άτομο που παραγγέλλει το αναζητά, βλέπει την εικόνα, το όνομα και τον αριθμό άρθρου, και το 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 με την κεφαλίδα Authorization: Bearer <callback_token>. Τρεις προαιρετικές τιμές ακολουθούν την κάρτα:

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

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

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

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

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

Σχετικά

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

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

Τι είναι ένα διεπαφή API στο Skava;

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

Ποιοι επιτρέπεται να δημιουργούν και να ενεργοποιούν διεπαφές API;

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

Ποια είναι η διαφορά μεταξύ «Ping» και «Δοκιμαστικό Αίτημα»;

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

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

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

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

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

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

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