# Expected data for a physical-store connector

## Goal

We can integrate physical-store data in two main cases:

1. **Customers only**
   - only the in-store customer database is sent

2. **Customers + orders**
   - customers are sent
   - store tickets / orders are sent
   - product details for each ticket are sent

The second case is the most complete because it gives access to:
- the customer base
- purchase history
- purchased products
- sales channels / stores

## Two possible integration modes

We support two integration modes depending on the client’s preferred level of autonomy.

### Option 1 — Direct Kiliba API integration

If your technical team prefers, it can **push data directly into the Kiliba API**.

In that case:
- your team calls our import endpoints directly
- your team pushes already-structured payloads
- your team manages the sending logic to Kiliba

Public developer documentation:

- https://developers.kiliba.ai/

### Option 2 — File drop + parser handled by Kiliba

If you prefer, your team can simply **drop export files**, and **the Kiliba team will build the connector** between your exports and our API.

In that case:
- you provide data exports
- we analyze the mapping
- we build the parser / connector
- we transform your files into our API contract

## How secure file uploads work

When the integration is file-based, the flow is:

1. an API call creates an upload session
2. a temporary secure S3 upload URL is generated
3. the raw file is uploaded to the secure drop zone
4. a second API call completes the upload
5. Kiliba then starts parsing and ingestion

In practice:
- uploads go to a **secure S3 bucket** through a **pre-signed URL**
- the client does not need direct access to Kiliba infrastructure
- we can provide a **Python example script** to automate uploads

## Expected format

We can adapt to CSV, delimited TXT, or equivalent formats, as long as:
- the delimiter is known
- the encoding is known
- the column set is stable
- each file has reliable join keys

A first delivery can be:
- a **full historical export**

Then later deliveries can be:
- **incremental updates**

## Case 1 — Customers export only

If you only want to send customers, we need at least the following information.

### Minimum required fields

| Expected field | Description | Required |
|---|---|---|
| `customer_id` | Unique customer identifier in your system | Yes |
| `email` or `telephone` | A usable contact method | Yes, at least one |
| `store_id` / `sales_channel_id` | Store or sales-channel identifier | Yes if multiple stores / entities exist |
| `created_at` | Customer creation timestamp | Yes |
| `updated_at` | Customer last update timestamp | Yes |

### Strongly recommended fields

| Expected field | Description |
|---|---|
| `first_name` | First name |
| `last_name` | Last name |
| `birthdate` | Birth date |
| `gender` | Title / gender if available |
| `newsletter_optin` | Email marketing consent |
| `sms_optin` | SMS marketing consent |
| `deleted` | Whether the customer is deleted / inactive |
| `language` | Contact language |
| `country` / `country_code` | Country |
| `city` | City |
| `postal_code` | Postal code |
| `address` | Address |

## Case 2 — Customers + orders

If you want to send store tickets / orders, the expected model is:

- **customer file**
- **ticket header file**
- **ticket line file**

In other words:

- **1 customer**
- **1 ticket**
- **N product lines in that ticket**

## Ticket header file

Each row represents one ticket / one order.

### Minimum required fields

| Expected field | Description | Required |
|---|---|---|
| `order_id` / `ticket_id` | Unique ticket identifier | Yes |
| `store_id` / `sales_channel_id` | Store / channel identifier | Yes if multiple stores exist or if `order_id` is not globally unique |
| `customer_id` | Customer identifier linked to the ticket | Recommended, but may be empty for anonymous tickets |
| `created_at` | Ticket creation datetime | Yes |
| `updated_at` | Ticket last update datetime | Yes |

### Possible variant

Depending on your system, two order delivery modes are possible:

#### Option A — `orders` with products included

Each order directly contains:
- the ticket header information
- the list of products in the ticket

#### Option B — 2 separate files

- **header file**: 1 row = 1 ticket
- **product lines file**: N rows = products linked to that ticket

## Ticket line file

### Minimum required fields

| Expected field | Description | Required |
|---|---|---|
| `order_id` / `ticket_id` | Ticket identifier | Yes |
| `line_id` / `line_number` | Line number inside the ticket | Yes |
| `product_id` | Product identifier in your system | Yes |
| `quantity` | Purchased quantity | Yes |
| `amount_ht` | Net amount or usable net unit price | Yes |
| `amount_ttc` | Gross amount or usable gross unit price | Yes |

## Expected product identifiers

For each purchased product, we need a **unique product identifier**.

For example, you can provide **at least one** of the following:

1. **barcode / EAN**
2. **SKU**
3. **internal product identifier**

## CMS product identifiers

If you want in-store purchases to be linked to your e-commerce / CMS catalog, it is useful to provide, or allow us to derive, a CMS-usable product identifier.

Possible matching strategies:
- through **barcode / EAN**
- through **SKU**
- through a **shared internal identifier** between the store system and the CMS

## Questions to confirm with the API / data team

### General structure

- Do you provide:
  - customers only
  - or customers + ticket headers + product lines?
- How many files are provided?
- What is the exact format?
- What is the delimiter?
- What is the encoding?

### Customers

- What is the unique customer identifier?
- Can a customer exist without an email?
- Can a customer exist with a phone but without an email?
- Do you have an email / marketing consent field?
- Do you have creation and update timestamps for the customer record?

### Tickets

- What is the ticket identifier?
- Is the ticket identifier globally unique, or only unique within a store / entity?
- Can tickets exist without a linked customer?
- Do you have creation and update timestamps?
- Do you have a source ticket status and/or cancellation / deletion flag?

### Product lines

- Which field links a product line to its ticket?
- Is the ticket key globally unique in the line file, or must it be combined with a store / entity?
- What is the most reliable product identifier?
  - barcode / EAN
  - SKU
  - internal identifier
- Do you also have a product or variant identifier on the CMS / e-commerce side?
- If yes, which key allows the product-store to CMS-product match?

### Stores / sales channels

- Do you have a stable technical store / sales-channel identifier?
- Can you provide a readable store name for each store?
- Is that mapping provided in a dedicated file or in an existing export?

### Frequency and delivery mode

- Will the first delivery be a full historical export?
- After that, will you send:
  - full files
  - or increments?
- For increments, how do you identify updates?
  - update timestamp
  - another indicator