# Γενικές οδηγίες

Όλοι οι τύποι διασύνδεσης θα πρέπει να ακολουθούν την προδιαγραφή αυτή για την σωστή εισαγωγή και ενημέρωση των δεδομένων από το ERP προς το e-shop. Κάποιες πιο συγκεκριμένες οδηγίες περιγράφονται παρακάτω.

Το Sébastien υποστηρίζει:

- 3 κανάλια ενημέρωσης από το ERP προς το e-shop
- 1 κανάλι ενημέρωσης παραγγελιών από το e-shop προς το ERP
- Webhook για ενημέρωση κατάστασης παραγγελίας από το ERP προς το e-shop

Τα κανάλια ενημέρωσης μπορούν να χρησιμοποιηθούν ταυτόχρονα από διαφορετικές πηγές. Για παράδειγμα, μπορεί να γίνει import τιμών απο τη διασύνδεση με το ERP, απο αρχείο .CSV, απο XML, κλπ.

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

## Ενημέρωση προϊόντων

Όλα τα απαραίτητα και προαιρετικά πεδία ορίζονται στις προδιαγραφές εισαγωγής προϊόντων για το [Magento](https://app.sebastien.gr/docs/magento/products) και το [WooCommerce](https://app.sebastien.gr/docs/woocommerce/products). Τα ονόματα των πεδίων είναι προαιρετικά καθώς υπάρχει δυνατότητα αντιστοίχισης μέσα από το διαχειριστικό.

Το μοναδικό κλειδί για οποιαδήποτε ενημέρωση προς το e-shop είναι αυστηρά το SKU. Κατά την ενημέρωση εάν ένα SKU βρεθεί στο e-shop θα γίνει ενημέρωση των χαρακτηριστικών του. Εάν ένα SKU δεν βρεθεί στο e-shop τότε θα δημιουργηθεί ένα νέο προϊόν με τα διαθέσιμα χαρακτηριστικά του.

Για τα υποχρεωτικά πεδία price, quantity και status υπάρχει δυνατότητα να οριστεί default τιμή μέσα από τις ρυθμίσεις προϊόντων.

## Configurable προϊόντα

Στην παρούσα έκδοση το Sébastien χρειάζεται ΜΟΝΟ τα variations ενός προϊόντος (simple products) στα δεδομένα που του εισάγονται. Τα configurable προϊόντα προκύπτουν από το πεδίο code όταν αυτό είναι συμπληρωμένο.

Στο WooCommerce τα configurable προϊόντα ονομάζονται variable και τα simple προϊόντα που ανήκουν σε αυτά variations. Η λογική είναι ίδια.

Σε περίπτωση που το code είναι συμπληρωμένο σε ένα ή περισσότερα προϊόντα τότε θα δημιουργήσει:

- το configurable με sku την τιμή του code
- τα simple προϊόντα με τα δικά τους sku
- τη συσχέτιση των simple προϊόντων με το configurable βάσει του κοινού code

Σε περίπτωση που ένα προϊόν είναι simple και δεν έχει variations τότε το πεδίο code πρέπει να παραμένει κενό.

### Δημιουργία ή ενημέρωση ενός (1) simple προϊόντος

#### RESPONSE

```json
[
  {
    "category_ids": "Αξεσουάρ > Γυναικεία > Γυαλιά Ηλίου",
    "code": null,
    "name": "Γυναικεία Γυαλιά Ηλίου",
    "price": 69.99,
    "quantity": 50,
    "sku": "gynaikeia-gyalia-hliou",
    "status": 1
  }
]
```

### Δημιουργία ή ενημέρωση ενός (1) configurable και δύο (2) simple προϊόντων συνδεδεμένα μεταξύ τους βάσει μεγέθους

#### RESPONSE

```json
[
  {
    "category_ids": "Ρούχα > Ανδρικά > Παντελόνια",
    "code": "andriko-panteloni",
    "name": "Ανδρικό Παντελόνι",
    "price": 39.99,
    "quantity": 10,
    "size": "S",
    "sku": "andriko-panteloni-s",
    "status": 1
  },
  {
    "category_ids": "Ρούχα > Ανδρικά > Παντελόνια",
    "code": "andriko-panteloni",
    "name": "Ανδρικό Παντελόνι",
    "price": 39.99,
    "quantity": 5,
    "size": "M",
    "sku": "andriko-panteloni-m",
    "status": 1
  }
]
```

## Mapping

Υπάρχουν περιπτώσεις όπου τα ονόματα των πεδίων στο ERP διαφέρουν από αυτά που χρησιμοποιεί το e-shop. Για αυτό το λόγο υπάρχει η δυνατότητα αντιστοίχισης (mapping) των πεδίων μέσα από το διαχειριστικό του Sébastien.

Για παράδειγμα, το πεδίο `name` μπορεί να ονομάζεται `product_name` στο ERP. Μέσα από το διαχειριστικό του Sébastien μπορεί να γίνει αυτή η αντιστοίχιση ώστε να αναγνωρίζεται σωστά το πεδίο κατά την εισαγωγή των δεδομένων.

Ή για παράδειγμα, η κατηγορία `Ανδρικά` μπορεί να ονομάζεται `mens` στο ERP. Μέσα από το διαχειριστικό του Sébastien μπορεί να γίνει αυτή η αντιστοίχιση ώστε να αναγνωρίζεται σωστά η κατηγορία κατά την εισαγωγή των δεδομένων.

Το Sébastien μέσω του διαχειριστικού δίνει τη δυνατότητα αντιστοίχισης:

- των χαρακτηριστικών
- των τιμών που έχουν τα χαρακτηριστικά
- των κατηγοριών

## Φωτογραφίες

Για την εισαγωγή των φωτογραφιών μέσω του import των προϊόντων θα πρέπει να συμπληρωθεί το πεδίο `media_gallery` στο Magento ή `images` στο WooCommerce με τα URLs μίας ή περισσότερων φωτογραφιών χωρισμένες μεταξύ τους με `,` (κόμμα). Οι φωτογραφίες θα πρέπει να είναι προσβάσιμες σε ένα δημόσιο domain.

Κατά την ενημέρωση των προϊόντων υπάρχει επιλογή για:

| Skip | Αγνοεί πλήρως τις φωτογραφίες κατά την ενημέρωση |
|---|---|
| Replace | Αντικαθιστά τις φωτογραφίες μόνο σε περίπτωση που έρθουν νέες κατά την ενημέρωση |
| Merge | Συγκρίνει και ενημερώνει μόνο τις νέες φωτογραφίες, χωρίς να αφαιρεί τις παλιές (για τη σύγκριση χρησιμοποιούνται checksum των φωτογραφιών) |

### Φωτογραφίες προϊόντος Magento

#### RESPONSE

```json
[
  {
    "media_gallery": "https://example.com/images/andriko-panteloni-1.jpg,https://example.com/images/andriko-panteloni-2.jpg",
    "name": "Ανδρικό Παντελόνι",
    "sku": "andriko-panteloni"
  }
]
```

### Φωτογραφίες προϊόντος WooCommerce

#### RESPONSE

```json
[
  {
    "images": "https://example.com/images/gynaikeio-forema-1.jpg,https://example.com/images/gynaikeio-forema-2.jpg",
    "name": "Γυναικείο Φόρεμα Floral",
    "sku": "gynaikeio-forema-floral-m"
  }
]
```

## Κατηγορίες

Οι κατηγορίες αντιστοιχίζονται με δύο τρόπους:

- Με το όνομα της κατηγορίας
- Με το ID της κατηγορίας

Στο πεδίο των κατηγοριών μπορεί να μπει είτε ολόκληρη η ιεραρχία της κατηγορίας με διαχωριστικό το `>` (μεγαλύτερο από), είτε μεμονωμένες κατηγορίες χωρισμένες με `,` (κόμμα), `;` (ερωτηματικό) ή `|` (κάθετος).

Το διαχωριστικό ορίζεται στις ρυθμίσεις κατηγοριών και είναι ένα για όλες τις εισαγωγές. Το προεπιλεγμένο είναι το `,` (κόμμα), το οποίο χρησιμοποιείται και στα παρακάτω παραδείγματα.

Για παράδειγμα:

| Ιεραρχία κατηγοριών | Ρούχα > Ανδρικά > Παντελόνια |
|---|---|
| Μεμονωμένες κατηγορίες | Ρούχα, Ανδρικά, Παντελόνια ή 10, 17, 31 |
| Συνδυασμός των δύο | Ρούχα > Ανδρικά > Παντελόνια, Ρούχα > Ανδρικά > Παντελόνια Εργασίας, Outlet |

Σε περίπτωση που υπάρχουν κατηγορίες με ίδιο όνομα χρησιμοποιείται αυστηρά η δομή της ιεραρχίας ώστε να είναι εφικτή η αντιστοίχηση στη σωστή κατηγορία βάσει ονόματος.

### Παράδειγμα κατηγοριών

#### RESPONSE

```json
[
  {
    "category_ids": "Ρούχα > Ανδρικά > Παντελόνια",
    "name": "Ανδρικό Παντελόνι",
    "sku": "andriko-panteloni"
  },
  {
    "category_ids": "Ρούχα > Γυναικεία > Παντελόνια",
    "name": "Γυναικείο Παντελόνι",
    "sku": "gynaikeio-panteloni"
  }
]
```

## Συσχέτιση προϊόντων

Για την ενημέρωση των συσχετιζόμενων προϊόντων χρησιμοποιούνται τα πεδία:

|  | Magento | WooCommerce |
|---|---|---|
| Cross-sell products | `crosssell_skus` | `cross_sell_ids` |
| Related products | `related_skus` | – |
| Up-sell products | `upsell_skus` | `upsell_ids` |

Σε αυτά τα πεδία μπαίνει το SKU κάθε συσχετιζόμενου προϊόντος, χωρισμένο με `,` (κόμμα). Στο WooCommerce, παρά το όνομα των πεδίων, στέλνονται επίσης SKU και όχι IDs. Στο Magento η σειρά των SKU καθορίζει και τη θέση τους στη λίστα.

Τα συσχετιζόμενα προϊόντα πρέπει να υπάρχουν στο e-shop. Οι συσχετίσεις δημιουργούνται αφού δημιουργηθούν τα προϊόντα, οπότε ένα προϊόν μπορεί να συσχετιστεί και με προϊόντα της ίδιας εισαγωγής. Στο WooCommerce, SKU που δεν βρίσκονται αγνοούνται.

Οι συσχετίσεις ορίζονται κατά τη δημιουργία ενός προϊόντος. Σε υπάρχοντα προϊόντα ενημερώνονται μόνο αν έχει ενεργοποιηθεί η ενημέρωσή τους στις ρυθμίσεις προϊόντων. Σε αυτή την περίπτωση η λίστα που στέλνεται αντικαθιστά την υπάρχουσα.

### Συσχέτιση προϊόντων Magento

#### RESPONSE

```json
[
  {
    "name": "Ανδρικό Πουκάμισο Λευκό",
    "sku": "andriko-poukamiso-leyko-m",
    "crosssell_skus": "gravata-mplu-classic,zoni-dermatini-mayrh",
    "related_skus": "andriko-poukamiso-mplu-m,andriko-poukamiso-roz-m",
    "upsell_skus": "andriko-poukamiso-premium-leyko-m,andriko-poukamiso-designer-leyko-m"
  }
]
```

### Συσχέτιση προϊόντων WooCommerce

#### RESPONSE

```json
[
  {
    "name": "Γυναικείο Φόρεμα Floral",
    "sku": "gynaikeio-forema-floral-m",
    "cross_sell_ids": "tsanta-verniki-mayrh,sandalia-psila-kokkina",
    "upsell_ids": "gynaikeio-forema-designer-floral-m,gynaikeio-forema-premium-floral-m"
  }
]
```

## Ενημέρωση τιμών

Ενημερώνει αποκλειστικά τα πεδία των τιμών, σε προϊόντα που υπάρχουν ήδη στο e-shop. Η εισαγωγή τιμών δεν δημιουργεί προϊόντα, και SKU που δεν βρίσκονται στο e-shop καταγράφονται ως σφάλμα.

Πέρα από την τιμή υπάρχει η δυνατότητα να σταλεί η τιμή έκπτωσης και το διάστημα από - μέχρι κατά το οποίο αυτή ισχύει. Στο Magento μπορούν να σταλούν επιπλέον κλιμακωτές τιμές (tier prices) ανά ομάδα πελατών.

|  | Magento | WooCommerce |
|---|---|---|
| Τιμή | `price` | `regular_price` |
| Τιμή έκπτωσης | `special_price` | `sale_price` |
| Έναρξη έκπτωσης | `special_from_date` | `date_on_sale_from` |
| Λήξη έκπτωσης | `special_to_date` | `date_on_sale_to` |
| Tier prices | `tier_prices` | – |

Μια τιμή έκπτωσης που δεν στέλνεται, είναι κενή, μηδέν ή ίση με την τιμή δεν θεωρείται έκπτωση. Σε αυτή την περίπτωση αφαιρείται η τιμή έκπτωσης που έχει ήδη το προϊόν, ώστε το e-shop να ακολουθεί πάντα το ERP. Γι' αυτό, αν ένα προϊόν έχει έκπτωση, η τιμή έκπτωσης πρέπει να στέλνεται σε κάθε ενημέρωση τιμών.

Τιμές που δεν έχουν αλλάξει δεν αποστέλλονται ξανά στο e-shop. Τα αναλυτικά πεδία περιγράφονται στις προδιαγραφές τιμών για το [Magento](https://app.sebastien.gr/docs/magento/prices) και το [WooCommerce](https://app.sebastien.gr/docs/woocommerce/prices).

### Ενημέρωση τιμών Magento

#### RESPONSE

```json
[
  {
    "price": 39.99,
    "sku": "andriko-panteloni-s",
    "special_from_date": "2025-12-01",
    "special_price": 29.99,
    "special_to_date": "2025-12-31"
  },
  {
    "price": 69.99,
    "sku": "gynaikeia-gyalia-hliou"
  }
]
```

### Ενημέρωση τιμών WooCommerce

#### RESPONSE

```json
[
  {
    "date_on_sale_from": "2025-12-01",
    "date_on_sale_to": "2025-12-31",
    "regular_price": 49.99,
    "sale_price": 39.99,
    "sku": "gynaikeio-forema-floral-m"
  },
  {
    "regular_price": 29.99,
    "sku": "tsanta-verniki-mayrh"
  }
]
```

## Ενημέρωση αποθεμάτων

Ενημερώνει αποκλειστικά τα πεδία των αποθεμάτων, σε προϊόντα που υπάρχουν ήδη στο e-shop. Η εισαγωγή αποθεμάτων δεν δημιουργεί προϊόντα, και SKU που δεν βρίσκονται στο e-shop καταγράφονται ως σφάλμα.

|  | Magento | WooCommerce |
|---|---|---|
| Ποσότητα | `quantity` | `stock_quantity` |
| Κατάσταση αποθέματος | `is_in_stock` | `stock_status` |
| Backorders | `backorders` | – |
| Out-of-Stock Threshold | `min_quantity` | `stock_threshold` |

Πεδία που δεν στέλνονται ή είναι κενά δεν αλλάζουν στο e-shop, οπότε μπορεί να σταλεί μόνο η ποσότητα. Αποθέματα που δεν έχουν αλλάξει δεν αποστέλλονται ξανά στο e-shop.

Το `min_quantity` του Magento και το `stock_threshold` του WooCommerce επιτρέπουν στο προϊόν να πωληθεί και όταν η ποσότητα πέσει κάτω από το μηδέν, μέχρι το όριο αυτό. Χρησιμοποιούνται μόνο όταν υπάρχει διαχείριση των backorders στο e-shop. Σε αντίθετη περίπτωση αυτά τα πεδία να αγνοούνται τελείως από τα δεδομένα.

Τα αναλυτικά πεδία περιγράφονται στις προδιαγραφές αποθεμάτων για το [Magento](https://app.sebastien.gr/docs/magento/stocks) και το [WooCommerce](https://app.sebastien.gr/docs/woocommerce/stocks).

### Ενημέρωση αποθεμάτων Magento

#### RESPONSE

```json
[
  {
    "quantity": 10,
    "sku": "andriko-panteloni-s"
  },
  {
    "min_quantity": 5,
    "quantity": 0,
    "sku": "andriko-panteloni-m"
  }
]
```

### Ενημέρωση αποθεμάτων WooCommerce

#### RESPONSE

```json
[
  {
    "sku": "gynaikeio-forema-floral-m",
    "stock_quantity": 8
  },
  {
    "sku": "tsanta-verniki-mayrh",
    "stock_quantity": 0,
    "stock_threshold": 5
  }
]
```