The E-shop API connects any e-shop to BulkGate. Your e-shop uses it to report store events: a new order, a status change, a payment, a new customer and more. For each event, the portal finds the notification set up for the application, fills the variables from the request into its template and sends the message to the customer, to the store administrators, or to both.

The API itself does not set the message text. When no notification is set up for the event, the request succeeds and nothing is sent.

## Endpoints

All endpoints accept `POST` at `https://portal.bulkgate.com/api/1.0/eshop/<area>/<action>`.

| ENDPOINT                         | EVENT                                     | PAGE                                                           |
|:---------------------------------|:------------------------------------------|:---------------------------------------------------------------|
| `eshop/order/new`                | New order                                 | [Orders](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)                            |
| `eshop/order/change-status`      | Order status change                       | [Orders](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)                            |
| `eshop/order/payment`            | Order paid                                | [Orders](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)                            |
| `eshop/order/tracking-number`    | Tracking number assigned                  | [Orders](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)                            |
| `eshop/order/product-cancel`     | Product cancelled in an order             | [Orders](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)                            |
| `eshop/order/slip-add`           | Credit slip added to an order             | [Orders](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)                            |
| `eshop/customer/new`             | New customer                              | [Customers](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-customers/)                      |
| `eshop/product/out-of-stock`     | Product out of stock                      | [Products](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-products/)                        |
| `eshop/product/on-back-order`    | Product on back order                     | [Products](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-products/)                        |
| `eshop/product/update-quantity`  | Stock quantity changed                    | [Products](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-products/)                        |
| `eshop/product/delete`           | Product deleted                           | [Products](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-products/)                        |
| `eshop/return/new`               | New return                                | [Returns](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-returns/)                          |
| `eshop/return/change-status`     | Return status change                      | [Returns](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-returns/)                          |
| `eshop/contact/form`             | Contact form submitted                    | [Contact form](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-contact-form/)                |
| `eshop/setup`                    | Languages, stores and statuses setup      | [Setup](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-setup/)                              |

> [!NOTE]
> If the request does not reach its destination, repeat it on the [backup server](https://www.bulkgate.com/en/docs/api-administration-tokens/api-backup-server/) `backup1.bulkgate.com`.

## Request parameters

The event endpoints (all except `eshop/setup`) accept the same parameters. An unknown top-level parameter makes the request fail with `invalid_input_parameters`, so event data belongs in the `variables` object.

| PARAMETER NAME      | VALUE                                                      | MANDATORY | DEFAULT VALUE |
|:--------------------|:-----------------------------------------------------------|:----------|:--------------|
| application_id      | [Application ID](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/)              | **Yes**   | -             |
| application_token   | [Application authentication token](https://www.bulkgate.com/en/docs/api-administration-tokens/api-tokens/)    | **Yes**   | -             |
| language            | Language of the customer notification, e.g. `en`           | No        | `default`     |
| shop_id             | Store identifier if you run multiple stores                | No        | `0`           |
| variables           | Event data — a `name: value` object with scalar values     | No        | `{}`          |

Send the request as `application/json`.

## How the portal picks the notification

Notifications are set up in the portal for each application separately, in the **Customer SMS** and **Admin SMS** sections. Each one is tied to an event and a store (`shop_id`), and customer notifications also to a language. Your e-shop uploads the languages, stores and order and return statuses the portal offers notifications for via the [setup](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-setup/).

- **The customer notification** is looked up for the language in the `language` parameter. When the application does not have language mutations turned on, the portal ignores the language and uses `default`.
- **The admin notification** is always looked up for the `default` language and goes to the numbers of the administrators assigned to it.
- The customer and admin notifications are evaluated independently — an event can send one, both or neither.

> [!IMPORTANT]
> The portal does not send the same text to the same number twice within 24 hours. Calling the same event again therefore does not send the customer a duplicate message.

## Customer phone number

The portal looks for the customer's number in `variables`. The order is set by the `contact_address_preference` variable:

| `contact_address_preference` | ORDER OF NUMBER VARIABLES                                                                                                           | ORDER OF COUNTRY VARIABLES                                                                                                                  |
|:-----------------------------|:-------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------|
| `delivery` (default)         | `customer_mobile`, `customer_phone`, `customer_invoice_mobile`, `customer_invoice_phone`, `phone_mobile`, `phone`, `phone_number`   | `customer_country_id`, `customer_invoice_country_id`, `customer_country`, `customer_invoice_country`, `iso`, `country_iso`                 |
| `invoice`                    | `customer_invoice_mobile`, `customer_invoice_phone`, `customer_mobile`, `customer_phone`, `phone_mobile`, `phone`, `phone_number`   | `customer_invoice_country_id`, `customer_country_id`, `customer_invoice_country`, `customer_country`, `iso`, `country_iso`                 |

The first variable that yields a valid number is used. The portal reads the country as a two-letter ISO code (`cz`, `sk`, …) and uses it to add the prefix to numbers entered without one. When no valid number is found, the customer notification is not sent.

## Template variables

A notification template uses the variables from `variables` written as `<name>`, e.g. `<order_id>`. Write a default value right in the template as `<name:value>`. The portal also fills in:

- `shop_name` — the name of the store matching `shop_id` from the [store list](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-setup/), unless you send it yourself,
- `language_iso` — the value of the `language` parameter.

Variables you do not send are replaced in the text by their default value — an empty string for most, a dash for `order_id`, `long_order_id` and `order_ref`. These variables have a default value:

| GROUP       | VARIABLES                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|:------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Store       | `shop_id`, `shop_email`, `shop_name`, `shop_domain`, `shop_currency`, `shop_phone`, `store_id`, `lang_id`, `language_iso`                                                                                                                                                                                                                                                                                                                                                                    |
| Customer    | `customer_id`, `customer_company`, `customer_firstname`, `customer_lastname`, `customer_name`, `customer_address`, `customer_postcode`, `customer_city`, `customer_state`, `customer_country`, `customer_country_id`, `customer_phone`, `customer_mobile`, `customer_email`, `customer_vat_number`, `customer_fax`, `customer_message`, `customer_firstname_vokativ`, `customer_lastname_vokativ`                                                                                         |
| Billing     | `customer_invoice_company`, `customer_invoice_firstname`, `customer_invoice_lastname`, `customer_invoice_address`, `customer_invoice_postcode`, `customer_invoice_city`, `customer_invoice_state`, `customer_invoice_country`, `customer_invoice_country_id`, `customer_invoice_phone`, `customer_invoice_mobile`, `customer_invoice_vat_number`, `customer_invoice_firstname_vokativ`, `customer_invoice_lastname_vokativ`                                                              |
| Order       | `order_id`, `long_order_id`, `order_ref`, `order_reference`, `order_status`, `order_status_id`, `order_status_message`, `order_message`, `order_currency`, `order_payment`, `order_total_paid`, `order_total_locale`, `order_date`, `order_datetime`, `order_time`, `order_date1`–`order_date7`, `order_time1`, `order_products1`–`order_products8`, `order_smsprinter1`–`order_smsprinter4`, `cart_id`, `id_address_delivery`, `id_address_invoice`                                         |
| Shipping    | `carrier_id`, `order_carrier_name`, `order_carrier_code`, `order_carrier_url`, `order_carrier_delay`, `order_carrier_tracking_number`, `order_carrier_tracking_date`, `order_carrier_price`, `order_carrier_price_locale`, `order_carrier_weight`, `order_tracking`                                                                                                                                                                                                                         |
| Product     | `product_id`, `product_name`, `product_quantity`, `product_minimal_quantity`, `product_model`, `product_ref`, `product_description`, `product_manufacturer`, `product_supplier`, `product_supplier_id`, `product_supplier_ref`, `product_price`, `product_price_locale`, `product_ean`, `product_ean13`, `product_upc`, `product_isbn`, `product_jan`, `product_mpn`, `product_sku`                                                                                                        |
| Return      | `return_id`, `return_status`, `return_status_id`, `return_action`, `return_action_id`, `return_reason`, `return_reason_id`, `return_date`, `return_customer_message`, `return_question`, `return_products1`–`return_products8`                                                                                                                                                                                                                                                              |
| Employee    | `employee_id`, `employee_email`, `employee_firstname`, `employee_lastname`                                                                                                                                                                                                                                                                                                                                                                                                                    |

You can send your own variables as well — the template uses them the same way.

## Response

**On success** it returns a `data` object with the result of each sent message, separately for the customer (`customer`) and for administrators (`admin`). A key is missing when that notification is not set up for the event. A customer notification that is set up but turned off returns an empty array.

```json
{
    "data": {
        "customer": [
            {
                "status": "accepted",
                "message_id": "tmpde1bcd4b1d1",
                "part_id": ["tmpde1bcd4b1d1"],
                "number": "420777777777",
                "channel": "sms"
            }
        ]
    }
}
```

When no notification is set up for the event, the response is `{"data": []}`.

If a notification cannot be sent (invalid sender, blacklisted number, duplicate message…), the request still succeeds and contains the error code instead of the message result:

```json
{
    "data": {
        "customer": [
            ["duplicity_message"]
        ]
    }
}
```

**On error:**

```json
{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "detail": null
}
```

Where:

- **type** and **error** (error description) are listed in the [error types table](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/)
- **code** is the HTTP error code
- **detail** is additional information about the error

### E-shop API error types

| TYPE                       | WHEN IT OCCURS                                                              |
|:---------------------------|:----------------------------------------------------------------------------|
| `unknown_identity`         | `application_id` or `application_token` is missing or invalid.              |
| `invalid_input_parameters` | The request contains an unknown parameter or a parameter of the wrong type. |
| `unknown_action`           | The action in the URL does not exist, e.g. `eshop/order/cancel`.            |
