Tenhle návod je pro správce portálu a člověka, který ve firmě řeší napojení systémů. Vysvětluje, k čemu jsou API, webhooky a MCP a co je potřeba nastavit. Technické detaily má váš vývojář v dokumentaci API, odkaz Otevřít dokumentaci API najdete v portálu na stránce API a integrace.
Co k čemu slouží
| Nástroj | Kdy ho použít | Příklad |
|---|---|---|
| REST API | jiný systém si z portálu něco čte nebo do něj zapisuje | ERP si stahuje objednávky, skript založí nabídku |
| Webhooky | portál sám dá vědět, když se něco stane | zákazník schválil nabídku a CRM si založí úkol |
| MCP | AI asistent pracuje s daty v portálu | „Které moje nabídky čekají na odpověď?“ |
Portál nemá hotové konektory na Pohodu, Money ani jiné ERP. Napojení si uděláte přes API a webhooky, sami nebo s dodavatelem. Objednávky přitom vznikají ve Shoptetu, takže napojení Shoptetu na ERP funguje dál jako dosud.
REST API
Co umíte v portálu, umí i API: číst zákazníky, objednávky, nabídky, katalog a přehledy, počítat B2B ceny, zakládat objednávky a nabídky. Manažerovi a správci API slouží i ke správě pravidel, týmu a nastavení.
Jak vytvořit API token
- V menu otevřete API a integrace.
- V kartě Nový token vyplňte název, podle kterého ho poznáte, třeba „ERP, import objednávek“.
- Volitelně zadejte Platnost do. Nejdelší platnost určuje manažer, výchozí je 365 dní.
- Zaškrtněte Oprávnění (scopes). Tlačítko Jen čtení vybere jen čtecí oprávnění.
- Klikněte na Vytvořit token.
Token se zobrazí jen jednou. Zkopírujte si ho a uložte do systému, který ho bude používat. Znovu ho nezobrazí nikdo, ani správce.
Pár zásad:
- Pro každý systém vytvořte samostatný token, ať ho jde zrušit bez vlivu na ostatní.
- Dávejte mu jen oprávnění, která opravdu potřebuje.
- Token nevkládejte do e-mailu, chatu ani do kódu v gitu.
Co token smí
Token jedná vaším jménem a ve vaší roli. Token obchodníka proto uvidí jen zákazníky jeho kmene, stejně jako v portálu. Každý zápis se objeví v audit logu s kanálem API.
Manažer a správce musí mít zapnuté dvoufázové ověření, jinak jejich tokeny nefungují.
Všechny vaše tokeny se zruší, když si změníte heslo, když vás někdo deaktivuje, nebo když při odhlášení ostatních zařízení zaškrtnete Zrušit i API tokeny.
Tokeny celého týmu
Správce vidí v API a integrace navíc kartu Tokeny celého týmu: komu token patří, kdy byl naposledy použit a do kdy platí. Může kterýkoli zrušit, třeba po kolegovi, který odešel. Za jiného uživatele token vytvořit nejde.
Limity
Každý token smí poslat nejvýš 120 požadavků za minutu, REST API a MCP dohromady. Vytvoření objednávky a převod nabídky mají navíc limit 20 za minutu na uživatele.
Webhooky
Webhook je zpráva, kterou portál sám pošle na adresu vašeho systému, když se něco stane. Váš systém se tak nemusí pořád ptát přes API. Hodí se i pro automatizační nástroje jako Make nebo n8n. Webhooky spravuje jen správce.
Jak přidat webhook
- V menu otevřete Webhooky a klikněte na Přidat webhook.
- Vyplňte URL adresu příjemce. Musí začínat
https://a vést na veřejný server. - Volitelně doplňte popis.
- Vyberte události, o kterých chcete zprávy dostávat.
- Klikněte na Přidat webhook.
Portál hned ukáže secret pro ověření podpisu. Zkopírujte si ho a předejte tomu, kdo příjemce nastavuje, po zavření ho už neuvidíte. Příjemce má podle něj ověřit, že zprávu poslal opravdu portál. Postup je v dokumentaci API.
Jaké události portál posílá
- Nabídky: odeslání, dotaz zákazníka, schválení, odmítnutí, vypršení, stažení, převod na objednávku.
- Objednávky: založení objednávky portálem, žádost o schválení, schválení a zamítnutí manažerem. Objednávky z e-shopu sem nepatří.
- Zákazníci: přiřazení obchodníkovi. Při předání kmene přijde zpráva za každého zákazníka.
- Cenová pravidla: vytvoření, změna a vypnutí.
Když příjemce neodpovídá
Po chybě to portál zkusí znovu po 1 minutě, 5 minutách, 30 minutách, 2 hodinách a 12 hodinách. Pak doručení označí jako Selhalo. Problém s webhookem nikdy nezastaví obchodní akci, objednávka nebo nabídka vznikne i tak.
V detailu webhooku je Log doručení za posledních 30 dní. Tlačítko Otestovat pošle zkušební zprávu a Poslat znovu zopakuje konkrétní doručení.
MCP: napojení AI asistenta
MCP je standardní způsob, jak dát AI asistentovi přístup k jinému systému. Když asistenta připojíte k portálu, můžete mu napsat třeba „Najdi zákazníka Novák a ukaž mi jeho pohledávky“ a on si data sám vyžádá.
Co budete potřebovat
- Adresu MCP serveru. Najdete ji v API a integrace v kartě „Jak API použít“.
- API token, nejlépe samostatný pro asistenta a pro začátek jen pro čtení.
- AI klienta, který umí vzdálený MCP server s vlastní hlavičkou
Authorization. Patří mezi ně například Claude Code.
Portál zatím nepodporuje přihlášení přes OAuth. Klienti, kteří u vzdálených serverů umí jen OAuth, typicky webové konektory bez možnosti zadat hlavičku, se proto zatím nepřipojí.
Připojení v Claude Code
claude mcp add --transport http b2b-portal https://adresa-vaseho-portalu/mcp \
--header "Authorization: Bearer VAS_TOKEN"
Místo adresy a VAS_TOKEN doplňte své údaje. Konfiguraci s tokenem nikomu neposílejte.
Co může asistent dělat
- hledat zákazníky a shrnout jejich tržby a pohledávky,
- spočítat B2B cenu i s rozpadem, odkud se bere,
- číst nabídky a objednávky,
- připravit a odeslat nabídku nebo založit objednávku,
- ukázat tržby a pohledávky za měsíc, čtvrtletí nebo rok,
- hledat v nápovědě a ve wiki vaší firmy.
Co přesně smí, určují oprávnění tokenu a vaše role.
Zápis jen po potvrzení
Všechno, co něco mění, probíhá ve dvou krocích. Asistent nejdřív ukáže náhled: položky, ceny, součty, jestli bude potřeba schválení manažerem a komu se pošle e-mail. Zapíše to až po vašem souhlasu.
- Náhled si přečtěte, než zápis odsouhlasíte. Portál nepozná, jestli jste ho opravdu četli.
- Používejte klienta, který se vás před každým použitím nástroje zeptá.
- Přes MCP nejde nic smazat.
- Cena pod minimální marží čeká na schválení manažerem, stejně jako v portálu.
Co asistent vidí
Stejná pravidla jako v portálu. Obchodník přes asistenta uvidí jen svůj kmen a stránky wiki pro manažery nedostane. Každý zápis přes MCP je v audit logu s kanálem AI (MCP) a pod vaším jménem.
Dotazy zákazníků a obsah wiki jsou pro asistenta data, ne pokyny. Portál mu to výslovně říká. I tak platí, že zápis schvalujete vy.
Příklady, co asistentovi napsat
- „Najdi zákazníka s IČO 12345678 a shrň mi jeho tržby a pohledávky po splatnosti.“
- „Které moje nabídky čekají na odpověď zákazníka nebo mají dotaz?“
- „Kolik by stálo 20 ks produktu 21/XL pro firmu Novák s.r.o.? Ukaž, odkud se cena bere.“
- „Připrav nabídku pro Novák s.r.o.: 20 ks 21/XL a 5 ks 33/M, platnost 14 dní. Nejdřív mi ukaž náhled.“
- „Jaké mám tržby tento měsíc ve srovnání s minulým?“
- „Co říká naše wiki o platebních podmínkách pro nové zákazníky?“