ePodací Hárok
ePodací Hárok je oficiálny systém Slovenskej pošty na elektronické podávanie zásielok a generovanie adresných štítkov. Plugin sa priamo integruje s REST API ePodacieho Hárku, čím umožňuje vytvárať a registrovať zásielky bez opustenia WooCommerce.
Čo môžete robiť
- Generovať PDF adresné štítky pre ľubovoľnú WooCommerce objednávku.
- Podávať zásielky Slovenskej pošte jednotlivo (z editačnej stránky objednávky) alebo hromadne (zo zoznamu objednávok).
- Nastavovať druh zásielky, triedu zásielky, spôsob úhrady a doplnkové služby pre každú objednávku zvlášť alebo ako predvolené hodnoty pre celý obchod.
- Automaticky rozpoznať objednávky na dobierku a predvyplniť sumu dobierky.
- Automaticky doplniť tracking číslo zásielky po jej vytvorení.
- Logovať všetky API požiadavky a odpovede pre účely ladenia.
Predpoklady
- Aktívny účet ePodací Hárok u Slovenskej pošty — prihlasovacie údaje (User ID a API Key) získate priamo od Slovenskej pošty, oddelene od licencie pluginu.
- Aktívna licencia pluginu.
V tejto sekcii
- Nastavenie a konfigurácia — API údaje, informácie o odosielateľovi a všetky predvolené nastavenia.
- Jedna objednávka — Vytvorenie, registrácia a stiahnutie štítka pre jednu objednávku.
- Hromadné generovanie štítkov — Spracovanie viacerých objednávok naraz zo zoznamu objednávok.
- Referencia možností zásielky — Všetky druhy zásielok, triedy, spôsoby úhrady a služby.
Nastavenie a konfigurácia
Všetky nastavenia ePodacieho Hárku sa nachádzajú v WP-Admin > Slovenská Pošta > ePodací Hárok.
API údaje
Tieto prihlasovacie údaje poskytuje Slovenská pošta pri registrácii prístupu k ePodaciemu Hárku.
| Pole | Popis |
|---|---|
| User ID | Váš identifikátor používateľa ePodacieho Hárku (API ho označuje ako userId). |
| API Key | Tajný API kľúč používaný na autentifikáciu požiadaviek. Uložený ako pole pre heslo. |
Obe polia sú povinné. Vytvorenie zásielky zlyhá, ak niektoré chýba alebo je nesprávne.
Informácie o odosielateľovi
Údaje o odosielateľovi sú vytlačené na každom vygenerovanom štítku. Vyplňte obchodné informácie o vašej firme.
| Pole | Poznámky |
|---|---|
| Kontaktná osoba | Meno zodpovednej kontaktnej osoby. |
| Organizácia / Spoločnosť | Názov vašej firmy alebo obchodu. |
| Ulica | Iba názov ulice (bez čísla domu). |
| Mesto | Názov mesta. |
| PSČ | Poštové smerovacie číslo. Povinné pre validáciu. |
| Kód krajiny | Dvojpísmenkový kód ISO. Predvolená hodnota SK. |
| Telefónne číslo | Voliteľné. |
| E-mailová adresa | Predvolená hodnota je administrátorský e-mail WordPress, ak je pole prázdne. |
Predvolené nastavenia zásielky
Tieto hodnoty predvypĺňajú formulár ePH pri každej objednávke. Pred vytvorením zásielky ich možno vždy zmeniť pre konkrétnu objednávku.
| Nastavenie | Možnosti | Predvolené |
|---|---|---|
| Druh zásielky | Pozri Možnosti zásielky | Balík (b) |
| Trieda zásielky | 1.trieda (c1), 2.trieda (c2) | 2.trieda (c2) |
| Spôsob úhrady | Pozri Možnosti zásielky | Faktúra (fa) |
| Spôsob podaja | Na pošte — Podaj na pošte (post); Kuriér — Podaj u kuriéra (courier) | Podaj na pošte |
| Predvolené služby | Pozri Možnosti zásielky | Žiadne |
Dobierka
| Nastavenie | Popis |
|---|---|
| COD Payment Methods | Vyberte jeden alebo viac platobných spôsobov WooCommerce, ktoré majú spúšťať automatickú detekciu dobierky. Keď objednávka použije uvedený platobný spôsob, formulár ePH predvyplní sumu dobierky hodnotou objednávky. |
| COD IBAN | Číslo účtu IBAN pre dobierkové prevody. Zobrazuje sa v metaboxe objednávky, keď je dobierka aktívna, a je vytlačené na štítku. |
| Bulk Existing ePH Action | Určuje, čo robí hromadný generátor, keď objednávka už má existujúci ePH: Vytvoriť a zaregistrovať nový ePH (prepíše existujúci) alebo Preskočiť objednávku. Predvolené: prepísať. |
Poistenie
| Nastavenie | Popis |
|---|---|
| Auto-poistenie | Keď je povolené, pole pre sumu poistenia vo formulári ePH objednávky sa automaticky predvyplní hodnotou objednávky WooCommerce. Hodnotu možno zmeniť pred vytvorením zásielky. Predvolene vypnuté. |
Integrácia sledovania
| Nastavenie | Popis |
|---|---|
| Automatické doplnenie tracking čísla | Keď je povolené (predvolené), čiarový kód zásielky vrátený API ePH sa automaticky skopíruje do poľa tracking čísla objednávky po vytvorení zásielky. Tým sa spustí synchronizácia sledovania na pozadí bez akýchkoľvek manuálnych krokov. |
Logovanie
| Nastavenie | Popis |
|---|---|
| Zapnúť logovanie API volaní | Zaznamenáva každú API požiadavku a odpoveď ePH. Užitočné pri diagnostike problémov s pripojením alebo validáciou. Log je obmedzený na 500 záznamov (staré sa automaticky odstraňujú) a je viditeľný v dolnej časti záložky nastavení ePodacieho Hárku. Predvolene vypnuté — zapínajte iba počas ladenia a potom vypnite. |
Jedna objednávka
Každá WooCommerce objednávka má v postrannom paneli editácie objednávky dedikovaný metabox ePodací Hárok. Môžete ho použiť na vytvorenie zásielky, stiahnutie štítka a resetovanie alebo opätovné vygenerovanie ePH bez opustenia obrazovky objednávky.
Metabox ePH je dostupný pre všetky WooCommerce objednávky, nielen pre tie, ktoré používajú prepravné metódy Slovenskej pošty.
Metabox ePH
Umiestnenie: Editačná stránka objednávky → postranný panel → box Slovenská Pošta – ePodací Hárok.
Pred vytvorením zásielky
Keď ešte nebol vytvorený žiadny ePH, metabox zobrazí editačný formulár s nasledujúcimi poľami:
| Pole | Popis |
|---|---|
| Hmotnosť | Celková hmotnosť zásielky v kilogramoch. Automaticky vypočítaná z hmotností produktov objednávky a nastavenia hmotnosti obalu. |
| Druh zásielky | Typ zásielky. Predvolená hodnota zodpovedá celoobchodnému nastaveniu. Pozri Možnosti zásielky. |
| Trieda zásielky | Trieda doručenia (1. alebo 2.). Predvolená hodnota zodpovedá celoobchodnému nastaveniu. |
| Spôsob úhrady | Spôsob platby poštovného. Predvolená hodnota zodpovedá celoobchodnému nastaveniu. Pozri Možnosti zásielky. |
| Služby | Voliteľné doplnkové služby (napr. Krehké, Doručenka). Pozri Možnosti zásielky. |
| Suma dobierky | Suma dobierky v EUR. Relevantné iba ak sa vzťahuje dobierka. |
| Suma poistenia | Deklarovaná hodnota pre poistenie v EUR. |
| Poznámka | Voľný text poznámky k zásielke. Predvolená hodnota je číslo WooCommerce objednávky. |
Automatické predvyplnenie
Pri načítaní formulára metaboxu sa niektoré polia automaticky predvypĺňajú na základe údajov objednávky:
Dobierka: Ak je platobný spôsob WooCommerce objednávky uvedený v nastavení COD Payment Methods, suma dobierky sa predvyplní hodnotou objednávky. Sumu možno upraviť pred vytvorením zásielky.
Neskladné balenie:
Ak má niektorý produkt v objednávke rozmery, ktoré spúšťajú detekciu neštandardného balenia, služba Neskladné (nsk) sa automaticky zaškrtne. Toto odráža, čo by sa odoslalo do API.
Doručovacia služba na výdajné miesto:
Pre objednávky doručované cez Balík na Poštu alebo BalikoBOX sa služba Doručenie na poštu / BalíkoBOX / PoštaPOINT (pr) automaticky zaškrtne a uzamkne — pre tieto prepravné metódy ju nie je možné odškrtnúť.
Vytvorenie zásielky
Kliknite na Create and Register Shipment. Plugin vykoná nasledujúce kroky v jednej akcii:
- Vytvorí nový ePodací Hárok cez API.
- Pridá zásielku do hárku so všetkými nakonfigurovanými údajmi.
- Vygeneruje PDF adresný štítok.
- Zaregistruje hárok (podá ho Slovenskej pošte).
- Stiahne a uloží PDF štítka lokálne do
/wp-content/uploads/wcsp-eph-labels/.
Ak je povolené Automatické doplnenie tracking čísla, čiarový kód zásielky sa v tomto bode zapíše aj do poľa tracking čísla objednávky.
Po registrácii
Po vytvorení a registrácii zásielky je formulár nahradený súhrnným zobrazením, ktoré ukazuje:
- Číslo zásielky — čiarový kód pridelený Slovenskou poštou.
- Iba na čítanie súhrn odoslaných polí (hmotnosť, druh, trieda, spôsob úhrady, služby, dobierka, poistenie).
- Odznak Zaregistrovaný, keď bol hárok úspešne podaný.
- Tlačidlo Stiahnuť štítok — stiahne lokálne uložené PDF štítka.
- Tlačidlo Regenerovať ePH — vymaže všetky údaje ePH pre túto objednávku a znovu otvorí editačný formulár, čo umožňuje začať odznova. Toto nezruší predtým zaregistrovanú zásielku u Slovenskej pošty.
Stĺpec v zozname objednávok
Keď objednávka obsahuje údaje ePH, v zozname objednávok sa zobrazí súhrnný odznak:
- Označenie druhu zásielky a hmotnosť.
- Suma dobierky (ak je väčšia ako nula).
- Suma poistenia (ak je väčšia ako nula).
- Odkaz Upraviť, ktorý otvorí modálne okno na rýchlu úpravu druhu, hmotnosti, dobierky a poistenia.
- Odkaz Stiahnuť ePH, ak je k dispozícii PDF štítka.
Hromadné generovanie štítkov
Zásielky ePH pre viacero objednávok môžete vytvoriť a zaregistrovať v jednej operácii priamo zo zoznamu objednávok WooCommerce.
Spustenie hromadného generovania
- Prejdite na WP-Admin > WooCommerce > Orders.
- Označte objednávky, ktoré chcete spracovať, pomocou zaškrtávacích políčok riadkov.
- Otvorte rozbaľovací zoznam Bulk actions a zvoľte Generate ePH Labels.
- Kliknite na Apply.
Pred začatím spracovania sa otvorí dialógové okno s nastaveniami.
Dialógové okno hromadných nastavení
Dialógové okno umožňuje nastaviť spoločné parametre zásielky, ktoré sa vzťahujú na všetky vybrané objednávky. Individuálne údaje objednávky (adresa príjemcu, hmotnosť, dobierka) sa stále preberajú z každej objednávky zvlášť.
| Nastavenie | Popis |
|---|---|
| Druh zásielky | Typ zásielky pre všetky spracované objednávky. Pozri Možnosti zásielky. |
| Trieda zásielky | Trieda doručenia (1. alebo 2.). |
| Spôsob úhrady | Spôsob platby poštovného. Pozri Možnosti zásielky. |
| Služby | Doplnkové služby, ktoré sa vzťahujú na všetky zásielky. Pozri Možnosti zásielky. |
| Poznámka | Voľný text poznámky na všetkých zásierkach. |
Potvrďte nastavenia a spustite spracovanie. Každá objednávka sa spracúva postupne.
Spracovanie objednávok s existujúcim ePH
Ak vybraná objednávka už má existujúci záznam ePH, správanie riadi nastavenie Bulk Existing ePH Action v nastaveniach ePodacieho Hárku:
| Možnosť | Správanie |
|---|---|
| Vytvoriť a zaregistrovať nový ePH (predvolené) | Vymaže existujúce údaje ePH a vytvorí novú zásielku. |
| Preskočiť objednávku | Ponechá existujúce údaje ePH nezmenené a preskočí na ďalšiu objednávku. |
Výsledky
Po spracovaní sa zobrazí súhrn výsledkov:
- Úspešné: Objednávky, ktoré boli vytvorené a zaregistrované, každá s odkazom Stiahnuť štítok pre vygenerované PDF.
- Preskočené: Objednávky, ktoré boli preskočené, pretože už mali ePH a akcia bola nastavená na preskočenie.
- Chyby: Objednávky, pri ktorých vytvorenie alebo registrácia zlyhali, s podrobnosťami o chybe z API.
Štítky z úspešných objednávok možno stiahnuť jednotlivo zo súhrnu výsledkov, alebo neskôr z metaboxu ePH každej objednávky alebo stĺpca zoznamu objednávok.
Referencia možností zásielky
Táto stránka používa oficiálnu terminológiu Slovenskej pošty.
Druh zásielky
Druh zásielky definuje typ produktu registrovaného u Slovenskej pošty. Vyberte druh, ktorý zodpovedá skutočnej zásielke.
| Kód | Oficiálny názov |
|---|---|
b | Balík (predvolené) |
r | Doporučený list |
pl | Poistený list |
uz | Úradná zásielka |
ek | Expres kuriér |
ems | EMS zásielka |
epg | EPG – Obchodný balík |
zb | Balík – Zmluvní zákazníci |
zbc | Balík – Zmluvní zákazníci – Consignment |
lt | Balíček |
epo1 | Easy Expres 1 |
epo10 | Easy Expres 10 |
pz | Prime zásielka |
olz | List |
Nie všetky druhy sú dostupné pre všetky typy zmlúv so Slovenskou poštou. Skontrolujte svoju zmluvu ePodacieho Hárku a overte, ktoré druhy sa vzťahujú na váš účet.
Trieda zásielky
| Kód | Oficiálny názov |
|---|---|
c2 | 2.trieda (predvolené) |
c1 | 1.trieda |
Spôsob úhrady
Spôsob úhrady určuje, ako sa vysporiadava poštovné so Slovenskou poštou.
| Kód | Oficiálny názov |
|---|---|
fa | Faktúra (predvolené) |
up | Úver poštovného |
vsz | Výplatný stroj |
pz | Poštové známky |
pr | Platené prevodom |
h | Platené v hotovosti |
vps | Vec poštovej služby |
ol | Online |
Doplnkové služby
Doplnkové služby, ktoré možno pridať k zásielke. Služby sa konfigurujú pre každú objednávku zvlášť alebo sa nastavujú ako celoobchodné predvolené hodnoty v nastaveniach ePodacieho Hárku.
| Kód | Oficiálny názov | Poznámky |
|---|---|---|
pr | Doručenie na poštu/BalíkoBOXu/PoštaPOINTu | Automaticky vynútené pre objednávky využívajúce prepravné metódy Balík na Poštu alebo BalikoBOX. Pre tieto objednávky nie je možné odškrtnúť. |
nsk | Neskladné | Automaticky detekované keď rozmery produktu spúšťajú neštandardné balenie. |
d | Doručenka | |
doh | Doručiť do 10:00 | |
f | Krehké | |
iod | Info o doručení | |
ndo | Nedoposielať | |
neu | Neukladať | |
nev | Nevrátiť | |
od | Opakované doručenie | |
sv | Splnomocnenie vylúčené | |
svd | Spätné vrátenie potvrdenej dokumentácie | |
vr | Do vlastných rúk | |
vt | Výmena tovaru |
Dostupnosť služieb závisí od vybraného druhu zásielky a vašej zmluvy so Slovenskou poštou.
Spôsob podaja
| Kód | Oficiálny názov |
|---|---|
post | Podaj na pošte |
courier | Podaj u kuriéra |
Stav hárku
| Kód | Oficiálny názov | Poznámka |
|---|---|---|
draft | hárok nebol odoslaný | |
registered | hárok bol odoslaný | stav „Nepodaný" vo webe |
opened | hárok sa spracováva na pošte | prebieha príjem zásielok |
received | hárok bol podaný | stav „Podaný" vo webe |
confirmed | hárok bol uzatvorený | stav „Podaný" vo webe |
expired | hárok exspiroval | stav „Exspirovaný" vo webe |
aborted | hárok bol zrušený | stav „Zrušený" vo webe |
Obal
| Kód | Oficiálny názov |
|---|---|
standard | Štandardná zásielka |
nonstandard | Neštandardná zásielka |
Obsah
| Kód | Oficiálny názov |
|---|---|
goods | Tovar |
documents | Dokumenty |
Dobierka
| Kód | Oficiálny názov |
|---|---|
bdnu | Bezdokladová dobierka na účet |
bdna | Bezdokladová dobierka na adresu |
cn29 | Dobierková poukážka |
Validačné chyby
| Kód | Oficiálny význam |
|---|---|
out_of_range | hodnota mimo rozsah |
invalid_format | neplatný formát |
invalid_value | neplatná hodnota |
required | povinný údaj |
parcel_number_parcel_type_not_match | podacie číslo nie je možné použiť pre daný druh zásielky |
parcel_number_country_not_match | podacie číslo nie je možné použiť pre uvedenú krajinu adresáta |
parcel_number_subject_not_match | podacie číslo bolo pridelené inému používateľovi |
parcel_number_unavailable | podacie číslo nie je možné použiť |
parcel_number_already_used | zásielka so zadaným podacím číslom už bola podaná |
already_exists | zásielka so zadaným podacím číslom už v hárku existuje |
customs_weight_exceded | hmotnosť položiek v colnom vyhlásení presahuje celkovú hmotnosť |
invalid_zip | neplatné PSČ |
invalid_bnp_zip | neplatné PSČ pre zásielku so službou „Na poštu/do BalíkoBOXu/do PoštaPOINTu" |
invalid_nobnp_street | nepovolený spôsob doručenia |
invalid_nopr_street | nepovolený spôsob doručenia |
invalid_post_name | neplatný názov pošty pre dané PSČ |
invalid_prefix_checksum | neplatný kontrolný súčet |
invalid_base_checksum | neplatný kontrolný súčet |
invalid_bank_code | neplatný kód banky |
invalid_iban_checksum | neplatný kontrolný súčet IBANu |