API

Přes API zakládá váš e-shop nebo skladový systém reklamace a servisní zakázky rovnou do Spree a čte jejich stav. Nikdo je pak nemusí přepisovat ručně.

API je součástí každého placeného tarifu. Tarify se liší jen počtem dotazů za minutu: Standard 60, Profi 240, u individuálních tarifů podle domluvy. Kolik máte vy, uvidíte na stránce Nastavení → API. V tarifu Free stránku uvidíte, ale token na ní nevydáte.

Vydání tokenu

Otevřete Nastavení → API.
Klikněte na Vytvořit token a pojmenujte ho podle systému, který ho bude používat.
Token se zobrazí jen jednou. Zkopírujte si ho a uložte do svého systému. Uchováváme jen jeho otisk, takže vám ho nedokážeme znovu ukázat ani my.

Token má práva účtu, pod kterým jste ho vydali, a vidí jen záznamy vaší firmy. V seznamu u něj vidíte, kdy byl naposledy použit. Tlačítkem Zrušit ho kdykoli zneplatníte, systém, který ho používá, se od té chvíle nepřipojí.

Volání

Token se posílá v hlavičce:

Authorization: Bearer VÁŠ_TOKEN
Accept: application/json

Počet dotazů za minutu je daný tarifem a počítá se za celou firmu, ne za jednotlivý token. Když limit překročíte, vrátíme stav 429; zopakujte dotaz za chvíli.

Založení záznamu

curl -X POST https://spree.cz/api/v1/claims \
  -H "Authorization: Bearer VÁŠ_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "complaint",
    "external_id": "OBJ-1001",
    "name": "Jan Novák",
    "email": "[email protected]",
    "phone": "+420777123456",
    "subject": "Rozbitý displej",
    "description": "Displej po měsíci prasknul.",
    "package_content": "telefon, nabíječka",
    "invoice_number": "FA-2026-1",
    "requested_resolution_method": "repair"
  }'

type je complaint, nebo service. U reklamace je povinné číslo dokladu a požadovaný způsob vyřízení, u servisu ne; servis navíc přijímá expected_price, tedy odhad ceny sdělený zákazníkovi.

external_id je číslo záznamu ve vašem systému. Není povinné, ale vyplatí se: když se spojení přeruší a vy zavoláte znovu, dostanete původní záznam místo duplicity.

Odpověď obsahuje číslo záznamu a odkaz na sledování, který můžete poslat zákazníkovi:

{
  "data": {
    "reference": "260042",
    "external_id": "OBJ-1001",
    "type": "complaint",
    "status": { "slug": "awaiting", "name": "Na cestě" },
    "tracking_url": "https://spree.cz/sledovani/..."
  }
}

Stav záznamu

curl https://spree.cz/api/v1/claims/260042 \
  -H "Authorization: Bearer VÁŠ_TOKEN" \
  -H "Accept: application/json"

Seznam záznamů

Pro průběžnou synchronizaci se hodí seznam seřazený podle poslední změny:

curl "https://spree.cz/api/v1/claims?updated_since=2026-09-01&limit=50" \
  -H "Authorization: Bearer VÁŠ_TOKEN" \
  -H "Accept: application/json"

Parametry jsou nepovinné: updated_since (datum), status (například arrived), limit (nejvýš 100) a cursor.

Odpověď obsahuje next_cursor. Dokud není null, jsou další stránky; hodnotu pošlete zpátky v parametru cursor:

{ "data": [ ... ], "next_cursor": "eyJjbGFpbXMudXBk..." }

Když si u sebe uložíte čas posledního stažení a příště ho pošlete v updated_since, doptáte se jen na to, co se od té doby změnilo.

Doklad v PDF

curl "https://spree.cz/api/v1/claims/260042/documents/17" \
  -H "Authorization: Bearer VÁŠ_TOKEN" \
  -o doklad.pdf

Čísla dokladů k záznamu zjistíte ze seznamu dokladů v aplikaci. Doklad cizího záznamu se přes API nestáhne.

Oznámení o změně stavu

Aby se váš systém nemusel doptávat, můžeme mu při každé změně stavu záznamu poslat zprávu sami. V Nastavení → API zvolte Nastavit webhook a zadejte adresu. Prázdné pole oznámení vypne.

Posíláme POST s tělem:

{
  "event": "claim.status_changed",
  "sent_at": "2026-09-13T17:30:00+02:00",
  "data": { "reference": "260042", "status": { "slug": "arrived", "name": "Přijato" } }
}

Spolu s adresou vznikne tajemství, které vidíte na stránce. Z těla zprávy si spočítejte HMAC SHA-256 tímto klíčem a porovnejte s hlavičkou X-Spree-Signature ve tvaru sha256=…. Když podpis nesedí, zprávu zahoďte, nepřišla od nás.

Odpovězte stavem 2xx. Když odpovíte chybou nebo neodpovíte vůbec, zprávu zkusíme poslat znovu, celkem pětkrát s rostoucí prodlevou od minuty do hodiny. Potom tu zprávu vzdáme.

Když se za sebou nepodaří doručit pět zpráv, oznámení vypneme a napíšeme vám o tom e-mail. Nemá smysl bušit do adresy, která neodpovídá. Na stránce Nastavení → API to uvidíte červeně. Až bude váš systém v pořádku, zapnete oznámení tím, že adresu uložíte znovu; stavy, které mezitím unikly, si doberete seznamem záznamů. Jedna nedoručená zpráva mezi doručenými nevadí, počítadlo se při každém úspěchu vynuluje.

Chyby

Chyba přijde jako JSON se strojovým kódem a českou zprávou:

{ "error": { "code": "plan_limit_reached", "message": "V tomto zúčtovacím období jste vyčerpali limit záznamů svého tarifu." } }

Kód	Co se stalo
`api_not_in_plan`	Váš tarif API nezahrnuje.
`service_not_in_plan`	Váš tarif nezahrnuje servisní zakázky.
`plan_limit_reached`	Vyčerpaný limit záznamů v tomto období.
`billing_restricted`	Účet je v omezeném režimu, nové záznamy zakládat nelze.
`not_found`	Záznam s tímto číslem neexistuje.

Chybějící nebo špatně vyplněná pole vrací stav 422 se seznamem chyb u jednotlivých polí.

Co si hlídat

Záznam založený přes API se počítá do limitu tarifu stejně jako záznam založený v aplikaci.
Zboží u záznamu z API se čeká poštou nebo osobně, svoz se přes API domluvit nedá.
Token nikam nevystavujte veřejně. Kdo ho má, může zakládat a číst záznamy vaší firmy.