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
- Otevřete Nastavení → Integrace → API pro platby a stiskněte Spravovat API pro platby.
- Stiskněte Vygenerovat přihlašovací údaje.
- 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.
- 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_limitednebotoo_many_failed_logins), odpověď má hlavičkuRetry-Afters 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:
{ "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.
Stránkování, chyby a mezipaměť
pageNumberzačíná jedničkou. Nad 100 000 vrací API prázdný seznam (items: [],totalje skutečný počet). Hodnota, která není celé číslo (napříkladabc), vrátí 400invalid_parameter.- Každá chyba má tvar
{ "error": "...", "message": "..." }. Nepovolená metoda (napříkladPOST /api/v1/payments/pingneboGET .../confirm) vrací 405method_not_alloweds hlavičkouAllow. 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.