SoftOne API στο OpenCart

Εισαγωγή στις Προσαρμοσμένες Κλήσεις API

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

Η λειτουργία αυτή σας δίνει μεγάλη ευελιξία για να αυτοματοποιήσετε ροές εργασίας και να ενσωματώσετε το OpenCart και το SoftOne με άλλα συστήματα, αντλώντας δεδομένα μέσω API.

Βασικές Απαιτήσεις

Για να λειτουργήσει μια προσαρμοσμένη κλήση API μέσω της γέφυρας, πρέπει να πληρούνται οι παρακάτω προϋποθέσεις:

• Μέθοδος HTTP: Για λήψη δεδομένων υποστηρίζεται μόνο η μέθοδος GET.
• Μορφή Απάντησης (Response): Το API στο οποίο κάνετε την κλήση πρέπει να επιστρέφει την απάντησή του σε μορφή JSON. Η γέφυρα αναλύει αυτή την απάντηση για να μπορέσετε να αντιστοιχίσετε τα πεδία.
• Στοιχεία API: Πρέπει να γνωρίζετε το URL του API endpoint και τυχόν απαιτούμενα
• JSON Template (για Αντιστοίχιση): Θα χρειαστεί να ορίσετε ένα JSON template που αντικατοπτρίζει τη δομή της αναμενόμενης απάντησης από το API. Αυτό χρησιμοποιείται από τη γέφυρα για να κατανοήσει τα πεδία που θα είναι διαθέσιμα για αντιστοίχιση μετά την εκτέλεση της κλήσης.

Διαδικασία Ρύθμισης

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

1. Μεταβείτε στην Ενότητα: Εντοπίστε την ενότητα διαχείρισης των προσαρμοσμένων κλήσεων API στη γέφυρα.
2. Δημιουργία Νέας Κλήσης: Ξεκινήστε τη δημιουργία μιας νέας κλήσης.
3. Ορισμός Παραμέτρων Κλήσης:
   • Ενέργεια: Επιλέξτε την ενέργεια. Προς το παρόν, διαθέσιμη είναι μόνο η "Λήψη" (Fetch).
   • Τύπος: Επιλέξτε τον τύπο δεδομένων που αφορά η κλήση. Οι διαθέσιμες επιλογές καθορίζουν πώς θα χρησιμοποιηθούν τα δεδομένα που θα ληφθούν (π.χ., "Προϊόντα-> Εισαγωγή / Ενημέρωση", "Προϊόντα->Ενημέρωση Αποθέματος", "Προϊόντα->Ενημέρωση Τιμής", "Προϊόντα->Επιλογές").
   • Καθαρισμός δεδομένων πριν το συγχρονισμό:
     • Επιλεγμένο (Checked): Πριν την εισαγωγή/ενημέρωση των νέων δεδομένων που λαμβάνονται από το API, τα υπάρχοντα σχετικά δεδομένα στον επιλεγμένο 'Τύπο' θα διαγραφούν (π.χ., αν ο τύπος είναι "Ενημέρωση Αποθέματος", τα τρέχοντα δεδομένα αποθέματος που διαχειρίζεται η γέφυρα θα καθαριστούν πριν περαστούν τα νέα).
     • Μη επιλεγμένο (Unchecked): Τα νέα δεδομένα από το API θα ενημερώσουν/αντικαταστήσουν τα υπάρχοντα χωρίς προηγούμενη διαγραφή.
   • URL API: Εισάγετε το πλήρες URL του API endpoint από το οποίο θα γίνει η λήψη δεδομένων (μέθοδος GET).
   • JSON Template (Δομή Απάντησης): Εισάγετε ένα δείγμα JSON που αντιστοιχεί στη δομή της απάντησης που περιμένετε να λάβετε από το API. Αυτό είναι απαραίτητο για το βήμα της αντιστοίχισης πεδίων. Δεν στέλνεται στο API, χρησιμοποιείται μόνο εσωτερικά από τη γέφυρα.
4. Αποθήκευση: Αποθηκεύστε τις ρυθμίσεις της κλήσης.

Παράδειγμα Ρύθμισης (Γενικό)

Ας υποθέσουμε ότι θέλετε να ρυθμίσετε μια κλήση για να λαμβάνετε περιοδικά τις τιμές των προϊόντων από ένα εξωτερικό API.

• Ενέργεια: Λήψη
• Τύπος: Προϊόντα->Ενημέρωση Τιμής
• Καθαρισμός δεδομένων: (Ανάλογα με τις ανάγκες σας)
• URL API: https://api.externalprovider.com/products/prices?format=json (Παράδειγμα URL)
• JSON Template (Δομή Απάντησης):

  {
    "products": [
    {
        "sku": "EXAMPLE-SKU-1",
        "price": 120.50,
        "currency": "EUR"
      },
      {
        "sku": "EXAMPLE-SKU-2",
        "price": 85.00,
        "currency": "EUR"
      }
      // ... more products
    ],
    "last_update": "2024-01-15T12:00:00Z"
  }

  (Αυτό το JSON δείχνει στη γέφυρα ότι η απάντηση θα περιέχει μια λίστα 'products', όπου κάθε προϊόν έχει 'sku', 'price', και 'currency'.)

Έλεγχος Κλήσης ("Έλεγχος Κλήσης")

Αφού αποθηκεύσετε τις ρυθμίσεις, το επόμενο κρίσιμο βήμα είναι ο έλεγχος της κλήσης. Η επιλογή "Έλεγχος Κλήσης" (Test Call) εκτελεί τα εξής:

• Στέλνει ένα GET αίτημα στο καθορισμένο URL API.
• Ο κύριος σκοπός αυτού του ελέγχου είναι να επιβεβαιώσει ότι:
  • Το URL είναι σωστό και προσβάσιμο.
  • Το API απαντά με επιτυχία (π.χ., HTTP status 200 OK) και επιστρέφει μια απάντηση σε μορφή JSON.

Η γέφυρα θα σας δείξει την απάντηση του API. Αν δείτε "success": true (ή μια έγκυρη JSON απάντηση σύμφωνα με το API), αυτό σημαίνει ότι η βασική επικοινωνία λειτουργεί. Αν λάβετε σφάλμα (π.χ., 401 Unauthorized, 404 Not Found, 500 Internal Server Error), τότε υπάρχει πρόβλημα στις ρυθμίσεις σας (URL, αυθεντικοποίηση) ή στο ίδιο το API endpoint.

Εκτέλεση Κλήσης ("Εκτέλεση Κλήσης")

Μόλις ο "Έλεγχος Κλήσης" είναι επιτυχής, το επόμενο βήμα είναι η "Εκτέλεση Κλήσης" (Execute Call). Αυτή η ενέργεια είναι απαραίτητη για να μπορέσετε να κάνετε την αντιστοίχιση πεδίων.

• Πατώντας "Εκτέλεση Κλήσης", η γέφυρα εκτελεί την κλήση GET μία φορά στον browser σας προς το URL API που ορίσατε.
• Η JSON απάντηση που επιστρέφει το API από αυτή τη συγκεκριμένη κλήση αποθηκεύεται προσωρινά από τη γέφυρα.

Ο σκοπός της "Εκτέλεσης Κλήσης" είναι να ληφθεί ένα πραγματικό δείγμα της απάντησης JSON από το API, ώστε η γέφυρα να μπορεί να συγκρίνει τη ληφθείσα δομή με το JSON template που δώσατε και να σας παρουσιάσει τα διαθέσιμα πεδία για αντιστοίχιση.

Αντιστοίχιση Πεδίων

Αφού έχετε εκτελέσει επιτυχώς την κλήση ("Εκτέλεση Κλήσης") και η γέφυρα έχει λάβει ένα δείγμα της JSON απάντησης, ενεργοποιείται η δυνατότητα "Αντιστοίχιση Πεδίων" (Field Mapping).

Σε αυτή την οθόνη:

• Η γέφυρα θα σας δείξει τα πεδία που εντόπισε στην JSON απάντηση του API, βασιζόμενη και στο JSON template που παρείχατε.
• Θα μπορείτε να αντιστοιχίσετε αυτά τα πεδία από την απάντηση του API με συγκεκριμένα πεδία στο OpenCart, ανάλογα με τον "Τύπο" κλήσης που επιλέξατε (π.χ., αντιστοίχιση του πεδίου 'price' από το API με το πεδίο τιμής του προϊόντος στο OpenCart, αν ο τύπος είναι "Ενημέρωση Τιμής").

Για παράδειγμα, αν η απάντηση του API για τις τιμές ήταν όπως στο παραπάνω παράδειγμα, στην αντιστοίχιση πεδίων θα μπορούσατε να πείτε:

• Το πεδίο products[].sku της απάντησης αντιστοιχεί στο πεδίο 'Μοντέλο' (ή 'SKU') του προϊόντος στο OpenCart.
• Το πεδίο products[].price της απάντησης αντιστοιχεί στο πεδίο 'Τιμή' του προϊόντος στο OpenCart.

Η ακριβής λειτουργία της αντιστοίχισης εξαρτάται από τον "Τύπο" της κλήσης που έχετε επιλέξει.

Συμβουλές

• Τεκμηρίωση API: Πάντα να συμβουλεύεστε την τεκμηρίωση του API που θέλετε να καλέσετε για τα σωστά endpoints και τη δομή της JSON απάντησης.
• Αυθεντικοποίηση: Δώστε ιδιαίτερη προσοχή στα στοιχεία λογαριασμού σας που κάνουν login και authenticate στην SoftOne. Είναι η πιο συχνή αιτία αποτυχίας του "Ελέγχου Κλήσης".
• JSON Template Απάντησης: Βεβαιωθείτε ότι το JSON template που παρέχετε αντικατοπτρίζει σωστά τη δομή της απάντησης που περιμένετε από το API. Λάθη εδώ μπορεί να οδηγήσουν σε προβλήματα στην αντιστοίχιση πεδίων.
• Δοκιμές: Κάντε εκτενείς δοκιμές, ειδικά αν η κλήση ενημερώνει κρίσιμα δεδομένα (τιμές, απόθεμα), για να βεβαιωθείτε ότι λειτουργεί όπως αναμένεται.
• Error Handling: Σκεφτείτε πώς θα χειριστείτε πιθανά σφάλματα από το API. Η γέφυρα μπορεί να καταγράφει τα logs των κλήσεων.

Χρειάζεστε Υποστήριξη;

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