Savrsoft API — dokumentace pro vývojáře

Ověřování

Všechny API požadavky používají API klíč jako bearer token. Vytvořte si ho v aplikaci v sekci Developer → API keys. Klíče mohou být pouze pro čtení nebo pro čtení i zápis.

curl https://savrsoft.com/api/v1/events \
  -H "Authorization: Bearer savr_live_your_key_here"

Základní URL: https://savrsoft.com/api/v1 · Všechny odpovědi jsou ve formátu JSON. Chyby vracejí { "error": "…" } se stavovým kódem 4xx/5xx.

Stavové kódy

Kód	Kdy ho obdržíte
`200`	Úspěšné čtení.
`201`	Úspěšně vytvořeno. Tělo odpovědi je `{ "id": 42 }` — pokud potřebujete zbytek údajů, záznam si stáhněte.
`400`	Chybí povinné pole, např. `{ "error": "name is required" }`, nebo se nepodařilo načíst kurzor pro stránkování.
`401`	Chybí API klíč, klíč má neplatný formát, nebo byl zneplatněn.
`403`	Byl použit klíč pouze pro čtení na operaci zápisu. Vytvořte klíč pro čtení i zápis v sekci Developer → API keys.
`404`	Záznam neexistuje, nebo patří jiné organizaci — tyto dva stavy jsou záměrně nerozlišitelné. Stejná odpověď se vrací i pro neznámou cestu nebo metodu.

Rozsah tohoto API

Toto API je určeno pouze pro čtení a vytváření. Neexistují zde žádné DELETE, PUT ani PATCH koncové body — požadavek s některou z těchto metod vrátí 404 Unknown endpoint, stejně jako jakákoli nerozpoznaná cesta. Mazání a úpravy se provádějí v aplikaci, takže integrace nemůže zničit záznamy cateringové firmy. Pokud potřebujete přístup pro zápis nad rámec vytváření, napište nám, co vyvíjíte.

Stránkování

Každý koncový bod se seznamem je stránkovaný. Předejte limit (výchozí 100, maximum 500) a následujte next_cursor , dokud has_more není false:

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0"
}

Předejte kurzor zpět beze změny, abyste získali další stránku. Považujte ho za neprůhledný — kódování se může měnit:

curl "https://savrsoft.com/api/v1/clients?limit=100&cursor=eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0" \
  -H "Authorization: Bearer savr_live_your_key_here"

Stránkování je ukotveno k poslednímu přijatému řádku, nikoli k offsetu, takže řádky vytvořené nebo smazané během stránkování nezpůsobí přeskočení nebo opakování záznamu. Kurzor zůstává platný neomezeně dlouho.

Parametr	Chování
`limit`	1–500. Chybějící, nulová, záporná nebo nečíselná hodnota se vrátí na 100; vše nad 500 je omezeno na 500.
`cursor`	`next_cursor` z předchozí stránky. Pro první stránku jej vynechte. Kurzor, který nelze přečíst — poškozený nebo z jiného endpointu — vrátí `400 Invalid cursor` namísto tichého restartu od začátku.

Řazení: /events a /invoices od nejnovějších; /recipes a /clients podle jména, přičemž shody se řeší podle id, aby stránkování zůstalo stabilní i při opakujících se jménech.

Endpointy

GET/v1/me

Vaše organizace (id, název, měna).

GET/v1/events

Seznam událostí, od nejnovějších. Stránkováno — viz Stránkování výše.

GET/v1/events/{id}

Jedna akce s jejími pokrmy.

POST/v1/events · vyžaduje čtení/zápis

Vytvořit akci. Tělo požadavku:

{ "name": "Acme holiday party", "event_date": "2026-12-18",
  "guests": 120, "price_per_head": 55, "event_type": "corporate" }

GET/v1/recipes · GET/v1/recipes/{id}

Seznam receptů (s alergeny & dietními štítky), nebo jeden recept se surovinami. Seznam je stránkovaný a řazený podle názvu.

GET/v1/clients · POST/v1/clients

Seznam klientů (stránkovaný, podle jména) nebo vytvoření nového. Tělo požadavku pro vytvoření: { "name": "...", "email": "...", "phone": "...", "company": "..." }

GET/v1/invoices · GET/v1/invoices/{id}

Seznam faktur s vypočtenými součty, od nejnovější, nebo jedna faktura s položkami. Seznam je stránkovaný.

Webhooky

Zaregistrujte endpoint v sekci Vývojář → Webhooky. Při vzniku události odesíláme metodou POST JSON payload:

{
  "id": "evt_abc123",
  "type": "event.inquiry",
  "created_at": "2026-07-17T18:20:00.000Z",
  "data": { "id": 42, "name": "Corporate lunch — Dana Ruiz", ... }
}

Typy událostí

Typ	Spustí se, když
`event.created`	Je vytvořena akce
`event.inquiry`	Přijde nová online poptávka na catering
`invoice.sent`	Faktura je označena jako odeslaná
`invoice.paid`	Faktura je označena jako zaplacená
`proposal.approved`	Klient schválí nabídku
`client.created`	Je vytvořen klient

Ověřování podpisů

Každé doručení obsahuje hlavičku x-savrsoft-signature : HMAC-SHA256 z těla surového požadavku, podepsané vaším signing secret pro webhook. Vypočítejte totéž a porovnejte:

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(rawBody).digest('hex');
if (sig !== req.headers['x-savrsoft-signature']) reject();

Ochrana osobních údajů · Zabezpečení · Podmínky · Máte dotazy? savrsoft.com · Vytvořte cateringové integrace za pár minut.