# Bot API (Sinsay proxy)

REST API for external bots using the same shipping and payment method IDs as the checkout UI.

**Recommended:** step-by-step checkout sessions — see **[checkout-api.md](checkout-api.md)** (`/api/bot/v1/checkout/sessions/...`).

**Legacy** one-shot endpoints below (`POST /orders`) remain for compatibility but are deprecated.

**Base URL:** `https://<your-domain>/api/bot/v1`

**Authentication:** set `BOT_API_KEY` in the app environment, then send either:

- Header `X-API-Key: <key>`
- Header `Authorization: Bearer <key>`

## Endpoints

### `GET /payment-methods`

List all payment methods (catalog mirror).

```bash
curl -s -H "X-API-Key: $BOT_API_KEY" \
  "https://example.com/api/bot/v1/payment-methods"
```

### `GET /shipping-methods`

List shipping methods. Optional query `cartTotal` (reserved for future pricing rules).

```bash
curl -s -H "X-API-Key: $BOT_API_KEY" \
  "https://example.com/api/bot/v1/shipping-methods?cartTotal=199.99"
```

Filter payments for a shipping method:

```bash
curl -s -H "X-API-Key: $BOT_API_KEY" \
  "https://example.com/api/bot/v1/shipping-methods?shippingMethodId=inpostpp"
```

### `POST /orders`

Create an order. Body must include customer, delivery, and payment fields (same as browser checkout).

**Option A — explicit items:**

```bash
curl -s -X POST -H "X-API-Key: $BOT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "firstname": "Jan",
    "lastname": "Kowalski",
    "phone": "+48123456789",
    "email": "jan@example.com",
    "address": "Paczkomat InPost, ul. Testowa 1",
    "city": "Warszawa",
    "zip": "00-001",
    "country": "PL",
    "shippingMethodId": "inpostpp",
    "shippingPrice": 9.99,
    "deliveryType": "pickup",
    "pickupPointId": "WAW01A",
    "paymentMethod": "lpp_papay_payu_blik",
    "items": [
      { "productId": "123", "name": "T-shirt", "price": 49.99, "qty": 2 }
    ]
  }' \
  "https://example.com/api/bot/v1/orders"
```

**Option B — mirror cart session (`sid` cookie value):**

```bash
curl -s -X POST -H "X-API-Key: $BOT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "useCartSession": true,
    "cartSessionId": "<sid-cookie-value>",
    "firstname": "Jan",
    "lastname": "Kowalski",
    "phone": "+48123456789",
    "email": "jan@example.com",
    "address": "Sklep Sinsay, Galeria X",
    "city": "Kraków",
    "zip": "30-001",
    "shippingMethodId": "storemethod",
    "shippingPrice": 0,
    "deliveryType": "store",
    "pickupPointId": "store-42",
    "paymentMethod": "lpp_papay_payu_card"
  }' \
  "https://example.com/api/bot/v1/orders"
```

Response `201`:

```json
{
  "ok": true,
  "orderId": 42,
  "reference": "ABC123XYZ",
  "status": "new",
  "total": 109.98,
  "currency": "PLN",
  "paymentMethod": "lpp_papay_payu_blik",
  "shippingMethodId": "inpostpp"
}
```

### `GET /orders/:id`

Order status snapshot.

### `POST /orders/:id/pay`

Start Felopay payment. Requires `returnUrlSuccess` and `returnUrlFailure`. Optional `webhookUrl` (stored in Redis for future payment status callbacks).

```bash
curl -s -X POST -H "X-API-Key: $BOT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "returnUrlSuccess": "https://bot.example/success",
    "returnUrlFailure": "https://bot.example/failure",
    "webhookUrl": "https://bot.example/webhook/payment"
  }' \
  "https://example.com/api/bot/v1/orders/42/pay"
```

Response:

```json
{
  "ok": true,
  "orderId": 42,
  "reference": "ABC123XYZ",
  "paymentMethod": "lpp_papay_payu_blik",
  "paymentMethodLabel": "BLIK",
  "redirectUrl": "https://felopay.com/?token=..."
}
```

## Method IDs

Shipping: `storemethod`, `orlenpp`, `dpdmetapp`, `inpostpp`, `pocztapolskacouriermethod`, `dpdmetacouriermethod`, `dpdmetacouriermethodcod`.

Payments: `lpp_papay_payu_blik`, `lpp_papay_paypo`, `lpp_papay_payu_card`, `lpp_papay_payu_quickcheckout`, `lpp_papay_klarna`, `giftcard`, `lpp_papay_paypal`, `cashondelivery` (COD shipping only).

Real card/BLIK collection happens on **Felopay**, not on the proxy domain.