Toret QR platby technická dokumentace (generováno Claude)

Plugin Name: Toret QR payments
Version: 3.1.0
Author: Toret.cz
License: GPLv3
Requires: WordPress 6.2+, WooCommerce 6.7+, PHP 7.4+

Obsah

1. Přehled funkcionality
2. Struktura souborů
3. Hooky a Filtry
4. Shortcody
5. Třídy a metody
6. Konstanty
7. Order Meta klíče
8. Integrace s třetími stranami
9. API endpointy pro QR kódy
10. Příklady použití
11. Debugging a Logging
12. Požadavky na server
13. Support a dokumentace

1. Přehled funkcionality

Co plugin dělá

Toret QR Platby je prémiový WordPress plugin pro WooCommerce, který přidává možnost zobrazit QR kód pro platbu bankovním převodem. Plugin podporuje:

QR kódy pro platby dle standardů CZ (QR Platba), SK (PayBySquare) a SEPA
Zobrazení na thank you page po dokončení objednávky
Automatické přidání do emailů (on-hold, processing)
Integrace s PDF faktury (WooCommerce PDF Invoices & Packing Slips, Booster Invoice, Toret Faktura)
Podpora více bankovních účtů pro různé platební metody
Variabilní symboly z různých zdrojů (objednávka, custom field, pluginy pro pořadová čísla)
Logging všech generovaných QR kódů

Podporované platební metody

Plugin standardně podporuje:

bacs (WooCommerce bankovní převod)
pnu (Toret Platba na účet)
dropshipping-pnu (Toret Dropshipping PNU)

Seznam lze rozšířit pomocí nastavení tqr_supported_payment_methods.

Podporované země a standardy

Česká republika (CZ): QR Platba (Paylibo API)
Slovensko (SK): PayBySquare (QRgenerator.sk API)
SEPA: SEPA QR kódy pro mezinárodní platby (epc-qr.eu)
Německo: Bezahlcode/GiroCode

2. Struktura souborů

toret-qrplatby/
├── toret-qrplatby.php              # Hlavní soubor pluginu
├── readme.txt                       # WordPress readme
├── license.txt                      # GPL licence
│
├── public/
│   ├── class-toret-qrplatby.php    # Hlavní veřejná třída
│   └── puc.php                      # Plugin Update Checker konfigurace
│
├── admin/
│   ├── class-toret-qrplatby-admin.php   # Hlavní admin třída
│   ├── assets/
│   │   ├── css/admin.css            # Admin styly
│   │   └── js/admin.js              # Admin skripty
│   ├── includes/
│   │   ├── class-admin-save.php     # Ukládání nastavení
│   │   ├── licence-handling.php     # Správa licencí
│   │   └── metabox.php              # Metabox pro detail objednávky
│   └── views/
│       ├── admin.php                # Hlavní stránka nastavení
│       ├── log.php                  # Zobrazení logů
│       └── toret.php                # Toret info stránka
│
├── includes/
│   ├── aux_methods.php              # Pomocné funkce
│   ├── class-log.php                # Logging třída
│   ├── class-toret-hpos-compatibility.php  # HPOS kompatibilita
│   └── puc.php                      # Update checker konfigurace
│
├── assets/
│   └── css/public.css               # Veřejné styly
│
├── woocommerce/
│   └── templates/
│       └── checkout/
│           └── payment-method.php   # Přepsaný template platební metody
│
├── languages/                       # Překlady (cs_CZ, sk_SK, de_DE)
└── vendor/                          # Composer dependencies

3. Hooky a Filtry

Actions (do_action)

Hook	Parametry	Popis
`toret_plugins_diag`	–	Zobrazení diagnostických informací na Toret stránce
`tqr_template_payment-method`	`$gateway`	Vyvolán v payment-method.php template pro zobrazení QR kódu
`tqr_delete_images_daily_event`	–	Cron event pro denní mazání dočasných QR obrázků
`toret_faktura_qr_code`	`$order`, `$type`, `$vs`	Integrace s pluginem Toret Faktura

Filters (apply_filters)

Obecné nastavení

Filter	Parametry	Výchozí hodnota	Popis
`tqp_thankyou_hook`	`$hook`	`'woocommerce_before_thankyou'`	Hook pro zobrazení QR na thank you page
`tqr_statuses_to_show_qr_in_account`	`$allowed_statuses`	`['on-hold', 'processing', 'pending', 'failed']`	Stavy objednávek, kdy se zobrazí QR v zákaznickém účtu

Platební metody

Filter	Parametry	Popis
`tqp_email_payment_method`	`$method`, `$order_id`	Modifikace platební metody pro email
`tqp_frontend_payment_method`	`$method`, `$order_id`	Modifikace platební metody pro frontend
`tqp_allowed_payment_methods_email`	`$allowed_methods`, `$order`	Povolené platební metody pro email
`tqp_allowed_payment_methods_frontend`	`$allowed_methods`, `$order`	Povolené platební metody pro frontend

Částka a měna

Filter	Parametry	Výchozí hodnota	Popis
`toret_qr_amount`	`$amount`, `$order`	Celková částka objednávky	Úprava částky v QR kódu
`tqr_currency`	`$currency`, `$order`	Měna objednávky	Úprava měny v QR kódu
`tqr_currency_skip_control`	`$skipCurrency`, `$order`	`false`	Přeskočit kontrolu podporované měny

IBAN a bankovní údaje

Filter	Parametry	Výchozí hodnota	Popis
`tqr_forced_cz_iban_selection`	`$forced`, `$country`, `$order`	`false`	Vynutit použití IBAN i pro CZ účty
`tqr_sepa_qr_code_url_parameters`	`$url_parameters`, `$order_id`, `$account_name`, `$iban`, `$bic`, `$value`, `$payment_note`, `$currency`, `$vs`	–	Úprava parametrů SEPA QR kódu

Texty před/po QR kódu

Filter	Parametry	Popis
`tqr_text_before_email`	`$custom_pre`	Text před QR v emailu
`tqr_text_after_email`	`$custom_post`	Text za QR v emailu
`tqr_text_before_thankyou`	`$custom_pre`	Text před QR na thank you page
`tqr_text_after_thankyou`	`$custom_post`	Text za QR na thank you page

PDF integrace

Filter	Parametry	Popis
`tqp_pdfinvoicesslips_img_style`	`$style`	CSS styl pro QR v PDF Invoices
`tqp_pdfinvoicesslips_skip_download`	`$skip`, `$order`	Přeskočit stahování QR pro PDF
`tqp_pdfinvoicesslips_hook_before`	`$text`, `$order`	Text před QR v PDF
`tqp_pdfinvoicesslips_hook_after`	`$text`, `$order`	Text za QR v PDF

Booster integrace

Filter	Parametry	Popis
`tqp_booster_img_style`	`$style`	CSS styl pro QR v Booster
`tqp_booster_hook_before`	`$text`, `$order`	Text před QR v Booster
`tqp_booster_hook_after`	`$text`, `$order`	Text za QR v Booster

4. Shortcody

[tqr_thankyou_shortcode]

Popis: Zobrazí QR kód pro platbu
Použití: Umístit na thank you page nebo do jiných šablon
Atributy: Žádné

Příklad:

[tqr_thankyou_shortcode]

[tqr_booster_img]

Popis: Zobrazí QR kód v Booster Invoice PDF
Použití: V Booster Invoice template
Atributy: Žádné

Příklad v Booster:

[tqr_booster_img]

5. Třídy a metody

5.1 Toret_QRplatby

Hlavní veřejná třída pluginu odpovědná za zobrazení QR kódů.
Soubor: public/class-toret-qrplatby.php

Klíčové metody

get_instance()

Vrací singleton instanci třídy.

activate($network_wide)

Aktivační hook pro plugin. Kontroluje WooCommerce verzi, nastavuje výchozí options.

Parametry:

$network_wide (bool) – Aktivace v celé síti (multisite)

display_qr($order_id, …)

Hlavní metoda pro generování a zobrazení QR kódu.

Parametry:

$order_id (int) – ID objednávky
$email (bool) – Zobrazení v emailu
$sent_to_admin (bool) – Email pro admina
$plain_text (bool) – Plain text email
$return (bool) – Vrátit HTML místo echování
$payment_method (string|null) – Specifická platební metoda
$in_my_account (bool) – Zobrazení v zákaznickém účtu

Návratová hodnota: String (HTML) nebo void

Proces:

Kontrola platební metody objednávky
Získání bankovních údajů pro danou metodu a účet
Extrakce IBAN, BIC, VS, částky
Generování URL QR kódu dle země (CZ/SK/SEPA)
Uložení odkazu v order meta tqr_qr_links
Vygenerování HTML s QR kódem
Logování do databáze

add_qr_to_email($order, $sent_to_admin)

Přidá QR kód do WooCommerce emailů.

Parametry:

$order (WC_Order) – Objekt objednávky
$sent_to_admin (bool) – Email pro admina

5.2 Toret_QRplatby_Admin

Třída pro správu admin rozhraní.
Soubor: admin/class-toret-qrplatby-admin.php

Klíčové metody

add_plugin_admin_menu()

Přidává položky do WordPress admin menu.

metabox($post_type, $post)

Přidává metabox do detailu objednávky s info o QR kódu.

Parametry:

$post_type (string) – Typ postu
$post (WP_Post|WC_Order) – Post nebo objednávka

5.3 Pomocné funkce

Soubor: includes/aux_methods.php

tqr_get_supported_payment_methods()

Vrací pole podporovaných platebních metod.

Návratová hodnota: Array

tqr_is_method_enabled($method)

Zjišťuje, zda je platební metoda aktivní.

Parametry:

$method (string) – ID platební metody

Návratová hodnota: Boolean

tqr_get_payment_method_title($method)

Získává název platební metody.

Parametry:

$method (string) – ID platební metody

Návratová hodnota: String

5.4 Globální funkce

tqr_log($data)

Globální funkce pro logování.

Parametry:

$data (array) – Data k zalogování
- type (int) – Typ logu
- order_id (int) – ID objednávky
- log (string) – Zpráva
- context (string) – Kontext/detaily

Použití:

tqr_log([
    'type' => 3,
    'order_id' => 123,
    'log' => 'QR code generated',
    'context' => 'https://api.paylibo.com/...'
]);

tqr_plot_qr($order)

Vykresluje QR kód pro PDF Invoices plugin.

Parametry:

$order (WC_Order) – Objekt objednávky

Návratová hodnota: String (HTML)

tqr_get_qr_only($order, $single = false)

Získává pouze URL QR kódu bez HTML wrapperu.

Parametry:

$order (WC_Order) – Objekt objednávky
$single (bool) – Vrátit pouze první QR (pokud je jich více)

Návratová hodnota: String nebo Array

6. Konstanty

QRPLATBYURL           // URL pluginu
QRPLATBYDIR           // Cesta k pluginu
TORETQRPLATBYSLUG     // Slug pluginu ('toret-qrplatby')
QRPLATBYVERSION       // Verze ('3.1.0')
TORETQRPLATBY         // ID pluginu (22412)
TORETQRPLATBYSETTINGS // URL nastavení
TORETQRPLATBYLIC      // Option licence
TORET_QR_LOG_SLUG     // Slug logu
TORET_QR_LOG_TABLE    // Tabulka logů
TORET_QR_DOCUMENTATION // URL dokumentace

7. Order Meta klíče

Plugin ukládá následující meta data k objednávkám:

Meta klíč	Typ	Popis
`tqr_qr_links`	Array	Pole URL vygenerovaných QR kódů
`_wc_deposits_payment_schedule`	Array	Data platebního kalendáře (WC Deposits)
`_wc_deposits_order_has_deposit`	String	Zda má objednávka zálohu

8. Integrace s třetími stranami

8.1 WooCommerce PDF Invoices & Packing Slips

Hook: wpo_wcpdf_after_document_label_{type}

Plugin automaticky vkládá QR kódy do PDF faktur.

Podporované typy dokumentů:

invoice
proforma

Nastavení:

tqp_pdfinvoicesslips_hook – Výběr hooku
tqp_pdfinvoicesslips_text_pre – Text před QR
tqp_pdfinvoicesslips_text_post – Text za QR
tqp_pdfinvoicesslips_css – CSS pro obrázek

8.2 Booster for WooCommerce

Shortcode: [tqr_booster_img]

Používá Booster shortcode [wcj_order_number] pro získání ID objednávky.

Nastavení:

tqp_booster_text_pre – Text před QR
tqp_booster_text_post – Text za QR
tqp_booster_css – CSS pro obrázek

8.3 Toret Faktura

Hook: toret_faktura_qr_code

Parametry:

$order (WC_Order) – Objednávka
$type (string) – Typ faktury
$vs (string) – Variabilní symbol

Nastavení:

tqp_toret_faktura_support – Zapnutí integrace (ok)

8.4 WooCommerce Deposits

Plugin automaticky detekuje zálohy a generuje QR kód pro částku zálohy namísto celkové částky objednávky.

Kontrolované meta:

_wc_deposits_order_has_deposit
_wc_deposits_payment_schedule

8.5 Custom Order Numbers

Podporované pluginy:

Custom Order Numbers for WooCommerce
Toret Order Numbers
Sequential Order Numbers for WooCommerce
WooCommerce Sequential Order Numbers

Nastavení:

tqp_vs_selection – Výběr zdroje VS

8.6 Polylang

Plugin podporuje multi-jazyčné texty před/po QR kódem pomocí Polylang stringů:

'Text before QR'
'Text after QR'

9. API endpointy pro QR kódy

CZ – Paylibo

URL: https://api.paylibo.com/paylibo/generator/czech/image

Parametry:

accountNumber
bankCode
amount
currency
vs (variabilní symbol)
size
branding=false
message (poznámka)

CZ – IBAN (Paylibo)

URL: https://api.paylibo.com/paylibo/generator/image

Parametry:

iban
bic
amount
size
branding=false
message
currency
sendersReference (VS)

SK – PayBySquare

URL: https://api.qrgenerator.sk/by-square/pay/qr.png

Parametry:

iban
amount
currency
vs
mode (light/dark)
size
transparent
beneficiary_name
payment_note

SEPA

URL: https://epc-qr.eu

Parametry:

iban
bic
euro (částka)
acc (reference/VS)
bname (název příjemce)
logo=none
cut=tblr
color=black
pic=pic
pixel (velikost)

10. Příklady použití

Příklad 1: Vlastní částka v QR kódu

add_filter('toret_qr_amount', function($amount, $order) {
    // Zaokrouhlit částku nahoru
    return ceil($amount);
}, 10, 2);

Příklad 2: Vlastní text před QR v emailu

add_filter('tqr_text_before_email', function($text) {
    return '<h3>Zaplaťte prosím pomocí QR kódu:</h3>';
});

Příklad 3: Přidání vlastní platební metody

add_filter('tqr_supported_payment_methods', function($methods) {
    $methods[] = 'my-custom-payment';
    return $methods;
});

Příklad 4: Skrytí QR pro specifickou objednávku

add_filter('tqp_allowed_payment_methods_frontend', function($methods, $order) {
    if ($order->get_total() < 100) {
        return []; // Nezobrazit QR pro objednávky pod 100 Kč
    }
    return $methods;
}, 10, 2);

Příklad 5: Vlastní SEPA parametry

add_filter('tqr_sepa_qr_code_url_parameters', function($params, $order_id) {
    $params['color'] = 'blue';
    $params['pixel'] = 300;
    return $params;
}, 10, 2);

11. Debugging a Logging

Zobrazení logů

Admin menu: WooCommerce → QR Platby → Log

Log typy

type: 1 – Info
type: 2 – Warning
type: 3 – QR code generation
type: 4 – Error

Manuální logování

tqr_log([
    'type' => 3,
    'order_id' => 123,
    'log' => 'Custom message',
    'context' => 'Additional data'
]);

12. Požadavky na server

PHP: 7.4 nebo vyšší
WordPress: 6.2 nebo vyšší
WooCommerce: 6.7 nebo vyšší
allow_url_fopen: Doporučeno (pro stahování QR obrázků do PDF)

13. Support a dokumentace

Oficiální dokumentace: https://documentation.toret.cz/qr-platby/
Website: https://toret.cz/produkt/qr-platby/
Support: přes Toret.cz

Konec dokumentace