Napojení dat z Depota přes API (GraphQL)

Než začnete

• Přihlaste se do Depota jako správce — pro API přístup potřebujete vlastní uživatelský účet s odpovídajícími právy.
• Pro přístup jen ke čtení doporučujeme vytvořit samostatný účet s omezenými oprávněními (Nastavení → Uživatelé).

Přehled API

Depoto poskytuje data přes GraphQL API. GraphQL umožňuje dotazovat přesně ta pole, která potřebujete. Vhodné pro vlastní dashboardy, napojení na BI nástroje (Google Sheets, Metabase), nebo automatizace.

Endpoint

• Produkční: https://server1.depoto.cz/graphql
• GraphQL Explorer (interaktivní dokumentace): https://server1.depoto.cz/graphql/explorer
• Stage (testovací): https://server1.depoto.cz.tomatomstage.cz/graphql

Autentizace

API používá OAuth2 (username + password flow). Token se získá automaticky při inicializaci PHP klienta, nebo ručně přes OAuth2 token endpoint.

Doporučujeme pro API přístupy vytvořit samostatného uživatele s minimálními oprávněními — viz Nastavení → Uživatelé.

Potřebuji API klíč pro napojení e-shopu

Depoto API klíče nevydává. K API se přihlašujete e-mailem a heslem uživatele Depota, za které dostanete přístupový token.

1. Pokud e-shop běží na platformě, pro kterou má Depoto hotový doplněk (například Shoptet, Shopify nebo Upgates), API nepotřebujete. Postup je v článku Začínáme: napojení e-shopu.
2. Pro vlastní napojení založte v Nastavení → Uživatelé samostatného uživatele jen pro tuto integraci a dejte mu jen práva, která integrace potřebuje. Jeho e-mail a heslo předejte tomu, kdo napojení programuje.
3. Oficiální PHP knihovna (viz níže) si token získá a obnovuje sama, stačí jí adresa serveru, e-mail a heslo.
4. Při napojení v jiném jazyce se token získává na adrese https://server1.depoto.cz/oauth/v2/token (OAuth2, typ password). Kromě e-mailu a hesla k tomu jsou potřeba identifikátor a tajný klíč klienta OAuth (client_id, client_secret).

Přístupový token platí 12 hodin, obnovovací token 14 dní. Napojení si můžete nejdřív vyzkoušet na testovacím serveru (stage).

PHP klientská knihovna

Pro PHP existuje oficiální klientská knihovna tomatom/depoto-php-client:

composer require tomatom/depoto-php-client

Inicializace (vyžaduje PSR-18 HTTP klient, PSR-16 cache, PSR-3 logger):

$depoto = new Client($httpClient, $psr17Factory, $psr17Factory, $cache, $logger);
$depoto->setBaseUrl('https://server1.depoto.cz')
    ->setUsername('vas-email@firma.cz')
    ->setPassword('heslo');

Příklady dotazů

Načtení produktu

$product = $depoto->query('product', ['id' => 123], [
    'data' => ['id', 'name', 'ean', 'code', 'quantities' => ['depot', 'quantityAvailable']]
]);

Načtení objednávky

$order = $depoto->query('order', ['id' => 456], [
    'data' => ['id', 'reservationNumber', 'processStatus' => ['id', 'name']]
]);

Vytvoření objednávky

$order = $depoto->mutation('createOrder', [
    'status' => 'reservation',
    'customer' => $customerId,
    // ... další parametry
]);

Rate limits

Konkrétní rate limity nejsou veřejně zdokumentovány. Pro dotazy na limity nebo při větším objemu requestů kontaktujte podporu Depoto na podpora@depoto.cz.

Interaktivní dokumentace (GraphQL Explorer)

Přehled všech dostupných dotazů (queries), mutací a datových typů najdete v GraphQL Exploreru na adrese https://server1.depoto.cz/graphql/explorer. Explorer umožňuje dotazy rovnou testovat v prohlížeči po přihlášení.

Kdy použít API vs. exporty

• Exporty (Excel): jednorázové nebo pravidelné stažení dat, vhodné pro účetnictví a Excel.
• GraphQL API: průběžná integrace, vlastní reporting, napojení na BI nástroje, automatizace (tvorba objednávek, aktualizace zásob).

Související články

• Jak číst statistiky prodejů
• Přístup na testovací (stage) server
• Automatické reporty e-mailem (např. faktury do účetnictví)
• Inventura skladu krok za krokem
• Skladový list a hodnota skladu
• Report prodaného zboží v nákupních cenách (NC)