# API pro platby

Jak získat přihlašovací údaje k API pro platby, ověřit spojení, přečíst čekající platby rezervací a vstupenek a platbu potvrdit nebo zamítnout.

## Pro koho to je

Pro poskytovatele s vlastním systémem (účetnictví, párování plateb z banky), který chce k Obsadtu přistupovat strojově. Obsadto samo žádné požadavky na adresu vašeho systému neposílá (webhooky nemá); váš systém se na čekající platby dotazuje sám.

Článek popisuje získání přihlašovacích údajů, ověření spojení a operace s rezervacemi (platba předem) a s objednávkami vstupenek placenými převodem.

## Než začnete

Potřebujete tarif Pro+ s aktivním předplatným a přihlášení jako majitel účtu. Tarif zkontrolujete v Předplatné. Za bezpečné uložení secretu a osobních údajů ve svém systému odpovídáte vy.

## Jak získat přihlašovací údaje

1. Otevřete Nastavení → Integrace → API pro platby a stiskněte Spravovat API pro platby.
2. Stiskněte Vygenerovat přihlašovací údaje.
3. Zkopírujte Client id a Secret tlačítky Kopírovat a uložte je do svého systému na bezpečné místo. Secret se zobrazí jen jednou a znovu ho zobrazit nejde.
4. Kdyby se secret ztratil nebo unikl, stiskněte Vygenerovat nové a potvrďte. Starý secret okamžitě přestane platit. Přístup úplně zrušíte tlačítkem Zrušit přístup.

## Jak ověřit spojení

Každý požadavek nese hlavičku `Authorization: Basic` s hodnotou `base64(clientId:secret)`. Ověření spojení je volání `GET /api/v1/payments/ping`:

```
curl -u CLIENT_ID:SECRET https://obsadto.cz/api/v1/payments/ping
```

Při správných údajích přijde odpověď 200:

```
{ "provider": "Salon Marika", "serverTime": "2026-11-17T10:15:30.1234567Z" }
```

Chyby mají vždy tvar `{ "error": "kód", "message": "text česky" }`:

- 401 neplatné nebo zrušené údaje (`invalid_credentials`),
- 403 účet nemá Pro+ nebo má neaktivní předplatné (`forbidden`),
- 429 překročený limit (`rate_limited` nebo `too_many_failed_logins`), odpověď má hlavičku `Retry-After` s počtem sekund do dalšího pokusu.

## Rezervace

Operace se týkají rezervací s platbou předem a pracují výhradně s daty poskytovatele, kterému patří client id. Všechny adresy jsou pod `https://obsadto.cz/api/v1/payments/bookings` a používají stejné přihlášení `Authorization: Basic` jako ověření spojení. Variabilní symbol (VS) je v adrese, částku API nepřijímá: vrací jen očekávanou částku, kontrola přeplatků a nedoplatků je věcí vašeho systému. Těla požadavků `confirm` a `reject` jsou prázdná a případný obsah se ignoruje.

### Seznam čekajících

`GET /api/v1/payments/bookings/pending?pageNumber=1` vrátí rezervace, které právě čekají na platbu (platba předem uplatněná, nezaplaceno, čeká na schválení). Historie v seznamu není. Na stránce je 100 položek od nejstarší, `pageNumber` začíná jedničkou.

```
curl -u CLIENT_ID:SECRET "https://obsadto.cz/api/v1/payments/bookings/pending?pageNumber=1"
```

```
{
  "items": [
    {
      "variableSymbol": "77110042",
      "status": "pending",
      "amount": 150.00,
      "currency": "CZK",
      "start": "2026-11-20T10:00:00+01:00",
      "end": "2026-11-20T11:00:00+01:00",
      "createdAt": "2026-11-18T09:15:02+01:00",
      "dueDate": null,
      "service": "Střih",
      "staff": "Marie",
      "customer": { "name": "Jana Nováková", "email": "jana@example.com", "phone": "+420777111222", "note": "Prosím kratší" }
    }
  ],
  "pageNumber": 1,
  "pageSize": 100,
  "total": 1
}
```

Každá položka má pole: `variableSymbol`, `status`, `amount` (v korunách, vždy se dvěma desetinnými místy), `currency`, `start` a `end` (ISO 8601 s posunem časové zóny poskytovatele), `createdAt`, `dueDate` (rezervace dnes splatnost nemá, vrací se `null`), `service` (název služby), `staff` (jméno nebo `null`) a `customer` (`name`, `email`, `phone`, `note`, kterékoli může být `null`).

### Stav podle VS

`GET /api/v1/payments/bookings/{vs}` vrátí tutéž položku pro jeden VS, **i v minulosti**. Hodí se ke zjištění, že platba patří ke zrušené rezervaci: zákazník mohl rezervaci zrušit a přesto zaplatit.

```
curl -u CLIENT_ID:SECRET https://obsadto.cz/api/v1/payments/bookings/77110042
```

Odpověď 200 je položka jako výše, například se `status` `cancelled`.

### Potvrzení platby

`POST /api/v1/payments/bookings/{vs}/confirm` provede totéž co tlačítko Platba přijata v panelu: rezervace se potvrdí, zapíše se datum úhrady a zákazník dostane potvrzení e-mailem.

```
curl -u CLIENT_ID:SECRET -X POST https://obsadto.cz/api/v1/payments/bookings/77110042/confirm
```

Odpověď 200 s položkou, `status` je `paid`. Opakované potvrzení už zaplacené rezervace nic neprovede (žádný druhý e-mail, datum úhrady zůstane) a vrátí 200 se stavem `paid`. U rezervace, která už není (`rejected`, `cancelled`, `completed`), se nic neprovede a odpověď je 409:

```
{ "error": "booking_not_pending", "message": "Taková rezervace už není." }
```

### Zamítnutí

`POST /api/v1/payments/bookings/{vs}/reject` odmítne rezervaci, uvolní termín a pošle zákazníkovi e-mail, stejně jako odmítnutí v panelu. Platí i pro už zaplacenou rezervaci, jejíž termín ještě neproběhl; vrácení peněz Obsadto neřeší.

```
curl -u CLIENT_ID:SECRET -X POST https://obsadto.cz/api/v1/payments/bookings/77110042/reject
```

Odpověď 200 se `status` `rejected`. Opakované zamítnutí už zamítnuté rezervace vrátí 200 bez dalšího účinku. U `cancelled` a `completed` je odpověď 409 `booking_not_pending`.

### Stavy a chybové kódy

| `status` | Význam |
|---|---|
| `pending` | čeká na platbu |
| `paid` | zaplaceno, rezervace potvrzená |
| `rejected` | zamítnuto |
| `cancelled` | rezervace zrušena (zákazníkem i poskytovatelem) nebo vypršela splatnost; data nerozlišují, kdo zrušil |
| `completed` | proběhlo |

| Odpověď | Kdy |
|---|---|
| 200 | operace proběhla, nebo už byla provedena dříve |
| 401 `invalid_credentials` | neplatné nebo zrušené údaje |
| 403 `forbidden` | účet nemá Pro+ nebo neaktivní předplatné |
| 404 `not_found` | neznámý VS, VS jiného poskytovatele nebo rezervace bez platby předem (odpověď je záměrně stejná) |
| 409 `booking_not_pending` | rezervace už není ve stavu, ve kterém jde operaci provést |
| 429 `rate_limited`, `too_many_failed_logins` | překročený limit, hlavička `Retry-After` |

Příklad odpovědi 404:

```json
{ "error": "not_found", "message": "Položka s tímto variabilním symbolem neexistuje." }
```

Lhůty si hlídá váš systém, Obsadto nic samo neruší. Když splatnost vyprší, pošlete zamítnutí. Do té doby rezervace drží termín. Při souběhu dvou potvrzení téhož VS je výsledek stejný jako u opakovaného požadavku a e-mail odejde jednou. Každé volání se zapisuje do záznamu (operace `bookings.pending`, `bookings.status`, `bookings.confirm`, `bookings.reject`).

## Vstupenky

Stejné operace existují pro objednávky vstupenek na akce, které zákazník platí převodem na účet. Adresy jsou pod `https://obsadto.cz/api/v1/payments/tickets`, přihlášení, limity, záznam volání, chybové odpovědi a chování při opakovaném požadavku jsou stejné jako u rezervací. API vidí jen objednávky placené převodem: objednávky placené jinak nejsou v seznamu a jejich stav vrací 404. Blokace prodeje vstupenek ve zkušební době se nemění.

| Adresa | Co dělá |
|---|---|
| `GET /api/v1/payments/tickets/pending?pageNumber=1` | objednávky, které právě čekají na platbu převodem; bez historie, 100 na stránku od nejstarší |
| `GET /api/v1/payments/tickets/{vs}` | stav jedné objednávky, i v minulosti |
| `POST /api/v1/payments/tickets/{vs}/confirm` | potvrzení platby, totéž co Platba přijata v panelu; zákazníkovi odejdou vstupenky |
| `POST /api/v1/payments/tickets/{vs}/reject` | zamítnutí, totéž co Platba nedorazila v panelu; místa se vrátí do prodeje a zákazník dostane e-mail |

```
curl -u CLIENT_ID:SECRET "https://obsadto.cz/api/v1/payments/tickets/pending?pageNumber=1"
```

```
{
  "items": [
    {
      "variableSymbol": "88120017",
      "status": "pending",
      "amount": 500.00,
      "currency": "CZK",
      "eventName": "Ples",
      "eventStart": "2026-11-28T19:00:00+01:00",
      "ticketCount": 3,
      "tickets": [ { "type": "Vstupné", "count": 2 }, { "type": "Děti", "count": 1 } ],
      "createdAt": "2026-11-18T09:15:02+01:00",
      "dueDate": "2026-11-21T09:15:02+01:00",
      "customer": { "name": "Jana Nováková", "email": "jana@example.com", "phone": "+420777111222", "note": null }
    }
  ],
  "pageNumber": 1,
  "pageSize": 100,
  "total": 1
}
```

Každá položka má pole: `variableSymbol`, `status`, `amount` (v korunách, vždy se dvěma desetinnými místy), `currency`, `eventName`, `eventStart` (ISO 8601 s posunem časové zóny poskytovatele), `ticketCount`, `tickets` (pole `type` a `count`), `createdAt`, `dueDate` (splatnost objednávky nebo `null`) a `customer` (`name`, `email`, `phone`, `note`, kterékoli může být `null`; `note` je u vstupenek vždy `null`).

**Potvrzení.** U čekající objednávky se potvrdí platba a odejdou vstupenky; odpověď 200 má `status` `paid`. U už zaplacené objednávky vrátí 200 bez účinku (vstupenky se podruhé neposílají). U ostatních stavů je odpověď 409:

```
{ "error": "order_not_pending", "message": "Taková objednávka už není." }
```

**Zamítnutí.** U čekající objednávky se uvolní místa a zákazník dostane e-mail o stornu. U už zaplacené objednávky se objednávka zruší stejně jako tlačítko Zrušit v panelu: vstupenky přestanou platit (sken vrátí neplatnou), místa se uvolní, zákazník dostane e-mail Objednávka vstupenek byla zrušena s kontaktem na pořadatele a peníze mu vracíte sami, Obsadto je nevrací. Odpověď 200 má `status` `rejected`; opakované zamítnutí vrátí 200 bez dalšího účinku. U `cancelled` a `completed` je odpověď 409 `order_not_pending`.

| `status` | Význam |
|---|---|
| `pending` | čeká na platbu |
| `paid` | zaplaceno, vstupenky odeslány |
| `rejected` | zamítnuto nebo zrušeno pořadatelem |
| `cancelled` | akce byla zrušena |
| `completed` | akce proběhla |

Zákazník objednávku sám zrušit nemůže, proto stav zrušeno zákazníkem u vstupenek neexistuje. Operace záznamu volání jsou `tickets.pending`, `tickets.status`, `tickets.confirm` a `tickets.reject`.

### Předčíslí variabilního symbolu

Rezervace a vstupenky hledá API podle variabilního symbolu zvlášť, každá adresa pracuje jen se svými položkami. Aby se symboly nepletly, dejte rezervacím a vstupenkám dvě různá předčíslí stejné délky, například 7711 a 8812. Předčíslí nastavíte v poli Předčíslí variabilního symbolu vstupenek a u rezervací v poli Prefix variabilního symbolu.

## Limity a záznam volání

Povoleno je 30 požadavků za minutu na jedno client id. Počítají se jen požadavky, u kterých platilo přihlášení; cizí požadavky se špatným secretem vám limit nespotřebují. Hlavička `Retry-After` u odpovědi 429 říká, za kolik sekund okno skončí. Po 10 neúspěšných přihlášeních za minutu z jedné adresy se z ní 15 minut odmítá vše a vznikne jediný řádek v záznamu o blokaci. Posledních 50 volání vidíte na stránce API pro platby, záznam se uchovává 90 dní. Neúspěšné přihlášení se zapíše jen tehdy, když zadané client id patří vám (platné i zrušené), takže pokus se zrušenými údaji uvidíte. Neznámé client id a požadavky z blokované adresy se nezapisují. Podrobnosti jsou v příručce [API pro platby](https://obsadto.cz/napoveda/reference/api-platby.md).

## Stránkování, chyby a mezipaměť

- `pageNumber` začíná jedničkou. Nad 100 000 vrací API prázdný seznam (`items: []`, `total` je skutečný počet). Hodnota, která není celé číslo (například `abc`), vrátí 400 `invalid_parameter`.
- Každá chyba má tvar `{ "error": "...", "message": "..." }`. Nepovolená metoda (například `POST /api/v1/payments/ping` nebo `GET .../confirm`) vrací 405 `method_not_allowed` s hlavičkou `Allow`. Záznam volání v panelu ukazuje stejný kód, jaký dostal váš systém.
- Odpovědi obsahují osobní údaje zákazníků a mají hlavičku `Cache-Control: no-store`; neukládejte je do sdílené mezipaměti.
- Zrušená objednávka vstupenek se nedá potvrdit ani po zrušení v panelu: potvrzení vrátí 409 `order_not_pending`.

Verze nápovědy: 1.0.2.74, 2026-11-22
