Version History

Description

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

Το παρόν έγγραφο αποτελεί  την τεκμηρίωση του iQom WebService για τελικούς χρήστες, προγραμματιστές και επαγγελματίες IT. Περιέχει αναλυτική περιγραφή για το iQom WebService API και παραδείγματα κώδικα.

Συνοδεύεται απο κλήσεις – παραδείγματα και συμπεριλαμβάνει τις οδηγίες για την παραμετροποίησης που απαιτείται.

iQom Web Service Core Guide

Entity Model

Το Entity Model είναι ένα πρότυπο που αναπαριστά την δομή των δεδομένων ως οντότητες και σχέσεις μέσα απο το οποίο υλοποιούνται όλες οι λειτουργίες που είναι διαθέσιμες. Περιγράφει την εκάστοτε οντότητα όπως αυτή έχει οριστεί μέσα στο RetailStudio και με βάση αυτή τη περιγραφή υλοποιούνται οι ενέργειες της επιλογής, διαγραφής, ενημέρωσης και της εισαγωγής. Για κάθε οντότητα που θέλουμε να αποκτήσουμε πρόσβαση από το iQom WebService θα πρέπει να ορίσουμε το αντίστοιχο φίλτρο WebServiceAccess σε true. Το φίλτρο βρίσκετε στον ορισμό οντοτήτων του RetailStudio.

Actions Available Through Entity Model

Entity Filter

Με την χρήση του φίλτρου Web Service Access μπορείτε να επιλέξετε ποιές οντότητες μπορούν να χρησιμοποιηθούν απο το iQom WebService. Το φίλτρο μορεί να ενεργοποιηθεί / απενεργοποιηθεί οποιδήποτε στιγμή και είναι διαθέσιμο στον ορισμό οντοτήτων του RetailStudio.

Document Model

Το Document Model είναι ένα πρότυπο που αναπαριστά την δομή ενός παραστατικού μέσα από το οποίο υλοποιούνται όλες οι λειτουργίες που είναι διαθέσιμες. Περιγράφει το εκάστοτε παραστατικό όπως αυτό έχει οριστεί μέσα στο RetailStudio και με βάση αυτή τη περιγραφή υλοποιούνται οι ενέργειες της εισαγωγής, του υπολογισμού και του επαναϋπολογισμού.

Actions Available Through Document Model

Extra Tools

Το εργαλείο ExecuteSQL επιτρέπει να εκτελούνται Microsoft Transact-SQL εντολές μέσα από το iQom WebService  για περισσότερη ευελιξία και ολοκληρωμένη διαχείριση. Για κάθε valid εκτέλεση Transact-SQL εντολής επιστρέφετε ο αριθμός εγγραφών που επηρεάστηκε από την εντολή.

iQom Web Service Request

SelectEntity

Λειτουργία που επιλέγει τα δεδομένα που υπάρχουν σε μία οντότητα με την δυνατότητα χρήσης φίλτρων. Δίνοντας το όνομα της οντότητας και ορίζοντας τα φίλτρα επιλογής εφόσον χρειάζονται επιλέγουμε τα δεδομένα από την οντότητα. Τα δεδομένα μπορεί να προέρχονται από Table(s), View(s) ή Stored Procedure. Σε ελληνική εγκατάσταση του RetailStudio για Κωδικό Γλώσσας ορίζουμε GR ενώ για αγγλική EN.

Φίλτρα

Για την επιλογή δεδομένων από Table(s) ή View(s) τα φίλτρα είναι λογικές εκφράσεις όπως: AND, OR, IN, NOT IN κτλ

Για Stored Procedure οι παράμετροι εκτέλεσης μέσα σε ” (Single Quotes) αν πρόκειται για αλφαριθμητικό τύπο δεδομένων και ημερομηνία ή χωρίς ” (Single Quotes) αν πρόκειται για αριθμό και bit.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format.

Entity (Table ή View)

Entity (Stored Procedure)

InsertEntity

Λειτουργία που υλοποιεί την αποθήκευση δεδομένων σε μία οντότητα. Δίνοντας το όνομα της οντότητας και ορίζοντας τα πεδία μαζί με τις τιμές τους το iQom WebService θα ελέγξει αν όλα τα υποχρεωτικά πεδία έχουν συμπληρωθεί και εφόσον είναι αποδεκτές οι τιμές τους θα προχωρήσει στην αποθήκευση των δεδομένων.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε εισαγωγή στην οντότητα με όνομα Item.

UpdateEntity

Λειτουργία που υλοποιεί την ενημέρωση δεδομένων σε μία οντότητα. Δίνοντας το όνομα της οντότητας και ορίζοντας τα πεδία μαζί με τις τιμές τους το iQom WebService θα ελέγξει αν όλα τα υποχρεωτικά πεδία έχουν συμπληρωθεί και εφόσον είναι αποδεκτές οι τιμές τους θα προχωρήσει στην ενημέρωση των δεδομένων.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε ενημέρωση στην οντότητα με όνομα ADBranch.

DeleteEntity

Λειτουργία που υλοποιεί την διαγραφή δεδομένων σε μία οντότητα. Δίνοντας το όνομα της οντότητας και ορίζοντας τα πεδία μαζί με τις τιμές τους το iQom WebService θα ελέγξει αν όλα τα υποχρεωτικά πεδία έχουν συμπληρωθεί και εφόσον είναι αποδεκτές οι τιμές τους θα προχωρήσει στην διαγραφή των δεδομένων.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε διαγραφή στην οντότητα με όνομα Item.

ExecuteSQL

Το εργαλείο ExecuteSQL επιτρέπει να εκτελούνται Microsoft Transact-SQL εντολές μέσα από το iQom WebService  για περισσότερη ευελιξία και ολοκληρωμένη διαχείριση. Για κάθε valid εκτέλεση Transact-SQL εντολής επιστρέφετε ο αριθμός εγγραφών που επηρεάστηκε από την εντολή.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε διαγραφή στην οντότητα με όνομα Item.

GetEntity

Λειτουργία που επιστρέφει ένα JSON αντικείμενο με πληροφορίες για όλα τα πεδία της οντότητας που ζητήθηκε.

Parameters

iQom Web Service Request Sample

Ακολουθεί παράδειγμα το οποίο υλοποιεί requests με JSON και ζητά απο την οντότητα Item να προβάλει τα πεδία της.

ValidateDocument

Λειτουργία που θα λαμβάνει το εκάστοτε καλάθι του πελάτη και βάση κριτηρίων που έχουν οριστεί στο RetailStudio θα υπολογίζει αν ο πελάτης με τις επιλογές που έχει κάνει θα δεχθεί πιθανά δώρα ή/και εκπτώσεις.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format.

PostDocument

Με την λειτουργία PostDocument υλοποιούνται οι ενέργειες της εισαγωγής και του επαναϋπολογισμού ενός παραστατικού. Επιλέγοντας τον κατάλληλο συνδυασμό από τις διαθέσιμες επιλογές μπορεί να επιτευχθούν οι παρακάτω ενέργειες:

• έλεγχος εγκυρότητας  και αποθήκευση παραστατικού
• έλεγχος εγκυρότητας χωρίς αποθήκευση παραστατικού
• επαναϋπολογισμός αξιών χωρίς αποθήκευση παραστατικού

Parameters

Header Data

Παραστατικά – Επικεφαλίδες.

Parameters

HeaderExtension Data

Παραστατικά – Πληροφορίες Επικεφαλίδων.

Parameters

Correlation Data

Παραστατικά – Σχέσεις μεταξύ Παραστατικών.

Parameters

Detail Data

Παραστατικά – Γραμμές.

Parameters

DetailExtension Data

Παραστατικά – Πληροφορίες Γραμμών.

Parameters

DetailDim Data

Παραστατικά – Γραμμές με Διαστάσεις.

Parameters

Payment Data

Παραστατικά – Πληρωμές.

Parameters

PaymentDetail Data

Παραστατικά – Λεπτομέρεις Πληρωμών.

Parameters

DetailPromotions Data

Παραστατικά – Γραμμές Εκπτώσεων.

Parameters

iQom Web Service Request Sample

Ακολουθούν παραδείγματα τα οποία υλοποιούν requests με JSON και XML format.

iQom Web Service Response

SelectEntity

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

* Στο πεδίο Rows μπορεί να περιέχονται απο 0 έως Ν γραμμες. Πρόκειτε για μία λίστα με όλα τα δεδομένα που επιστρέφει η οντότητα.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format.

Entity (Table ή View)

Entity (Stored Procedure)

InsertEntity

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε εισαγωγή στην οντότητα με όνομα Item.

UpdateEntity

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε ενημέρωση στην οντότητα με όνομα Item.

DeleteEntity

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε διαγραφή στην οντότητα με όνομα Item.

ExecuteSQL

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format. Ενδεικτικά στο παράδειγμα γίνετε διαγραφή στην οντότητα με όνομα Item και στο response ενημερωνόμαστε για το πόσες έγραφες έχουν επηρεαστεί από την εκτέλεση της εντολής.

GetEntity

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

iQom Web Service Response Sample

Ακολουθεί παράδειγμα response με JSON που είχε ζητήσει απο την οντότητα ADCompany να προβάλει τα πεδία της.

ValidateDocument

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

* Στο πεδίο DiscountList μπορεί να περιέχονται απο 0 έως Ν εκπτώσεις παραστατικού. Πρόκειτε για μία λίστα με όλες τις εκπτώσεις που θα προκύπτουν.

* Στο τμήμα ScenarioBarcodes μπορεί να περιέχονται απο 0 έως Ν Barcode Ενεργειών.  Πρόκειτε για μια λίστα με τα Barcode Ενεργειών όπως αυτή έχει έρθει από το request και για κάθε barcode φέρει την πληροφορία αν είναι valid ή όχι.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format.

PostDocument

Επεξήγηση για την μορφή και τα πεδία που επιστρέφονται από το response του iQom WebService.

iQom Web Service Response Sample

Ακολουθούν παραδείγματα response σε JSON και XML format.

Data Validation

Entity Model

Σε περίπτωση που η οντότητα δεν υπάρχει ή δεν επιτρέπεται η χρήση της απο το iQom Web Service με βάση την παραμετροποίηση τότε στο response θα υπάρχουν τα αντίστοιχα μηνύματα λάθους.

Status Codes

Extra Tools

Για κάθε περίπτωση μη εκτέλεσης της Transact-SQL εντολής στο response θα υπάρχουν τα αντίστοιχα μηνύματα λάθους.

Status Codes

Document Model

ValidateDocument Status Codes

Σε περίπτωση που υπάρχουν εσφαλμένες ή ελλειπής πληροφορίες στην κλήση του web service  τότε αυτό απαντάει για κάθε γραμμή του καλαθιού με την ανάλογη περιγραφή του λάθους στο πεδίο StatusMessage. Αν όλα τα δεδομένα είναι σωστά τότε το πεδίο θα περιέχει το λεκτικό ΟΚ.

Σε περίπτωση που είναι ενεργοποιημένη η παράμετρος αυτόματης πώλησης σε κάποιες προωθητικες ενέργειες τότε στο καλάθι  θα περιέχονται επιπλέον είδη λόγο αυτών των ενεργειών. Σε αυτα τα είδη στο SatusMessage θα υπάρχει το λεκτικό AutoSale που θα υποδηλώνει ότι αυτό το detail είναι αποτέλεσμα αυτόματης πώλησης.

PostDocument Status Codes

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

Default Values

Οι προκαθορισμένες τιμές που θα παίρνουν τα πεδία σε περίπτωση που δεν υπάρχει πληροφορία ανάλογα με τον τύπο των δεδομένων.

Default Values JSON

Default Values XML

Αν για κάποιο πεδίο δεν υπάρχει κάτι για να επιστραφεί τότε το κενό tag με το όνομα του πεδίου επιστρέφεται σαν απάντηση. Πχ .

Αν το τμήμα ScenarioBarcodes δεν έχει να επιστρέψει τίποτα δεν θα περιλαμβάνετε στην απάντηση.

Web Service Endpoints

Ανάλογα με την κλήση που θα γίνετε στο iQom Web Service θα ακολουθείτε ο κανόνας επιλογής: Protocol://url:port/RetailWebService.asmx/SelectedSufix.

Παραδείγματος χάριν η κλήση στο endpoint για την επιλογή δεδομένων απο μία οντότητα σε JSON και XML θα ήταν αντίστοιχα η παρακάτω:

• http://url:port/RetailWebService.asmx/SelectEntityJSON
• http://url:port/RetailWebService.asmx/SelectEntityXML