# Setl — integrace plateb

Setl je česká platební platforma pro QR platby bankovním převodem (formát SPAYD).
Zákazník naskenuje QR kód v bankovní aplikaci, převod dorazí přímo na účet obchodníka
(Fio banka) a Setl platbu automaticky spáruje podle variabilního symbolu. Žádná
karetní brána, žádné procento z transakce.

## Základní fakta

|                   |                                                                           |
| ----------------- | ------------------------------------------------------------------------- |
| API base URL      | `https://api.bezbrany.cz`                                                 |
| Web + dashboard   | `https://setl.cz`                                                         |
| OpenAPI (Swagger) | `https://api.bezbrany.cz/api/v1/docs` (JSON: `/api/v1/docs/openapi.json`) |
| Měna              | CZK                                                                       |
| **Částky**        | **v korunách jako decimal číslo** (`100` = 100,00 Kč) — NE v haléřích     |

## API klíče a autentizace

| Prefix      | Hlavička       | Kde smí být          | Oprávnění                            |
| ----------- | -------------- | -------------------- | ------------------------------------ |
| `sk_live_…` | `X-API-Key`    | jen server (backend) | plný přístup k Public API            |
| `sk_test_…` | `X-API-Key`    | jen server (backend) | testovací platby + simulace úspěchu  |
| `pk_…`      | `X-Public-Key` | frontend/prohlížeč   | jen vytvoření platby přes widget API |

**Nikdy nevkládej `sk_` klíč do frontendového kódu.** Pro platby vytvářené přímo
z prohlížeče použij veřejný `pk_` klíč a widget API.

Klíče vytváří jen přihlášený majitel účtu. Nejrychlejší cesta je stránka
`https://setl.cz/nastenka/nastaveni/pripojit` („Připojit projekt“): jedním tlačítkem
vytvoří `sk_test_` a `pk_` klíč, povolí doménu projektu a vypíše pokyny i s klíči ke
zkopírování. Pokud klíče nemáš, požádej o ně uživatele a odkaž ho tam. Ostrý `sk_live_`
klíč se vytváří v `https://setl.cz/nastenka/nastaveni/api-klice`.

## Předpoklady (jednorázové nastavení obchodníka)

1. Registrace na `https://setl.cz/prihlaseni` (magic link nebo Google).
2. Onboarding v dashboardu: údaje o firmě + bankovní účet s Fio API tokenem (read-only
   token z internetbankingu Fio). Nový Fio token vyžaduje jednorázové potvrzení v bance (PSD2).
3. Vytvořit klíče a pokyny v Nastavení → Připojit projekt.

Tyto tři kroky musí udělat člověk. Všechno ostatní (webhook URL, povolené domény pro
widget, kontrola stavu účtu) zvládneš sám přes API tajným klíčem — viz „Nastavení přes API“.

## Tarify a limity (důležité pro integraci)

| Tarif | Spárované platby / měsíc | Blokace nových plateb od | Bankovní účty | Webhooky | Branding |
| ----- | ------------------------ | ------------------------ | ------------- | -------- | -------- |
| Free  | 20                       | 22                       | 1             | ano      | ano      |
| Pro   | neomezeně                | —                        | 10            | ano      | ne       |

- Počítají se spárované (ne testovací) platby od začátku kalendářního měsíce (Europe/Prague).
- Limit v tabulce platí pro platby z integrace: vše založené přes API klíč, widget a checkout.
  QR platby, které obchodník zakládá sám v pokladně Setl (web, mobilní aplikace), mají vlastní
  limit (Free 200 měsíčně) a do tohoto se nepočítají. Přes API platbu jako pokladní označit nejde.
- Nad limitem + 10 % tolerance vrací vytvoření platby (`POST /api/v1/payments`,
  `POST /api/v1/widget/payments`) **HTTP 402** — viz sekce „Chyba 402 PLAN_LIMIT_REACHED“ níže.
  Už vytvořené platby se spárují vždy.
- **Webhooky fungují ve všech tarifech včetně Free** (i při simulaci). Jako pojistku pro
  případ nedoručení ověřuj stav přes `GET /api/v1/payments/{paymentCode}`.
- Ceny: Free 0 Kč, Pro 249 Kč/měsíc nebo 2 490 Kč/rok. Účty na dřívějším tarifu Start
  mají stejná práva jako Pro.
- `branding: true` (Free) v odpovědi widget API → widget a checkout zobrazí odkaz
  „Platby přes Setl“.

## Nastavení přes API (tajný klíč)

Začni tímhle dotazem. Ověří klíč a řekne, co je hotové:

```bash
curl https://api.bezbrany.cz/api/v1/settings -H "X-API-Key: sk_test_..."
```

```json
{
	"merchant": { "id": "uuid", "name": "Pražírna Hrnek" },
	"keyType": "test",
	"webhook": { "url": null, "secret": "whsec_..." },
	"corsOrigins": [{ "id": "uuid", "origin": "https://prazirna-hrnek.cz" }],
	"plan": { "name": "free", "matchedPayments": 3, "matchedPaymentsLimit": 20 },
	"canReceivePayments": true,
	"autoMatching": true
}
```

- `webhook.secret` ulož do env (např. `BEZBRANY_WEBHOOK_SECRET`) — ověřuješ jím podpis.
- `canReceivePayments: false` → účet nemá bankovní účet; platbu nejde vytvořit. Řekni
  uživateli, ať dokončí onboarding v `https://setl.cz/nastenka`.
- `autoMatching: false` → chybí Fio token; platby se vytvoří, ale samy se nespárují.
  Testovací platby a `simulate-success` fungují i tak. Před ostrým provozem na to upozorni.

Webhook URL (pro všechny platby bez vlastního `callback.notificationUrl`; `null` ho vypne):

```bash
curl -X PUT https://api.bezbrany.cz/api/v1/settings/webhook \
  -H "X-API-Key: sk_test_..." -H "Content-Type: application/json" \
  -d '{"url":"https://vas-eshop.cz/api/webhooks/bezbrany"}'
```

Povolené domény pro widget (protokol + doména bez cesty, nejvýš 100, platí hned;
opakované přidání téže domény vrátí `200`, ne chybu):

```bash
curl -X POST https://api.bezbrany.cz/api/v1/settings/cors-origins \
  -H "X-API-Key: sk_test_..." -H "Content-Type: application/json" \
  -d '{"origin":"https://vas-eshop.cz"}'
# GET /api/v1/settings/cors-origins — seznam; DELETE /api/v1/settings/cors-origins/{id} — odebrání
```

Bankovní účty, Fio tokeny a API klíče se přes API spravovat nedají.

## Tři způsoby integrace — kdy který

1. **REST API (backend)** — plná kontrola; e-shop se serverovou částí. Vytvoření platby
   ze serveru s `sk_` klíčem, zobrazení QR/widgetu, potvrzení webhookem.
2. **JS widget (frontend)** — nejrychlejší; statické weby nebo jednoduché košíky.
   Platbu lze vytvořit i přímo z prohlížeče s `pk_` klíčem.
3. **Hosted checkout (bez kódu)** — přesměrování zákazníka na
   `https://setl.cz/platba/{paymentCode}`; stránku hostuje Setl.

## REST API

### Vytvoření platby

Nejmenší možný požadavek:

```bash
curl -X POST https://api.bezbrany.cz/api/v1/payments \
  -H "X-API-Key: sk_test_..." -H "Content-Type: application/json" \
  -d '{"amount": 489, "currency": "CZK", "orderNumber": "OBJ-2026-001"}'
```

Se všemi volitelnými poli:

```bash
curl -X POST https://api.bezbrany.cz/api/v1/payments \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: obj-2026-001-pokus-1" \
  -d '{
    "amount": 1250.50,
    "currency": "CZK",
    "orderNumber": "OBJ-2026-001",
    "orderDescription": "Nákup v e-shopu",
    "payer": {
      "contact": { "firstName": "Jan", "lastName": "Novák", "email": "jan@example.cz", "phone": "+420777123456" },
      "billingAddress": { "street": "Vodičkova 12", "city": "Praha 1", "zipCode": "11000", "countryCode": "CZE" }
    },
    "items": [
      { "name": "Tričko s potiskem", "amount": 1250.50, "quantity": 1, "vatRate": 21 }
    ],
    "callback": {
      "returnUrl": "https://vas-eshop.cz/objednavka/dekujeme",
      "notificationUrl": "https://vas-eshop.cz/api/bezbrany-webhook"
    },
    "metadata": { "source": "web" }
  }'
```

- Povinné jsou jen `amount`, `currency` a `orderNumber`.
- `payer` je nepovinný; když ho pošleš, musí mít úplný `contact` (firstName, lastName,
  email) a zákazník dostane e-mail s potvrzením o zaplacení.
- `items` jsou nepovinné a jen informativní (name, amount, quantity); do QR ani do
  párování nevstupují.
- `expiresInMinutes` (1 až 86 400, tj. 60 dní) nastaví platnost; platbu na fakturu se
  splatností vytvoř s dostatečnou rezervou, po vypršení se už nespáruje.
- `amount` musí být v rozsahu **1 – 10 000 000 Kč**; `currency` je zatím jen `CZK`.
- `items[].amount` je cena za kus v korunách; součet položek by měl odpovídat `amount`.
- `callback.returnUrl` i `callback.notificationUrl` musí být **https** na veřejnou doménu
  (http, `localhost` a interní/privátní IP jsou v produkci odmítnuty — SSRF ochrana).
- `Idempotency-Key` (volitelná hlavička) chrání proti duplicitám při retry — stejný klíč
  se stejným payloadem vrátí původní odpověď, s jiným payloadem vrátí konflikt.

Odpověď `201`:

```json
{
	"paymentCode": "7E200D6C96FB4118",
	"status": "pending",
	"amount": 1250.5,
	"currency": "CZK",
	"orderNumber": "OBJ-2026-001",
	"qrCodeData": "data:image/png;base64,iVBORw0KGgo..."
}
```

`qrCodeData` je hotový obrázek QR kódu (PNG jako data URI) — dej ho rovnou do
`<img src="…">`. Není to textový SPAYD řetězec. Jednodušší je použít widget nebo hosted
checkout, které QR i stav platby zobrazí samy.

### Chyba 402 PLAN_LIMIT_REACHED

Když obchodník vyčerpá měsíční limit tarifu, vytvoření platby vrátí `402`:

```json
{
	"error": "Tarif Free má limit 20 spárovaných plateb za měsíc. Přejděte na vyšší tarif pro další platby.",
	"code": "PLAN_LIMIT_REACHED",
	"details": {
		"limit": "matchedPayments",
		"current": 22,
		"max": 20,
		"plan": "free",
		"upgradeTo": "pro"
	},
	"status": 402,
	"path": "/api/v1/payments",
	"timestamp": "2026-10-24T09:15:00.000Z"
}
```

- `details.limit` = který limit (`matchedPayments` / `accounts`; `posPayments` vrací jen pokladna
  Setl, integrace ho nedostane), `max` = limit tarifu,
  `plan` = aktuálně platný tarif, `upgradeTo` = doporučený vyšší tarif (`null` u Pro).
- Zákazníkovi nezobrazuj technickou chybu — ukaž přívětivou zprávu a nabídni náhradní
  platbu (např. ruční převod podle údajů v objednávce). Objednávku nezahazuj.
- Upozorni obchodníka (e-mail, log, notifikace), ať přejde na vyšší tarif.
- 402 automaticky neopakuj — dokud se tarif nezmění, skončí stejně.

### Stav platby

```bash
curl https://api.bezbrany.cz/api/v1/payments/{paymentCode} -H "X-API-Key: sk_live_..."
```

Stavy: `pending` → `completed` | `expired` | `failed`; po refundaci `refunded` /
`partially_refunded`. Platnost určuje `expiresInMinutes`. Pro potvrzení objednávky se spoléhej
primárně na webhook, stav plánovaně nepolluj častěji než ~1× za 5 s.

### Testování

S `sk_test_` klíčem vytvoř platbu a dokonči ji bez skutečných peněz:

```bash
curl -X POST https://api.bezbrany.cz/api/v1/payments/{paymentCode}/simulate-success \
  -H "X-API-Key: sk_test_..."
```

Simulace spustí i webhook — otestuješ tím celý flow.

## JS widget

Widget zobrazí QR kód, sleduje stav platby v reálném čase (Socket.IO) a po zaplacení
zobrazí potvrzení. Doména, kde widget běží, musí být v CORS doménách obchodníka.

```html
<script src="https://api.bezbrany.cz/widget/v1.js"></script>
<div data-bezbrany-widget data-payment-code="PAYMENT_CODE_Z_API"></div>
```

Programaticky:

```html
<script src="https://api.bezbrany.cz/widget/v1.js"></script>
<div id="platba"></div>
<script>
	BezBranyWidget.init({
		paymentCode: 'PAYMENT_CODE_Z_API',
		containerId: 'platba',
		onPaymentSuccess: () => {
			window.location.href = '/dekujeme';
		},
	});
</script>
```

Vytvoření platby přímo z prohlížeče (bez vlastního backendu) — veřejný `pk_` klíč:

```js
const res = await fetch('https://api.bezbrany.cz/api/v1/widget/payments', {
	method: 'POST',
	headers: { 'Content-Type': 'application/json', 'X-Public-Key': 'pk_...' },
	body: JSON.stringify({
		amount: 1250.5,
		currency: 'CZK',
		orderNumber: 'OBJ-2026-001',
	}),
});
const { paymentCode } = await res.json();
```

Stav pro widget (bez autentizace): `GET https://api.bezbrany.cz/api/v1/widget/payments/{paymentCode}`.
Odpověď obsahuje i `branding` (boolean) — `true` na tarifu Free, widget pak v patičce
zobrazí odkaz „Platby přes Setl“.

## Webhooky

Po dokončení platby pošle Setl `POST` na `callback.notificationUrl` (per platba)
nebo na webhook URL z profilu obchodníka, ve všech tarifech včetně Free.

```json
{
	"id": "b7c3e1a2-5f9d-4c2a-8e11-9a0f2d3c4b5e",
	"event": "payment.completed",
	"createdAt": "2026-07-24T10:12:30.000Z",
	"paymentId": "uuid",
	"paymentCode": "7E200D6C96FB4118",
	"orderNumber": "OBJ-2026-001",
	"status": "completed",
	"amount": 1250.5,
	"currency": "CZK",
	"metadata": {}
}
```

- `id` je unikátní ID doručení → **deduplikuj podle něj** (retry pošle stejné `id`).
- `event` je typ události (dnes `payment.completed`) → **filtruj podle něj** a ignoruj
  neznámé typy, ať tě nerozbijí budoucí události.
- `createdAt` je čas vzniku události (ISO 8601).

Každý webhook nese hlavičku `X-BezBrany-Signature: t=<unix_timestamp>,v1=<hex_podpis>`.
Podpis je HMAC SHA-256 z řetězce `"<t>.<raw_body>"` webhook secretem obchodníka —
**ověřuj nad raw tělem requestu, ne nad re-serializovaným JSON**:

```js
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
	const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
	const expected = crypto
		.createHmac('sha256', secret)
		.update(`${parts.t}.${rawBody}`)
		.digest('hex');
	return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
```

Secret získáš z `GET /api/v1/settings` (`webhook.secret`).

Odpověz `2xx` do 10 sekund; přesměrování se nenásleduje. Při selhání Setl doručení
opakuje po 1 min, 5 min, 30 min a pak každé 2 hodiny (celkem 42 pokusů), potom dostane
majitel e-mail. Endpoint musí být idempotentní — stejný webhook může dorazit vícekrát.

## Doporučený postup implementace (checklist pro agenta)

1. Zavolej `GET /api/v1/settings` — ověříš klíč a zjistíš, co je nastavené.
2. Zjisti, jestli má projekt backend → zvol REST API (backend) vs. widget s `pk_` klíčem.
3. Ulož klíče a webhook secret do env proměnných (`BEZBRANY_SECRET_KEY`,
   `BEZBRANY_PUBLIC_KEY`, `BEZBRANY_WEBHOOK_SECRET`), nikdy do kódu ani do gitu.
4. Nastav webhook URL (`PUT /api/v1/settings/webhook`) a u widgetu povol doménu
   (`POST /api/v1/settings/cors-origins`).
5. Implementuj vytvoření platby při dokončení objednávky; `orderNumber` = číslo objednávky.
6. Zobraz platbu: widget (doporučeno) / obrázek z `qrCodeData` / redirect na hosted checkout.
7. Implementuj webhook endpoint: ověření podpisu nad raw body → idempotentní zpracování
   → označ objednávku jako zaplacenou při `status === "completed"` → vrať `200`.
8. Ošetři `402 PLAN_LIMIT_REACHED` při vytváření platby (přívětivá zpráva + náhradní
   platební instrukce zákazníkovi, upozornění obchodníkovi).
9. Otestuj celý flow s `sk_test_` klíčem a `simulate-success`; pak požádej uživatele
   o `sk_live_` klíč a vyměň ho v env.

## Časté chyby

- ❌ Částky v haléřích (`10000` místo `100`) — API pracuje **v korunách** (decimal).
- ❌ `sk_` klíč ve frontendu — do prohlížeče patří jen `pk_`.
- ❌ Widget na doméně, která není v CORS doménách obchodníka → requesty selžou.
- ❌ Ověřování webhook podpisu nad `JSON.stringify(req.body)` místo raw body.
- ❌ Potvrzení objednávky jen podle `returnUrl` — návrat zákazníka nic negarantuje,
  jediný spolehlivý signál je webhook (nebo dotaz na stav platby přes API).
- ❌ Chybějící `Idempotency-Key` u retry logiky → duplicitní platby.
- ❌ `notificationUrl`/`returnUrl` na `http`, `localhost` nebo interní IP → v produkci
  odmítnuto (musí být https na veřejnou doménu).
- ❌ Webhook zpracovaný vícekrát bez deduplikace → použij pole `id` z payloadu.
- ❌ Vykreslování `qrCodeData` jako textu do QR knihovny — je to už hotový obrázek PNG.
- ❌ Neošetřená `402 PLAN_LIMIT_REACHED` → zákazník uvidí chybu místo náhradních platebních instrukcí.
