Pro vývojáře

REST API, CLI a MCP server pro posílání fyzických dopisů v Česku — tři rozhraní, jedno jádro.

REST API

Čtyři JSON endpointy pod /api. Tělo požadavku u odesílání a náhledu je stejné jako vstup MCP nástroje send_letter_cz.

POST /api/send

Odeslat dopis

Vytiskne, obálkuje a odešle dopis přes Českou poštu. Strhává se z předplaceného kreditu; cena se počítá z vykresleného PDF (pásmo poštovného + tisk).

POST /api/preview

Náhled + pevná cena

Vykreslí přesné PDF, které by šlo do tisku, a vrátí ho i s pevnou cenou. Bez vedlejších efektů — použij před /api/send nebo /api/oneoff, aby člověk viděl, co se pošle.

POST /api/topup

Dobít kredit

Dobije předplacený kredit v CZK přes Stripe. Vrátí odkaz na Stripe Checkout.

POST /api/oneoff

Zaplatit jeden dopis bez účtu

Jednorázová platba kartou za jeden dopis. Cena se spočítá z vykresleného PDF a vrátí se platební odkaz.

Autentizace a platba (401 / 402)

Chybějící nebo neplatný API klíč u neplatného dopisu vrací 401.
Platný, ale nekrytý dopis (bez klíče, nebo s nedostatkem kreditu) vrací 402 s tělem, které nese obě platební cesty: rails.oneoff.payUrl (hotový platební odkaz přesně na tenhle dopis) a rails.credit.topupUrl (dobití předplaceného kreditu).
/api/preview nikdy nic neúčtuje ani neodesílá — jen vykreslí PDF a spočítá pevnou cenu.

CLI

Terminálový klient @postbotcz/cli volá stejné jádro jako REST a MCP.

Instalace

npm i -g @postbotcz/cli
# nebo: bun add -g @postbotcz/cli

Použití

posta send letter.md --to-name "Jan Novák" --to-street "Dlouhá" --to-house "5" --to-city "Praha" --to-zip "110 00"
posta status 201007091003

MCP self-host

Hostovaný server (bez instalace)

Přidej https://postbot.cz/mcp do svého agenta jako vzdálený MCP server (Streamable HTTP) — nic neinstaluješ.

Vlastní hosting (stdio)

bunx @postbot/mcp

Kompletní 3-krokový recept na připojení agenta (instalace, první dopis, kredit) najdeš na stránce Pro agenty.

Discovery pro agenty

Strojově čitelné vstupní body pro agenty, kteří si Postbot objevují sami.

Ceny

Aktuální minimální částky a vzorec pro výpočet ceny najdeš na stránce Ceník.