# Διασύνδεση με Entersoft

## Σύνδεση

Για να συνδεθείτε με το Entersoft περιβάλλον σας, χρειάζεται να συμπληρώσετε τα παρακάτω πεδία στην φόρμα **Connection settings** για να γίνει η κλήση στο endpoint `/api/login/login`.

### Host (string, απαραίτητο)

Το URL του Entersoft περιβάλλοντος.
Π.χ. `https://api.entersoft.gr`.

### Subscription ID (string, απαραίτητο)

Το Subscription ID για την σύνδεση στο Entersoft περιβάλλον.
Π.χ. `demo`.

### Subscription Password (string, απαραίτητο)

Ο κωδικός πρόσβασης του Subscription για την σύνδεση στο Entersoft περιβάλλον.
Π.χ. `secret`.

### Bridge ID (string, απαραίτητο)

Το Bridge ID που έχει οριστεί στο Entersoft περιβάλλον για την διασύνδεση.
Π.χ. `001`.

### User ID (string, απαραίτητο)

Το User ID που έχει οριστεί στο Entersoft περιβάλλον για την διασύνδεση.
Π.χ. `demo`.

### Password (string, απαραίτητο)

Ο κωδικός πρόσβασης που έχει οριστεί στο Entersoft περιβάλλον για την διασύνδεση.
Π.χ. `secret`.

### Branch ID (string, απαραίτητο)

Το Branch ID που έχει οριστεί στο Entersoft περιβάλλον για την διασύνδεση.
Π.χ. `1`.

### Application ID (ESApplicationID) (string, απαραίτητο)

Το Application ID που έχει οριστεί στο Entersoft περιβάλλον για την διασύνδεση.
Π.χ. `ecomfreeconnector`.

Σε περίπτωση που υπάρχει API Key, μπορείτε να συμπληρώσετε το όνομα του header και το value στα παρακάτω πεδία. Με αυτό τον τρόπο δε χρειάζεται να γίνεται η κλήση για το login.

### Header name (string, απαραίτητο)

Το όνομα του header για το API Key.
Π.χ. `X-ESAPIKEY-ECOMCONNECTOR`.

### Header value (string, απαραίτητο)

Η τιμή του header για το API Key.
Π.χ. `3dcb6999-1d41-43dd-b7f2-c0a56652e760,0d9fe249-985b-32ad-90a8-40cce66c7ce1,63277478206`.

### Παράδειγμα κλήσης login

- URL: `https://api.entersoft.gr`
- Subscription ID: `demo`
- Subscription Password: `secret`
- Bridge ID: `001`
- User ID: `demo`
- Password: `secret`
- Branch ID: `1`
- Application ID: `ecomfreeconnector`

#### REQUEST

POST `https://api.entersoft.gr/api/login/login`

```json
{
  "SubscriptionID": "demo",
  "SubscriptionPassword": "secret",
  "BridgeID": "001",
  "Model": {
    "BranchID": "1",
    "LangID": "en-US",
    "UserID": "demo",
    "Password": "secret"
  },
  "Claims": {
    "ESApplicationID": "ecomfreeconnector"
  }
}
```

#### RESPONSE

```json
{
  "Model": {
    "WebApiToken": "5307a9ec-7c31-31b7-8865-3702aa9b1aa7",
    "WebApiTokenExpiresAt": "2025-12-31T23:59:59"
  }
}
```

## Εισαγωγές δεδομένων

Απαιτούνται 3 κλήσεις: μία για τα προϊόντα, μία για τις τιμές και μία για τα αποθέματα. Τα δεδομένα που χρειάζονται για την εισαγωγή περιγράφονται στις αντίστοιχες ενότητες για το Magento και το WooCommerce.

Η εισαγωγή δεδομένων μπορεί να γίνει με Public Query ή με Simple Scroller.

Συνήθως επιλέγεται η χρήση Public Query διότι υπάρχει μεγαλύτερη ευελιξία στα δεδομένα που μπορούμε να έχουμε στη διάθεσή μας. Σε κάθε περίπτωση μας ενδιαφέρει να λαμβάνουμε από το ERP τα differentials.

Για να γίνει η λήψη των differentials, το Sébastien στέλνει με την κλήση την τελευταία ημερομηνία συγχρονισμού που έγινε επιτυχώς. Το Entersoft θα πρέπει να επιστρέφει μόνο τα δεδομένα που έχουν ενημερωθεί μετά από αυτή την ημερομηνία. Σε περίπτωση που δε σταλεί πεδίο με ημερομηνία, τότε θα πρέπει να επιστραφούν όλα τα δεδομένα.

### Εισαγωγή από public query

Οι κλήσεις γίνονται με pagination με `PageSize` 1000 στο request header `X-ESPQOptions`.

### Group (string, απαραίτητο)

Το όνομα του group που θα φέρει τα δεδομένα.
Π.χ. `WEB_Scrolls`.

### Query (string, απαραίτητο)

Το όνομα του query που θα φέρει τα δεδομένα.
Π.χ. `GetProducts`.

### Date parameter (string, προαιρετικό)

Το όνομα του πεδίου που θα χρησιμοποιηθεί για φιλτράρισμα των δεδομένων με βάση την ημερομηνία.
Η μορφή της ημερομηνίας που αποστέλλεται είναι `YYYY-MM-DD hh:mm:ss`.
Π.χ. `ESDModified`.

### Παράδειγμα κλήσης public query

- Group: `WEB_Scrolls`
- Query: `GetProducts`
- Date parameter: `ESDModified`

#### REQUEST

GET `https://api.entersoft.gr/api/rpc/PubliQuery/WEB_Scrolls/GetProducts?ESDModified=2025-01-01%2000:00:00`

#### HEADERS

```json
Content-Type: "application/json"
X-ESAPIKEY-ECOMCONNECTOR: "5307a9ec-7c31-31b7-8865-3702aa9b1aa7"
X-ESPQOptions: { "Page": 1, "PageSize": 1000, "WithCount": true }
```

#### RESPONSE

```json
{
  "Count": 1000,
  "PageSize": 1000,
  "Page": 1,
  "Rows": [
    {
      "sku": "PROD-001",
      "name": "Product 001"
    },
    {
      "sku": "PROD-002",
      "name": "Product 002"
    }
  ]
}
```

### Εισαγωγή από scroller

Η παράμετρος για την ημερομηνία είναι `UnixTS` και δέχεται ημερομηνία σε μορφή Unix timestamp.

### Endpoint (string, απαραίτητο)

Το Filter ID του scroller.
Π.χ. `WebApiPrices`.

### Items (string, απαραίτητο)

Το όνομα του πεδίου που περιέχει τα δεδομένα.
Π.χ. `WebItems`.

### Παράδειγμα κλήσης simple scroller

- Endpoint: `WebApiPrices`
- Items: `WebItems`

#### REQUEST

GET `https://api.entersoft.gr/api/rpc/SimpleScroller/ESWBCommon/WebApiPrices?UnixTS=1735689600`

#### HEADERS

```json
Content-Type: "application/json"
X-ESAPIKEY-ECOMCONNECTOR: "5307a9ec-7c31-31b7-8865-3702aa9b1aa7"
```

#### RESPONSE

```json
{
  "WebItems": [
    {
      "sku": "PROD-001",
      "name": "Product 001"
    },
    {
      "sku": "PROD-002",
      "name": "Product 002"
    }
  ]
}
```

## Εισαγωγές παραγγελιών

Η διαδικασία εισαγωγής παραγγελίας στο Entersoft γίνεται μέσω Scroller Command με τα εξής βήματα:

1. Αναζήτηση πελάτη μέσω **Public Query** και φίλτρα αναζήτησης πελάτη
- Αν δεν υπάρχει πελάτης: αναζήτηση με τα επόμενα φίλτρα ή δημιουργία πελάτη με **Scroller Command**
- Αν υπάρχουν παραπάνω από ένας πελάτες: αναζήτηση με τα επόμενα φίλτρα ή σφάλμα
2. Δημιουργία παραγγελίας με **Scroller Command**

Στο διαχειριστικό του Sébastien στην καρτέλα **Order settings** υπάρχουν τα πεδία για να οριστούν τα φίλτρα αναζήτησης πελάτη, το public query για την αναζήτηση πελάτη, το scroller command για τη δημιουργία πελάτη και το scroller command για τη δημιουργία παραγγελίας.

Στις καρτέλες **Orders table**, **Order Items table**, **Customers table**, **Addresses table** υπάρχει η δυνατότητα να γίνει αντιστοίχιση των δεδομένων της παραγγελίας του e-shop με τα πεδία των πινάκων του Entersoft.

Τα δεδομένα της παραγγελίας μπορούν να σταλούν με δύο μορφές:

- Σε έναν πίνακα σαν array που περιέχει κάθε προϊόν της παραγγελίας μαζί με όλα τα υπολοιπα πεδία της παραγγελίας σε κάθε εγγραφή
- Σε δύο πίνακες, έναν για τα γενικά στοιχεία της παραγγελίας και έναν για τα προϊόντα της παραγγελίας

#### Σημαντικό

Για να γίνει η αντιστοίχιση των πεδίων θα πρέπει να σταλούν οδηγίες από τον τεχνικό ή τον υπεύθυνο του ERP. Συνήθως είναι ένα JSON αρχείο με το επιθυμητό payload.

### Παράδειγμα αναζήτησης πελάτη

- Group: `WEB_Scrolls`
- Query: `Customers_Search`
- Entersoft field: `EMailAddress`
- Customer variable: `CustomerCode`

#### REQUEST

GET `https://api.entersoft.gr/api/rpc/PubliQuery/WEB_Scrolls/Customers_Search?EMailAddress=customer@example.com`

#### RESPONSE

```json
{
  "Rows": [
    {
      "CustomerCode": "4af30242-8934-3f0c-a84c-cdca03146553",
      "EMailAddress": "customer@example.com"
    },
  ]
}
```

### Παράδειγμα δημιουργίας πελάτη

- Command: `CreateCustomer`
- Scroller ID: `WEB_Scrolls/Customers`
- Command ID: `AddCustomer`
- Customers table: `ESFITradeAccount`
- Addresses table: `ESGOSites`
- Customer variable: `CustomerCode`

#### REQUEST

POST `https://api.entersoft.gr/api/rpc/ScrollerCommand/CreateCustomer`

```json
{
  "ScrollerID": "WEB_Scrolls/Customers",
  "CommandID": "AddCustomer",
  "CommandParams": {},
  "UnboundVariables": {},
  "ScrollerParams": {},
  "ScrollerDataset": {
    "ESFITradeAccount": [
      {
        "fPersonCodeGID": "9f8d79c8-4939-4c4a-84a7-f93e58fe26f8",
        "Name": "John Doe",
        "EMailAddress": "customer@example.com"
      }
    ],
    "ESGOSites": [
      {
        "fPersonCodeGID": "9f8d79c8-4939-4c4a-84a7-f93e58fe26f8",
        "Address1": "123 Main St",
        "Telephone1": "+30 2101234567",
        "fCityCode": "Athens",
        "fPostalCode": "12345",
        "fDistrictCode": "Attica",
        "fCountryCode": "Greece"
      }
    ]
  }
}
```

#### RESPONSE

```json
{
  "Variables": {
    "CustomerCode": ["4af30242-8934-3f0c-a84c-cdca03146553"]
  }
}
```

### Παράδειγμα δημιουργίας παραγγελίας με έναν πίνακα

- Command: `CreateOrder`
- Scroller ID: `WEB_Scrolls/Orders`
- Command ID: `AddOrder`
- Orders table:
- Order Items table: `ESFILineItem`
- Order variable: `OrderCode`

#### REQUEST

POST `https://api.entersoft.gr/api/rpc/ScrollerCommand/CreateOrder`

```json
{
  "ScrollerID": "WEB_Scrolls/Orders",
  "CommandID": "AddOrder",
  "CommandParams": {},
  "UnboundVariables": {},
  "ScrollerParams": {},
  "ScrollerDataset": {
    "ESFILineItem": [
      {
        "SKU": "CHAMP-S",
        "BillingAddressCity": "Athens",
        "BillingAddressZipCode": "12345",
        "BillingAddress1": "123 Main St",
        "CustomerName": "John Doe",
        "DeliveryAddressCity": "Athens",
        "DeliveryAddressZipCode": "12345",
        "DeliveryAddress1": "123 Main St",
        "EMailAddress": "customer@example.com",
        "Price": 100.00,
        "Quantity": 1,
        "VatPercentage": 24.00,
        "TotalValue": 100.00,
        "DocTotalValue": 200.00
      },
      {
        "SKU": "CHAMP-M",
        "BillingAddressCity": "Athens",
        "BillingAddressZipCode": "12345",
        "BillingAddress1": "123 Main St",
        "CustomerName": "John Doe",
        "DeliveryAddressCity": "Athens",
        "DeliveryAddressZipCode": "12345",
        "DeliveryAddress1": "123 Main St",
        "EMailAddress": "customer@example.com",
        "Price": 100.00,
        "Quantity": 1,
        "VatPercentage": 24.00,
        "TotalValue": 100.00,
        "DocTotalValue": 200.00
      }
    ]
  }
}
```

#### RESPONSE

```json
{
  "Variables": {
    "OrderCode": ["4af30242-8934-3f0c-a84c-cdca03146553"]
  }
}
```

### Παράδειγμα δημιουργίας παραγγελίας με δύο πίνακες

- Command: `CreateOrder`
- Scroller ID: `WEB_Scrolls/Orders`
- Command ID: `AddOrder`
- Orders table: ESFIDocumentTrade
- Order Items table: `ESFILineItem`
- Order variable: `OrderCode`

#### REQUEST

POST `https://api.entersoft.gr/api/rpc/ScrollerCommand/CreateOrder`

```json
{
  "ScrollerID": "WEB_Scrolls/Orders",
  "CommandID": "AddOrder",
  "CommandParams": {},
  "UnboundVariables": {},
  "ScrollerParams": {},
  "ScrollerDataset": {
    "ESFIDocumentTrade": [
      {
        "BillingAddressCity": "Athens",
        "BillingAddressZipCode": "12345",
        "BillingAddress1": "123 Main St",
        "CustomerName": "John Doe",
        "DeliveryAddressCity": "Athens",
        "DeliveryAddressZipCode": "12345",
        "DeliveryAddress1": "123 Main St",
        "EMailAddress": "customer@example.com",
        "DocTotalValue": 200.00
      }
    ],
    "ESFILineItem": [
      {
        "SKU": "CHAMP-S",
        "Price": 100.00,
        "Quantity": 1,
        "VatPercentage": 24.00,
        "TotalValue": 100.00
      },
      {
        "SKU": "CHAMP-M",
        "Price": 100.00,
        "Quantity": 1,
        "VatPercentage": 24.00,
        "TotalValue": 100.00
      }
    ]
  }
}
```

#### RESPONSE

```json
{
  "Variables": {
    "OrderCode": ["4af30242-8934-3f0c-a84c-cdca03146553"]
  }
}
```