Dokumentácia API

Prvé volanie za pár minút

Základná adresa je https://www.billex.sk/api/v1. Posielajte Accept: application/json; pre JSON telo aj Content-Type: application/json.

curl 'https://www.billex.sk/api/v1/overenie' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer blx_live_VAS_API_KLUC'

Autentifikácia a prístup

API kľúč posielajte v hlavičke Authorization: Bearer …. Firma sa určí z overeného poverenia. Kľúč nepíšte do URL, klientského JavaScriptu ani logov.

Odpovede a peňažné sumy

Jednotlivé moduly si zachovávajú vlastné dátové názvy a úspešné obálky. Ich presný tvar uvádza schéma operácie. HTTP 201 znamená vytvorenie, 202 prijatie na spracovanie; úspešná odpoveď môže byť aj PDF, XML alebo súbor.

Chyby a limity

Pri chybe rozhodujte podľa HTTP stavu a error.code. Správa je pre človeka. fields je vždy objekt, pri validácii mapuje názvy polí na zoznam správ.

{
  "error": {
    "code": "NEPLATNE_UDAJE",
    "message": "Údaje nie sú platné.",
    "fields": {"datum_splatnosti": ["Pole je povinné."]}
  }
}

Limity kľúča sa riadia balíkom. Hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset uvádzajú strop, zostávajúce volania a UTC Unix čas obnovy v sekundách. Pri 429 čítajte aj Retry-After. Čas obnovy zodpovedá skutočnému koncu limitu. Nástroje dokumentov majú minútovú kvótu a pri prihlásenej firme aj dennú. Pri prekročení dennej kvóty hlavičky opisujú denný limit s obnovou o nasledujúcej polnoci UTC.

Stránkovanie zoznamov

Kurzorová odpoveď uvádza meta.pagination.next_cursor a meta.pagination.has_more. Kurzor je nepriehľadný: neupravujte ho a neposúvajte ho medzi firmami, kľúčmi či filtrami. Platí 15 minút; pri 410 začnite bez kurzora. Veľkosť strany nemeníte medzi volaniami; pri podporovanom limit použite 1–100, predvolene 50.

{
  "data": [],
  "meta": {"pagination": {"next_cursor": null, "has_more": false}}
}

curl --get 'https://www.billex.sk/api/v1/doklady' \
  --header 'Authorization: Bearer blx_live_VAS_API_KLUC' \
  --header 'Accept: application/json' \
  --data-urlencode 'cursor=KURZOR_Z_PREDCHADZAJUCEJ_ODPOVEDE' \
  --data-urlencode 'limit=50'

Pri dokladoch, odberateľoch a archíve udalostí je po starší alias parametra cursor. Nové integrácie používajú parameter cursor; staršie vstupy po, po_checkpoint, page či pageToken zostávajú v referencii ako kompatibilné aliasy. Primárne zoznamy používajú pozíciu záznamu; malé číselníky sa stránkujú z nemenného snapshotu. Staršie číslované zdroje používajú offset: zmeny počas čítania môžu posunúť hranicu strany. Checkpoint, snapshot a kontinuita zostávajú v doménovej odpovedi.

Jeden pokus, jeden výsledok

Všetky stavové zápisy s API kľúčom vyžadujú povinnú hlavičku Idempotency-Key, najviac 100 tlačiteľných ASCII znakov bez medzier. Pri výpadku odošlite rovnaký kľúč, metódu, cestu, query parametre a presné bajty tela a súborov. Pre nový zámer vytvorte nový kľúč.

Kľúč je viazaný na konkrétny API kľúč a uchováva sa trvalo. Dávky, objednávky a sandbox majú navyše vlastné doménové identifikátory; ich pravidlá uvádza schéma. Sandbox zápisy /sandbox/simulacie a /sandbox/reset aj sieťové /sietove/sapi/document/send a /sietove/sapi/document/receive/{documentId}/acknowledge tiež vyžadujú hlavičku. Sieťový kľúč je viazaný na integráciu; ACK aj na doklad. Výmena, obnova a zrušenie tokenov neopakujú uložené tajné odpovede. Dávky majú predvolený limit 100 riadkov a 2 MiB; nasadenie môže zmeniť hranicu cez api_davky.max_rows a api_davky.max_bytes. Pri chybe limitu rozdeľte dávku.

Overenie podpisu webhooku

Billex odošle JSON POST na váš HTTPS endpoint. X-Webhook-Event označuje udalosť a X-Webhook-Signature obsahuje HMAC SHA-256 ako hex reťazec. Kľúčom je tajomstvo webhook endpointu.

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$provided = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_V2'] ?? '';
$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $webhookSecret);

if (!ctype_digit($timestamp) || abs(time() - (int)$timestamp) > 300
    || !hash_equals($expected, $provided)) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true, flags: JSON_THROW_ON_ERROR);

Podpisujte pôvodné bajty prijatého tela, bez opätovnej serializácie JSON. Nový podpis X-Webhook-Signature-V2 zahŕňa X-Webhook-Timestamp, bodku a pôvodné telo; odmietnite odchýlku nad 300 sekúnd. Staršia hlavička X-Webhook-Signature ostáva kompatibilná. Prijímač V2 pri chybe nesmie prepnúť na starší podpis. X-Webhook-Delivery je stabilná identita doručenia. Spracovanie musí zvládnuť opakované doručenie podľa identity udalosti vo svojom doménovom payload-e. Za úspech sa považuje 2xx; neúspech ide do trvalej retry fronty. Archív GET /udalosti slúži na dobehnutie po výpadku.

Testovacia firma a sandbox

Sandbox je oddelený nástroj integrátora dostupný po zapnutí funkcie a splnení balíka. Kľúč vytvoríte v Nastaveniach → Testovacia firma a sandbox. blx_test_… funguje len na sandbox trasách; ostré API ho odmietne.

curl 'https://www.billex.sk/api/v1/sandbox/simulacie' \
  --header 'Authorization: Bearer blx_test_VAS_SANDBOX_KLUC' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: sandbox-pokus-001' \
  --data '{"typ":"email"}'

Typy sú email, peppol a platba. Odpoveď nesie environment: sandbox a simulovane: true. Simulácie zapisujú izolované udalosti; nedoručujú e-mail, sieťový doklad ani platbu. POST /sandbox/reset vyčistí sandbox udalosti príslušnej firmy a tiež vyžaduje Idempotency-Key. Opakovanie dokončeného resetu s rovnakým kľúčom vráti pôvodný výsledok a zachová udalosti vytvorené po prvom resete. Pre ďalšie vyčistenie použite nový kľúč.

Referencia operácií

Každá metóda a cesta v tejto referencii má záznam v stiahnuteľnom kontrakte. Schémy zachovávajú názvy doménových vstupov a odpovedí.

Žiadna operácia nevyhovuje hľadaniu. Skúste cestu, názov modulu alebo rozsah.

Dátové schémy

Úplné schémy s povinnými poľami, typmi a obmedzeniami pochádzajú z toho istého kontraktu. Odkaz $ref smeruje na schému s príslušným názvom.