API

REST API zabezpečeno protokolem HTTPS

HTTP Metody

• GET - vrací data - neprovádí žádné změny
• POST - odesílá nová data
• PUT - aktuazlizace data
• DELETE - odstraňuje data

HTTP Kódy

• 200 - OK
• 400 - Bad Request
• 401 - Unauthorized
• 404 - Not Found
• 409 - Conflict
• 422 - Unprocessable Entity - Data validation error
• 500 - Server Error

Ukázka response 422 - Unprocessable Entity

{
  "status": "error",
  "code": 422,
  "message": "Request body contains an error. See context for details.",
  "context": {
	"validation": {
	  "productBarcodes": [
		"This value should not be blank."
	  ],
	  "productImagesUrl": [
		"This value should not be blank."
	  ]
	}
  }
}

Data JSON

Všechna data formátu JSON a kódování UTF-8. Header Content-Type: application/json

Datové typy

Datové typy jednotlivých atributů těla requestu zjistíte v popisu každého EP, v části Request Body, odkaz Schema. Nepovinné atributy jsou označeny příznakem nullable

API EP

Produkce: https://app.log4u.cz/

Autorizace request

Postupy pro napojení na jednotlivé části API. Popis všech polí a možnost vyzkoušení najdete níže v interaktivní dokumentaci, číselníky v části Číselníky.

Přijaté objednávky (partner-orders)

Verze 2 (20. 10. 2026) – metoda PUT jako doporučený způsob založení i změn, vyhodnocení stavů každých 15 minut.

K čemu to slouží

Objednávku, kterou od vás objednal váš zákazník, nám pošlete hned po jejím přijetí – ještě předtím, než vytvoříte výdejku. Sklad podle ní pozná, které zboží z vašich příjemek už někdo čeká a není skladem, a takové zboží přijme přednostně. Vaše objednávky se tak expedují rychleji.

Přijatá objednávka nic nerezervuje a nic neexpeduje. Expedici dál spouští jen výdejka, kterou pošlete jako dosud.

Jak postupovat (doporučený způsob)

1. Zákazník u vás objedná → pošlete celou objednávku: PUT /api/v1/partner-orders/{číslo objednávky}.
2. Když se objednávka změní (jiné množství, jiný dopravce, zrušená nebo přidaná položka), pošlete znovu celou aktuální objednávku stejným voláním PUT pod stejným číslem. Nemusíte si pamatovat, co jste poslali dříve, ani porovnávat rozdíly – Log4U uloženou objednávku porovná sám: nové položky přidá, změněná množství upraví, položky, které v těle chybí, stornuje, a přepíše údaje hlavičky. Vše proběhne najednou; když je v požadavku chyba (např. neznámý produkt), uložená objednávka zůstane beze změny.
3. Když zákazník objednávku zruší, pošlete storno: DELETE /api/v1/partner-orders/{číslo}/cancel.
4. Až budete objednávku expedovat, vytvořte výdejku jako dosud, se stejným číslem objednávky (externalId). Podle něj se přijatá objednávka s výdejkou spáruje a po expedici přejde do stavu „Odesláno“.
5. Stav objednávky si můžete kdykoli zjistit – jednotlivě, nebo hromadně všechny změny od zadaného času.

Přihlášení je stejné jako u ostatních endpointů API (hlavičky Client-Key a Authorization-Token; token se počítá z HTTP metody, u PUT tedy z řetězce PUT).

Endpointy

Základ https://app.log4u.cz/api/v1

Doporučené:

• PUT /partner-orders/{externalId} – založení nebo nahrazení celé objednávky (neexistuje → založí se, odpověď 201; existuje a není odeslaná → nahradí se, 200; beze změny → nic se nezapíše, 200)
• DELETE /partner-orders/{externalId}/cancel – zrušení celé objednávky
• GET /partner-orders/{externalId} – detail se stavy
• GET /partner-orders – hromadný výpis (filtry status, externalIds, createdFrom, createdTo, changedSince, includeItems, limit, offset)

Alternativa pro dílčí změny (není nutné implementovat, pokud používáte PUT):

• POST /partner-orders – založení objednávky včetně položek (409, pokud číslo už existuje)
• PATCH /partner-orders/{externalId} – změna dopravce, státu nebo PSČ
• POST /partner-orders/{externalId}/items – přidání položek
• PATCH /partner-orders/{externalId}/items/{sku} – změna množství položky
• DELETE /partner-orders/{externalId}/items/{sku} – zrušení položky

Údaje objednávky

• externalId – vaše číslo objednávky, 2–20 znaků (písmena, číslice, -, _). Musí být stejné jako číslo pozdější výdejky. Číslo je u vás jedinečné; zrušenou objednávku nelze obnovit ani znovu založit pod stejným číslem, použijte nové číslo. U PUT je číslo v adrese, v těle je nepovinné (pokud ho pošlete, musí se shodovat).
• courierId – dopravce ze seznamu vašich povolených dopravců (stejně jako u výdejky).
• destinationCountry – kód státu doručení, např. CZ.
• destinationZip – PSČ, nepovinné.
• items – položky: sku (kód produktu, EAN nebo externí ID – stejně jako u výdejky) a quantity (celé kladné číslo). U PUT povinné, aspoň jedna položka.

Příklad těla (PUT /partner-orders/OBJ-2026-001 i POST /partner-orders):

{
  "externalId": "OBJ-2026-001",
  "courierId": 12,
  "destinationCountry": "CZ",
  "destinationZip": "60200",
  "items": [
    { "sku": "ABC-1", "quantity": 4 },
    { "sku": "SET-10", "quantity": 2 }
  ]
}

Pravidla

• Každý produkt je na objednávce jen jednou. Další kusy = jiné množství téže položky.
• Sady (sety) se rozloží na jednotlivé produkty stejně jako ve výdejce (počet sad × počet kusů v sadě). V odpovědi se sada vrací jako jedna položka s rozpisem components. Množství nebo zrušení měňte vždy u celé sady, ne u jejích částí.
• Změnit nebo zrušit objednávku lze, dokud není odeslaná. Po změně množství se položka znovu vyhodnotí.
• Opakované zrušení již zrušené objednávky nevadí (vrací úspěch).

Stavy

Vrací se u objednávky i u každé položky.

• created – Založeno: objednávku jsme přijali, sklad ji zatím nevyhodnotil
• waiting_for_goods – Čeká na zboží: zboží není skladem ani na žádné vaší příjemce
• waiting_for_receipt – Čeká na příjem: zboží je na vaší příjemce, sklad ho přijme přednostně
• cleared – Vykryto: objednané množství je skladem
• shipped – Odesláno: výdejka se stejným číslem byla expedována
• cancelled – Storno

Stav objednávky odpovídá nejméně pokročilé z jejích položek. Stavy vyhodnocuje sklad průběžně, zhruba každých 15 minut – změna se tedy neprojeví okamžitě. Pro pravidelné stahování změn doporučujeme hromadný výpis s parametrem changedSince (stačí předat čas posledního dotazu).

Odpovědi a chyby

• 201 / 200 – v pořádku, vrací aktuální stav objednávky
• 404 – objednávka, produkt nebo položka neexistuje
• 409 – konflikt (číslo už použité, nepovolený dopravce, neznámý produkt, produkt už na objednávce, objednávku už nelze měnit – odeslaná nebo stornovaná)
• 422 – chybně vyplněný požadavek (chybějící nebo neplatný údaj)

Text chyby vždy říká, co přesně je špatně.

Testovací režim: objednávky se uloží a lze s nimi pracovat, ale sklad je nevyhodnocuje – zůstanou ve stavu created.

Chyby importu objednávek (výdejek)

Verze 2 (31. 10. 2026) – odpověď importu nese u každé chyby kód errorCode; doplněn tvar chybových odpovědí a slovník textů hlášek s kódy a postupem.

Kde chyby najdete

• Odpověď importu POST /api/v1/pick/import – vrací HTTP 200, i když se některá objednávka nezaložila. Založené objednávky jsou v vydejkyImportedIds, chyby v errors (číslo objednávky, text chyby a kód chyby errorCode).
• Aplikace – menu Úkoly - Komunikace → Chyby importu (filtr, změna stavu, export). Odkaz na přehled je i v e-mailovém souhrnu importu.
• API – GET /api/v1/import-error/list (výchozí filtr state=open, dále errorCode, externalId, source, dateFrom, dateTo), detail GET /api/v1/import-error/{id}, změna stavu PATCH /api/v1/import-error/{id}/state.

Přehled zahrnuje importy přes API i z napojených e-shopů. Jeden záznam = zdroj + číslo objednávky + kód chyby; opakovaný výskyt zvýší počet výskytů. Když se objednávka později naimportuje úspěšně, její otevřené chyby se uzavřou automaticky.

Jak vypadá chybová odpověď

1. Import proběhl, ale některá objednávka se nezaložila – HTTP 200. Chyby jsou v poli errors: sourceId = číslo objednávky (externalId), msg = text chyby, errorCode = kód chyby z tabulky níže (u informativní hlášky testovacího režimu null). Na chyby reagujte podle errorCode – text hlášky slouží pro člověka a může se upřesňovat. Jedna objednávka může mít více chyb najednou (např. všechny neznámé produkty a všechny položky bez zásoby). Objednávka, která v errors je, se nezaložila – výjimkou je hláška Step6, viz slovník hlášek níže.

{
  "vydejkyImportedCount": 1,
  "vydejkyImportedIds": ["2616054100"],
  "errors": [
    {
      "sourceId": "2616054101",
      "msg": "Step3 - Cannot create vydejka (2616054101). Item (QS19133A) does not have enough stock. Current quantity in stock is 0. Requested quantity in stock was 1",
      "errorCode": "insufficient_stock"
    },
    {
      "sourceId": "2616054102",
      "msg": "Step2 - Cannot create vydejka (2616054102). Order has no items",
      "errorCode": "missing_items"
    }
  ]
}

2. Požadavek se nezpracoval vůbec – HTTP 4xx / 5xx

Tělo odpovědi má tvar status, code (HTTP kód) a message (text chyby):

{
  "status": "error",
  "code": 401,
  "message": "Invalid request token or headers"
}

Kódy chyb (errorCode)

Slovník hlášek importu objednávky

Text chyby v poli errors[].msg začíná krokem importu, ve kterém objednávka neprošla (Step1 číslo objednávky a účet, Step2 položky, Step3 zásoba a sety, Step4 doručovací údaje a dopravce, Step5 uložení, Step6 předání k expedici). Kód ve třetím sloupci je hodnota errors[].errorCode v odpovědi a tentýž kód vidíte v aplikaci (Chyby importu) i v GET /api/v1/import-error/list. Hlášky psané česky přicházejí v jazyce vašeho účtu (česky nebo anglicky), ostatní vždy anglicky. Kurzívou jsou proměnné části (číslo objednávky, kód produktu, množství…). U Step4 předchází vlastnímu textu úvod Step4 - [Validator Error.] Cannot create vydejka (…) Cannot create address for vydejka (…) address … with Error:.

Stav objednávky v odpovědi (status, stockStatus)

GET /api/v1/pick/{externalId} a POST /api/v1/pick/batch vracejí dva stavy:

• status – stav dokladu ve skladovém systému, např. wait (založena, čeká na zařazení), wpkin, pking, pked, exped, str (storno).
• stockStatus – zjednodušený stav pro vás (0 Vytvořena, 1 Čeká na vyskladnění … 1000 Storno); úplný přehled je v části Číselníky, Výdejka - Číselník skladových stavů.

wait + stockStatus 0 znamená, že objednávka je založená, ale sklad ji zatím nezařadil ke zpracování. Pokud takto objednávka zůstává dlouho, mohla být založena bez položek – od 31. 10. 2026 už objednávka bez položek nevznikne a import vrátí chybu missing_items.

Jak opakovat odeslání

• Import je atomický po objednávkách: při chybě se daná objednávka nezaloží vůbec, ostatní objednávky v dávce se zpracují normálně.
• Po opravě pošlete stejnou objednávku se stejným číslem znovu – otevřená chyba se po úspěšném importu uzavře sama.
• Vždy posílejte kompletní objednávku včetně items a delivery; objednávku bez položek neposílejte.
• Pokud odpověď vrátí duplicate_order, objednávka už existuje – zkontrolujte ji přes GET /api/v1/pick/{externalId}.