# Kaspi Shop (seller API)

Read Kaspi.kz shop orders and payments.

URL: https://docs.qaldy.com/connectors/kaspi/

- **Status:** [[Preview]]
- **Shelf:** Commerce and payments
- **How you connect:** API key
- **Regions:** global and Kazakhstan
- **The service’s own API reference:** https://kaspi.kz/merchantcabinet/support/display/Support/API

Apps read Kaspi.kz shop orders with your **seller API token**. Kaspi is reached through the HTTP API
connector with a preset: the gate calls only `kaspi.kz/shop/api/v2` and only with `GET`. The token
is sealed to the gate and apps never see it.

> **Status: Preview.** The preset follows Kaspi's seller API as documented
> ([Kaspi merchant cabinet](https://kaspi.kz/merchantcabinet/support/display/Support/API)), but it
> **needs a real seller token to verify**: nobody has run it against a live shop. If a call fails,
> the gate's message and the upstream status say why. Please report what Kaspi answered.

## Connect it

1. In the Kaspi **Seller Cabinet** open **Settings** and generate an **API token**
   ([kaspi.kz/merchantcabinet](https://kaspi.kz/merchantcabinet/)).
2. Qaldy → **Connectors** → Kaspi → **Connect Kaspi** → paste the token → **Seal and connect**.

**Test connection** only checks that the sealed token opens. Kaspi's order list needs a date range
and a state, which a fixed test call can't carry, so the gate sends nothing.

## What the gate allows

| | |
|---|---|
| Host | `kaspi.kz`, base path `/shop/api/v2` (pinned, every resolved address public) |
| Methods | `GET` (reading orders; accepting or shipping an order needs `POST`, which this preset does not allow) |
| Paths | everything under `/shop/api/v2` |
| Key | `X-Auth-Token: <token>`, added by the gate; an app-supplied one is dropped |
| Fixed headers | `Accept: application/vnd.api+json`, `Content-Type: application/vnd.api+json` |

## Use it from an app

```json
{ "id": "http", "actions": ["request"], "scope": "conn_k3v9…" }
```

```ts
const api = ctx.connectors.http('conn_k3v9…')
const since = Date.now() - 24 * 60 * 60 * 1000
const orders = await api.get('/orders', {
  query: {
    'page[number]': 0,
    'page[size]': 20,
    'filter[orders][state]': 'NEW',
    'filter[orders][creationDate][$ge]': since,
    'filter[orders][creationDate][$le]': Date.now(),
  },
})
```

Kaspi expects millisecond timestamps and a creation-date window of at most 14 days.

## When it breaks

| You see | Why | Do |
|---|---|---|
| `401` or `403` | The token was regenerated or mistyped | Generate a new token and replace it |
| `400` | Missing filters (state, creation date) | Add the filters above |
| Blocked: `method_not_allowed` | The app tried to change an order | Not allowed by this preset |

Native Kaspi actions (`ctx.connectors.kaspi.listOrders`) are not served by the gate.