e-Shop API – Dokumentácia

Integrácia e-shopu s automatickým vystavovaním faktúr

Ako to funguje

  1. 1V Nastaveniach API vytvoríte integráciu – systém vygeneruje API kľúč a HMAC signing secret.
  2. 2Vo vašom e-shope nakonfigurujete webhook, ktorý po každej novej objednávke zavolá ingest endpoint.
  3. 3Request musí byť podpísaný HMAC-SHA256 signatúrou tela a obsahovať hlavičku X-Api-Key.
  4. 4Systém objednávku prijme, uloží a (podľa nastavení) automaticky vystaví faktúru.
  5. 5Všetky volania sú zalogované v Integračnom logu.

Hlavný endpoint pre prijímanie objednávok z e-shopu. Volanie je idempotentné – rovnaký external_order_id sa spracuje len raz. Oddelenie môžete nastaviť predvolene v integrácii alebo jednorazovo override cez department_id v payload-e.

Hlavičky

X-Api-Keyrequired
string
API kľúč integrácie (generovaný v Nastaveniach API)
X-Signaturerequired
string
HMAC-SHA256 hex podpis JSON tela requestu, kľúčom je signing secret
X-Timestamprequired
number
Unix timestamp v sekundách. Požiadavka musí prísť ±300 s od servera.
X-Request-Id
string
Voliteľné unikátne ID requestu pre idempotentnosť a debug

Telo requestu (JSON)

external_order_idrequired
string
Unikátne ID objednávky vo vašom e-shope (nesmie sa opakovať pre rovnakú firmu)
external_order_number
string
Čitateľné číslo objednávky, napr. #10042
source_platform
string
Platforma e-shopu: woocommerce, shoptet, shopify, magento, prestashop, custom
ordered_atrequired
ISO 8601
Čas vytvorenia objednávky v e-shope
statusrequired
string
Stav objednávky: created, paid, shipped, completed, cancelled, refunded
department_id
uuid
Voliteľné oddelenie pre túto konkrétnu objednávku. Ak nie je zadané, použije sa predvolené oddelenie z integrácie.
currencyrequired
string
ISO 4217 kód meny, napr. EUR
customerrequired
object
Zákaznícke údaje (name, email, phone, ico, dic, ic_dph, peppol_id, type: person|company)
billing_addressrequired
object
Fakturačná adresa (street, city, postal_code, country_code)
shipping_address
object
Doručovacia adresa (rovnaká štruktúra ako billing_address)
payment
object
Platobné údaje (method, status, paid_at, variable_symbol)
shipping
object
Spôsob dopravy (method, carrier, tracking_number)
itemsrequired
array
Položky objednávky (external_line_id, sku, name, quantity, unit, unit_price, discount_percent, vat_rate, line_subtotal, line_vat_total, line_total)
totalsrequired
object
Sumy objednávky (subtotal, shipping_total, discount_total, vat_total, grand_total)
notes
string
Voliteľná poznámka k objednávke
metadata
object
Voliteľné doplnkové údaje. Neznáme polia sa bezpečne ignorujú.

Príklad requestu


POST /api/integrations/eshop/orders
X-Api-Key: <váš API kľúč>
X-Signature: <HMAC-SHA256 hex podpis tela requestu>
X-Request-Id: req_20260424_001          # voliteľné, pre idempotentnosť
X-Timestamp: 1745489999                  # Unix timestamp ± 300 s
Content-Type: application/json

{
  "external_order_id": "WC-10042",
  "external_order_number": "#10042",
  "source_platform": "woocommerce",
  "ordered_at": "2026-04-24T10:30:00Z",
  "status": "created",
  "department_id": "550e8400-e29b-41d4-a716-446655440111",
  "currency": "EUR",
  "language": "sk",
  "totals": {
    "subtotal": 99.98,
    "shipping_total": 3.90,
    "discount_total": 0,
    "vat_total": 20.78,
    "grand_total": 103.88
  },
  "customer": {
    "type": "company",
    "name": "Acme s.r.o.",
    "email": "info@acme.sk",
    "phone": "+421900000000",
    "ico": "12345678",
    "dic": "2012345678",
    "ic_dph": "SK2012345678",
    "peppol_id": "0208:12345678"
  },
  "billing_address": {
    "street": "Hlavná 1",
    "city": "Bratislava",
    "postal_code": "81101",
    "country_code": "SK"
  },
  "shipping_address": {
    "street": "Hlavná 1",
    "city": "Bratislava",
    "postal_code": "81101",
    "country_code": "SK"
  },
  "payment": {
    "method": "card",
    "status": "unpaid",
    "paid_at": null,
    "variable_symbol": "2026001042"
  },
  "shipping": {
    "method": "packeta",
    "carrier": "Packeta",
    "tracking_number": null
  },
  "items": [
    {
      "external_line_id": "line_1",
      "sku": "PROD-001",
      "name": "Produkt A",
      "quantity": 2,
      "unit": "ks",
      "unit_price": 49.99,
      "discount_percent": 0,
      "vat_rate": 20,
      "line_subtotal": 99.98,
      "line_vat_total": 19.996,
      "line_total": 119.976
    }
  ],
  "notes": "Poznámka k objednávke",
  "metadata": {
    "channel": "eshop"
  }
}

Odpovede

201Objednávka prijatá a uložená
200Idempotentné volanie – objednávka už existuje, vrátený existujúci záznam
400Chybný payload (INVALID_PAYLOAD, MISSING_FIELD, TIMESTAMP_SKEW)
401Neplatný alebo chýbajúci API kľúč (INVALID_API_KEY)
403Modul e-Shop nie je aktivovaný pre firmu (MODULE_DISABLED)
422HMAC podpis nesedí (INVALID_SIGNATURE)
429Prekročený rate limit – max 10 requestov za minútu (RATE_LIMIT_EXCEEDED)

Úspešná odpoveď (201)


{
  "success": true,
  "status": "created",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "660e8400-e29b-41d4-a716-446655440000",
  "invoice_status": "draft",
  "external_order_id": "WC-10042",
  "processed_at": "2026-04-24T10:30:01Z",
  "warnings": [],
  "request_id": "req_20260424_001"
}

Úspešná odpoveď (200 idempotent replay)


{
  "success": true,
  "status": "duplicate_ignored",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "660e8400-e29b-41d4-a716-446655440000",
  "external_order_id": "WC-10042",
  "processed_at": "2026-04-24T10:31:11Z",
  "warnings": ["IDEMPOTENT_REPLAY"]
}

Chybová odpoveď


{
  "success": false,
  "error_code": "INVALID_PAYLOAD",
  "message": "customer.email is required",
  "details": {
    "field": "customer.email",
    "rule": "required"
  },
  "request_id": "req_20260424_001"
}

Každý request musí byť podpísaný. Signatúra je HMAC-SHA256 hex digest tela requestu (presne to isté JSON string čo pošlete v body), kľúčom je váš signing secret.

Dôležité:

  • Signing secret a API kľúč sa zobrazia iba raz pri vytvorení / rotácii kľúčov.
  • Nikdy nevkladajte kľúče priamo do zdrojového kódu – používajte env premenné.
  • Timestamp v hlavičke musí byť v rozmedzí ±5 minút od aktuálneho UTC času servera.

Node.js / JavaScript


const crypto = require('crypto')

const body = JSON.stringify(payload)          // presne to isté telo čo pošlete
const signature = crypto
  .createHmac('sha256', process.env.ESHOP_SIGNING_SECRET)
  .update(body)
  .digest('hex')

fetch('https://vasa-domena.sk/api/integrations/eshop/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.ESHOP_API_KEY,
    'X-Signature': signature,
    'X-Timestamp': String(Math.floor(Date.now() / 1000)),
    'X-Request-Id': 'req_' + Date.now(),
  },
  body,
})

PHP


<?php
$body    = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$sig     = hash_hmac('sha256', $body, getenv('ESHOP_SIGNING_SECRET'));
$headers = [
    'Content-Type: application/json',
    'X-Api-Key: ' . getenv('ESHOP_API_KEY'),
    'X-Signature: ' . $sig,
    'X-Timestamp: ' . time(),
    'X-Request-Id: req_' . uniqid(),
];

$ch = curl_init('https://vasa-domena.sk/api/integrations/eshop/orders');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = curl_exec($ch);

Po prijatí objednávky má status created. Váš e-shop môže následne meniť stav objednávky cez PATCH endpoint nižšie.

created

Prijatá

Objednávka doručená do systému

paid

Zaplatená

Platba potvrdená

shipped

Odoslaná

Tovar expedovaný

completed

Dokončená

Doručená zákazníkovi

cancelled

Zrušená

Objednávka stornovaná

refunded

Vrátená

Refund spracovaný

PATCH endpoint pre zmenu stavu

PATCH
/api/integrations/eshop/orders/{externalOrderId}

Aktualizuje existujúcu objednávku bez vytvorenia novej.

Body: status (required) + voliteľne invoice_status, send_invoice (boolean), send_via=peppol.

Ak je v integrácii nastavené invoice_on_order_create=true a nový status sa rovná invoice_trigger_status, systém najprv automaticky vytvorí faktúru. Pri režime issued_and_send_email sa ju následne pokúsi automaticky odoslať cez Peppol.

POST
/api/integrations/eshop/orders/{externalOrderId}/send-invoice

Ručne odošle faktúru naviazanú na objednávku cez Peppol (bez zmeny statusu objednávky).

Tieto endpointy môžete volať na overenie, že objednávka bola správne prijatá, alebo na získanie údajov o faktúre.

GET
/api/integrations/eshop/orders/{externalOrderId}

Vráti stav objednávky, invoice_id a invoice_status

Autentifikácia: rovnaké X-Api-Key + X-Signature hlavičky.

GET
/api/integrations/eshop/invoices/{invoiceId}

Vráti metadáta faktúry (číslo, suma, dátum splatnosti, stav)

Autentifikácia: rovnaké X-Api-Key + X-Signature hlavičky.

GET
/api/integrations/eshop/invoices/{invoiceId}/pdf

Vráti PDF faktúry ako binárny súbor (Content-Type: application/pdf)

Autentifikácia: rovnaké X-Api-Key + X-Signature hlavičky.

Pripravený na integráciu?

Vytvorte integráciu, získajte API kľúče a nakonfigurujte váš e-shop.

Otvoriť nastavenia API