Nápověda k nastavení

API pro platby

Nastavujete s pomocí AI? Dejte jí nejdřív přečíst naši nápovědu. Zkopírujte tuto adresu a vložte ji do chatu:

https://obsadto.cz/llms-full.txt

← Všechny články nápovědy

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" }:

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ěť