Pro vývojáře

Shortcody

Formulář odstoupení

[wpify_woo_withdrawal_form]

Vyrenderuje formulář pro odstoupení. Vrátí prázdný řetězec (žádný výstup), pokud Stránka pro odstoupení není přiřazena v nastavení modulu.

V Gutenberg/block editoru se zobrazí admin-only placeholder, když je polovina vypnutá — víš že blok existuje, ale na frontendu nic nevyrenderuje.

Formulář reklamace

[wpify_woo_claim_form]

Renderuje reklamační (záruční) formulář. Stejné chování při vypnutí jako formulář pro odstoupení.

Oba formuláře na jedné stránce

Oba shortcody/bloky lze umístit na jednu stránku. URL parametr ?form=withdrawal nebo ?form=claim říká, který formulář se má předvyplnit. HTML kotvy #wpify-woo-withdrawal-form a #wpify-woo-claim-form umožňují přímé odkazy.

Příklad odkazu:

/vraceni-zbozi/?order_key=wc_order_abc123&form=withdrawal#wpify-woo-withdrawal-form

Gutenberg bloky

Blok	Ekvivalent shortcode
`wpify-woo/withdrawal-form`	`[wpify_woo_withdrawal_form]`
`wpify-woo/claim-form`	`[wpify_woo_claim_form]`

Oba bloky podporují align, className a používají ServerSideRender pro live náhled v editoru.

URL parametry

Parametr	Účel	Auth model
`?order_key={wc_order_key}`	Důvěryhodný token z WC (používá se v plugin-generovaných odkazech v e-mailech) — plný pre-fill, žádný email match nutný	Vlastnictví kryptografického klíče = autorizace
`?order={number_or_id}`	Hint identifikátoru (manuální zadání, footer link) — prázdný formulář, 2-faktor (číslo objednávky + shoda billing emailu) povinný	Two-factor verifikace
`?form=withdrawal\|claim`	Vybírá který formulář se na sdílené stránce předvyplní/aktivuje	—
`?submitted=1`	Spustí thank-you stav (plugin nastavuje po úspěšném podání)	—
`?wcr_err={message}`	Chybová zpráva ve formuláři (jen no-JS PRG fallback)	—

Filtry

`wpify_woo_withdrawal_claims_blocked_statuses`

Definuje stavy objednávek, kde jsou nové žádosti blokovány.

apply_filters( 'wpify_woo_withdrawal_claims_blocked_statuses', array $statuses, WC_Order $order );

Default

array( 'refunded', 'cancelled', 'failed', 'checkout-draft', 'auto-draft' )

Příklad: blokovat i „on-hold” objednávky

add_filter( 'wpify_woo_withdrawal_claims_blocked_statuses', function( $statuses ) {
    $statuses[] = 'on-hold';
    return $statuses;
} );

`wpify_woo_withdrawal_claims_resolve_order`

Fallback resolver pro custom order_number formáty. Volá se až poté, co selže default číselné ID lookup A vestavěné WooCommerce vyhledávání objednávek.

apply_filters( 'wpify_woo_withdrawal_claims_resolve_order', ?WC_Order $order, string $identifier );

Příklad: podpora prefixu „ORD-”

add_filter( 'wpify_woo_withdrawal_claims_resolve_order', function( $order, $identifier ) {
    if ( strpos( $identifier, 'ORD-' ) === 0 ) {
        $id = (int) substr( $identifier, 4 );
        return wc_get_order( $id );
    }
    return $order;
}, 10, 2 );

`wpify_woo_withdrawal_claims_eligible_items`

Modifikuje seznam položek zobrazených ve formuláři per typ.

apply_filters( 'wpify_woo_withdrawal_claims_eligible_items', array $result, WC_Order $order, string $type );

$result má klíče: items (pole řádků), eligible_count, ineligible_count.

`wpify_woo_withdrawal_claims_is_eligible_item`

Per-item override eligibility.

apply_filters( 'wpify_woo_withdrawal_claims_is_eligible_item', array $result, WC_Order_Item $item, WC_Order $order, string $type );

$result má klíče: eligible (bool), reason (string), line_item_id (int).

`wpify_woo_withdrawal_claims_period_end` / `period_start`

Override vypočtených datumů konce/startu lhůty.

apply_filters( 'wpify_woo_withdrawal_claims_period_end', DateTimeInterface $end, WC_Order $order, string $type );
apply_filters( 'wpify_woo_withdrawal_claims_period_start', DateTimeInterface $start, WC_Order $order, string $type );

`wpify_woo_withdrawal_claims_is_excluded_product`

Per-produkt exclusion override (default čte _wpify_woo_withdrawal_excluded / _wpify_woo_warranty_excluded meta).

apply_filters( 'wpify_woo_withdrawal_claims_is_excluded_product', bool $excluded, WC_Product $product, string $type );

`wpify_woo_withdrawal_claims_request_type_labels`

Lidsky čitelné popisky typů žádostí. Umožňuje doplnit další typy nebo přepsat výchozí.

apply_filters( 'wpify_woo_withdrawal_claims_request_type_labels', array $labels );

Výchozí: withdrawal → „Odstoupení”, claim → „Reklamace”.

`wpify_woo_withdrawal_claims_scope_labels`

Lidsky čitelné popisky rozsahů žádosti.

apply_filters( 'wpify_woo_withdrawal_claims_scope_labels', array $labels );

Výchozí: whole_order → „Celá objednávka”, specific_items → „Konkrétní položky”.

`wpify_woo_withdrawal_claims_status_labels`

Lidsky čitelné popisky stavů žádosti. Použijte k registraci vlastních stavů (z vlastní integrace), aby se správně zobrazily v emailech i v adminu.

apply_filters( 'wpify_woo_withdrawal_claims_status_labels', array $labels );

Výchozí: submitted → „Odesláno”.

Příklad: registrace vlastních stavů

add_filter( 'wpify_woo_withdrawal_claims_status_labels', function( $labels ) {
    $labels['in_progress'] = __( 'Zpracovává se', 'my-plugin' );
    $labels['resolved']    = __( 'Vyřízeno', 'my-plugin' );
    return $labels;
} );

`wpify_woo_withdrawal_claims_request_data`

Modifikace dat žádosti těsně před uložením (vč. status, custom meta).

apply_filters( 'wpify_woo_withdrawal_claims_request_data', array $data, string $type );

Příklad: nastavit custom default status

add_filter( 'wpify_woo_withdrawal_claims_request_data', function( $data, $type ) {
    $data['status'] = 'pending_review';
    return $data;
}, 10, 2 );

`wpify_woo_withdrawal_claims_email_recipient`

Override příjemce e-mailu žádosti.

apply_filters( 'wpify_woo_withdrawal_claims_email_recipient', string $email, int $request_id, string $context );

$context je 'customer' nebo 'admin'.

`wpify_woo_withdrawal_claims_inject_link_emails`

Override seznamu WC e-mailů, do kterých se vkládá odkaz na odstoupení.

apply_filters( 'wpify_woo_withdrawal_claims_inject_link_emails', array $email_ids );

`wpify_woo_withdrawal_claims_my_account_button_args`

Modifikace tlačítka v Můj účet → detail objednávky (text, URL, atributy).

apply_filters( 'wpify_woo_withdrawal_claims_my_account_button_args', array $args, WC_Order $order, string $type );

`wpify_woo_withdrawal_claims_form_fields`

Přidává vlastní pole do formuláře žádosti (např. IBAN, telefon, vlastní souhlas). Definované pole se automaticky vykreslí ve formuláři, validuje, uloží do databáze a zobrazí na všech místech, kde plugin žádost ukazuje — v adminu, v zákaznickém přehledu „Moje objednávky” i v e-mailech (HTML i plain).

apply_filters( 'wpify_woo_withdrawal_claims_form_fields', array $fields, string $type );

Struktura pole

Každé pole je asociativní pole s následujícími klíči:

Klíč	Typ	Povinné	Popis
`id`	string	ano	Unikátní identifikátor (použije se jako `name` HTML inputu i jako klíč v uložených datech)
`label`	string	ano	Popisek pole — zobrazí se ve formuláři, v adminu i v e-mailech
`type`	string	ne	`text` (výchozí), `email`, `tel`, `textarea`, `select`, `checkbox`
`placeholder`	string	ne	HTML placeholder pro inputy
`required`	bool	ne	`true` = vyžadováno pro odeslání (s validační hláškou)
`options`	array	jen pro `select`	Pole `['value' => ..., 'label' => ...]`
`sanitize`	callable	ne	Vlastní sanitizace; jinak se použije výchozí podle `type`
`validate`	callable	ne	Vlastní validace; vrátí `WP_Error` nebo `true`

Příklad: přidat IBAN k formuláři pro odstoupení

add_filter( 'wpify_woo_withdrawal_claims_form_fields', function ( array $fields, string $type ) {
    if ( $type !== 'withdrawal' ) {
        return $fields;
    }

    $fields[] = array(
        'id'          => 'iban',
        'type'        => 'text',
        'label'       => __( 'IBAN pro vrácení peněz', 'my-textdomain' ),
        'placeholder' => 'SK00 0000 0000 0000 0000 0000',
        'required'    => true,
    );

    return $fields;
}, 10, 2 );

Tím se IBAN objeví ve formuláři, vyžádá se před odesláním, uloží se k žádosti a zobrazí se v adminu, v zákaznické historii „Moje objednávky” i v admin/customer e-mailech — bez dalšího kódu.

Akce

`wpify_woo_withdrawal_claims_request_created`

Spouští se po úspěšném uložení žádosti. Primární extension point pro custom workflowy.

do_action( 'wpify_woo_withdrawal_claims_request_created', int $request_id, int $order_id, string $type );

Příklad: notifikovat Slack po každé žádosti

add_action( 'wpify_woo_withdrawal_claims_request_created', function( $request_id, $order_id, $type ) {
    wp_remote_post( 'https://hooks.slack.com/services/...', array(
        'body' => wp_json_encode( array(
            'text' => sprintf( 'Nová %s žádost #%d pro objednávku #%d', $type, $request_id, $order_id ),
        ) ),
    ) );
}, 10, 3 );

`wpify_woo_withdrawal_claims_status_changed`

Pro custom workflow rozšíření, která mění status žádosti. Plugin sám status nikdy nemění.

do_action( 'wpify_woo_withdrawal_claims_status_changed', int $request_id, string $old_status, string $new_status );

`wpify_woo_withdrawal_claims_before_email_send` / `after_email_send`

Spouštějí se kolem odesílání e-mailu.

do_action( 'wpify_woo_withdrawal_claims_before_email_send', WC_Email $email, int $request_id );
do_action( 'wpify_woo_withdrawal_claims_after_email_send', WC_Email $email, int $request_id, bool $success );

`wpify_woo_withdrawal_claims_my_account_after_buttons`

Vlož vlastní obsah pod tlačítka v Můj účet.

do_action( 'wpify_woo_withdrawal_claims_my_account_after_buttons', WC_Order $order );

`wpify_woo_withdrawal_claims_form_before` / `form_after`

Obal formulář vlastním HTML.

do_action( 'wpify_woo_withdrawal_claims_form_before', string $type, ?WC_Order $order );
do_action( 'wpify_woo_withdrawal_claims_form_after', string $type, ?WC_Order $order );

REST API

Formulář interně používá dva REST endpointy:

Endpoint	Metoda	Účel
`/wp-json/wpify-woo/v1/withdrawal-claims/validate`	POST	Validuje auth pole (untrusted scénář) a vrátí předrenderované HTML eligibility sekce
`/wp-json/wpify-woo/v1/withdrawal-claims/submit`	POST	Finální podání — validuje vše, uloží do DB, odešle e-maily

Oba endpointy přijímají JSON body s poli formuláře. Autentifikace přes X-WP-Nonce header (REST nonce) plus interní _wpify_woo_nonce form-specifický nonce.

Databázová tabulka

Tabulka: {prefix}wpify_woo_requests (vytvořena automaticky přes Wpify\Model\CustomTableRepository).

Sloupec	Typ	Poznámka
`id`	INT, AUTO_INCREMENT, PK
`request_type`	VARCHAR(20)	`withdrawal` \| `claim`
`order_id`	BIGINT	WC order ID
`order_number`	VARCHAR(50)	Pro zobrazení/vyhledávání
`customer_email`	VARCHAR(255)	Snapshot `billing_email` v okamžiku podání
`customer_name`	VARCHAR(255)	Jméno z formuláře
`items_json`	TEXT	JSON `[{line_item_id, quantity}]`
`reason`	TEXT	Volitelné u withdrawal, povinné u claim
`scope`	VARCHAR(20)	`whole_order` \| `specific_items`
`status`	VARCHAR(50)	Default `submitted`, plugin nemění — extension point
`period_end`	DATETIME	Snapshot konce lhůty v okamžiku podání
`submitted_at`	DATETIME	Vyžadováno směrnicí 2023/2673
`customer_ip`, `customer_user_agent`	VARCHAR	Audit
`created_at`	DATETIME

CSS třídy

Třída	Element
`.wpify-woo-form`	Wrapper sekce formuláře
`.wpify-woo-form--withdrawal` / `.wpify-woo-form--claim`	Type-specific class
`.wpify-woo-form--submitted`	Thank-you stav
`.wpify-woo-form--loading`	Loading stav během AJAXu
`.wpify-woo-form-errors`	Blok chybových zpráv
`.wpify-woo-items`	Items fieldset (toggle scope radiem)
`.wpify-woo-scope`	Scope radio fieldset
`.woocommerce-form-withdrawal` / `.woocommerce-form-claim`	Class form elementu
`.wpify-woo-helper-text`	Helper text pod submit tlačítkem

Per-produkt meta klíče

Meta klíč	Typ	Popis
`_wpify_woo_withdrawal_excluded`	yes/no	Vyloučeno z odstoupení
`_wpify_woo_warranty_excluded`	yes/no	Vyloučeno ze záruky/reklamace
`_wpify_woo_withdrawal_period_override`	int (dny)	Per-produkt lhůta pro odstoupení
`_wpify_woo_warranty_months_override`	int (měsíce)	Per-produkt záruční doba

Per-objednávka meta klíče

Meta klíč	Typ	Popis
`_wpify_woo_period_start`	datetime (mysql)	Uloženo pluginem, když objednávka poprvé přejde do stavu konfigurovaného jako start lhůty

Kam přidávat kód

Vlastní funkce můžeš přidat do:

Souboru functions.php ve vašem child tématu
Pluginu Code Snippets
Vlastního pluginu

Pro vývojáře

Shortcody

Formulář odstoupení

Formulář reklamace

Oba formuláře na jedné stránce

Gutenberg bloky

URL parametry

Filtry

wpify_woo_withdrawal_claims_blocked_statuses

Default

Příklad: blokovat i „on-hold” objednávky

wpify_woo_withdrawal_claims_resolve_order

Příklad: podpora prefixu „ORD-”

wpify_woo_withdrawal_claims_eligible_items

wpify_woo_withdrawal_claims_is_eligible_item

wpify_woo_withdrawal_claims_period_end / period_start

wpify_woo_withdrawal_claims_is_excluded_product

wpify_woo_withdrawal_claims_request_type_labels

wpify_woo_withdrawal_claims_scope_labels

wpify_woo_withdrawal_claims_status_labels