# Integrace platebního tlačítka QRabbit (Příručka pro vývojáře)

Tento dokument popisuje, jak správně integrovat platební tlačítko QRabbit do vašich fakturačních systémů, HTML e-mailových šablon nebo webových stránek. Cílem je poskytnout zákazníkům bezproblémový zážitek při placení (zobrazení QR kódu a přímé otevření bankovní aplikace v telefonu).

---

## 1. Základní princip

Služba QRabbit nevyžaduje žádné API klíče ani registraci. K vytvoření platebního kiosku stačí vygenerovat správnou URL adresu obsahující detaily platby (jako URL parametry) a vložit ji do běžného HTML odkazu (`<a>`).

### Příklad základního HTML tlačítka:

```html
<a href="https://qrabbit.eu/?a=123456789/0100&v=1500&c=CZK" target="_blank" rel="noopener noreferrer" style="display:inline-block; background-color:#ffffff; border:2px solid #f97316; border-radius:8px; padding:6px 16px; text-decoration:none; color:#111827; font-weight:bold;">
  Zaplatit přes QRabbit
</a>
```

**KRITICKÉ BEZPEČNOSTNÍ PRAVIDLO PRO E-MAILY:**
Vždy používejte atributy `target="_blank"` a `rel="noopener noreferrer"`. E-mailoví klienti (např. Seznam, Outlook) často vykreslují e-maily v přísně izolovaných iframech (tzv. sandbox). Pokud by se odkaz otevřel uvnitř tohoto iframu, prohlížeč by z bezpečnostních důvodů mohl zablokovat generování QR kódu nebo funkce tlačítek. `target="_blank"` zaručí, že se platební kiosek otevře čistě v novém panelu prohlížeče.

---

## 2. URL Parametry (Query string)

Pro dynamické generování platby použijte následující parametry v URL. Parametry musí být správně kódované (tzv. URL Encoding), obzvláště pokud obsahují mezery nebo diakritiku.

| Parametr | Význam | Povinné | Příklad | Poznámka |
| :--- | :--- | :---: | :--- | :--- |
| **`a`** | Číslo účtu / IBAN | **Ano** | `123456789/0100` | Lze použít český formát nebo IBAN. |
| **`v`** | Částka | **Ano** | `1500.50` | Formát čísla, oddělte haléře/centy tečkou. |
| **`c`** | Měna | **Ano** | `CZK` | Podporováno: `CZK`, `EUR`. |
| **`n`** | Jméno příjemce | Ne | `Moje Firma s.r.o.` | Zobrazí se zákazníkovi a v jeho bankovnictví. |
| **`m`** | Zpráva pro příjemce | Ne | `Faktura 2026001` | Vzkaz, který se propíše do bankovního výpisu. |
| **`vs`** | Variabilní symbol | Ne | `2026001` | Důležité pro párování plateb v účetnictví. Lze použít i alias `ref`. |
| **`ss`** | Specifický symbol | Ne | `1234` | |
| **`ks`** | Konstantní symbol | Ne | `0308` | |

---

## 3. Příklady sestavení URL (Generování na backendu)

### Příklad v PHP
Pokud generujete e-mailovou fakturu v PHP, URL byste sestavili takto:

```php
$params = http_build_query([
    'a' => '107107/2250',
    'v' => 1478.00,
    'c' => 'CZK',
    'n' => 'Firma s.r.o.',
    'vs' => '202640521'
]);

$buttonUrl = "https://qrabbit.eu/?" . $params;
echo '<a href="' . htmlspecialchars($buttonUrl) . '" target="_blank" rel="noopener noreferrer">Zaplatit fakturu</a>';
```

### Příklad v C# / .NET
```csharp
var query = HttpUtility.ParseQueryString(string.Empty);
query["a"] = "107107/2250";
query["v"] = "1478.00";
query["c"] = "CZK";
query["n"] = "Firma s.r.o.";
query["vs"] = "202640521";

string buttonUrl = "https://qrabbit.eu/?" + query.ToString();
```

---

## 4. Tipy a časté chyby

- **PDF Faktury:** Pokud generujete faktury přímo do formátu PDF, mějte na paměti, že některé prohlížeče PDF nezvládají složitá HTML tlačítka. Doporučujeme pod tlačítko nebo QR kód přidat i prostý textový odkaz (např. *Pro platbu klikněte zde: https://qrabbit.eu/?a=...*).
- **Validace symbolů:** Variabilní (vs), konstantní (ks) a specifický symbol (ss) smějí obsahovat **pouze číslice** a jejich délka je omezena (typicky na maximálně 10 znaků). Přítomnost písmen způsobí, že bankovní aplikace platbu odmítne.
- **Bezstavovost:** Služba funguje jako tzv. "bezstavová" (stateless). Nic se neukládá na server. Jakákoliv data předaná přes URL parametry jsou použita výhradně k vykreslení kiosku přímo v prohlížeči uživatele.