QR platba

POST

/api/v2/qr/payment

Operace vrátí řetězec SPAYD (formát QR platby České bankovní asociace) a QR kód, který zákazník naskenuje v bankovní aplikaci. Číslo účtu (IBAN) se bere z tiskové sestavy skladu, příjemcem je fakturační název skladu, jinak název firmy. Řetězec obsahuje PT:IP, tedy žádost o okamžitou platbu.

Pokladna v prohlížeči používá pro QR platbu stejnou operaci, takže QR z API a z pokladny jsou stejné.

Variabilní symbol a doklad

Když variableSymbol nepošlete, server použije další číslo dokladu v řadě skladu a vrátí ho ve variableSymbol. Číslo se tím nerezervuje. Variabilní symbol má vždy 1 až 10 číslic, tisková sestava skladu proto potřebuje číselný prefix, například [ROK]. Prefix s písmeny vrátí HTTP 422 s variable-not-numeric.

Po zaplacení vystavte doklad s payment: "bank" a variable rovným vrácenému variableSymbol, viz Vystavení dokladu. Doklad pak dostane stejný variabilní symbol jako QR platba a platbu jde v bance spárovat.

Zobrazení QR kódu

svg je hotový prvek <svg>, který roztáhne na šířku nadřazeného prvku. Vložte ho přímo do stránky nebo uložte jako soubor .svg. png obsahuje obrázek v base64, který zobrazíte jako data:image/png;base64,.... Pro tisk na termotiskárně nebo vlastní vykreslení zvolte format: "none" a QR vytvořte z řetězce spayd.

Autentizace a oprávnění

Vyžaduje API token: Bearer v hlavičce nebo URL token.

10220 - Platba QR kódem Bez modulu Platba QR kódem vrací operace HTTP 403 s code module-disabled. Modul musí mít uživatel, kterému patří použitý API token.

Parametry

Tělo požadavku

Název	Typ	Povinný	Popis	Příklad
`amount`	number	ano	Částka k úhradě, kladné číslo s nejvýše 2 desetinnými místy.	`450`
`currency`	enum	ne	CZK (výchozí) nebo EUR. Kód Kč z číselníku pokladny se převede na CZK.	`CZK`
`stockId`	integer	ne	Sklad, z jehož tiskové sestavy se vezme bankovní účet a číselná řada. Uživatel musí mít do skladu přístup. Výchozí je aktivní sklad uživatele.	`12`
`type`	enum	ne	Typ dokladu, z jehož řady se určí variabilní symbol: cash (výchozí), invoice, invoice_proforma, order, offer, reservation.	`cash`
`variableSymbol`	string	ne	Variabilní symbol, 1 až 10 číslic. Bez hodnoty se použije další číslo dokladu v řadě skladu.	`null`
`message`	string	ne	Zpráva pro příjemce, nejvýše 60 znaků.	`Hydropolis`
`format`	enum	ne	Podoba QR kódu: svg (výchozí), png (obrázek v base64) nebo none (jen řetězec SPAYD).	`svg`

Příklad požadavku

curl

curl -X POST 'https://www.elpokladny.cz/api/v2/qr/payment' \
  -H 'Authorization: Bearer elp_live_example.example_secret' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "amount": 450,
  "currency": "CZK",
  "stockId": 12,
  "type": "cash",
  "message": "Hydropolis",
  "format": "svg"
}'

PHP

<?php
$ch = curl_init('https://www.elpokladny.cz/api/v2/qr/payment');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array (
  0 => 'Authorization: Bearer elp_live_example.example_secret',
  1 => 'Content-Type: application/json',
),
    CURLOPT_POSTFIELDS => '{
  "amount": 450,
  "currency": "CZK",
  "stockId": 12,
  "type": "cash",
  "message": "Hydropolis",
  "format": "svg"
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

javascript

const response = await fetch("https://www.elpokladny.cz/api/v2/qr/payment", {
    "method": "POST",
    "headers": {
        "Authorization": "Bearer elp_live_example.example_secret",
        "Content-Type": "application/json"
    },
    "body": "{\n  \"amount\": 450,\n  \"currency\": \"CZK\",\n  \"stockId\": 12,\n  \"type\": \"cash\",\n  \"message\": \"Hydropolis\",\n  \"format\": \"svg\"\n}"
});
const data = await response.json();

Ukázkové odpovědi

QR platba (HTTP 200)

application/json

{
  "status": "success",
  "spayd": "SPD*1.0*ACC:CZ6508000000192000145399*AM:450.00*CC:CZK*X-VS:2026000042*RN:Ukázkový obchod s.r.o.*MSG:Hydropolis*PT:IP",
  "variableSymbol": "2026000042",
  "amount": 450,
  "currency": "CZK",
  "iban": "CZ6508000000192000145399",
  "stockId": 12,
  "svg": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<svg xmlns=\"http://www.w3.org/2000/svg\" ...>...</svg>",
  "png": null
}

Neplatná částka (HTTP 400)

application/json

{
  "status": "error",
  "code": "invalid-amount",
  "message": "Částka musí být kladné číslo s nejvýše 2 desetinnými místy."
}

Sklad nemá bankovní účet (HTTP 422)

application/json

{
  "status": "error",
  "code": "bank-missing",
  "message": "Tisková sestava skladu nemá bankovní účet s IBAN."
}

Chybí modul Platba QR kódem (HTTP 403)

application/json

{
  "status": "error",
  "code": "module-disabled",
  "message": "Modul Platba QR kódem (10220) není zapnutý."
}

Možné chyby

Chybové stavy

HTTP	Kdy	Podoba
400	Neplatné JSON tělo (message), neplatná částka (code invalid-amount), měna (unsupported-currency), typ (invalid-type), variabilní symbol (invalid-variable-symbol), zpráva (invalid-message) nebo format (invalid-format).	status-message
401	Chybí nebo je neplatný API token.	status-message
403	Chybí modul Platba QR kódem (code module-disabled), sklad neexistuje nebo do něj uživatel nemá přístup (stock-not-allowed), nebo nepovolená IP adresa.	status-message
422	Tisková sestava skladu nemá bankovní účet s IBAN (code bank-missing), nebo další číslo dokladu není použitelné jako variabilní symbol (variable-not-numeric).	status-message

Související návody

Platba QR kódem