# Διασύνδεση με SoftOne ## Σύνδεση Για να συνδεθείτε με το SoftOne περιβάλλον σας, χρειάζεται να συμπληρώσετε τα παρακάτω πεδία στην φόρμα **Connection settings** για να γίνει η κλήση στο `login` service. ### URL (string, απαραίτητο) Το URL του SoftOne περιβάλλοντος. Π.χ. `https://example.oncloud.gr/s1services`. ### Username (string, απαραίτητο) Το όνομα χρήστη για την σύνδεση στο SoftOne περιβάλλον. ### Password (string, απαραίτητο) Ο κωδικός πρόσβασης για την σύνδεση στο SoftOne περιβάλλον. ### Web Service ID (AppId) (integer, απαραίτητο) Το Web Service ID (AppId) που έχει οριστεί στο SoftOne περιβάλλον για την διασύνδεση. Π.χ. `2001`. Σε περίπτωση που γνωρίζετε τον χρήστη, μπορείτε να συμπληρώσετε τα στοιχεία του στα παρακάτω πεδία. ### Company (integer, απαραίτητο) Ο κωδικός της εταιρείας στην οποία ανήκει ο χρήστης. Π.χ. `1000`. ### Branch (integer, απαραίτητο) Ο κωδικός του υποκαταστήματος στην οποία ανήκει ο χρήστης. Π.χ. `1000`. ### Module (integer, απαραίτητο) Ο κωδικός του module στο οποίο ανήκει ο χρήστης. Π.χ. `0`. ### Ref ID (integer, απαραίτητο) Το Ref ID του χρήστη. Π.χ. `1`. ### Παράδειγμα κλήσης login - URL: `https://example.oncloud.gr/s1services` - Username: `demo` - Password: `secret` - Web Service ID: `2001` #### REQUEST ```json { "service": "login", "username": "demo", "password": "secret", "appId": 2001 } ``` #### RESPONSE ```json { "success": true, "clientID": "Wj8T3tvs...tlrT8", "objs": [ { "COMPANY": "1000", "COMPANYNAME": "Demo Company SA", "BRANCH": "1000", "BRANCHNAME": "Athens", "MODULE": "0", "MODULENAME": "Center", "REFID": "1", "REFNAME": "Administrator" } ] } ``` ### Παράδειγμα κλήσης login με στοιχεία χρήστη - Company: `1000` - Branch: `1000` - Module: `0` - Ref ID: `1` #### REQUEST ```json { "service": "login", "username": "demo", "password": "secret", "appId": 2001, "company": 1000, "branch": 1000, "module": 0, "refid": 1 } ``` #### RESPONSE ```json { "success": true, "clientID": "Wj8T3tvs...tlrT8" } ``` ## Εισαγωγές δεδομένων Απαιτούνται 3 κλήσεις: μία για τα προϊόντα, μία για τις τιμές και μία για τα αποθέματα. Τα δεδομένα που χρειάζονται για την εισαγωγή περιγράφονται στις αντίστοιχες ενότητες για το Magento και το WooCommerce. Η εισαγωγή δεδομένων μπορεί να γίνει με browser, με custom endpoint ή με SQL data. Συνήθως επιλέγεται η χρήση των endpoints διότι υπάρχει μεγαλύτερη ευελιξία στα δεδομένα που μπορούμε να έχουμε στη διάθεσή μας. Σε κάθε περίπτωση μας ενδιαφέρει να λαμβάνουμε από το ERP τα differentials. Για να γίνει η λήψη των differentials, το Sébastien στέλνει με την κλήση την τελευταία ημερομηνία συγχρονισμού που έγινε επιτυχώς. Το SoftOne θα πρέπει να επιστρέφει μόνο τα δεδομένα που έχουν ενημερωθεί μετά από αυτή την ημερομηνία. Σε περίπτωση που δε σταλεί πεδίο με ημερομηνία, τότε θα πρέπει να επιστραφούν όλα τα δεδομένα. ### Εισαγωγή από browser ### Browser name (string, απαραίτητο) Το όνομα του browser που αποστέλλεται στην παράμετρο `list` στο service `getBrowserInfo`. Π.χ. `getProducts`. ### Filter parameter (string, προαιρετικό) Το όνομα του πεδίου από τον πίνακα `ITEM` που αποστέλλεται στην παράμετρο `filters`. Π.χ. `ITEM.WEBVIEW`. ### Filter value (string, προαιρετικό) Η τιμή που αποστέλλεται στην παραπάνω παράμετρο φίλτρου. Π.χ. `1`. ### Παράδειγμα κλήσης getBrowserInfo - Browser name: `getProducts` - Filter parameter: `ITEM.WEBVIEW` - Filter value: `1` #### REQUEST ```json { "service": "getBrowserInfo", "clientID": "Wj8T3tvs...tlrT8", "appId": 2001, "object": "ITEM", "list": "getProducts", "filters": "ITEM.WEBVIEW=1" } ``` #### RESPONSE ```json { "success": true, "upddate": "20251001 00:00:00", "formDesign": "ITEM", "reqID": "A1A000000A0AA0A0A", "totalcount": 1000, "fields": [ { "name": "ZOOMINFO", "type": "string" }, { "name": "ITEM.CODE", "type": "string" }, { "name": "ITEM.NAME", "type": "string" } ], "columns": [ { "dataIndex": "ITEM.CODE", "header": "Κωδικός s1", "width": 180, "decs": 0, "hidden": false, "sortable": true }, { "dataIndex": "ITEM.NAME", "header": "Περιγραφή", "width": 420, "decs": 0, "hidden": false, "sortable": true }, ] } ``` ### Παράδειγμα κλήσης getBrowserData #### REQUEST ```json { "service": "getBrowserData", "clientID": "Wj8T3tvs...tlrT8", "appId": 2001, "reqID": "A1A000000A0AA0A0A", "start": 0, "limit": 1000 } ``` #### RESPONSE ```json { "success": true, "totalcount": 1000, "rows": [ [ "ITEM;0001", "001-001-0001", "Όνομα προϊόντος" ] ] } ``` ### Εισαγωγή από custom endpoint Το request method είναι `GET` και τα δεδομένα φιλτράρονται με παραμέτρους query string. Το response πρέπει να είναι σε μορφή JSON και πρέπει να έχει ένα πεδίο `data` που να περιέχει έναν πίνακα με τα δεδομένα. ### Endpoint URL (string, απαραίτητο) Το URL του custom endpoint που θα φέρει τα δεδομένα. Π.χ. `https://example.oncloud.gr/s1services/js/getPrices`. ### Date parameter (string, προαιρετικό) Το όνομα του πεδίου που θα χρησιμοποιηθεί για φιλτράρισμα των δεδομένων με βάση την ημερομηνία. Π.χ. `from`. ### Date format (string, προαιρετικό) Η μορφή ημερομηνίας ISO 8601 που θα χρησιμοποιηθεί για φιλτράρισμα των δεδομένων με βάση την ημερομηνία. Π.χ. `YYYY-MM-DD hh:mm:ss`. ### Page name (string, προαιρετικό) Το όνομα του πεδίου που θα χρησιμοποιηθεί για να οριστεί ο αριθμός σελίδας. Η αρχική σελίδα είναι 1. Π.χ. `page`. ### Per Page name (string, προαιρετικό) Το όνομα του πεδίου που θα χρησιμοποιηθεί για να οριστεί ο αριθμός αποτελεσμάτων ανά σελίδα. Π.χ. `per_page`. ### Per Page number (integer, προαιρετικό) Ο αριθμός των αποτελεσμάτων ανά σελίδα. Π.χ. `1000`. ### Παράδειγμα κλήσης custom endpoint - Endpoint URL: `https://example.oncloud.gr/s1services/js/getPrices` - Date parameter: `from` - Date format: `YYYY-MM-DD hh:mm:ss` - Page name: `page` - Per Page name: `per_page` - Per Page number: `1000` #### REQUEST GET `https://example.oncloud.gr/s1services/js/getPrices?from=2025-01-01%2000:00:00&page=1&per_page=1000` #### RESPONSE ```json { "success": true, "data": [ { "ITEM": "1001", "Price": 29.99 }, { "ITEM": "1002", "Price": 19.99 } ], } ``` ### Εισαγωγή από SqlData ### SQL name (string, απαραίτητο) Το όνομα του SQL data που αποστέλλεται στην παράμετρο `SqlName` στο service `SqlData`. ### Date parameter (string, προαιρετικό) Το όνομα της παραμέτρου που θα χρησιμοποιηθεί για να φιλτράρει τα δεδομένα με βάση την ημερομηνία. Π.χ. `date`. ### Date format (string, προαιρετικό) Η μορφή ISO 8601 της ημερομηνίας που θα χρησιμοποιηθεί για να φιλτράρει τα δεδομένα με βάση την ημερομηνία. Π.χ. `YYYY-MM-DD hh:mm:ss`. ### Query parameters (string, προαιρετικό) Πρόσθετες παράμετροι σε μορφή query string μπορούν να χρησιμοποιηθούν για να φιλτράρουν τα δεδομένα. Αυτές οι παράμετροι προστίθενται απευθείας στο JSON payload. Π.χ. οι παράμετροι `eshop=1&status=active` στέλνονται ως `{"eshop": "1", "status": "active"}`. ### Παράδειγμα κλήσης SqlData - SQL name: `getStocks` - Date parameter: `date` - Date format: `YYYY-MM-DD hh:mm:ss` - Query parameters: `eshop=1&status=active` #### REQUEST ```json { "service": "SqlData", "clientID": "Wj8T3tvs...tlrT8", "appId": "2001", "SqlName": "getStocks", "eshop": "1", "status": "active", "date": "2025-01-01 00:00:00", "ROWCNT": 2000, "OFFSET": 0 } ``` #### RESPONSE ```json { "success": true, "totalcount": 1000, "rows": [ { "ITEM": "1001", "QTY": 50 }, { "ITEM": "1002", "QTY": 20 } ] } ``` ## Εισαγωγές παραγγελιών Η διαδικασία εισαγωγής παραγγελίας στο SoftOne περιγράφεται στα παρακάτω βήματα: 1. `SqlData` για αναζήτηση παραγγελίας, προαιρετικά. 2. `getBrowserInfo` με object `CUSTOMER` και φίλτρα αναζήτησης πελάτη - Αν δεν υπάρχει πελάτης: αναζήτηση με τα επόμενα φίλτρα ή `setData` με object `CUSTOMER`, και table `CUSTOMER`, `CUSBRANCH`, `CUSEXTRA` - Αν υπάρχουν παραπάνω από ένας πελάτες: αναζήτηση με τα επόμενα φίλτρα ή σφάλμα - Αν υπάρχει ακριβώς ένας πελάτης: `getBrowserData` με object `CUSTOMER` - Αν δεν υπάρχει διεύθυνση: `getData` με object `CUSTOMER` και το κλειδί του πελάτη - Αν δεν υπάρχει branch: `setData` με object `CUSTOMER`, και table `CUSBRANCH` 3. `setData` με object `SALDOC`, και table `SALDOC`, `ITELINES`, `MTRDOC`, `EXPANAL` ### Έλεγχος υπάρχουσας παραγγελίας Για την αποφυγή αποστολής πολλαπλών παραγγελιών, υπάρχει δυνατότητα να γίνεται έλεγχος στο SoftOne μέσω SqlData για υπάρχουσα παραγγελία. Αυτή η κλήση γίνεται με μία παράμετρο η οποία έχει ένα μοναδικό αναγνωριστικό της παραγγελίας. Στο διαχειριστικό του Sébastien στην καρτέλα **Integrations > Softone > Order Settings**, στην ενότητα **Check if order exists** συμπληρώστε τα παρακάτω πεδία: ### SQL script name (string, απαραίτητο) Το όνομα του SQL data που θα χρησιμοποιηθεί για την αναζήτηση της παραγγελίας στο SoftOne. Π.χ. `findOrder`. ### SQL parameter name (string, απαραίτητο) Το όνομα της παραμέτρου που θα χρησιμοποιηθεί για να φιλτράρει τις παραγγελίες Π.χ. `orderNumber`. ### SQL parameter value (string, απαραίτητο) Το πεδίο της παραγγελίας που θα σταλεί στην παραπάνω παράμετρο. Π.χ. `Order > Increment ID`. ### SQL row field (string, απαραίτητο) Το όνομα του πεδίου στο object της πρώτης γραμμής των αποτελεσμάτων που καθορίζει αν η παραγγελία υπάρχει ή όχι. Π.χ. `orderFound`. ### Κλήση SqlData για έλεγχο μοναδικής παραγγελίας - SQL script name: `findOrder` - SQL parameter name: `orderNumber` - SQL parameter value: `Order > Increment ID` - SQL row field: `orderFound` #### REQUEST ```json { "service": "SqlData", "clientID": "Wj8T3tvs...tlrT8", "appId": "2001", "SqlName": "findOrder", "orderNumber": "00001234" } ``` #### RESPONSE ```json { "success": true, "totalcount": 1, "rows": [ { "orderFound": true } ] } ``` Στο διαχειριστικό του Sébastien στις καρτέλες **CUSTOMER**, **CUSBRANCH**, **CUSEXTRA**, **SALDOC**, **ITELINES**, **MTRDOC**, **EXPANAL** υπάρχει η δυνατότητα να γίνει αντιστοίχιση των δεδομένων της παραγγελίας του e-shop με τα πεδία των πινάκων του SoftOne. #### Σημαντικό Για να γίνει η αντιστοίχιση των πεδίων θα πρέπει να σταλούν οδηγίες από τον τεχνικό ή τον υπεύθυνο του ERP. Συνήθως είναι ένα JSON αρχείο με το επιθυμητό payload.