# Introduction

Smarts allows to scan products and pay for them by using mobile app.

## Powered by: 

![](https://2620668582-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LkW9lt6QQlo62wmQ4y6%2F-M48mmqX2X7WMoRODdbf%2F-M48qQNAgii-X_FUv6Qp%2Fimage.png?alt=media\&token=fa3c4f6e-8cef-4db2-aea9-7d476274a6a6)

## General Flow

* Customer scans store's QR code with Smarts app to start shopping
* Customer will add products to shopping cart by scanning SKU or searching it from product catalog
* Customer will pay for the purchase by scanning QR code at the store exit.

## Integration

Smarts is communicating with merchant through restful API-s. It is required to create API endpoints in the merchant side to establish communication between the Smarts and merchant. 

*Smarts offers **2 different** integration methods*

####       [Spring Boot Integration](/integration/spring-boot-starter/overview) - Generates secured and required API endpoints automatically

      [**Custom integration**](/integration/custom-integration/overview) **- Create API endpoints and data objects manually**

Smarts need API-s to exchange  

* Product information
* Invoice and payment confirmation information
* Purchase check information
* Marketing information
* Home delivery information
* Loyalty card information

{% hint style="warning" %}
Smarts **strongly** **recommends** Spring Boot Starter integration.
{% endhint %}

## Payment processing

Smarts is using **Stripe** payment provider because it allows to

* move payment amount from client to merchant directly **without third party intervention**
* start payment in the **merchant behalf**
* **one-click onboarding** for merchant with Stripe OAuth service

   [Check stripe pricing here](https://stripe.com/en-ee/pricing)

## Before you open your first store

1.) Open Smarts account and create new subscription

2.) Open Stripe Merchant [account](https://stripe.com/en-ee).

3.)  Choose the integration method

* [Spring Boot Starter](/integration/spring-boot-starter/overview)
* [Customer Integration](/integration/custom-integration/overview)

For further questions please write an email or call 

<kristo.truu@smarts.ee>&#x20;

+372 563 14 762


# Spring Boot Starter

Spring Boot Starter developed by SMARTS.


# Overview

Spring Boot integration

Spring Boot is the easiest way to integrate with Smarts platform. Smarts has made a software development kit ( SDK ) for creating required API endpoints automatically.

*There is minimum **3 steps** to get your store up and running.*

### **1.** [**Set up your project**](/integration/spring-boot-starter/setup-your-project)

### **2.** [**Implement product search**](/integration/spring-boot-starter/product-search)

*Smarts platform need API-s for getting product information from merchant.*&#x20;

{% hint style="info" %}
*SDK will generate required and secured API endpoints automatically when the product search interface is implemented.*
{% endhint %}

### **3.** [**Implement invoicing**](/integration/spring-boot-starter/invoicing)

Smarts platform need API-s for sending payment confirmation and invoice back to merchant.

{% hint style="info" %}
*SDK will generate required and secured API endpoints automatically when the invoicing interface is implemented.*
{% endhint %}

## Additional integration

Smarts allows also to

* [generate invoice in the merchant ](/integration/spring-boot-starter/merchant-side-invoicing)side
* [manage purchase check in the merchant side](/integration/spring-boot-starter/merchant-side-purchase-control)
* [link and use loyalty cards](/integration/spring-boot-starter/loyalty-cards)
* [home delivery](/integration/spring-boot-starter/home-delivery)
* [show in-app offers](/integration/spring-boot-starter/marketing-and-offers)

Those functionalities needs additional implementations and configuring. All configuration can be done in the Smarts UI.&#x20;


# Setup your project

Spring Boot integration process overview

**1. Create new store** in Smarts Web Manager to get access token

2\. **Register store** from  your application property file

```
smarts.access[0].token=${PASTE_YOUR_ACCESS_TOKEN_HERE}
smarts.access[0].institution={PASTE_YOUR_STORE_ID_HERE}
```

&#x20;3\. I**mport Smarts dependency** to your Spring Boot project

```
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>smarts-central</id>
        <name>libs-release</name>
        <url>http://repo.huefy.eu/artifactory/libs-release</url>
    </repository>
    <repository>
        <snapshots />
        <id>smarts-snapshots</id>
        <name>libs-snapshot</name>
        <url>http://repo.huefy.eu/artifactory/libs-snapshot</url>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>smarts-central</id>
        <name>libs-release</name>
        <url>http://repo.huefy.eu/artifactory/libs-release</url>
    </pluginRepository>
    <pluginRepository>
        <snapshots />
        <id>smarts-snapshots</id>
        <name>libs-snapshot</name>
        <url>http://repo.huefy.eu/artifactory/libs-snapshot</url>
    </pluginRepository>
</pluginRepositories>
```

```
<dependency>
    <groupId>ee.smarts</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <version>0.0.49-SNAPSHOT</version>
</dependency>
```


# Product search

Implementing product search functionality

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

### Implementation

You only need to create a new class, implement **`ProductSearchAdapter`** interface and fill all required methods.  API endpoints for product search are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.Entities.product.Product;
import ee.smarts.common.v1.requests.ProductSearchRequest;
import ee.smarts.starter.adapter.ProductSearchAdapter;
import org.springframework.stereotype.Component;
import java.util.List;

@Component
public class ProductSearchImpl implements ProductSearchAdapter {
    @Override
    public Product searchByBarcode(ProductSearchRequest request) { 
        // implement this method
        return null;
    }
    @Override
    public List<Product> searchByName(ProductSearchRequest request) { 
        // implement this method
        return null;
    }
    @Override
    public Pageable<Product> findAll(PageRequest<ProductSearchRequest> productSearchRequest){
        // implement this method
        return null;
    }
    @Override
    public List<Category> findProductCategories(InstitutionRequest institutionRequest){
        // implement this method
        return null;
    }
}
```

### Methods description

#### searchByBarcode

Method used to request product details based on product SKU code. Used for: adding product to shopping cart, adding product to shopping list, purchase check validation.&#x20;

#### searchByName

Method used to request products which contains in the name requested string. Used for: adding product to shopping cart from catalog, adding product to pickup order from catalog.&#x20;

#### findAll

Method used to display products in product catalog.&#x20;

#### findProductCategories

Method used to display product categories in product catalog.&#x20;


# Invoicing

Default Smarts invoicing - receive invoice and payment confirmation.

{% hint style="info" %}
Implementation is **OPTIONAL** (*Recommended*)
{% endhint %}

Smarts will store detailed confirmation invoice only for two months. So it is important to save detailed invoice copy.

### Implementation

You only need to create a new class, implement **`InvoiceReceiverAdapter`** interface and fill all required methods.  API endpoints for invoicing are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.Entities.invoice.Invoice;
import ee.smarts.starter.adapter.InvoiceReceiverAdapter;
import org.springframework.stereotype.Component;

@Component
public class InvoiceReceiverImpl implements InvoiceReceiverAdapter {
    @Override
    public void receive(Invoice invoice) {
        // implement this method
    } 
}
```

{% hint style="warning" %}
Default invoicing **is not used** when merchant side invoicing is enabled. Merchant side invoicing is using receipt listener method in [ReceiptAdapter](/integration/spring-boot-starter/merchant-side-invoicing).
{% endhint %}


# Merchant side invoicing

Smarts offers merchant side invoice processing.

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General Flow

1. Customer scans products to shopping cart.
2. Smarts will send shopping cart to merchant when customer is ready to pay for the purchase.
3. Merchant will response with generated receipt
4. Customer will pay for receipt.
5. Smarts will send receipt payment confirmation to merchant.

### Configuration

Visit your store configuration page in Smarts manager UI. Switch store side invoicing to **ON** position and implement SDK required methods.

### Implementation

You only need to create a new class, implement **`ReceiptAdapter`** interface and fill all required methods.  API endpoints for merchant side invoicing are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.Entities.receipt.Receipt;
import ee.smarts.common.v1.requests.CreateReceiptRequest;
import ee.smarts.common.v1.requests.ReceiptPaymentConfirmationRequest;
import ee.smarts.starter.adapter.ReceiptAdapter;
import org.springframework.stereotype.Component;
@Component
public class ReceiptAdapterImpl implements ReceiptAdapter {
    @Override
    public Receipt create(CreateReceiptRequest request) {
        // implement this method
        return null;
    }
    @Override
    public void confirmationListener(ReceiptPaymentConfirmationRequest request) {
        // implement this method
    } 
}
```

{% hint style="info" %}
There is **additional step** for customer in payment process when using merchant side invoicing. Smarts shows generated receipt to customer before they are able to pay for the purchase.
{% endhint %}


# Merchant side purchase control

This functionality allows to get full control over the purchase check

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

*Purchase check rules are divided into two groups.*&#x20;

* **Product specific** rules will be sent along with product data request.&#x20;
* **Store based** rules can be configured in Smarts manager UI.&#x20;

### General Flow

* Smarts asks from merchant if the purchase check is needed by sending shopping cart information to merchant.
* Merchant will response with purchase check decision.&#x20;
  * Smarts will lock app and shows the purchase check notification to client.
* Merchant send the purchase check result to Smarts.
  * Smarts will unlock the  app
  * Purchase control supervisor is able to make changes from client shopping cart.
  * Purchase control supervisor is able to cancel the shopping process.
* After purchase check client will be directed to payment process.

{% hint style="danger" %}
App lock will **expire after 4 hours** and app will be unlocked.  This might be happen when client will not appear to purchase check or merchant will not send purchase check result back to Smarts.
{% endhint %}

### Configuration

Visit your store configuration page in Smarts manager UI. Switch merchant side purchase control to **ON** position and implement SDK required methods.

### Implementation

You only need to create a new class, implement **`PurchaseControlAdapter`** interface and fill all required methods.  API endpoints for purchase check are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.requests.PurchaseControlCheckRequest;
import ee.smarts.common.v1.responses.PurchaseControlCheckResponse;
import ee.smarts.starter.adapter.PurchaseControlAdapter;
import org.springframework.stereotype.Component;

@Component
public class PurchaseControlAdapterImpl implements PurchaseControlAdapter {
    @Override
    public PurchaseControlCheckResponse check(PurchaseControlCheckRequest request) {
        // implement this method
        return null;
    
} 
}
```

Send purchase check results back to Smarts by calling send method from`PurchaseControlResultSender`

```java
import ee.smarts.common.v1.requests.PurchaseControlCheckRequest;
import ee.smarts.common.v1.responses.PurchaseControlCheckResponse;
import ee.smarts.starter.adapter.PurchaseControlAdapter;
import org.springframework.stereotype.Component;
import lombok.RequiredArgsConstructor;

@Component
@RequiredArgsConstructor
public class PurchaseControlStoreSideSender{

    private final PurchaseControlResultSender resultSender
    
    public void sendResult(PurchaseControlResult result) {
        resultSender.send(result);
    } 
}
```


# Loyalty cards

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General Flow

* Smarts shows available loyalty cards in app.
* Client will select card and fill required fields to link loyalty cards.
* Merchant will verify loyalty card and send loyalty card information to Smarts
* Smarts will send loyalty card information along with request to get client based prices and offers.
* Bonus point system can be used in app and payment process.

### Configuration

* **Create and configure new loyalty card in Smarts manager UI.**
  * Choose loyalty card type (Default, Bonus, ... etc)
  * Choose stores where this card can be used
  * Choose validation methods.
    * Currently available: identification code, card number,  phone, email
* **Implement required SDK methods for loyalty card verification**

### Implementation

You only need to create a new class, implement **`LoyaltyCardAdapter`** interface and fill all required methods.  API endpoints for loyalty card services are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.Exceptions.LoyaltyCardException;
import ee.smarts.common.v1.requests.LoyaltyCardBonusRequest;
import ee.smarts.common.v1.requests.LoyaltyCardRegistrationRequest;
import ee.smarts.common.v1.responses.LoyaltyCardBonusResponse;
import ee.smarts.common.v1.responses.LoyaltyCardRegistrationResponse;
import ee.smarts.starter.adapter.LoyaltyCardAdapter;
import org.springframework.stereotype.Component;

@Component
public class LoyaltyCardAdapterImpl implements LoyaltyCardAdapter {

    @Override
    public LoyaltyCardRegistrationResponse register(LoyaltyCardRegistrationRequest request) throws LoyaltyCardException {
        // implement this method
        return null;
    }

    @Override
    public LoyaltyCardBonusResponse getLoyaltyCardBonus(LoyaltyCardBonusRequest request) throws LoyaltyCardException {
        // implement this method
        return null;
    }
}

```


# Home delivery

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General flow

Client flow

* add products into shopping cart
* choose delivery method and time
* authorize the payment

Merchant flow

* confirm or reject order
* process order and update order status

{% hint style="warning" %}
**The payment will be settled after merchant has been sent out the order !** This process is needed because merchant may not be able to fully fill the order due the out of stock products.
{% endhint %}

{% hint style="info" %}
The authorized payment **will be released** when merchant reject the order or authorization will be expired. Authorization expiration time is set by the card network.
{% endhint %}

### Configuration

**Configure home delivery via Smarts manager UI.**  Smarts supports 3 delivery methods: **courier, parcel, pickup by myself.** Home delivery can be fully customized. You can set delivery price, reaction time for each store, availability time and dates, location and much more.

**Implement required SDK methods for home delivery**

{% hint style="info" %}
**Smarts Worker App can be used to manage home delivery orders. (optional)**
{% endhint %}

### Implementation

You only need to create a new class, implement **`PickupAdapter`** interface and fill all required methods.  API endpoints for home delivery are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.Entities.pickup.Order;
import ee.smarts.starter.adapter.PickupAdapter;
import org.springframework.stereotype.Component;

@Component
public class PickupAdapterImpl implements PickupAdapter {

    @Override
    public void onUpdate(Order order) {
      // implement this method. Will used when order was update in Smarts system
      // or via Smarts Worker App
    }

    @Override
    public void onCreate(Order order) {
      // implement this method. listener for new Orders
    }
}
```

Use SmartsPickupExchange to update order status or get information from Smarts.

```java
import ee.smarts.common.global.type.ShipmentStatus;
import ee.smarts.common.v1.Entities.pickup.Order;
import ee.smarts.common.v1.Exceptions.PermissionDeniedException;
import ee.smarts.starter.services.pickup.SmartsPickupExchange;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;

@Component
@RequiredArgsConstructor
public class PickupOrderServiceImpl {

    private final SmartsPickupExchange pickupExchange;

    void testCommunicationWithSmarts() throws PermissionDeniedException {
        Order order0 = pickupExchange.updateOrderStatus("INSTITUTION_ID", "ORDER_ID", ShipmentStatus.ASSEMBLE_READY);

        Order order1 = pickupExchange.findOrderById("INSTITUTION_ID", "ORDER_ID");
        Order order2 = pickupExchange.findOrderByInstitutionInvoiceId("INSTITUTION_ID", "INSTITUTION_INVOICE_ID");
        Order order3 = pickupExchange.findOrderBySmartsInvoiceId("INSTITUTION_ID", "SMARTS_INVOICE_ID");

    }
}
```


# Marketing & Offers

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General flow

* Smarts shows marketing offers inside app after client log in to store.
* Client will tap to add the offer to shopping cart
* Client can accept more offers during the shopping process (tab will be available)
* **COMING SOON !** Cross-sale offer can be send along with product data which will be displayed after product has been added to shopping cart.

### Configuration

**Implement required SDK methods for offers and marketing.** There is no additional configuration needed at the moment.

### Implementation

You only need to create a new class, implement **`OfferAdapter`** interface and fill all required methods.  API endpoints for marketing are created automatically and secured with token.&#x20;

It is important to add `@Component` annotation on top of the class. There is no restriction for class name or location in your project. Our SDK will find your implementation based on the interface (DI).

```java
import ee.smarts.common.v1.Entities.offer.Offer;
import ee.smarts.common.v1.requests.OfferSearchRequest;
import ee.smarts.starter.adapter.OfferAdapter;
import org.springframework.stereotype.Component;
import java.util.List;

@Component
public class OfferServiceImpl implements OfferAdapter {

    @Override
    public List<Offer> searchOffers(OfferSearchRequest request) {
        // implement this method
        return null;
    }
}
```


# Custom Integration

Custom integration for any languages. Merchant must create all data -, request -and response objects for themselves. Merchant must create required rest endpoints for themselves.


# Overview

It is also welcome if you wish to do the pure integration by yourself.  For pure integration, you need to create API endpoints and data objects by yourself.

{% hint style="warning" %}
Smarts recommends [**Spring Boot Starter** ](/integration/spring-boot-starter/overview)integration which generates API-s and data objects **automatically**.
{% endhint %}

*There is minimum **3 steps** to get your store up and running.*

### **1.** [**Implement connection node endpoints**](/integration/custom-integration/connection-node)

### 2. [Implement product search endpoints](/integration/custom-integration/product-search-1)

### 3. [Implement invoice endpoints](/integration/spring-boot-starter/invoicing)

### Security

Smarts **ALWAYS** send store accessToken header along with request. Please validate every request before start processing it for security reasons.

### Additional services

Smarts allows also to

* [generate invoice in the merchant side](/integration/custom-integration/merchant-side-invoicing)
* [manage purchase check in the merchant side](/integration/custom-integration/merchant-side-purchase-control)
* [link and use loyalty cards](/integration/custom-integration/loyalty-cards)
* [home delivery](/integration/custom-integration/home-delivery)
* [show in-app offers](/integration/custom-integration/marketing-and-offers)

Those functionalities needs additional implementations and configuration. All configuration can be done in the Smarts UI.&#x20;


# Connection node

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

This endpoints are needed for Smarts to

* know if merchant communication node is UP and running
* get merchant communication node version

### Implementation

Implement following endpoints

[**Get node version endpoint**](/integration/custom-integration/connection-node/get-node-version-endpoint)

[**Get node health endpoint**](/integration/custom-integration/connection-node/get-node-health-endpoint)


# Get node version endpoint

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

**resource**:  /node/version

**method**:  *GET*

**Request** :  void

**Response**: [**NodeVersionResponse**](/general/request-and-responses/nodeversionresponse)

{% tabs %}
{% tab title="Response Example" %}

```
{
    "version": "1.0-SNAPSHOT"
}
```

{% endtab %}
{% endtabs %}


# Get node health endpoint

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

**resource**:  /node/health

**method**:  *GET*

**Request** :  void

**Response**: [**NodeHealthResponse**](/general/request-and-responses/nodehealthresponse)

{% tabs %}
{% tab title="Response Example" %}

```
{
    "status": "UP"
}
```

{% endtab %}
{% endtabs %}


# Product search

Implementing product search functionality

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

### Implementation

You need to create following endpoints to implement product search

[**Pageable product list search**](/integration/custom-integration/product-search-1/product-search)

[**Product barcode search**](/integration/custom-integration/product-search-1/product-bacrode-search)

[**Product name search**](/integration/custom-integration/product-search-1/product-name-search)

[**Product category search**](/integration/custom-integration/product-search-1/product-category-search)


# Pageable product list search endpoint

Pageable product search API

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

**resource**:  /product/search

**method**:  *POST*

**Request** :  [PageRequest](/general/request-and-responses/pagerequest)<[ProductSearchRequest](/general/request-and-responses/productsearchrequest)>

**Response**: [Pageable](/general/request-and-responses/pageable)<[Product](/general/data-object-description/product)>

{% tabs %}
{% tab title="Request Example" %}

```
{
    "page": 1,
    "limit": 50,
    "orderBy": "ACS",
    "orderFieldName": "barcode",
    "request": {
        "type": "SELF_SERVICE",
        "categoryName": "Teravi",
        "langCode": "ET",
        "personId": "1abcsd",
        "institutionId": "1ABCS"
    },
    "loyaltyCards": [
        {
            "id" : "1aBc",
            "cardNumber": "1234567",
            "useBonusOnPayment": false
        }
    ]
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
    "result": [
        {
            "id": "1ABC",
            "barcode": "ABC-abc-1234",
            "type": "SINGLE",
            "translatableName": {
                "originalText": "Helen Oats 500g",
                "translations": [
                    {
                        "ET": "Helen kiirkaeraheleb 500g"
                    }
                ]
            },
            "translatableDescription": {
                "originalText": "Oats made in Estonia",
                "translations": [
                    {
                        "ET": "Eestis toodetud kiirkaerahelbed"
                    }
                ]
            },
            "quantity": {
                "unit": "KILOGRAM",
                "value": "1.03"
            },
            "price": {
                "addition": {
                    "type": "DSC",
                    "sum": 1,
                    "rate": 10
                },
                "vat": {
                    "sumWithVAT": 12,
                    "sumWithoutVAT": 10,
                    "VATSum": 2,
                    "VATRate": 20
                },
                "total": 12
            },
            "weightItem": false,
            "information": {
                "imageUrl": "https://my.outs"
            },
            "inspections": [
                {
                    "action": "INSPECT",
                    "type" : "MIN_AGE",
                    "age": 18
                },
                {
                    "action": "RESTICT",
                    "type": "MAX_TIME",
                    "time": "22:00:00",
                    "timezone": "Europe/Tallinn"
                }
            ],
            "campaigns": [
                {
                    "name": "Big Discount Campaign",
                    "code": "B00000000501",
                    "operation": "total >= 50 ? total * 0.98 : total"
                }
            ],
            "subProducts": null,
            "categories": [
                {
                    "id": "1B",
                    "translatableName": {
                        "originalText": "Cereals",
                        "translations": [
                            {
                                "ET": "Teraviljad"
                            }
                        ]
                    },
                    "numberOfProducts":500,
                    "parentId": "1A"
                }
            ]
        }
    ],
    "lastPage": 100,
    "totalCount": 500
}
```

{% endtab %}
{% endtabs %}


# Product bacrode search endpoint

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

**resource**:  /product/search/barcode

**method**:  *POST*

**Request** :  [ProductSearchRequest](/general/request-and-responses/productsearchrequest)

**Response**: [Product](/general/data-object-description/product)

{% tabs %}
{% tab title="Request Example" %}

```
{
    "type": "SELF_SERVICE",
    "barcode": "1ABCS",
    "langCode": "ET",
    "personId": "1abcsd",
    "institutionId": "1ABCS"
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
	"id": "1ABC",
	"barcode": "ABC-abc-1234",
	"type": "SINGLE",
	"translatableName": {
		"originalText": "HelenOats500g",
		"translations": [
			{
				"ET": "Helenkiirkaeraheleb500g"
			}
		]
	},
	"translatableDescription": {
		"originalText": "OatsmadeinEstonia",
		"translations": [
			{
				"ET": "Eestistoodetudkiirkaerahelbed"
			}
		]
	},
	"quantity": {
		"unit": "KILOGRAM",
		"value": "1.03"
	},
	"price": {
		"addition": {
			"type": "DSC",
			"sum": 1,
			"rate": 10
		},
		"vat": {
			"sumWithVAT": 12,
			"sumWithoutVAT": 10,
			"VATSum": 2,
			"VATRate": 20
		},
		"total": 12
	},
	"weightItem": false,
	"information": {
		"imageUrl": "https: //my.outs"
	},
	"inspections": [
		{
			"action": "INSPECT",
			"type": "MIN_AGE",
			"age": 18
		},
		{
			"action": "RESTICT",
			"type": "MAX_TIME",
			"time": "22:00:00",
			"timezone": "Europe/Tallinn"
		}
	],
	"campaigns": [
		{
			"name": "BigDiscountCampaign",
			"code": "B00000000501",
			"operation": "total>=50?total*0.98: total"
		}
	],
	"subProducts": null,
	"categories": [
		{
			"id": "1B",
			"translatableName": {
				"originalText": "Cereals",
				"translations": [
					{
						"ET": "Teraviljad"
					}
				]
			},
			"numberOfProducts": 500,
			"parentId": "1A"
		}
	]
}
```

{% endtab %}
{% endtabs %}


# Product name search endpoint

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

**resource**:  /product/search/name

**method**:  *POST*

**Request** :  [ProductSearchRequest](/general/request-and-responses/productsearchrequest)

**Response**: List<[Product](/general/data-object-description/product)>

{% tabs %}
{% tab title="Request Example" %}

```
{
    "type": "SELF_SERVICE",
    "name": "Kiirka",
    "langCode": "ET",
    "personId": "1abcsd",
    "institutionId": "1ABCS"
}
```

{% endtab %}

{% tab title="Response Example" %}

```
[
	{
		"id": "1ABC",
		"barcode": "ABC-abc-1234",
		"type": "SINGLE",
		"translatableName": {
			"originalText": "HelenOats500g",
			"translations": [
				{
					"ET": "Helenkiirkaeraheleb500g"
				}
			]
		},
		"translatableDescription": {
			"originalText": "OatsmadeinEstonia",
			"translations": [
				{
					"ET": "Eestistoodetudkiirkaerahelbed"
				}
			]
		},
		"quantity": {
			"unit": "KILOGRAM",
			"value": "1.03"
		},
		"price": {
			"addition": {
				"type": "DSC",
				"sum": 1,
				"rate": 10
			},
			"vat": {
				"sumWithVAT": 12,
				"sumWithoutVAT": 10,
				"VATSum": 2,
				"VATRate": 20
			},
			"total": 12
		},
		"weightItem": false,
		"information": {
			"imageUrl": "https: //my.outs"
		},
		"inspections": [
			{
				"action": "INSPECT",
				"type": "MIN_AGE",
				"age": 18
			},
			{
				"action": "RESTICT",
				"type": "MAX_TIME",
				"time": "22: 00: 00",
				"timezone": "Europe/Tallinn"
			}
		],
		"campaigns": [
			{
				"name": "BigDiscountCampaign",
				"code": "B00000000501",
				"operation": "total>=50?total*0.98: total"
			}
		],
		"subProducts": null,
		"categories": [
			{
				"id": "1B",
				"translatableName": {
					"originalText": "Cereals",
					"translations": [
						{
							"ET": "Teraviljad"
						}
					]
				},
				"numberOfProducts": 500,
				"parentId": "1A"
			}
		]
	}
]
```

{% endtab %}
{% endtabs %}


# Product category search endpoint

{% hint style="danger" %}
Implementation is **REQUIRED**
{% endhint %}

**resource**:  /product/category

**method**:  *POST*

**Request** :  [InstitutionRequest](/general/request-and-responses/institutionrequest)

**Response**: [L](/general/request-and-responses/pageable)ist<[Category](/general/data-object-description/category)>

{% tabs %}
{% tab title="Request Example" %}

```
{

    "langCode": "ET",
    "personId": "1abcsd",
    "institutionId": "1ABCS"
}
```

{% endtab %}

{% tab title="Response Example" %}

```
[
	{
		"id": "1B",
		"translatableName": {
			"originalText": "Cereals",
			"translations": [
				{
					"ET": "Teraviljad"
				}
			]
		},
		"numberOfProducts": 500,
		"parentId": "1A"
	}
]
```

{% endtab %}
{% endtabs %}


# Invoicing

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

Smarts will store detailed confirmation invoice only for two months. So it is important to save detailed invoice copy.

### Implementation

Implement according endpoints

[**Receive invoice endpoint**](/integration/custom-integration/invoice/receive-invoice)


# Receive invoice endpoint

{% hint style="info" %}
Implementation is **OPTIONAL** (Recommended)
{% endhint %}

**resource**:  /invoice

**method**:  *POST*

**Request** :  [Invoice](/general/data-object-description/invoice)

**Response**: void

{% tabs %}
{% tab title="Request Example" %}

```
{
	"id": "1",
	"institutionInvoiceId": "1234",
	"seller": {
		"uniqueCode": "Smarts store unique ID",
		"sellerName": "Store name",
		"vatNumber": "1234",
		"regNumber": "1234",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartu mnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"buyer": {
		"uniqueCode": "SMARTS store unique client code",
		"loyaltyCards": [
			{
				"id": "1aBc",
				"cardNumber": "1234567",
				"useBonusOnPayment": false
			}
		]
	},
	"createdAt": "2020-01-01",
	"closedAt": "2020-01-01",
	"status": "PAYED",
	"products": [
		{
			"id": "1ABC",
			"barcode": "ABC-abc-1234",
			"type": "SINGLE",
			"translatableName": {
				"originalText": "HelenOats500g",
				"translations": [
					{
						"ET": "Helenkiirkaeraheleb500g"
					}
				]
			},
			"translatableDescription": {
				"originalText": "OatsmadeinEstonia",
				"translations": [
					{
						"ET": "Eestistoodetudkiirkaerahelbed"
					}
				]
			},
			"quantity": {
				"unit": "KILOGRAM",
				"value": "1.03"
			},
			"price": {
				"addition": {
					"type": "DSC",
					"sum": 1,
					"rate": 10
				},
				"vat": {
					"sumWithVAT": 12,
					"sumWithoutVAT": 10,
					"VATSum": 2,
					"VATRate": 20
				},
				"total": 12
			},
			"weightItem": false,
			"information": {
				"imageUrl": "https: //my.outs"
			},
			"inspections": [
				{
					"action": "INSPECT",
					"type": "MIN_AGE",
					"age": 18
				},
				{
					"action": "RESTICT",
					"type": "MAX_TIME",
					"time": "22:00:00",
					"timezone": "UTF-2"
				}
			],
			"campaigns": [
				{
					"name": "BigDiscountCampaign",
					"code": "B00000000501",
					"operation": "total>=50?total*0.98: total"
				}
			],
			"subProducts": null,
			"categories": [
				{
					"id": "1B",
					"translatableName": {
						"originalText": "Cereals",
						"translations": [
							{
								"ET": "Teraviljad"
							}
						]
					},
					"numberOfProducts": 500,
					"parentId": "1A"
				}
			]
		}
	],
	"institutionCampaigns": [
		{
			"name": "Crazy days",
			"code": "C00000SKP001",
			"operation": "amount >= 2 ? amount - (Math.floor(amount / 2) * 1) : amount"
		}
	],
	"currency": "EUR",
	"shipment": {
		"method": "COURIER",
		"status": "WAITING_FOR_CONFIRMATION",
		"price": 5,
		"currency": "EUR",
		"expectedDeliveryUTCTime": "2020-04-14T17:45:55.948353600",
		"createdUTCTime": "2020-04-15T17:45:55.948353600",
		"contactEmail": "test@test.ee",
		"contactPhone": "56314762",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartu mnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"total": {
		"vat": {
			"sumWithVAT": 18,
			"sumWithoutVAT": 15,
			"VATSum": 3
		},
		"totalToPay": 18
	},
	"timeZone": "UTF-2"
}
```

{% endtab %}
{% endtabs %}


# Merchant side invoicing

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General Flow

1. Customer scans products to shopping cart.
2. Smarts will send shopping cart to merchant when customer is ready to pay for the purchase.
3. Merchant will response with generated receipt
4. Customer will pay for receipt.
5. Smarts will send receipt payment confirmation to merchant.

### Configuration

Visit your store configuration page in Smarts manager UI. Switch store side invoicing to **ON** position and implement required endpoints.

### Implementation

Implement following endpoints

[**Create receipt endpoint**](/integration/custom-integration/merchant-side-invoicing/create-receipt)

[**Confirm receipt payment endpoint**](/integration/custom-integration/merchant-side-invoicing/confirm-receipt-payment)


# Create receipt endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /receipt

**method**:  *POST*

**Request** :  [**CreateReceiptRequest**](/general/request-and-responses/createreceiptrequest)

**Response**: [**Receipt**](/general/data-object-description/receipt)

{% tabs %}
{% tab title="Request Example" %}

```
{
	"invoiceId": "5bd5c446ad950100018a79c0",
	"personId": "0bcae298-867c-41af-9980-be0d8e828d3e",
	"institutionId": "0bcae304-867c-41af-9980-be0d8e828d4s",
	"langCode": "ET",
	"products": [
		{
			"id": "1ABC",
			"barcode": "ABC-abc-1234",
			"type": "SINGLE",
			"translatableName": {
				"originalText": "Helen Oats 500g",
				"translations": [
					{
						"ET": "Helen kiirkaeraheleb 500g"
					}
				]
			},
			"translatableDescription": {
				"originalText": "Oats made in Estonia",
				"translations": [
					{
						"ET": "Eestis toodetud kiirkaerahelbed"
					}
				]
			},
			"quantity": {
				"unit": "KILOGRAM",
				"value": "1.03"
			},
			"price": {
				"addition": {
					"type": "DSC",
					"sum": 1,
					"rate": 10
				},
				"vat": {
					"sumWithVAT": 12,
					"sumWithoutVAT": 10,
					"VATSum": 2,
					"VATRate": 20
				},
				"total": 12
			},
			"weightItem": false,
			"information": {
				"imageUrl": "https://my.outs"
			},
			"inspections": [
				{
					"type": "MIN_AGE",
					"age": 18
				},
				{
					"type": "MAX_TIME",
					"time": "22:00:00",
					"timezone": "Europe/Tallinn"
				}
			],
			"campaigns": [
				{
					"name": "Big Discount Campaign",
					"code": "B00000000501",
					"operation": "total >= 50 ? total * 0.98 : total"
				}
			],
			"subProducts": null,
			"categories": [
				{
					"id": "1B",
					"translatableName": {
						"originalText": "Cereals",
						"translations": [
							{
								"ET": "Teraviljad"
							}
						]
					},
					"numberOfProducts": 500,
					"parentId": "1A"
				}
			]
		}
	],
	"shipment": {
		"method": "PARCEL",
		"parcelId": "1ABSC",
		"name": "Ravala street parcel",
		"status": "WAITING_FOR_CONFIRMATION",
		"price": 5,
		"currency": "EUR",
		"expectedDeliveryUTCTime": "2019-04-20T19:30:00.000Z",
		"createdUTCTime": "2019-04-22T19:30:00.000Z",
		"contactEmail": "test@test.ee",
		"contactPhone": "56314762",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartu mnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"loyaltyCards": [
		{
			"id": "1aBc",
			"cardNumber": "1234567",
			"useBonusOnPayment": false
		}
	]
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
	"institutionInvoiceId": "12345",
	"invoiceId": "5bd5c446ad950100018a79c0",
	"institutionId": "0bcae304-867c-41af-9980-be0d8e828d4s",
	"customerId": "0bcae298-867c-41af-9980-be0d8e828d3e",
	"products": [
		{
			"id": "1ABC",
			"barcode": "ABC-abc-1234",
			"productName": "Helen kiirkaeraheleb 500g",
			"amount": "1.03",
			"rowPrice": "12",
			"categories": [
				{
					"id": "C1",
					"name": "Teraviljad"
				}
			]
		}
	],
	"loyaltyCards": [
		{
			"name": "BonusCard",
			"lastFourNumbers": "1234567"
		}
	],
	"shipment": {
		"method": "PARCEL",
		"parcelId": "1ABSC",
		"name": "Ravala street parcel",
		"status": "WAITING_FOR_CONFIRMATION",
		"price": 5,
		"currency": "EUR",
		"expectedDeliveryUTCTime": "2019-04-20T19: 30: 00.000Z",
		"createdUTCTime": "2019-04-22T19: 30: 00.000Z",
		"contactEmail": "test@test.ee",
		"contactPhone": "56314762",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartumnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"currency": "EUR",
	"totalWithoutAddition": 11,
	"additionSum": 1,
	"totalWithoutVAT": 10,
	"vatSum": 2,
	"total": 12
}
```

{% endtab %}
{% endtabs %}


# Confirm receipt payment endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /receipt/confirm

**method**:  *POST*

**Request** :  [**ReceiptPaymentConfirmationRequest**](/general/request-and-responses/receiptpaymentconfirmationrequest)

**Response**: void

{% tabs %}
{% tab title="Request Example" %}

```
{
	"receipt": {
		"institutionInvoiceId": "12345",
		"invoiceId": "5bd5c446ad950100018a79c0",
		"institutionId": "0bcae304-867c-41af-9980-be0d8e828d4s",
		"customerId": "0bcae298-867c-41af-9980-be0d8e828d3e",
		"products": [
			{
				"id": "1ABC",
				"barcode": "ABC-abc-1234",
				"productName": "Helen kiirkaeraheleb 500g",
				"amount": "1.03",
				"rowPrice": "12",
				"categories": [
					{
						"id": "C1",
						"name": "Teraviljad"
					}
				]
			}
		],
		"loyaltyCards": [
			{
				"name": "BonusCard",
				"lastFourNumbers": "1234567"
			}
		],
		"shipment": {
			"method": "PARCEL",
			"parcelId": "1ABSC",
			"name": "Ravala street parcel",
			"status": "WAITING_FOR_CONFIRMATION",
			"price": 5,
			"currency": "EUR",
			"expectedDeliveryUTCTime": "2019-04-20T19: 30: 00.000Z",
			"createdUTCTime": "2019-04-22T19: 30: 00.000Z",
			"contactEmail": "test@test.ee",
			"contactPhone": "56314762",
			"address": {
				"level1": "EE",
				"level2": "Harjumaa",
				"level3": "Tallinn",
				"level4": "kesklinn",
				"level5": "Tartumnt.",
				"level6": "53",
				"level7": null,
				"level8": null,
				"postalCode": "10115"
			}
		},
		"currency": "EUR",
		"totalWithoutAddition": 11,
		"additionSum": 1,
		"totalWithoutVAT": 10,
		"vatSum": 2,
		"total": 12
	},
	"status": "PAYED"
}
```

{% endtab %}
{% endtabs %}


# Merchant side purchase control

This functionality allows to get full control over the purchase check

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

*Purchase check rules are divided into two groups.*&#x20;

* **Product specific** rules will be send along with product data request.&#x20;
* **Store based** rules can be configured in Smarts manager UI.&#x20;

### General Flow

* Smarts asks from merchant if the purchase check is needed by sending shopping cart information to merchant.
* Merchant will response with purchase check decision.&#x20;
  * Smarts will lock app and shows the purchase check notification to client.
* Merchant send the purchase check result to Smarts.
  * Smarts will unlock the  app
  * Purchase control supervisor is able to make changes from client shopping cart.
  * Purchase control supervisor is able to cancel the shopping process.
* After purchase check client will be directed to payment process.

{% hint style="danger" %}
App lock will **expire after 4 hours** and app will be unlocked.  This might be happen when client will not appear to purchase check or merchant will not send purchase check result back to Smarts.
{% endhint %}

### Configuration

Visit your store configuration page in Smarts manager UI. Switch merchant side purchase control to **ON** position and implement required endpoints.

### Implementation

Implement following endpoints

[**Receive purchase check endpoint**](/integration/custom-integration/merchant-side-purchase-control/receive-purchase-check-request)

[**Send purchase check result to Smarts**](/integration/custom-integration/merchant-side-purchase-control/send-purchase-check-result)

[**Ask for purchase check resend from Smarts**](/integration/custom-integration/merchant-side-purchase-control/ask-for-purchase-check-data-resend)


# Receive purchase check endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /control/check

**method**:  *POST*

**Request** :  [PurchaseControlCheckRequest](/general/request-and-responses/purchasecontrolcheckrequest)

**Response**: [PurchaseControlCheckResponse](/general/request-and-responses/purchasecontrolcheckresponse)

{% tabs %}
{% tab title="Request Example" %}

```
{
	"invoiceId": "5bd5c446ad950100018a79c0",
	"personId": "0bcae298-867c-41af-9980-be0d8e828d3e",
	"institutionId": "0bcae304-867c-41af-9980-be0d8e828d4s",
	"langCode": "ET",
	"products": [
		{
			"id": "1ABC",
			"barcode": "ABC-abc-1234",
			"type": "SINGLE",
			"translatableName": {
				"originalText": "Helen Oats 500g",
				"translations": [
					{
						"ET": "Helen kiirkaeraheleb 500g"
					}
				]
			},
			"translatableDescription": {
				"originalText": "Oats made in Estonia",
				"translations": [
					{
						"ET": "Eestis toodetud kiirkaerahelbed"
					}
				]
			},
			"quantity": {
				"unit": "KILOGRAM",
				"value": "1.03"
			},
			"price": {
				"addition": {
					"type": "DSC",
					"sum": 1,
					"rate": 10
				},
				"vat": {
					"sumWithVAT": 12,
					"sumWithoutVAT": 10,
					"VATSum": 2,
					"VATRate": 20
				},
				"total": 12
			},
			"weightItem": false,
			"information": {
				"imageUrl": "https://my.outs"
			},
			"inspections": [
				{
					"type": "MIN_AGE",
					"age": 18
				},
				{
					"type": "MAX_TIME",
					"time": "22:00:00",
					"timezone": "Europe/Tallinn"
				}
			],
			"campaigns": [
				{
					"name": "Big Discount Campaign",
					"code": "B00000000501",
					"operation": "total >= 50 ? total * 0.98 : total"
				}
			],
			"subProducts": null,
			"categories": [
				{
					"id": "1B",
					"translatableName": {
						"originalText": "Cereals",
						"translations": [
							{
								"ET": "Teraviljad"
							}
						]
					},
					"numberOfProducts": 500,
					"parentId": "1A"
				}
			]
		}
	],
	"shipment": {
		"method": "PARCEL",
		"parcelId": "1ABSC",
		"name": "Ravala street parcel",
		"status": "WAITING_FOR_CONFIRMATION",
		"price": 5,
		"currency": "EUR",
		"expectedDeliveryUTCTime": "2019-04-20T19:30:00.000Z",
		"createdUTCTime": "2019-04-22T19:30:00.000Z",
		"contactEmail": "test@test.ee",
		"contactPhone": "56314762",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartu mnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"loyaltyCards": [
		{
			"id": "1aBc",
			"cardNumber": "1234567",
			"useBonusOnPayment": false
		}
	]
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
	"decision": "AGE"
}
```

{% endtab %}
{% endtabs %}


# Send purchase check result

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

{% hint style="warning" %}
**Reversed direction - Send to Smarts**
{% endhint %}

**resource**:  <https://gateway.smarts.ee/v1/control/result>

**method**:  *POST*

***headers:*** &#x20;

| ***Header*** | Value                            |
| ------------ | -------------------------------- |
| accessToken  | YOUR\_INSTITUTION\_ACCESS\_TOKEN |
| Content-Type | application/json;charset=UTF-8   |

**Request body** :  [**PurchaseControlResult**](/general/request-and-responses/purchasecontrolresult)

**Response**: void


# Ask for purchase check data resend

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

{% hint style="warning" %}
**Reversed direction - Send to Smarts**
{% endhint %}

**resource**:  <https://gateway.smarts.ee/v1/control/resend>

**method**:  *POST*

***headers:*** &#x20;

| ***Header*** | Value                            |
| ------------ | -------------------------------- |
| accessToken  | YOUR\_INSTITUTION\_ACCESS\_TOKEN |
| Content-Type | application/json;charset=UTF-8   |

**Request body**:  [**PurchaseControlCheckResendRequest**](/general/request-and-responses/purchasecontrolcheckresendrequest)

**Response**: [**PurchaseControlCheckRequest**](/general/request-and-responses/purchasecontrolcheckrequest)


# Loyalty cards

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General Flow

* Smarts shows available loyalty cards in app.
* Client will select card and fill required fields to link loyalty cards.
* Merchant will verify loyalty card and send loyalty card information to Smarts
* Smarts will send loyalty card information along with request to get client based prices and offers.
* Bonus point system can be used in app and payment process.

### Configuration

* **Create and configure new loyalty card in Smarts manager UI.**
  * Choose loyalty card type (Default, Bonus, ... etc)
  * Choose stores where this card can be used
  * Choose validation methods.
    * Currently available: identification code, card number,  phone email
* **Implement required endpoints for loyalty card**&#x20;

### **Implementation**

Implement according endpoints

[**Loyalty card registration endpoint**](/integration/custom-integration/loyalty-cards/loyalty-card-registration-endpoint)

[**Loyalty card bonus endpoint**](/integration/custom-integration/loyalty-cards/loyalty-card-bonus-endpoint)


# Loyalty card registration endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /card/loyalty

**method**:  *POST*

**Request** :  [**LoyaltyCardRegistrationRequest**](/general/request-and-responses/loyaltycardregistrationrequest)

**Response**: [**LoyaltyCardRegistrationResponse**](/general/request-and-responses/loyaltycardregistrationresponse)

{% tabs %}
{% tab title="Request Example" %}

```
{
	"loyaltyCard": {
		"id": "1234",
		"imageId": null,
		"type": "BONUS",
		"canUseBonusPointsForPayment": true,
		"name": {
			"originalText": "Bonus card",
			"translations": [
				{
					"ET": "Boonus kaart"
				}
			]
		},
		"description": {
			"originalText": "For special clients",
			"translations": [
				{
					"ET": "Preemiumkliendi kaart"
				}
			]
		},
		"validationTypes": [
			"CARD_NUMER",
			"IDCODE"
		],
		"colorTheme": "DARK",
		"primary": true,
		"colors": [
			"#fff",
			"#000"
		]
	},
	"value": "22103944833292",
	"personId": "123545454",
	"personEmail": "test@test.ee",
	"personName": "TestUser"
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
	"cardNumber": "22103944833292",
	"validFrom": "2019-02-01",
	"validTo": "2022-01-31"
}
```

{% endtab %}
{% endtabs %}


# Loyalty card bonus endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /card/loyalty/bonus

**method**:  *POST*

**Request** :  [**LoyaltyCardBonusRequest**](/general/request-and-responses/loyaltycardbonusrequest)

**Response**: [**LoyaltyCardBonusResponse**](/general/request-and-responses/loyaltycardbonusresponse)

{% tabs %}
{% tab title="Request Example" %}

```
{
	"loyaltyCard": {
		"id": "12345",
		"cardNumber: "22103944833292",
		"useBonusOnPayment": false
	},
	"personId": "123545454",
	"personEmail": "test@test.ee",
	"personName": "TestUser"
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
	"bonus": 221
}
```

{% endtab %}
{% endtabs %}


# Home delivery

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General flow

Client flow

* add products into shopping cart
* choose delivery method and time
* authorize the payment

Merchant flow

* confirm or reject order
* process order and update order status

{% hint style="warning" %}
**The payment will be settled after merchant has been sent out the order !** This process is needed because merchant may not be able to fully fill the order due the out of stock products.
{% endhint %}

{% hint style="info" %}
The authorized payment **will be release** when merchant reject the order or authorization will be expired. Authorization expiration time is set by the card network.
{% endhint %}

### Configuration

**Configure home delivery via Smarts manager UI.**  Smarts supports 3 delivery methods: **courier, parcel, pickup by myself.** Home delivery can be fully customized. You can set delivery price, reaction time for each store, availability time and dates, location and much more.

**Implement required endpoints for home delivery**

{% hint style="info" %}
**Smarts Worker App can be used also to manage home delivery orders**&#x20;
{% endhint %}

### Implementation

Create following endpoints

[**Receive order endpoint**](/integration/custom-integration/home-delivery/receive-order-endpoint)

[**Receive order update endpoint**](/integration/custom-integration/home-delivery/receive-order-update-endpoint)

Create following services to send and request order information from Smarts.

[**Update order status**](/integration/custom-integration/home-delivery/update-order-status)

[**Find order by id**](/integration/custom-integration/home-delivery/find-order-by-id)

[**Find order by invoice id**](/integration/custom-integration/home-delivery/find-order-by-invoice-id)

[**Find order by institution invoice id**](/integration/custom-integration/home-delivery/find-order-by-institution-invoice-id)


# Receive order endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /pickup/order

**method**:  *POST*

**Request** :  [**Order**](/general/data-object-description/order)

**Response**: **void**

{% tabs %}
{% tab title="Request Example" %}

```
{
	"id": "25252525",
	"customerId": "25325",
	"invoiceId": "36536363563",
	"institutionId: "20494",
	"institutionInvoiceId": "323232342",
	"resolverId": "abc323",
	"shipment": {
		"method": "PARCEL",
		"parcelId": "1ABSC",
		"name": "Ravala street parcel",
		"status": "WAITING_FOR_CONFIRMATION",
		"price": 5,
		"currency": "EUR",
		"expectedDeliveryUTCTime": "2019-04-20T19:30:00.000Z",
		"createdUTCTime": "2019-04-22T19:30:00.000Z",
		"contactEmail": "test@test.ee",
		"contactPhone": "56314762",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartu mnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"products": [
			{
				"id": "1ABC",
				"barcode": "ABC-abc-1234",
				"productName": "Helen kiirkaeraheleb 500g",
				"amount": "1.03",
				"rowPrice": "12",
				"categories": [
					{
						"id": "C1",
						"name": "Teraviljad"
					}
				]
			}
		],
	"currency": "EUR",
	"orderTotalPrice": 17,
	"create": "2020-04-04",
	"closed": "2020-04-04",
	"statusChangelogs": [
		{
			"personName": "Test Employee",
			"previousStatus": "WAITING_FOR_CONFIRMATION",
			"newStatus": "CONFIRMED",
			"created": "2020-04-04"
		}
	]
}
```

{% endtab %}
{% endtabs %}


# Receive order update endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /pickup/order

**method**:  *PUT*

**Request** :  [**Order**](/general/data-object-description/order)

**Response**: **void**

{% tabs %}
{% tab title="Request Example" %}

```
{
	"id": "25252525",
	"customerId": "25325",
	"invoiceId": "36536363563",
	"institutionId: "20494",
	"institutionInvoiceId": "323232342",
	"resolverId": "abc323",
	"shipment": {
		"method": "PARCEL",
		"parcelId": "1ABSC",
		"name": "Ravala street parcel",
		"status": "WAITING_FOR_CONFIRMATION",
		"price": 5,
		"currency": "EUR",
		"expectedDeliveryUTCTime": "2019-04-20T19:30:00.000Z",
		"createdUTCTime": "2019-04-22T19:30:00.000Z",
		"contactEmail": "test@test.ee",
		"contactPhone": "56314762",
		"address": {
			"level1": "EE",
			"level2": "Harjumaa",
			"level3": "Tallinn",
			"level4": "kesklinn",
			"level5": "Tartu mnt.",
			"level6": "53",
			"level7": null,
			"level8": null,
			"postalCode": "10115"
		}
	},
	"products": [
			{
				"id": "1ABC",
				"barcode": "ABC-abc-1234",
				"productName": "Helen kiirkaeraheleb 500g",
				"amount": "1.03",
				"rowPrice": "12",
				"categories": [
					{
						"id": "C1",
						"name": "Teraviljad"
					}
				]
			}
		],
	"currency": "EUR",
	"orderTotalPrice": 17,
	"create": "2020-04-04",
	"closed": "2020-04-04",
	"statusChangelogs": [
		{
			"personName": "Test Employee",
			"previousStatus": "WAITING_FOR_CONFIRMATION",
			"newStatus": "CONFIRMED",
			"created": "2020-04-04"
		}
	]
}
```

{% endtab %}
{% endtabs %}


# Update order status

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

{% hint style="warning" %}
**Reversed direction - Send to Smarts**
{% endhint %}

**resource**:  <https://gateway.smarts.ee/v1/pickup/external/institution/${YOUR\\_INSTITUTION\\_ID}/order/${ORDER\\_ID}/status>

**method**:  *POST*

***headers:*** &#x20;

| ***Header*** | Value                            |
| ------------ | -------------------------------- |
| accessToken  | YOUR\_INSTITUTION\_ACCESS\_TOKEN |
| Content-Type | application/json;charset=UTF-8   |

**Request body** : [**PickupOrderStatusChangeRequest**](/general/request-and-responses/pickuporderstatuschangerequest)

**Response**: [**Order**](/general/data-object-description/order)


# Find order by id

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

{% hint style="warning" %}
**Reversed direction - Send to Smarts**
{% endhint %}

**resource**:  <https://gateway.smarts.ee/v1/pickup/external/institution/${YOUR\\_INSTITUTION\\_ID}/order/${ORDER\\_ID}>

**method**:  *GET*

***headers:*** &#x20;

| ***Header*** | Value                            |
| ------------ | -------------------------------- |
| accessToken  | YOUR\_INSTITUTION\_ACCESS\_TOKEN |
| Content-Type | application/json;charset=UTF-8   |

**Request body** : void

**Response**: [**Order**](/general/data-object-description/order)


# Find order by invoice id

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

{% hint style="warning" %}
**Reversed direction - Send to Smarts**
{% endhint %}

**resource**:  <https://gateway.smarts.ee/v1/pickup/external/institution/${YOUR\\_INSTITUTION\\_ID}/order>

**query parameters:**

| **Parameter** | Value                |
| ------------- | -------------------- |
| field         | invoiceId            |
| value         | ${YOUR\_INVOICE\_ID} |

**method**:  *GET*

***headers:*** &#x20;

| ***Header*** | Value                               |
| ------------ | ----------------------------------- |
| accessToken  | ${YOUR\_INSTITUTION\_ACCESS\_TOKEN} |
| Content-Type | application/json;charset=UTF-8      |

**Request body** : void

**Response**: [**Order**](/general/data-object-description/order)


# Find order by institution invoice id

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

{% hint style="warning" %}
**Reversed direction - Send to Smarts**
{% endhint %}

**resource**:  <https://gateway.smarts.ee/v1/pickup/external/institution/${YOUR\\_INSTITUTION\\_ID}/order>

**query parameters:**

| **Parameter** | Value                             |
| ------------- | --------------------------------- |
| field         | institutionInvoiceId              |
| value         | ${YOUR\_INSTITUTION\_INVOICE\_ID} |

**method**:  *GET*

***headers:*** &#x20;

| ***Header*** | Value                               |
| ------------ | ----------------------------------- |
| accessToken  | ${YOUR\_INSTITUTION\_ACCESS\_TOKEN} |
| Content-Type | application/json;charset=UTF-8      |

**Request body** : void

**Response**: [**Order**](/general/data-object-description/order)


# Marketing & Offers

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

### General flow

* Smarts shows marketing offers inside app after client log in to store.
* Client will tap to add the product to shopping cart
* Client can accept more offers during the shopping process (tab will be available)
* **COMING SOON !** Cross-sale offer can be send along with product data which will be displayed after product has been added to shopping cart.

### Configuration

**Implement required endpoints for offers and marketing.** There is no additional configuration needed at the moment.

### **Implementation**

Implement following endpoints

[**Find offers endpoint**](/integration/custom-integration/marketing-and-offers/find-offers-endpoint)


# Find offers endpoint

{% hint style="info" %}
Implementation is **OPTIONAL**
{% endhint %}

**resource**:  /offer

**method**:  *POST*

**Request** :  [**OfferSearchRequest**](/general/request-and-responses/offersearchrequest)

**Response**: **List<**[**DefaultOffer**](/general/data-object-description/defaultoffer)**> OR List<**[**DiscountOffer**](/general/data-object-description/discountoffer)**> OR List<**[**ProductRelatedOffer**](/general/data-object-description/productrelatedoffer)**>**

{% tabs %}
{% tab title="Request Example" %}

```
{
	"personId": "0bcae298-867c-41af-9980-be0d8e828d3e",
	"institutionId": "0bcae304-867c-41af-9980-be0d8e828d4s",
	"langCode": "ET",
	"classification": "PERSONAL",
	"loyaltyCards": [
		{
			"id": "12345",
			"cardNumber": "22103944833292",
			"useBonusOnPayment": false
		}
	]
}
```

{% endtab %}

{% tab title="Response Example" %}

```
{
	"id": "1234",
	"type": "DISCOUNT",
	"discountPercentage": 20,
	"offerPrice": 10,
	"defaultPrice": 12,
	"title": {
		"originalText": "Crazy bonus offer",
		"translations": [
			{
				"ET": "Hull boonus pakkumine"
			}
		]
	},
	"imageUri": "https://myimageurl.com",
	"startDate": "2020-05-04",
	"endDate": "2020-06-04"
}
```

{% endtab %}
{% endtabs %}


# Data object descriptions

List of used data transfer objects


# HealthStatus

| HealthStatus         |                              |
| -------------------- | ---------------------------- |
| UP                   | Node is up                   |
| DOWN                 | Node is down                 |
| INVALID\_CREDENTIALS | Invalid credentials provided |


# DefaultOffer

### Object description

| Field     | Type                                                          | Required | Description                        |
| --------- | ------------------------------------------------------------- | -------- | ---------------------------------- |
| id        | String                                                        | Yes      | Offer identifier                   |
| title     | [Translatable](/general/data-object-description/translatable) | Yes      | Offer title                        |
| startDate | String                                                        | No       | Offer start date format YYYY-MM-DD |
| endDate   | String                                                        | No       | Offer end date format YYYY-MM-DD   |
| type      | [OfferType](/general/data-object-description/offertype)       | Yes      | Offer type = DEFAULT               |
| imageUri  | String                                                        | Yes      | Offer image location               |


# DiscountOffer

### Object description

| Field              | Type                                                          | Required | Description                        |
| ------------------ | ------------------------------------------------------------- | -------- | ---------------------------------- |
| id                 | String                                                        | Yes      | Offer identifier                   |
| title              | [Translatable](/general/data-object-description/translatable) | Yes      | Offer title                        |
| startDate          | String                                                        | No       | Offer start date format YYYY-MM-DD |
| endDate            | String                                                        | No       | Offer end date format YYYY-MM-DD   |
| type               | [OfferType](/general/data-object-description/offertype)       | Yes      | Offer type = DISCOUNT              |
| imageUri           | String                                                        | Yes      | Offer image location               |
| discountPercentage | int                                                           | Yes      | Discount percentage                |
| offerPrice         | double                                                        | Yes      | Discount product price             |
| defaultPrice       | double                                                        | Yes      | Standard product price             |


# ProductRelatedOffer

### Object description

| Field          | Type                                                          | Required | Description                        |
| -------------- | ------------------------------------------------------------- | -------- | ---------------------------------- |
| id             | String                                                        | Yes      | Offer identifier                   |
| title          | [Translatable](/general/data-object-description/translatable) | Yes      | Offer title                        |
| startDate      | String                                                        | No       | Offer start date format YYYY-MM-DD |
| endDate        | String                                                        | No       | Offer end date format YYYY-MM-DD   |
| type           | [OfferType](/general/data-object-description/offertype)       | Yes      | Offer type = PRODUCT\_RELATED      |
| relatedProduct | [Product](/general/data-object-description/product)           | Yes      | Related product                    |


# OfferType

| ColorTheme       |                       |
| ---------------- | --------------------- |
| PRODUCT\_RELATED | Product related offer |
| DISCOUNT         | Discount offer        |
| DEFAULT          | Default offer         |


# OfferClassification

| OfferClassification |                |
| ------------------- | -------------- |
| PERSONAL            | Personal offer |
| CAMPAIGN            | Campaign offer |


# Order

### Object description

| Field                | Type                                                                                | Required | Description                         |
| -------------------- | ----------------------------------------------------------------------------------- | -------- | ----------------------------------- |
| id                   | String                                                                              | Yes      | Shipping order id                   |
| customerId           | String                                                                              | Yes      | Smarts customer unique identifier   |
| institutionId        | String                                                                              | Yes      | Smarts store unique identifier      |
| institutionInvoiceId | String                                                                              | No       | Merchant unique invoice id          |
| resolverId           | String                                                                              | No       | Merchant employee id                |
| shipment             | [Shipment](/general/data-object-description/shipment)                               | Yes      | Shipment details                    |
| products             | List<[ReceiptProduct](/general/data-object-description/receiptproduct)>             | Yes      | Product information                 |
| currency             | Currency                                                                            | Yes      | Order currency                      |
| orderTotalPrice      | double                                                                              | Yes      | Order total price                   |
| created              | String                                                                              | Yes      | Created date format YYYY-MM-DD      |
| closed               | String                                                                              | Yes      | Closed date format YYYY-MM-DD       |
| statusChangelogs     | List<[OrderStatusChangeLog](/general/data-object-description/orderstatuschangelog)> | Yes      | Historical logs about order changes |


# OrderStatusChangeLog

### Object description

| Field          | Type                                                              | Required | Description                      |
| -------------- | ----------------------------------------------------------------- | -------- | -------------------------------- |
| personName     | String                                                            | Yes      | Change author name               |
| previousStatus | [ShipmentStatus](/general/data-object-description/shipmentstatus) | Yes      | Previous order status            |
| newStatus      | [ShipmentStatus](/general/data-object-description/shipmentstatus) | Yes      | New order status                 |
| created        | String                                                            | Yes      | Creation date FORMAT  YYYY-MM-DD |


# ColorTheme

| ColorTheme |                    |
| ---------- | ------------------ |
| DARK       | Dark colour theme  |
| LIGHT      | Light colour theme |


# LoyaltyCard

### Object description

| Field             | Type    | Required | Description                                 |
| ----------------- | ------- | -------- | ------------------------------------------- |
| id                | String  | Yes      | Loyalty card identifier                     |
| cardNumber        | String  | Yes      | Loyalty card number                         |
| useBonusOnPayment | Boolean | Yes      | Can be used bonus points in payment process |


# DefaultLoyaltyCard

### Object description

| Field          | Type                                                                                          | Required | Description                                 |
| -------------- | --------------------------------------------------------------------------------------------- | -------- | ------------------------------------------- |
| type           | [LoyaltyCardType](/general/data-object-description/loyaltycardtype)                           | Yes      | Type of the card - DEFAULT                  |
| id             | String                                                                                        | Yes      | Smarts loyalty card unique id               |
| imageId        | String                                                                                        | No       | Smarts loyalty card image unique identifier |
| name           | [Translatable](/general/data-object-description/translatable)                                 | Yes      | Loyalty card name                           |
| description    | [Translatable](/general/data-object-description/translatable)                                 | No       | Loyalty card description                    |
| validationType | List<[LoyaltyCardValidationType](/general/data-object-description/loyaltycardvalidationtype)> | Yes      | Possible loyalty card verification types    |
| colorTheme     | [ColorTheme](/general/data-object-description/colortheme)                                     | Yes      | Loyalty card colour theme                   |
| primary        | Boolean                                                                                       | Yes      | Check if is primary loyalty card            |
| colors         | [L](/general/data-object-description/address)ist\<String>                                     | Yes      | Loyalty card background colour HEX list     |


# BonusLoyaltyCard

### Object description

| Field                       | Type                                                                                          | Required | Description                                          |
| --------------------------- | --------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| canUseBonusPointsForPayment | Boolean                                                                                       | Yes      | show if bonus points can be used in payment process  |
| type                        | [LoyaltyCardType](/general/data-object-description/loyaltycardtype)                           | Yes      | Type of the card - BONUS                             |
| id                          | String                                                                                        | Yes      | Smarts loyalty card unique id                        |
| imageId                     | String                                                                                        | No       | Smarts loyalty card image unique identifier          |
| name                        | [Translatable](/general/data-object-description/translatable)                                 | Yes      | Loyalty card name                                    |
| description                 | [Translatable](/general/data-object-description/translatable)                                 | No       | Loyalty card description                             |
| validationType              | List<[LoyaltyCardValidationType](/general/data-object-description/loyaltycardvalidationtype)> | Yes      | Possible validation types for verifying loyalty card |
| colorTheme                  | [ColorTheme](/general/data-object-description/colortheme)                                     | Yes      | Loyalty card colour theme                            |
| primary                     | Boolean                                                                                       | Yes      | Check if is primary loyalty card                     |
| colors                      | [L](/general/data-object-description/address)ist\<String>                                     | Yes      | Loyalty card background colour HEX list              |


# LoyaltyCardType

| LoyaltyCardType |                      |
| --------------- | -------------------- |
| DEFAULT         | Default loyalty card |
| BONUS           | Bonus loyalty card   |


# LoyaltyCardValidationType

| LoyaltyCardValidationType |                                                 |
| ------------------------- | ----------------------------------------------- |
| IDCODE                    | Loyalty card can be verified by person id code  |
| PHONE                     | Loyalty card can be verified by person id phone |
| EMAIL                     | Loyalty card can be verified by person id email |
| CARD\_NUMBER              | Loyalty card can be verified by card number     |


# Shipment

### Object description

| Field                   | Type                                                                                  | Required | Description              |
| ----------------------- | ------------------------------------------------------------------------------------- | -------- | ------------------------ |
| method                  | [ShipmentMethod](/general/data-object-description/shipment#enum-type-possible-values) | Yes      | Method for shipment      |
| status                  | [ShipmentStatus](/general/data-object-description/shipmentstatus)                     | Yes      | Status for shipment      |
| price                   | double                                                                                | Yes      | Shipping price           |
| currency                | [Currency](/general/data-object-description/currency)                                 | Yes      | Shipping currency        |
| expectedDeliveryUTCTime | String                                                                                | Yes      | Expected delivery in UTC |
| createdUTCTime          | String                                                                                | Yes      | Shipment created UTC     |
| contactEmail            | String                                                                                | Yes      | Client email             |
| contactPhone            | String                                                                                | Yes      | Client phone             |
| address                 | [Address](/general/data-object-description/address)                                   | Yes      | Shipment address         |

## Enum type possible values

| ShipmentMethod |                                       |
| -------------- | ------------------------------------- |
| COURIER        | Shipment method courier               |
| PARCEL         | Shipment method parcel                |
| COME\_BY\_SPOT | Shipment method for pick up by myself |


# ShipmentStatus

| ShipmentStatus             |                                                          |
| -------------------------- | -------------------------------------------------------- |
| DRAFT                      | Shipment is not sent to confirmation                     |
| PAYMENT\_FAILED            | Shipment not valid due payment error                     |
| WAITING\_FOR\_CONFIRMATION | Waiting for merchant side order confirmation             |
| CONFIRMED                  | Order is confirmed by merchant                           |
| ASSEMBLE\_READY            | The order is compiled and ready to ship out              |
| SHIPPING                   | The order is in shipping process                         |
| READY\_TO\_PICKUP          | The order is compiled and shipped. Waiting for customer. |
| CANCELLED\_BY\_CLIENT      | The shipment was cancelled by client                     |
| CANCELLED\_BY\_INSTITUTION | The shipment was cancelled by store                      |
| COMPLETED                  | The shipment was completed successfully                  |
| MISSED                     | The shipment was expired                                 |


# Category

### Object description

| Field            | Type                                                          | Required | Description                        |
| ---------------- | ------------------------------------------------------------- | -------- | ---------------------------------- |
| id               | String                                                        | Yes      | Category ID                        |
| translatableName | [Translatable](/general/data-object-description/translatable) | Yes      | Category translatable name         |
| numberOfProducts | double                                                        | Yes      | Number of products in the category |
| parentId         | String                                                        | No       | Parent category ID                 |


# Addition

Addition data transfer object description

### Object description

| Field | Type                                                                                    | Required | Description            |
| ----- | --------------------------------------------------------------------------------------- | -------- | ---------------------- |
| type  | [**AdditionType**](/general/data-object-description/addition#enum-type-possible-values) | Yes      | Discount or markup     |
| sum   | Double                                                                                  | Yes      | Discount / markup sum  |
| rate  | Integer                                                                                 | Yes      | Discount / markup rate |

## Enum type possible values

| AdditionType |          |
| ------------ | -------- |
| DSC          | Discount |
| CHR          | Markup   |


# Address

Address data transfer object description

### Object description

| Field      | Type   | Required | Description     |
| ---------- | ------ | -------- | --------------- |
| level1     | String | Yes      | address level 1 |
| level2     | String | No       | address level 2 |
| level3     | String | No       | address level 3 |
| level4     | String | No       | address level 4 |
| level5     | String | No       | address level 5 |
| level6     | String | No       | address level 6 |
| level7     | String | No       | address level 7 |
| level8     | String | No       | address level 8 |
| postalCode | String | No       | Postal code     |

### Example

```javascript
{
    "level1": "EE",
    "level2": "Harjumaa",
    "level3": "Tallinn",
    "level4": "kesklinn",
    "level5": "Tartu mnt.",
    "level6": "53",
    "level7": null,
    "level8": null,
    "postalCode": "10115"
}
```


# Currency

## Supported currencies

| ShipmentMethod |                        |
| -------------- | ---------------------- |
| EUR            | Euro                   |
| USD            | US dollar              |
| MXN            | Mexico peso            |
| AUD            | Australia dollar       |
| HKD            | Hong Kong dollar       |
| RON            | Romanian leu           |
| HRK            | Croatia Kuna           |
| CHF            | Swiss franc            |
| IDR            | Indonesian rupiah      |
| CAD            | Canadian dollar        |
| CAR            | CFA frank              |
| JPY            | Japanese yen           |
| BRL            | Brazilian real         |
| HUF            | Hungarian forint       |
| CZK            | Czech koruna           |
| NOK            | Norwegian krone        |
| INR            | Indian rupee           |
| PLN            | Polish złoty           |
| ISK            | Icelandic króna        |
| PHP            | Philippine peso        |
| SEK            | Swedish krona          |
| ILS            | Israeli new shekel     |
| GBP            | British pound sterling |
| SGD            | Singapore dollar       |
| CNY            | Renminbi               |
| TRY            | Turkish lira           |
| MYR            | Malaysian ringgit      |
| RUB            | Russian ruble          |
| NZD            | New Zealand dollar     |
| KRW            | South Korean won       |
| THB            | Thai baht              |
| BGN            | Bulgarian lev          |
| DKK            | Danish krone           |


# BuyerParty

BuyerParty data transfer object description

### Object description

| Field       | Type                                                                | Description                    |
| ----------- | ------------------------------------------------------------------- | ------------------------------ |
| uniqueCode  | String                                                              | Smarts unique buyer identifier |
| clientCards | List<[**ClientCard**](/general/data-object-description/clientcard)> | Buyer client cards             |


# Campaign

Campaign data transfer object description

### Object description

| Field     | Type                                                          | Required | Description                          |
| --------- | ------------------------------------------------------------- | -------- | ------------------------------------ |
| name      | String                                                        | Yes      | Campaign name                        |
| code      | [CampaignCode](/general/data-object-description/campaigncode) | Yes      | Campaign details                     |
| operation | String                                                        | Yes      | Math operation written in Javascript |


# CampaignCode

CampaignCode data transfer object description

### Object description

| Field          | Type       | Required | Description                                                                                      |
| -------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| clientId       | ClientId   | Yes      | Which customers will apply                                                                       |
| campaignId     | CampaignId | Yes      | Campaign strategy number                                                                         |
| clientCardCode | String     | Yes      | <p>Client card machine readable code. </p><p>Default <code>00000000</code> - Applies for all</p> |

## Enum type possible values

| Client ID |                                                          |
| --------- | -------------------------------------------------------- |
| C         | Clients how has client card                              |
| U         | All customers (with client card and without client card) |
| B         | Only unauthorized customers                              |

| Campaign ID                        |                                               |
| ---------------------------------- | --------------------------------------------- |
| AMOUNT\_MODIFICATION               | Amount modification campaign                  |
| AMOUNT\_BASED\_UNIT\_PRICE         | Amount based unit price modification campaign |
| TOTAL\_MODIFICATION                | Total price modification campaign             |
| AMOUNT\_BASED\_TOTAL\_MODIFICATION |                                               |


# ClientCard

ClientCard data transfer object description

### Object description

| Field                  | Type   | Description                                      |
| ---------------------- | ------ | ------------------------------------------------ |
| cardNumber             | String | Client card number                               |
| cardIdentificationCode | String | Client card machine readable identification code |


# Information

Information data transfer object description

### Object description

| Field    | Type   | Required | Description                               |
| -------- | ------ | -------- | ----------------------------------------- |
| imageUrl | String | No       | Product image url. **Allowed only HTTPS** |


# Inspection

Inspection interface data transfer object description

## BetweenTimeInspection&#x20;

Applies if the current time does not belong to the start and end parameters range. If the rule is not set, it is allowed to buy the product at all times.

| Field    | Type                                                                                        | Required | Description                                                                    |
| -------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| start    | Time (HH:MM)                                                                                | Yes      | Start time when a product can be purchased (hours:minutes)                     |
| end      | Time (HH:MM)                                                                                | Yes      | End time when a product can be purchase (hours:minutes)                        |
| timezone | Timezone UTC                                                                                | Yes      | Time zone in UTC format                                                        |
| action   | [**InspectionType**](/general/data-object-description/inspection#enum-type-possible-values) | Yes      | <p>Take a purchase check or disable the product in the</p><p>shopping card</p> |

#### Example

*Product adding to shopping card is allowed only if current time between 10:00 and 22:00. Otherwise adding restricted.*

```javascript
{
    "action" : "RESTRICT",
    "start" : "10:00",
    "end": "22:00",
    "timezone" : "Europe/Tallinn",
    "type": "BETWEEN_TIME"
}
```

## MinTimeInspection

Applies if the current time is less than the set time value. If the rule is not set, it is allowed to buy the product at all times.

| Field    | Type                                                                                        | Required | Description                                                                    |
| -------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| time     | Time (HH:MM)                                                                                | Yes      | Time (hours:minutes)                                                           |
| timezone | Timezone UTC                                                                                | Yes      | Time zone in UTC format                                                        |
| action   | [**InspectionType**](/general/data-object-description/inspection#enum-type-possible-values) | Yes      | <p>Take a purchase check or disable the product in the</p><p>shopping card</p> |

## MaxTimeInspection

Applies if the current time is greater than the set time value. If the rule is not set, it is allowed to buy the product at all times.

| Field    | Type                                                                                        | Required | Description                                                                    |
| -------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| time     | Time (HH:MM)                                                                                | Yes      | Time                                                                           |
| timezone | Timezone UTC                                                                                | Yes      | Time zone                                                                      |
| action   | [**InspectionType**](/general/data-object-description/inspection#enum-type-possible-values) | Yes      | <p>Take a purchase check or disable the product in the</p><p>shopping card</p> |

## MinAgeInspection

Applies if rule is set.

| Field  | Type                                                                                        | Required | Description                                                                    |
| ------ | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| age    | Integer                                                                                     | Yes      | Age                                                                            |
| action | [**InspectionType**](/general/data-object-description/inspection#enum-type-possible-values) | Yes      | <p>Take a purchase check or disable the product in the</p><p>shopping card</p> |

#### Example

*Customer should be at least 18 years old to allow product purchase.*&#x20;

```javascript
{
    "action" : "INSPECT",
    "age" : 18,
    "type" : "MIN_AGE"
}
```

## MinAmountInspection

Applies when product quantity is less than amount.

| Field  | Type                                                                                        | Required | Description                                                                    |
| ------ | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| amount | Double                                                                                      | Yes      | Product quantity                                                               |
| action | [**InspectionType**](/general/data-object-description/inspection#enum-type-possible-values) | Yes      | <p>Take a purchase check or disable the product in the</p><p>shopping card</p> |

## MaxAmountInspection

Applies when product quantity is greater than amount.

| Field  | Type                                                                                        | Required | Description                                                                    |
| ------ | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| amount | Double                                                                                      | Yes      | Product quantity                                                               |
| action | [**InspectionType**](/general/data-object-description/inspection#enum-type-possible-values) | Yes      | <p>Take a purchase check or disable the product in the</p><p>shopping card</p> |

## Enum type possible values

| AdditionType |                                                           |
| ------------ | --------------------------------------------------------- |
| INSPECT      | Allow adding to shopping card but inspect before purchase |
| RESTRICT     | Restrict adding to shopping cart.                         |


# Invoice

Invoice data transfer object description

### Object description

| Field                | Type                                                                        | Description                     |
| -------------------- | --------------------------------------------------------------------------- | ------------------------------- |
| id                   | String                                                                      | Smarts system unique identifier |
| seller               | SellerParty                                                                 | Seller detailed information     |
| buyer                | BuyerParty                                                                  | Buyer detailed information      |
| status               | [**InvoiceStatus**](/general/data-object-description/invoice#invoicestatus) | Invoice status                  |
| createdAt            | Unix Timestamp (UTC)                                                        | Invoice creating time           |
| closedAt             | Unit Timestamp (UTC)                                                        | Invoice closing time            |
| products             | List<[**Product**](/general/data-object-description/product)>               | Invoice products                |
| currency             | [**Currency**](/general/data-object-description/invoice#currency)           | Currency                        |
| total                | Total                                                                       | Invoice detailed total          |
| institutionCampaigns | List<[Campaign](/general/data-object-description/campaign)>                 | Institution based campaigns     |

## Enum type possible values

### InvoiceStatus

| Invoice Status |   |
| -------------- | - |
| PAYED          |   |

### Currency

| Currency |           |
| -------- | --------- |
| EUR      | Euro      |
| USD      | US dollar |


# LangCode

Language codes list

SMARTS is using **ISO 639-1:2002** language name code format. ISO 639-1 defines abbreviations for languages, consisting of two lowercase letters.

| Language   | ISO |
| ---------- | :-: |
| English    |  EN |
| Estonian   |  ET |
| Latvian    |  LV |
| Lithuanian |  LT |
| Finnish    |  FI |
| Russian    |  RU |

**Full list of language codes**: <http://www.mathguide.de/info/tools/languagecode.html>


# Price

Price data transfer object description

### Object description

| Field    | Type                                                      | Required | Description                                   |
| -------- | --------------------------------------------------------- | -------- | --------------------------------------------- |
| addition | [**Addition**](/general/data-object-description/addition) | No       | Detailed product addition. Discount or markup |
| vat      | [**VAT**](/general/data-object-description/vat)           | Yes      | Detailed Tax description                      |
| total    | Double                                                    | Yes      | Product final price with addition and VAT     |


# Product

Product data transfer object description

### Object description

| Field                   | Type                                                                                  | Required                              | Description                                   |
| ----------------------- | ------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------- |
| barcode                 | String                                                                                | Yes                                   | Product SKU                                   |
| type                    | [**ProductType**](/general/data-object-description/product#enum-type-possible-values) | Yes                                   | Product type                                  |
| translatableName        | [**Translatable**](/general/data-object-description/translatable)                     | Yes                                   | Multilingual product name                     |
| translatableDescription | [**Translatable**](/general/data-object-description/translatable)                     | No                                    | <p>Multilingual product</p><p>description</p> |
| quantity                | [**Quantity**](/general/data-object-description/quantity)                             | Yes                                   | Product quantity and measure                  |
| price                   | [**Price**](/general/data-object-description/price)                                   | Yes                                   | Detailed price description                    |
| information             | [**Information**](/general/data-object-description/information)                       | No                                    | Additional information                        |
| weightItem              | Boolean                                                                               | Yes                                   | Whether it's a weight product                 |
| inspections             | List<[Inspection](/general/data-object-description/inspection)>                       | No                                    | Product based purchase check rules            |
| campaigns               | List<[Campaign](/general/data-object-description/campaign)>                           | No                                    | Product based campaign rules                  |
| subProducts             | List<[Product](/general/data-object-description/product)>                             | Yes if **ProductType** is `CONNECTED` | Connected products                            |
| categories              | List<[Category](/general/data-object-description/category)>                           | Yes                                   | Connected categories                          |

## Enum type possible values

| ProductType |   |
| ----------- | - |
| SINGLE      |   |
| CONNECTED   |   |


# Quantity

Quantity data transfer object description

### Object description

| Field | Type                                                                            | Required | Description      |
| ----- | ------------------------------------------------------------------------------- | -------- | ---------------- |
| unit  | [**Unit**](/general/data-object-description/quantity#enum-type-possible-values) | Yes      | Product unit     |
| value | double                                                                          | Yes      | Product quantity |

## Enum type possible values

| Unit       |   |
| ---------- | - |
| PIECE      |   |
| LITER      |   |
| DECILITER  |   |
| KILOGRAM   |   |
| GRAM       |   |
| TON        |   |
| METER      |   |
| CENTIMETER |   |
| DECIMETER  |   |
| PINT       |   |
| FOOT       |   |
| YARD       |   |
| MILE       |   |
| CUP        |   |
| QUART      |   |
| GALLON     |   |
| POUND      |   |
| STONE      |   |
| INCH       |   |


# SellerParty

SellerParty data transfer object description

### Object description

| Field      | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| uniqueCode | String | Smarts system unique institution identifier |
| sellerName | String | Merchant name                               |
| vatNumber  | String | Merchant VAT number                         |
| regNumber  | String | Merchant registry number                    |
| address    | String | Merchant address                            |


# Total

Total data transfer object description

### Object description

| Field      | Type     | Required | Description                    |
| ---------- | -------- | -------- | ------------------------------ |
| vat        | TotalVat | Yes      | Invoice detailed VAT           |
| totalToPay | Double   | Yes      | Transaction total without fees |


# TotalVAT

TotalVAT data transfer object description

### Object description

| Field         | Type   | Required | Description                                  |
| ------------- | ------ | -------- | -------------------------------------------- |
| sumWithVAT    | Double | Yes      | Invoice total with additions and VAT         |
| sumWithoutVAT | Double | Yes      | Invoice total with additions and without VAT |
| VATSum        | Double | Yes      | Invoice total VAT sum                        |


# Translatable

Translatable data transfer object description

### Object description

| Field        | Type                   | Required | Description       |
| ------------ | ---------------------- | -------- | ----------------- |
| originalText | String                 | Yes      | Original text     |
| translations | Map\<LangCode, String> | No       | Alternative texts |


# Receipt

### Object description

| Field                | Type                                                                            | Required | Description                         |
| -------------------- | ------------------------------------------------------------------------------- | -------- | ----------------------------------- |
| institutionInvoiceId | [S](/general/data-object-description/shipment#enum-type-possible-values)tring   | Yes      | Institution side invoice identifier |
| invoiceId            | [S](/general/data-object-description/shipment#enum-type-possible-values)tring   | Yes      | Smarts invoice unique identifier    |
| institutionId        | String                                                                          | Yes      | Smarts store unique identifier      |
| customerId           | String                                                                          | Yes      | Smarts customer unique identifier   |
| products             | List<[ReceiptProduct](/general/data-object-description/receiptproduct)>         | Yes      | Receipt product description         |
| loyaltyCards         | List<[ReceiptLoyaltyCard](/general/data-object-description/receiptloyaltycard)> | No       | Receipt loyalty cards description   |
| shipment             | [Shipment](/general/data-object-description/shipment)                           | No       | Shipment details                    |
| currency             | [Currency](/general/data-object-description/currency)                           | Yes      | Currency                            |
| totalWithoutAddition | double                                                                          | Yes      | Shipment address                    |
| additionSum          | double                                                                          | Yes      | Addition sum                        |
| totalWithoutVAT      | double                                                                          | Yes      | Total without VAT                   |
| vatSum               | double                                                                          | Yes      | VAT sum                             |
| total                | double                                                                          | Yes      | Total to pay                        |


# ReceiptProduct

### Object description

| Field       | Type                                                                          | Required | Description             |
| ----------- | ----------------------------------------------------------------------------- | -------- | ----------------------- |
| id          | [S](/general/data-object-description/shipment#enum-type-possible-values)tring | Yes      | Product identifier      |
| barcode     | [S](/general/data-object-description/shipment#enum-type-possible-values)tring | Yes      | Product SKU             |
| productName | String                                                                        | Yes      | Name of the product     |
| amount      | double                                                                        | Yes      | Product amount          |
| rowPrice    | double                                                                        | Yes      | Product total row price |
| categories  | List<[ReceiptCategory](/general/data-object-description/receiptcategory)>     | No       | Receipt category        |


# ReceiptLoyaltyCard

### Object description

| Field          | Type                                                                          | Required | Description                   |
| -------------- | ----------------------------------------------------------------------------- | -------- | ----------------------------- |
| name           | [S](/general/data-object-description/shipment#enum-type-possible-values)tring | Yes      | Loyalty Card name             |
| lastFourNumber | [S](/general/data-object-description/shipment#enum-type-possible-values)tring | Yes      | Loyalty Card last four number |


# ReceiptCategory

### Object description

| Field | Type                                                                          | Required | Description   |
| ----- | ----------------------------------------------------------------------------- | -------- | ------------- |
| id    | [S](/general/data-object-description/shipment#enum-type-possible-values)tring | Yes      | Category id   |
| name  | [S](/general/data-object-description/shipment#enum-type-possible-values)tring | Yes      | Category name |


# VAT

VAT data transfer object description

### Object description

| Field         | Type    | Required | Description                                 |
| ------------- | ------- | -------- | ------------------------------------------- |
| sumWithoutVAT | Double  | Yes      | Product price with addition and without VAT |
| VATSum        | Double  | Yes      | VAT summa                                   |
| sumWithVAT    | Double  | Yes      | Product price with addition and VAT         |
| VATRate       | Integer | Yes      | VAT percent                                 |


# Request & Responses


# NodeHealthResponse

| Field  | Type                                                          | Required | Description        |
| ------ | ------------------------------------------------------------- | -------- | ------------------ |
| status | [HealthStatus](/general/data-object-description/healthstatus) | Yes      | Node health status |


# NodeVersionResponse

| Field   | Type   | Required | Description             |
| ------- | ------ | -------- | ----------------------- |
| version | String | Yes      | Connection node version |


# OfferSearchRequest

| Field          | Type                                                                         | Required | Description             |
| -------------- | ---------------------------------------------------------------------------- | -------- | ----------------------- |
| classification | ​[OfferClassification](/general/data-object-description/offerclassification) | Yes      | Offer classification    |
| loyaltyCards   | List<[LoyaltyCard](/general/data-object-description/loyaltycard)>            | No       | Customer loyalty cards  |
| langCode       | [LangCode](/general/data-object-description/langcode)                        | Yes      | Language code           |
| personId       | String                                                                       | Yes      | Smarts person unique ID |
| institutionId  | String                                                                       | Yes      | Smarts store unique ID  |


# PickupOrderStatusChangeRequest

| Field  | Type                                                               | Required | Description     |
| ------ | ------------------------------------------------------------------ | -------- | --------------- |
| status | ​[ShipmentStatus](/general/data-object-description/shipmentstatus) | Yes      | Shipment status |


# LoyaltyCardBonusResponse

| Field | Type    | Required | Description  |
| ----- | ------- | -------- | ------------ |
| bonus | ​double | Yes      | Bonus amount |


# LoyaltyCardBonusRequest

### Object description <a href="#object-description" id="object-description"></a>

| Field       | Type                                                         | Required | Description                |
| ----------- | ------------------------------------------------------------ | -------- | -------------------------- |
| loyaltyCard | ​[LoyaltyCard](/general/data-object-description/loyaltycard) | Yes      | LoyaltyCard                |
| personId    | String                                                       | Yes      | Smarts customer identifier |
| personEmail | String                                                       | Yes      | Smarts customer email      |
| personName  | String                                                       | Yes      | Smarts customer name       |


# LoyaltyCardRegistrationResponse

### Object description <a href="#object-description" id="object-description"></a>

| Field      | Type    | Required | Description                       |
| ---------- | ------- | -------- | --------------------------------- |
| cardNumber | ​String | Yes      | Card number                       |
| validFrom  | String  | Yes      | Valid from date format YYYY-MM-DD |
| validTo    | String  | Yes      | Valid to date format YYYY-MM-DD   |


# LoyaltyCardRegistrationRequest

### Object description <a href="#object-description" id="object-description"></a>

| Field       | Type                                                                                                                                                                   | Required | Description                     |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------- |
| loyaltyCard | <p><a href="/general/data-object-description/default-loyalty-card">DefaultCard</a></p><p><a href="/general/data-object-description/bonusloyaltycard">BonusCard</a></p> | Yes      | Registered store loyalty card   |
| value       | String                                                                                                                                                                 | Yes      | Inserted value by client        |
| personId    | String                                                                                                                                                                 | Yes      | Smarts client unique identifier |
| personEmail | String                                                                                                                                                                 | Yes      | Smarts client email             |
| personName  | String                                                                                                                                                                 | Yes      | Smarts client name              |


# PurchaseControlCheckResendRequest

### Object description <a href="#object-description" id="object-description"></a>

| Field         | Type    | Required | Description                   |
| ------------- | ------- | -------- | ----------------------------- |
| invoiceId     | ​String | Yes      | Smarts invoice identifier     |
| institutionId | String  | Yes      | Smarts institution identifier |


# PurchaseControlResult

### Object description <a href="#object-description" id="object-description"></a>

| Field         | Type                                                                                                    | Required | Description                   |
| ------------- | ------------------------------------------------------------------------------------------------------- | -------- | ----------------------------- |
| invoiceId     | ​String                                                                                                 | Yes      | Smarts invoice identifier     |
| institutionId | String                                                                                                  | Yes      | Smarts institution identifier |
| products      | List<[Product](/general/data-object-description/product)>                                               | No       | Products if there was changes |
| status        | [PurchaseControlStatus](/general/request-and-responses/purchasecontrolresult#enum-type-possible-values) | Yes      | Purchase control status       |

## Enum type possible values <a href="#enum-type-possible-values" id="enum-type-possible-values"></a>

| PurchaseControlStatus  | ​Title                                  |
| ---------------------- | --------------------------------------- |
| PASSED                 | Purchase check passed                   |
| FAILED                 | Purchase check failed                   |
| PENDING                | Purchase check in progress              |
| EXIPRED                | Purchase check expired                  |
| FAILED\_ALLOW\_PAYMENT | Purchase check failed but allow payment |


# PurchaseControlCheckResponse

### Object description

| Field    | Type                                                                                                             | Required | Description               |
| -------- | ---------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- |
| decision | [PurchaseControlDecision](/general/request-and-responses/purchasecontrolcheckresponse#enum-type-possible-values) | Yes      | Purchase control decision |

## Enum type possible values

| PurchaseControlDecision |                   |
| ----------------------- | ----------------- |
| NO                      | Check not needed  |
| AGE                     | Age check needed  |
| FULL                    | Full check needed |


# PurchaseControlCheckRequest

### Object description

| Field         | Type                                                      | Required | Description               |
| ------------- | --------------------------------------------------------- | -------- | ------------------------- |
| invoiceId     | String                                                    | Yes      | Smarts invoice identifier |
| langCode      | [LangCode](/general/data-object-description/langcode)     | Yes      | Language code             |
| personId      | String                                                    | Yes      | Smarts person unique ID   |
| institutionId | String                                                    | Yes      | Smarts store unique ID    |
| products      | List<[Product](/general/data-object-description/product)> | Yes      | Shopping cart products    |


# ReceiptPaymentConfirmationRequest

### Object description

| Field   | Type                                                                                                        | Required | Description                |
| ------- | ----------------------------------------------------------------------------------------------------------- | -------- | -------------------------- |
| Receipt | [Receipt](/general/data-object-description/receipt)                                                         | Yes      | Receipt                    |
| status  | [ReceiptStatus](/general/request-and-responses/receiptpaymentconfirmationrequest#enum-type-possible-values) | Yes      | Payment status for receipt |

## Enum type possible values

| ReceiptStatus |                             |
| ------------- | --------------------------- |
| PAYED         | Receipt payment success     |
| FAILED        | Receipt payment failed      |
| PENDING       | Receipt payment in progress |
| ABANDONED     | Receipt payment missed      |


# InstitutionRequest

### Object description

| Field         | Type                                                  | Required | Description             |
| ------------- | ----------------------------------------------------- | -------- | ----------------------- |
| langCode      | [LangCode](/general/data-object-description/langcode) | Yes      | Language code           |
| personId      | String                                                | Yes      | Smarts person unique ID |
| institutionId | String                                                | Yes      | Smarts store unique ID  |


# Pageable

### Object description

| Field      | Type          | Required | Description                    |
| ---------- | ------------- | -------- | ------------------------------ |
| result     | List\<Object> | Yes      | List of generic objects        |
| lastPage   | int           | Yes      | Last page number               |
| totalCount | int           | YesT     | Total count of generic objects |


# PageRequest

### Object description

| Field        | Type      | Required | Description              |
| ------------ | --------- | -------- | ------------------------ |
| page         | int       | Yes      | Current page             |
| limit        | int       | Yes      | Number of items per page |
| orderBy      | PageOrder | Yes      | Order direction          |
| orderByField | String    | No       | Order field              |
| request      | Object    | No       | Request generic object   |

## Enum type possible values

| PageOrder |                 |
| --------- | --------------- |
| ACS       | Ascending order |
| DESC      | Reversed order  |




---

[Next Page](/llms-full.txt/1)