BiznisWeb Partner API

Partner API umožňuje integračným partnerom pristupovať k privilegovaným funkciám BiznisWeb GraphQL API — pokročilé filtre, bulk operácie, mutácie obsahu, content pages, custom order info, tracking URLs a ďalšie operácie, ktoré nie sú dostupné cez bežný webový token.

Tento dokument je v2 a obsahuje skúsenosti reálnych integrácií vrátane gotcha, ktoré nie sú v pôvodnej dokumentácii zrejmé. Pre rýchlu referenciu pôvodnej špecifikácie pozri stránku Volanie API.

1. Predpoklady

Pred prvým volaním Partner API potrebujete:

2. Autentizácia — dva tokeny

Každý partnerský request musí obsahovať oba headery:

BW-API-Key:     Token <32-znakový webový token>
BW-Partner-Key: <partner-id> <40-znakový SHA1 hash>
Content-Type:   application/json

2.1 Webový token REQUIRED

32-znakový string vygenerovaný klientom v admin paneli eshopu. Header value musí obsahovať prefix Token (so medzerou) pred tokenom:

BW-API-Key: Token Ab3xY9pQrSt2uVw5xYz8aB1cDeF4gH6i

X-Api-Key: Ab3xY...
Authorization: Bearer Ab3xY...
BW-API-Key: Ab3xY...   ← chýba "Token " prefix

2.2 Partner token REQUIRED

Header value je partner ID, medzera, a 40-znakový SHA1 hash:

BW-Partner-Key: Demo-Integrator-2026 d2f7e3a8b4c1e9f0a5b2c7d8e1f4a9b6c3d5e7a8

BW-Partner-Key: Partner d2f7e3...     ← prefix musí byť partner ID, nie slovo "Partner"
BW-Partner-Key: d2f7e3...             ← chýba partner ID prefix
BW-Partner-Key: Demo-Integrator-2026 raw_secret   ← musí to byť HASH, nie sám secret

2.3 Výpočet partner hashu

Hash je SHA1 (nie MD5, nie SHA256) z konkatenácie troch hodnôt v presnom poradí:

partner_hash = sha1(client_domain + partner_secret + partner_id)

Výstup je presne 40 hex znakov. Ak vidíte 32 znakov, použili ste MD5 — to je chyba.

Konkrétny príklad (Python)

import hashlib

client_domain = "eshop1.flox.sk"
partner_secret = "<your-partner-secret>"
partner_id = "Demo-Integrator-2026"

partner_hash = hashlib.sha1(
    (client_domain + partner_secret + partner_id).encode("utf-8")
).hexdigest()

print(partner_hash)
# → d2f7e3a8b4c1e9f0a5b2c7d8e1f4a9b6c3d5e7a8  (40 hex chars, ilustračná hodnota)

header_value = f"{partner_id} {partner_hash}"
# → "Demo-Integrator-2026 d2f7e3a8b4c1e9f0a5b2c7d8e1f4a9b6c3d5e7a8"

3. Endpoint URL — API endpoint domain vs Client domain

Cieľová URL pre HTTP POST je vždy:

https://<api-endpoint-domain>/api/graphql

Pri partner volaní existujú dve oddelené hodnoty:

4. ⚠ HTTP/1.1 — kritická požiadavka

Toto je menej zrejmé než sa zdá. Moderné HTTP knižnice často automaticky negotiate HTTP/2 cez ALPN, ak server podporuje (BiznisWeb server podporuje, ale partner middleware funguje len cez HTTP/1.1).

Diagnostika: ak vidíte HTTP/2 412 v debug výstupe, klient sa pripojil cez h2 a partner auth neprešla. Vynúťte HTTP/1.1.

5. Časté gotchas

5.1 Snap (staging) eshopy — strip prefixu z hash inputu

BiznisWeb používa „snap" eshopy ako staging / shadow kópie produkčných webov pre testovanie. Ich hostname má tvar:

snap<digits>-<production-host>.flox.sk

Napríklad: snap1234-eshop1.flox.sk je staging kópia eshop1.flox.sk (resp. www.eshop1.sk v produkcii).

Príklad (Python)

import hashlib
import re

snap_pattern = re.compile(r"^snap\d+-")

def hash_input_domain(client_domain: str) -> str:
    """Strip 'snap<digits>-' prefix for hash computation."""
    return snap_pattern.sub("", client_domain)

# Endpoint URL — snap hostname
endpoint = "https://snap1234-eshop1.flox.sk/api/graphql"

# Hash input — production identity (snap prefix stripped)
hash_input = hash_input_domain("snap1234-eshop1.flox.sk")
# → "eshop1.flox.sk"

partner_hash = hashlib.sha1(
    (hash_input + partner_secret + partner_id).encode("utf-8")
).hexdigest()

Ak na snap eshope vidíte HTTP 401 + generická chyba „Stalo sa niečo neočakávané" namiesto očakávaného 412, prvá vec na overenie: počítate hash bez snap prefixu?

5.2 HTTP 308 redirect z flox.* na vlastnú doménu

Eshopy s vlastnou doménou majú zvyčajne *.flox.sk subdomain nastavenú ako permanent redirect (HTTP 308) na primárnu doménu. Napr.:

https://eshop1.flox.sk/api/graphql
  → HTTP 308 Permanent Redirect
  → Location: https://www.eshop1.sk/api/graphql

Ak Váš klient followuje redirecty automaticky (defaultné správanie väčšiny knižníc), request prejde na www.eshop1.sk. Server tam ale očakáva hash voči jeho doméne — a Váš hash bol počítaný proti eshop1.flox.sk alebo voči www.eshop1.sk (čo nie je client domain). Výsledok: HTTP 412.

5.3 IP whitelist

BiznisWeb best practices odporúčajú obmedziť každý API token na konkrétne IP adresy (klient ho nastavuje v admin paneli pri vytváraní tokenu). Ak request prichádza z neallowed IP:

• Webový token (BW-API-Key) nepustí vôbec → HTTP 401
• Partner token (BW-Partner-Key) nepustí → HTTP 412

Pre vývoj môže klient ponechať whitelist prázdny (=povolené všetko). Pre produkčné integrácie odporúčame whitelist mať.

5.4 Aktivácia Partner Package

Klient musí mať na svojom eshope aktivovaný „Partner Package" — to mu povoľuje partner-specific volania (advanced filters, content mutations, content pages atď.). Bez tejto aktivácie aj správny partner token vráti HTTP 412 so správou „You can use the filter param with only valid partner token or your website must have Partner package!".

Klient si aktiváciu objednáva v BiznisWebe. Ako vývojár na to nemáte dosah — môžete len rozpoznať túto chybu a poslať klienta na podporu.

5.5 Limity frekvencie volaní BiznisWeb API

BiznisWeb API využíva pri spracovaní požiadaviek databázové pripojenia zo zdieľaného connection poolu. Pri príliš rýchlom odosielaní požiadaviek za sebou môže dôjsť k vyčerpaniu tohto poolu, čo sa prejaví chybovou odpoveďou namiesto štandardného JSON výstupu. Nejde o klasický rate limit v zmysle pevného počtu volaní za sekundu — server voľné kapacity priebežne uvoľňuje, preto je kľúčovým parametrom dĺžka pauzy medzi jednotlivými volaniami, nie ich celkový počet.

Na základe testovania odporúčame dodržiavať pri stránkovaných (paginovaných) požiadavkách minimálnu pauzu 0,5 sekundy medzi každým volaním. Táto hodnota poskytuje dostatočný bezpečnostný margin a pri bežných objemoch dát (tisíce až desaťtisíce záznamov) umožňuje plynulé stiahnutie bez výpadkov. Pri dlhodobých stiahnutiach presahujúcich 200 po sebe idúcich volaní odporúčame po každých 100 volaniach zaradiť krátku pauzu v trvaní 5 sekúnd, ktorá serveru umožní uvoľniť databázové pripojenia pred ďalšou dávkou požiadaviek.

6. HTTP error codes — diagnostika

7. Code samples

Všetky vzorky používajú rovnaké demo údaje pre čitateľnosť (hodnoty sú ilustračné):

domain         = "www.eshop1.sk"
client_domain  = "eshop1.flox.sk"
partner_id     = "Demo-Integrator-2026"
partner_secret = "<your-partner-secret>"
api_key        = "<your-32-char-api-token>"

7.1 Python (requests)

import hashlib
import requests

DOMAIN = "www.eshop1.sk"
CLIENT_DOMAIN = "eshop1.flox.sk"
PARTNER_ID = "Demo-Integrator-2026"
PARTNER_SECRET = ""
API_KEY = ""

def make_headers():
    partner_hash = hashlib.sha1(
        (CLIENT_DOMAIN + PARTNER_SECRET + PARTNER_ID).encode("utf-8")
    ).hexdigest()
    return {
        "BW-API-Key": f"Token {API_KEY}",
        "BW-Partner-Key": f"{PARTNER_ID} {partner_hash}",
        "Content-Type": "application/json",
    }

def call(query: str, variables: dict | None = None) -> dict:
    response = requests.post(
        f"https://{DOMAIN}/api/graphql",
        headers=make_headers(),
        json={"query": query, "variables": variables or {}},
        timeout=30,
        # Critical: don't auto-follow redirects (would mask domain config issues)
        allow_redirects=False,
    )
    if response.status_code == 308:
        raise RuntimeError(
            f"Server redirected to {response.headers.get('Location')}. "
            f"Update DOMAIN to the redirect target (but keep CLIENT_DOMAIN as flox.*)."
        )
    response.raise_for_status()
    return response.json()

# Example: partner-only advanced filter on getOrderList
result = call(
    """
    query Orders($params: OrderParams, $filter: OrderFilter) {
        getOrderList(lang_code: "SK", params: $params, filter: $filter) {
            pageInfo { hasNextPage nextCursor }
            data { order_num pur_date sum { value } }
        }
    }
    """,
    {
        "params": {"limit": 30, "cursor": 0},
        "filter": {"pur_date_from": "2026-01-01"},
    },
)
print(result["data"]["getOrderList"]["data"])

7.2 Node.js (fetch)

import crypto from "node:crypto";

const DOMAIN = "www.eshop1.sk";
const CLIENT_DOMAIN = "eshop1.flox.sk";
const PARTNER_ID = "Demo-Integrator-2026";
const PARTNER_SECRET = "";
const API_KEY = "";

function makeHeaders() {
  const partnerHash = crypto
    .createHash("sha1")
    .update(CLIENT_DOMAIN + PARTNER_SECRET + PARTNER_ID)
    .digest("hex");
  return {
    "BW-API-Key": `Token ${API_KEY}`,
    "BW-Partner-Key": `${PARTNER_ID} ${partnerHash}`,
    "Content-Type": "application/json",
  };
}

async function call(query, variables = {}) {
  const response = await fetch(`https://${DOMAIN}/api/graphql`, {
    method: "POST",
    headers: makeHeaders(),
    body: JSON.stringify({ query, variables }),
    redirect: "manual",  // catch 3xx so domain config issues don't get masked
  });
  if (response.status === 308) {
    const location = response.headers.get("location");
    throw new Error(
      `Redirect to ${location}. Update DOMAIN to the redirect target.`
    );
  }
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  return await response.json();
}

const result = await call(
  `query Orders($params: OrderParams, $filter: OrderFilter) {
     getOrderList(lang_code: "SK", params: $params, filter: $filter) {
       data { order_num pur_date sum { value } }
     }
   }`,
  { params: { limit: 30 }, filter: { pur_date_from: "2026-01-01" } }
);
console.log(result.data.getOrderList.data);

7.3 PHP (cURL)

<?php
$domain = "www.eshop1.sk";
$client_domain = "eshop1.flox.sk";
$partner_id = "Demo-Integrator-2026";
$partner_secret = "";
$api_key = "";

$partner_hash = sha1($client_domain . $partner_secret . $partner_id);
$headers = [
    "BW-API-Key: Token {$api_key}",
    "BW-Partner-Key: {$partner_id} {$partner_hash}",
    "Content-Type: application/json",
];

$query = 'query { getOrderList(lang_code: "SK", params: {limit: 30}, filter: {pur_date_from: "2026-01-01"}) { data { order_num } } }';
$payload = json_encode(["query" => $query, "variables" => new stdClass()]);

$ch = curl_init("https://{$domain}/api/graphql");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,  // critical
    CURLOPT_FOLLOWLOCATION => false,                 // detect 308 redirects
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code === 308) {
    throw new RuntimeException("Server redirected — update \$domain to primary domain.");
}
if ($http_code !== 200) {
    throw new RuntimeException("HTTP {$http_code}: {$response}");
}
$data = json_decode($response, true);
print_r($data["data"]["getOrderList"]["data"]);

7.4 curl (pre debug)

# Spočítajte hash v shelli (placeholder secret nahraďte skutočnou hodnotou)
HASH=$(printf "%s" "eshop1.flox.skDemo-Integrator-2026" | shasum -a 1 | awk '{print $1}')

curl --http1.1 \
  -X POST "https://www.eshop1.sk/api/graphql" \
  -H "BW-API-Key: Token " \
  -H "BW-Partner-Key: Demo-Integrator-2026 $HASH" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { getOrderList(lang_code: \"SK\", params: {limit: 5}, filter: {pur_date_from: \"2026-01-01\"}) { data { order_num pur_date sum { formatted } } } }"}'

8. Best practices

1. Obmedzte duplicitné volania. Cache statické dáta (kategórie, stati statusov, jazyky, meny). Tieto sa menia zriedka.
2. Obmedzte tokeny na konkrétne IP adresy v admin paneli.
3. Pravidelne mažte nepoužívané tokeny.
4. Posielajte request na primary doménu eshopu, nie na *.flox.sk. Šetríte HTTP 308 redirect a vyhýbate sa potenciálnemu mismatch hashu.
5. Vypnite automatic redirect following (allow_redirects=False / redirect: "manual"). Ak vidíte 3xx, je to konfiguračný problém.
6. Vynúťte HTTP/1.1. Server nepodporuje partner auth cez HTTP/2.
7. Pýtajte sa len na potrebné polia. GraphQL umožňuje field selection — využite to.
8. Pre paged endpoints (getOrderList, getProductList, ...) používajte limit ≤ 30. Vyššie hodnoty môžu spôsobiť timeout/partial responses.
9. Pri mutáciách žiadajte aj zmenené polia v response — overíte si tým správnosť operácie:

   mutation {
     changeOrderStatus(order_num: "12345", status_id: 4) {
       order_num
       status { id name }   <!-- ← potvrdenie zmeny -->
     }
   }

10. Loggujte HTTP code a partial response — ale nikdy nezapisujte raw token alebo partner secret do logov.
11. Rate limiting: rešpektujte Retry-After header pri 429 / 501.

9. Troubleshooting checklist

Keď Vaša integrácia padá, postupujte zhora nadol: