REST API

WebEPH REST API je kanál na automatizovaný import, validáciu a odoslanie ePodacích hárkov. V jednom ePodacom hárku je možné zadať údaje pre 5 000 zásielok.

Autentifikácia

WebEPH API je potrebné pred prvým použitím aktivovať:

  • prihláste sa do WebEPH
  • v menu Viac / Notifikácie a API / WebEPH API zvoľte možnosť WebEPH API aktivované
  • uložte zmeny

Po aktivácii WebEPH API sa sprístupnia autentifikačné údaje (userId a apiKey), ktoré je potrebné odosielať v každom requeste ako hlavičku vo formáte:

x-api-auth: apikey {userId}:{apiKey}

Príklad:

x-api-auth: apikey 5E78187E742523700C000054:D7EF52D02B8BF9ABF981A8B62139F94A1A833DEA46AA8A9C017A7D2F1AD0C381

Služby

baseUrl: https://mojezasielky.posta.sk/integration/rest/v1

Vytvorenie hárku

PUT {baseUrl}/sheets

create_sheet_request() :: {
    sheet: sheet()
}.
create_sheet_response() :: {
    status: "ok",
    sheet: sheet()
} | {
    status: "validation_failed",
    validation_errors: [validation_error(), ...]
}.

Vytvorenie zásielky

PUT {baseUrl}/sheets/{sheetId}/parcels

create_parcel_request() :: {
    parcel: parcel()
}.
create_parcel_response() :: {
    status: "ok",
    parcel: parcel()
} | {
    status: "validation_failed",
    validation_errors: [validation_error(), ...]
}.

Odstránenie zásielky

DELETE {baseUrl}/sheets/{sheetId}/parcels/{parcelId}

delete_parcel_response() :: {
    status: "ok",
}.

Generovanie adresných štítkov

POST {baseUrl}/sheets/{sheetId}/parcels/{parcelId}/labels

parcel_label_request() :: {
    format: "pdf"
}.
parcel_label_response() :: {
    status: "ok",
    labels: file_ref(),
    parcel: parcel()
}.

Odoslanie hárku

POST {baseUrl}/sheets/{sheetId}/register

register_sheet_request() :: {
}.
register_sheet_response() :: {
    status: "ok",
    sheet: sheet()
} | {
    status: string()
}

Detail hárku

GET {baseUrl}/sheets/{sheetId}

Query parametre:

  • parcels=1 - okrem údajov hárku služba vráti tiež zoznam zásielok
get_sheet_response() :: {
    status: "ok",
    sheet: sheet()
}

Dátové typy

Hárok

sheet() :: {
    // Jedinečný identifikátor
    id:                 string(),

    // Stav hárku
    state:              sheet_state(),

    // Číslo hárku
    ephid:              string(),

    // Druh zásielky
    parcel_category:    parcel_category_code(),

    // Spôsob úhrady
    payment_type:       payment_type_code(),

    // Spôsob podaja
    reception_method:   reception_method_code(),

    // Odosielateľ
    sender:             address(),

    // Mám so Slovenskou poštou zmluvný vzťah
    contract:           boolean(),

    // Mám pridelený rozsah podacích čísel
    own_parcel_numbers: boolean(),

    // Zásielkly v hárku
    parcels:            [parcel()]
}.
AtribútPovinnéDefaultPoznámka
id--Automaticky prideľuje server pri vytvorení hárku. Viď. sheet_state
state--Automaticky prideľuje server pri vytvorení hárku. Viď. sheet_state
ephid--Automaticky prideľuje server po odoslaní hárku.
parcel_categorynier - Doporučený listZoznam dostupných produktov sa nachádza v parcel_category_code
payment_typenieh - Platené v hotovostiAtribútom payment_type sa definuje spôsob úhrady za podávané zásielky. Zoznam kódov pre spôsoby úhrady je dostupný v payment_type_code.
reception_methodniepost - Podaj na pošteSpôsob podaja definuje, či budú zásielky podávané na pošte alebo u kuriéra. Na základe spôsobu podaja sa vypočíta cena za zásielku. Zoznam kódov pre spôsoby podaja je dostupný na reception_method_code
senderáno-Rozsah údajov Odosielateľa je uvedený v address.
contractniefalseAtribút contract definuje, či odosielateľ má uzavretú zmluvu o podaji zásielok so Slovenskou poštou. Pre uplatnenie zmluvných cien je potrebné uvádzať rozsah podacích čísel, ktoré boli pridelené po podpise zmluvy.
own_parcel_numbersniefalseAtribút s hodnotou true je potrebné uviesť, ak odosielateľovi boli pridelené podacie čísla Slovenskou poštou.
parcels--Vracia server iba pri detaile hárku.

Zásielka

parcel() :: {
    // Jedinečný identifikátor
    id:                 string(),

    // Podacie číslo
    parcel_number:      string(),

    // Adresát
    recipient:          address(),

    // Adresa späť
    back:               address(),

    // Trieda
    parcel_class:       parcel_class_code(),

    // Hmotnosť
    weight:             decima(),

    // Poistenie
    insurance:          amount(),

    // Dobierka
    cod:                cod(),

    // Doplnkové a dispozičné služby
    services:           [service_code(), ...],

    // Počet kusov (viackusová zásielka)
    parts:              integer(),

    // Obal
    packaging:          packing_code(),

    // Obsah
    content_category:   content_category_code(),

    // Úložná lehota
    handover_period:    integer(),

    // Identifikátor zákazníka
    custom_identifier:  string(),

    // Poznámka
    note:               string(),

    // Colná deklarácia
    cd:                 parcel_cd(),

    // Smerovanie zásielky
    routing:            parcel_routing()
}.
AtribútPovinné pri vytváraníDefaultPoznámka
id--Automaticky prideľuje server pri vytvorení hárku.
parcel_numberPre hárok s príznakom own_parcel_numbers-Vypĺňajú zmluvní podávatelia. Podacie číslo sa uvádza vo formáte PPNNNNNNNNCSS, resp. v tvare PPNNNNNNNNSS, kde PP je prefix, NNNNNNNN je podacie číslo zásielky, C je kontrolná číslica a SS je sufix zásielky.
recipientÁno-Rozsah údajov Adresáta je uvedený v address.
backNie-Rozsah údajov prijímateľa vracanej zásielky je uvedený v address. Atribút sa uvádza len v prípade, ak adresa odosielateľa sa nachádza v zahraničí, alebo odosielateľ si praje vrátiť zásielku na inú adresu ako je uvedená v atribúte sender.
parcel_classNiec2 - 2.triedaAtribút sa môže uvádzať len pre produkty Doporučený list (vnútroštátny styk), Poistený list (vnútroštátny styk) a List (vnútroštátny list). c1 - 1.trieda c2 - 2.trieda
weightPre zásielky hradené online (payment_type: ol), alebo pre zásielky s colnou deklaráciou-Hmotnosť sa vypĺňa v kg na max. tri desatinné miesta.
insurancePre poistený list (parcel_category: pl)-Výška poistenia sa uvádza celým číslom. Maximálna hodnota je stanovená zmluvou alebo poštovými a zasielacími podmienkami. Službu Poistenie je možné využiť pre produkty Poistený list, Balík, Expres kuriér, Easy Expres 1, Easy Expres 10, EPG – Obchodný balík, Balík – zmluvní zákazníci a Balík – zmluvní zákazníci - Consignment. Uvádza sa v EUR.
codNie-Výška dobierkovej sumy sa uvádza v EUR ako reálne číslo na max. dve desatinné miesta. Maximálna hodnota je stanovená zmluvou alebo poštovými podmienkami.
servicesNie-Tento atribút sa uvádza v prípade, že je použitá aspoň jedna služba, ktorá je uvedená v zozname service_code. Povolené kombinácie služieb pre jednotlivé produkty sa nachádzajú v Technických parametroch - ePodací hárok.
partsNie1Atribút vyjadruje počet kusov zásielky, ak je zásielka rozdelená na viac kusov. Hodnotu vyššiu ako 1 je možné použiť len pre Expres kuriér zásielky.
packagingNiestandard - Štandardná zásielkaRozsah údajov pre obal je uvedený v packing_code. Doporučené listy a Úradné zásielky v hmotnostnej kategórii do 50 g majú neštandardný obal ak ktorýkoľvek rozmer presahuje príslušný najväčší rozmer listovej zásielky plochého pravouhlého tvaru listu (dĺžka 235 mm, šírka 165 mm, hrúbka 5 mm) alebo je podaný v doručenkovej obálke, ktorá nespĺňa podmienku podľa poštových podmienok, uplatní sa cena do hmotnosti 100 g.
content_categoryNiegoods - TovarAtribút sa používa len pre expresné medzinárodné zásielky. Zoznam údajov, ktoré je možné uvádzať je v content_category_code.
handover_periodNie-Odberná lehota zásielky sa uvádza len v prípade, ak má byť kratšia ako je štandardná - 18 dní. Uvádzaná hodnota je v rozmedzí 1 - 17 dní.
custom_identifierNie-Vlastný identifikátor odosielateľa zásielky. Max. počet číselných znakov je 100.
noteNie-Poznámka odosielateľa zásielky. Max. počet znakov je 200.
cdPre zásielky do krajín mimo EU-Zoznam jednotlivých atribútov je definovaný v parcel_cd.
routing--Vracia server po vytvorení zásielky. Smerovací kód sa uvádza na adresný štítok, ak si ho odosielateľ generuje sám vo svojom IS.

Smerovanie zásielky

parcel_routing() :: {
    // Smerovací kód
    code:               string(),

    // Názov pošty
    pudo_name:          string()
}.

Colná deklarácia

parcel_cd() :: {
    // Kategória zásielky
    category:           parcel_cd_category_code(),

    // Iná kategória
    category_other:     string(),

    // Obsah zásielky
    items:              [parcel_cd_item(), ...],

    // Sprievodné dokumenty
    documents:          [parcel_cd_document(), ...],

    // IČO/DIČ/kód dovozcu
    importer_ref:       string(),

    // Poznámky k obsahu
    note:               string()
}.
AtribútPovinné pri vytváraníDefaultPoznámka
categoryÁno-Zoznam jednotlivých atribútov je definovaný v parcel_cd_category_code.
category_otherPre kategóriu “Iné” (category: other)-V atribúte category_other sa popisuje kategória zásielky. Maximálny počet znakov je 50.
itemsÁno (minálne 1, maximálne 4 položky)-Jednotlivé atribúty sú definované v parcel_cd_item.
documentsNie (maximáne jedna položka pre každý typ dokumentu)-Jednotlivé atribúty sú definované v parcel_cd_document.
importer_refNie-Referencia dovozcu by mala obsahovať IČO/DIČ/kód dovozcu. Maximálny počet znakov je 40.
noteNie-Poznámka k colnému vyhláseniu. Maximálny počet znakov je 200.
parcel_cd_category_code() ::
    "gift"      |       // Darček
    "documents" |       // Dokumenty
    "sample"    |       // Obchodná vzorka
    "returned"  |       // Vrátený tovar
    "sale"      |       // Predaj tovaru
    "other".            // Iné
parcel_cd_item() :: {
    // Podrobný popis obsahu
    description:        string(),

    // Množstvo v kusoch
    quantity:           integer(),

    // Hmotnosť v kg
    weight:             decimal(),

    // Hodnota v EUR
    value:              decimal(),

    // Tarifné číslo
    tariff_number:      string(),

    // Krajina pôvodu
    origin_country:     country_code()
}.
AtribútPovinné pri vytváraníDefaultPoznámka
descriptionÁnoV atribúte sa uvádza podrobný popis tovaru v zásielke.
quantityÁnoPočet kusov tovarovej položky v colnom vyhlásení. Uvádza sa celé číslo.
weightÁnoHmotnosť položky v kg na max. 3 desatinné miesta. Maximálna hmotnosť položky je limitovaná max. hmotnosťou zásielky, ktorá je definovaná poštovými podmienkami.
valueÁno/Nie - ak v atribúre category je uvedený kód documents.Predstavuje hodnotu tovaru konkrétnej tovarovej položky. Maximálna hodnota je stanovená výškou sumy Poistného za zásielku uvádzanú v atribúte insurance.
tariff_numberÁnoPredstavuje HS kód tovaru podľa Colného sadzobníka. Položku vypĺňa odosielateľ obchodného tovaru. Maximálny počet znakov je 6.
origin_countryNiesk – SlovenskoUvádza sa kód krajiny pôvodu tovaru podľa špecifikácie ISO 3166-1 alpha 2 (napr. SK, CZ, …)
parcel_cd_document() :: {
    // Typ dokumenty
    type:               parcel_cd_document_type_code(),

    // Číslo dokumentu
    number:             string()
}.
AtribútPovinné pri vytváraníDefaultPoznámka
typeÁnoV atribúte sa uvádza typ dokumentu, ktorý sa pripája k colnému vyhláseniu. Uvádza sa kód podľa číselníka uvedeného v parcel_cd_document_type_code.
numberÁnoObsahuje číslo faktúry/licencie/certifikátu uvedených v atribúte type. Max. počet znakov je 20.
parcel_cd_document_type_code() ::
    "invoice"      |    // Faktúra
    "license"      |    // Licencia
    "certificate".      // Certifikát

Stav hárku

sheet_state() ::
    "draft"      |      // hárok nebol odoslaný
    "registered" |      // hárok bol odoslaný (stav “Nepodaný” vo webe)
    "opened"     |      // hárok sa spracováva na pošte, t.j. 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)

Druh zásielky

parcel_category_code() ::
    "r"     |           // Doporučený list
    "pl"    |           // Poistený list
    "uz"    |           // Úradná zásielka
    "b"     |           // Balík
    "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

Spôsob úhrady

payment_type_code() ::
    "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
    "fa"  |             // Faktúra
    "ol".               // Online

Spôsob podaja

reception_method_code() ::
    "post" |            // Podaj na pošte
    "courier".          // Podaj u kuriéra

Trieda zásielky

parcel_class_code() ::
    "c1" |              // 1.trieda
    "c2".               // 2.trieda

Doplnkové služby

service_code() ::
  "doh" |               // Doručiť do 10:00
  "d"   |               // Doručenka
  "f"   |               // Krehké
  "iod" |               // Info o doručení
  "ndo" |               // Nedoposielať
  "neu" |               // Neukladať
  "nev" |               // Nevrátiť
  "nsk" |               // Neskladné
  "od"  |               // Opakované doručenie
  "pr"  |               // Doručenie na poštu/BalíkoBOXu
  "sv"  |               // Splnomocnenie vylúčené
  "svd" |               // Spätné vrátenie potvrdenej dokumentácie
  "vr"  |               // Do vlastných rúk
  "vt".                 // Výmena tovaru

Obal

packing_code() ::
    "standard" |        // Štandardná zásielka
    "nonstandard".      // Neštandardná zásielka

Obsah

content_category_code() ::
    "goods" |           // Tovar
    "documents".        // Dokumenty

Krajina

country_code() ::
    string().

Suma

amount() :: {
    value:              decimal(),
    currency:           "EUR"
},

Dobierka

cod_type_code() ::
    "bdnu" |            // Bezdokladová dobierka na účet
    "bdna" |            // Bezdokladová dobierka na adresu
    "cn29".             // Dobierková poukážka
cod() :: {
    type:               cod_type_code(),
    amount:             amount(),
    iban:               string(),
    symbol:             string()
}.
AtribútPovinné pri vytváraníDefaultPoznámka
typeÁnoSpôsob úhrady vybranej dobierkovej sumy odosielateľovi zásielky, ktorá sa realizuje na účet, na adresu, resp. prostredníctvom Dobierkovej poukážky CN 29ter (pre zahraničné dobierky). Kód sa uvádza podľa číselníka uvedeného v cod_type_code.
amountÁnoVýška dobierkovej sumy. Uvádza sa ako reálne číslo s dvomi desatinnými miestami. Maximálna hodnota je stanovená zmluvou alebo poštovými a zasielacími podmienkami.
ibanPre dobierku na účet (type: bdnu)IBAN na ktorý budú odosielateľovi zásielky zaslané peniaze za dobierku.
symbolNieVariabilný symbol, ktorý sa použije pri prevode dobierkovej sumy na účet. Môže mať max. 10 numerických znakov. Je určený na jednoduchšiu identifikáciu poukázaných peňazí na účte odosielateľa zásielky.

Adresné údaje

address() :: {
    name:               string(),
    organization:       string(),
    street:             string(),
    city:               string(),
    zip:                string(),
    country:            country_code(),
    phone:              string(),
    email:              string()
}.
AtribútPovinné pri vytváraníDefaultPoznámka
nameAk nie je uvedená organizáciaUvádza sa meno a priezvisko, prípadne tituly. Max. počet znakov je 100.
organizationAk nie je uvedené menoUvádza sa názov organizácie. Max. počet znakov je 100.
streetÁnoUvádza sa ulica a číslo domu. Max. počet znakov je 100.
cityÁnoUvádza sa názov mesta/obce. Max. počet znakov je 100.
zipPre vnútroštátne zásielky (country: sk)PSČ. Max. počet znakov je 20.
countryNiesk – SlovenskoKód krajiny podľa ISO 3166-1 alpha 2 (napr. SK, CZ, …). Ak nie je uvedený, predvolí sa SK. Max. počet znakov sú 2.
phonePre zásielky so službou “Na poštu” ak nie je uvedený emailTel. číslo na mobilný telefón v tvare 0987654321, alebo v tvare +421987654321, alebo v tvare 00421987654321, na ktoré sa zasielajú notifikácie o doručovaní, resp. uložení balíkov. V prípade, že je použité tel. číslo na pevnú linku, tak tel. číslo bude použité len na telefonické kontaktovanie adresáta pri doručovaní zásielky. Pre zásielky so službou “Na poštu” je možné použiť iba tel. číslo slovenských mobilných operátorov. Max. počet znakov je 20.
emailPre zásielky so službou “Na poštu” ak nie je uvedený telefónAdresa elektronickej pošty, na ktorú sa zasiela notifikácia o podaji, doručovaní a uložení balíkov. Max. počet znakov je 80.

Odkaz na súbor

file_ref() :: {
    url:                string()
}.

Validačné chyby

validation_error() :: {
    attribute:          string(),
    error:              validation_error_code()
}.
validation_error_code() ::
    "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“
    "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

Príklady

Vytvorenie hárku

  • Slovenská pošta umožňuje zasielať dáta o zásielkach potrebné pre podaj v tzv. hárkoch, t.j. v „množinách“, ktoré môžu obsahovať  až cca 5 000 zásielok rovnakého druhu (napr. Expres kuriér).
  • V API je možné vytvárať súbežne niekoľko hárkov naraz. Do hárku/ov sa postupne zasielajú jednotlivé zásielky.
  • Ideálne je vytvárať jeden hárok na podaj za deň, resp. 1 hárok na 1 kamión. Max. doba na vytváranie hárku je definovaná na viac ako 2 týždne.
  • Hárok obsahuje základné informácie o odosielateľovi zásielok, druhu produktu (napr. Expres kuriér), spôsobe úhrady za zásielky (napr. faktúrou), spôsobe podaja, atď.
  • Informácie o jednotlivých zásielkach sa posielajú v samostatných požiadavkách na vytvorenie zásielky.

Príklad požiadavky:

PUT https://mojezasielky.posta.sk/integration/rest/v1/sheets
{
    "sheet": {
        "parcel_category": "ek",
        "sender": {
            "name": "Anička Jurkovičová",
            "organization": "Firma ABCD",
            "street": "Partizánska cesta 9",
            "city": "Banská Bystrica",
            "zip": "97401",
            "country": "SK",
            "phone": "+421999999999",
            "email": "anicka.jurkovicova@firmaabcd.sk"
        },
        "reception_method": "post",
        "payment_type": "fa",
        "own_parcel_numbers": true,
        "contract": true
    }
}
Odpoveď
{
    "status": "ok",
    "sheet": {
        "state": "draft",
        "sender": {
            "zip": "97401",
            "street": "Partizánska cesta 9",
            "phone": "00421999999999",
            "organization": "Firma ABCD",
            "name": "Anička Jurkovičová",
            "email": "anicka.jurkovicova@firmaabcd.sk",
            "country": "sk",
            "city": "Banská Bystrica"
        },
        "reception_method": "post",
        "payment_type": "fa",
        "parcel_category": "ek",
        "own_parcel_numbers": true,
        "id": "64DCAA7DBFF7348DD7D5E740",
        "contract": true
    }
}

Vytvorenie 1. zásielky v hárku

  • Informácie o jednotlivých adresátoch a službách k zásielke sú definované v požiadavke na vytvorenie zásielky.
  • V prípade, že adresa odosielateľa sa nezhoduje s adresou pre vracanie zásielok, tak sa v požiadavke zasiela adresa „Späť“ v atribúte „back“.
  • Ak sa adresátovi zasielajú pri Expres kuriérovi viackusové zásielky, tak sa vytvára len jedna požiadavka s podacím číslom, v ktorej je definovaný počet kusov zásielky v atribúte „parts“. Váha, poistenie a dobierka sa uvádzajú sumárne pre všetky zásielky.

Príklad požiadavky:

PUT https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740/parcels
{
    "parcel": {
        "parcel_number": "EB534780896SK",
        "recipient": {
            "name": "Jonáš Báťka",
            "organization": "Mrkva, s.r.o.",
            "street": "Fučíkova 1986/99",
            "city": "Detva",
            "zip": "96212",
            "country": "sk",
            "phone": "+421977777777",
            "email": "jonas.batka@test.sk"
        },
        "back": {
            "name": "Anička Jurkovičová",
            "organization": "Firma ABCD",
            "street": "Zeleninová 1786/77",
            "city": "Zvolen",
            "zip": "96001",
            "country": "sk",
            "phone": "+421999999999",
            "email": "anicka.jurkovicova@firmaabcd.sk"
        },
        "weight": 1.23,
        "insurance": {
            "value": 36,
            "currency": "EUR"
        },
        "cod": {
            "type": "bdnu",
            "amount": {
                "value": 35.99,
                "currency": "EUR"
            },
            "iban": " SK5809000000000000000123",
            "symbol": "1234567890"
        },
        "services": [
            "iod",
            "vr",
            "f"
        ],
        "parts": 2,
        "packaging": "standard",
        "handover_period": 10,
        "custom_identifier": "123456789",
        "note": "Záhradné vybavenie 1542023"
    }
}
Odpoveď
{
    "status": "ok",
    "parcel": {
        "weight": 1.23,
        "services": [
            "f",
            "iod",
            "vr"
        ],
        "routing": {
            "code": "ZV-OU ZV"
        },
        "recipient": {
            "zip": "96212",
            "type": "address",
            "street": "Fučíkova 1986/99",
            "phone": "00421977777777",
            "organization": "Mrkva, s.r.o.",
            "name": "Jonáš Báťka",
            "email": "jonas.batka@test.sk",
            "country": "sk",
            "city": "Detva"
        },
        "parts": 2,
        "parcel_number": "EB534780896SK",
        "note": "Záhradné vybavenie 1542023",
        "insurance": {
            "value": 36.0,
            "currency": "eur"
        },
        "id": "64DCAAB2BFF7348DD7D5EB7B",
        "handover_period": 10,
        "custom_identifier": "123456789",
        "cod": {
            "type": "bdnu",
            "symbol": "1234567890",
            "iban": "SK5809000000000000000123",
            "amount": {
                "value": 35.99,
                "currency": "eur"
            }
        },
        "back": {
            "zip": "96001",
            "street": "Zeleninová 1786/77",
            "organization": "Firma ABCD",
            "name": "Anička Jurkovičová",
            "country": "sk",
            "city": "Zvolen"
        }
    }
}

Vytvorenie adresného štítku pre 1. zásielku

  • Zaslaním požiadavky sa sprístupní url adresa na stiahnutie PDF adresného štítka vo formáte A6.
  • Adresný štítok je možné stiahnuť do momentu odoslania hárku.

Príklad požiadavky:

POST https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740/parcels/64DCAB05BFF7348DD7D5F1EC/labels
{
    "format": "pdf"
}
Odpoveď
{
    "status": "ok",
    "labels": {
        "url": "https://mojezasielky.posta.sk/api/webapp/cdn/64DCAB66BFF7348DD7D5F969?t=BADAF57377B91E3DC357C9D3BAB3564A"
    }
}

Vytvorenie 2. zásielky v hárku

  • V jednom hárku musia byť zásielky rovnakého druhu, pričom služby môžu mať rozdielne.
  • Napr. časť zásielok bude doručovaná na adresu, časť bude mať doručenie na poštu a časť môže byť smerovaná do cudziny, ak to povoľujú parametre produktu definované v Poštových podmienkach.

Príklad požiadavky:

PUT https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740/parcels
{
    "parcel": {
        "parcel_number": "EB534780905SK",
        "recipient": {
            "name": "Lenka Malá",
            "street": "Sokolská 96",
            "city": "Zvolen BalíkoBOX LIDL, Sokolská",
            "zip": "96190",
            "country": "sk",
            "phone": "+421988888888",
            "email": "lenka@test.sk"
        },
        "back": {
            "name": "Anička Jurkovičová",
            "organization": "Firma ABCD",
            "street": "Zeleninová 1786/77",
            "city": "Zvolen",
            "zip": "96001",
            "country": "sk",
            "phone": "+421999999999",
            "email": "anicka.jurkovicova@firmaabcd.sk"
        },
        "weight": 3.56,
        "insurance": {
            "value": 158,
            "currency": "EUR"
        },
        "cod": {
            "type": "bdnu",
            "amount": {
                "value": 158,
                "currency": "EUR"
            },
            "iban": " SK5809000000000000000123",
            "symbol": "1234567891"
        },
        "services": [
            "pr"
        ],
        "packaging": "standard",
        "handover_period": 10,
        "custom_identifier": "123456790",
        "note": "Záhradné vybavenie 1552023"
    }
}
Odpoveď
{
    "status": "ok",
    "parcel": {
        "weight": 3.56,
        "services": [
            "pr"
        ],
        "routing": {
            "pudo_name": "Zvolen BalíkoBOX LIDL, Sokolská",
            "code": "ZV-OSS ZV"
        },
        "recipient": {
            "zip": "96190",
            "type": "post",
            "street": "Sokolská 96",
            "phone": "00421988888888",
            "name": "Lenka Malá",
            "email": "lenka@test.sk",
            "country": "sk",
            "city": "Zvolen BalíkoBOX LIDL, Sokolská"
        },
        "parcel_number": "EB534780905SK",
        "note": "Záhradné vybavenie 1552023",
        "insurance": {
            "value": 158.0,
            "currency": "eur"
        },
        "id": "64DCAD63BFF7348DD7D6279C",
        "handover_period": 10,
        "custom_identifier": "123456790",
        "cod": {
            "type": "bdnu",
            "symbol": "1234567891",
            "iban": "SK5809000000000000000123",
            "amount": {
                "value": 158.0,
                "currency": "eur"
            }
        },
        "back": {
            "zip": "96001",
            "street": "Zeleninová 1786/77",
            "organization": "Firma ABCD",
            "name": "Anička Jurkovičová",
            "country": "sk",
            "city": "Zvolen"
        }
    }
}

Vytvorenie adresného štítku pre 2. zásielku

  • Zaslaním požiadavky sa sprístupní url adresa na stiahnutie PDF adresného štítka vo formáte A6.
  • Adresný štítok je možné stiahnuť do momentu odoslania hárku.

Príklad požiadavky:

POST https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740/parcels/64DCAD63BFF7348DD7D6279C/labels
{
    "format": "pdf"
}
Odpoveď
{
    "status": "ok",
    "labels": {
        "url": "https://mojezasielky.posta.sk/api/webapp/cdn/64DCADC5BFF7348DD7D62FF7?t=05E34BAC2B5055FF8770C4318F316E47"
    }
}

Odoslanie hárku

  • Pred samotným fyzickým podajom zásielok je potrebné poslať požiadavku na odoslanie hárku.
  • Po odoslaní hárku sa dáta sprístupnia pre jednotlivé pobočky pošty, ktoré si ich budú môcť stiahnuť.
  • Hárky sú dostupné na spracovanie na oblastných uzloch/poštách max. 10 kalendárnych dní.
  • Ak nedôjde k spracovaniu hárku, tak automatizovane nadobudne stav exspirovaný.
  • Pre prípadný podaj zásielok, ktoré sa nachádzali v už v exspirovanom hárku bude potrebné poslať nový ePodací hárok.

Príklad požiadavky:

POST https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740/register
{
}
Odpoveď
{
    "status": "ok",
    "sheet": {
        "state": "registered",
        "sender": {
            "zip": "97401",
            "street": "Partizánska cesta 9",
            "phone": "00421999999999",
            "organization": "Firma ABCD",
            "name": "Anička Jurkovičová",
            "email": "anicka.jurkovicova@firmaabcd.sk",
            "country": "sk",
            "city": "Banská Bystrica"
        },
        "reception_method": "post",
        "payment_type": "fa",
        "parcels": [
            {
                "weight": 1.23,
                "services": [
                    "f",
                    "iod",
                    "vr"
                ],
                "routing": {
                    "code": "ZV-OU ZV"
                },
                "recipient": {
                    "zip": "96212",
                    "type": "address",
                    "street": "Fučíkova 1986/99",
                    "phone": "00421977777777",
                    "organization": "Mrkva, s.r.o.",
                    "name": "Jonáš Báťka",
                    "email": "jonas.batka@test.sk",
                    "country": "sk",
                    "city": "Detva"
                },
                "parts": 2,
                "parcel_number": "EB534780848SK",
                "note": "Záhradné vybavenie 1542023",
                "insurance": {
                    "value": 36.0,
                    "currency": "eur"
                },
                "id": "64DCAE49BFF7348DD7D66578",
                "handover_period": 10,
                "custom_identifier": "123456789",
                "cod": {
                    "type": "bdnu",
                    "symbol": "1234567890",
                    "iban": "SK5809000000000000000123",
                    "amount": {
                        "value": 35.99,
                        "currency": "eur"
                    }
                },
                "back": {
                    "zip": "96001",
                    "street": "Zeleninová 1786/77",
                    "organization": "Firma ABCD",
                    "name": "Anička Jurkovičová",
                    "country": "sk",
                    "city": "Zvolen"
                }
            },
            {
                "weight": 1.23,
                "services": [
                    "f",
                    "iod",
                    "vr"
                ],
                "routing": {
                    "code": "ZV-OU ZV"
                },
                "recipient": {
                    "zip": "96212",
                    "type": "address",
                    "street": "Fučíkova 1986/99",
                    "phone": "00421977777777",
                    "organization": "Mrkva, s.r.o.",
                    "name": "Jonáš Báťka",
                    "email": "jonas.batka@test.sk",
                    "country": "sk",
                    "city": "Detva"
                },
                "parts": 2,
                "parcel_number": "EB534780896SK",
                "note": "Záhradné vybavenie 1542023",
                "insurance": {
                    "value": 36.0,
                    "currency": "eur"
                },
                "id": "64DCAE49BFF7348DD7D66579",
                "handover_period": 10,
                "custom_identifier": "123456789",
                "cod": {
                    "type": "bdnu",
                    "symbol": "1234567890",
                    "iban": "SK5809000000000000000123",
                    "amount": {
                        "value": 35.99,
                        "currency": "eur"
                    }
                },
                "back": {
                    "zip": "96001",
                    "street": "Zeleninová 1786/77",
                    "organization": "Firma ABCD",
                    "name": "Anička Jurkovičová",
                    "country": "sk",
                    "city": "Zvolen"
                }
            },
            {
                "weight": 3.56,
                "services": [
                    "pr"
                ],
                "routing": {
                    "pudo_name": "Zvolen BalíkoBOX LIDL, Sokolská",
                    "code": "ZV-OSS ZV"
                },
                "recipient": {
                    "zip": "96190",
                    "type": "post",
                    "street": "Sokolská 96",
                    "phone": "00421988888888",
                    "name": "Lenka Malá",
                    "email": "lenka@test.sk",
                    "country": "sk",
                    "city": "Zvolen BalíkoBOX LIDL, Sokolská"
                },
                "parcel_number": "EB534780905SK",
                "note": "Záhradné vybavenie 1552023",
                "insurance": {
                    "value": 158.0,
                    "currency": "eur"
                },
                "id": "64DCAE49BFF7348DD7D6657A",
                "handover_period": 10,
                "custom_identifier": "123456790",
                "cod": {
                    "type": "bdnu",
                    "symbol": "1234567891",
                    "iban": "SK5809000000000000000123",
                    "amount": {
                        "value": 158.0,
                        "currency": "eur"
                    }
                },
                "back": {
                    "zip": "96001",
                    "street": "Zeleninová 1786/77",
                    "organization": "Firma ABCD",
                    "name": "Anička Jurkovičová",
                    "country": "sk",
                    "city": "Zvolen"
                }
            }
        ],
        "parcel_category": "ek",
        "own_parcel_numbers": true,
        "id": "64DCAA7DBFF7348DD7D5E740",
        "ephid": "EPH340560341",
        "contract": true
    }
}

Zistenie stavu hárku

  • Keď ePodací hárok nadobudne stav „opened“ začína plynúť 5 dňová lehota na jeho spracovanie.
  • Je veľmi dôležité, aby počas tohto obdobia boli dodané všetky zásielky, ktoré sa budú z predmetného ePodacieho hárku podávať.
  • Pri zasielaní zásielok je posielanie tejto požiadavky nepovinné.

Príklad požiadavky:

GET https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740
Odpoveď
{
    "status": "ok",
    "sheet": {
        "state": "registered",
        "sender": {
            "zip": "97401",
            "street": "Partizánska cesta 9",
            "phone": "00421999999999",
            "organization": "Firma ABCD",
            "name": "Anička Jurkovičová",
            "email": "anicka.jurkovicova@firmaabcd.sk",
            "country": "sk",
            "city": "Banská Bystrica"
        },
        "reception_method": "post",
        "payment_type": "fa",
        "parcel_category": "ek",
        "own_parcel_numbers": true,
        "id": "64DCAA7DBFF7348DD7D5E740",
        "ephid": "EPH340560341",
        "contract": true
    }
}

Stiahnutie hárku

  • Pre aktualizáciu údajov o podaných zásielkach v IS zákazníka sa posiela požiadavka na stiahnutie hárku.
  • V stiahnutom hárku sú údaje týkajúce sa len stavu hárku, ale nie zásielok.
  • Informáciu o stave zásielok poskytuje T&T API, ktoré je dostupné na https://www.posta.sk/subory/39030/manual-pre-implementaciu-tt-api.pdf
  • Pri zasielaní zásielok je posielanie požiadavky na stiahnutie hárku nepovinné.

Príklad požiadavky:

GET https://mojezasielky.posta.sk/integration/rest/v1/sheets/64DCAA7DBFF7348DD7D5E740?parcels=1
Odpoveď
{
    "status": "ok",
    "sheet": {
        "state": "registered",
        "sender": {
            "zip": "97401",
            "street": "Partizánska cesta 9",
            "phone": "00421999999999",
            "organization": "Firma ABCD",
            "name": "Anička Jurkovičová",
            "email": "anicka.jurkovicova@firmaabcd.sk",
            "country": "sk",
            "city": "Banská Bystrica"
        },
        "reception_method": "post",
        "payment_type": "fa",
        "parcels": [
            {
                "weight": 1.23,
                "services": [
                    "f",
                    "iod",
                    "vr"
                ],
                "routing": {
                    "code": "ZV-OU ZV"
                },
                "recipient": {
                    "zip": "96212",
                    "type": "address",
                    "street": "Fučíkova 1986/99",
                    "phone": "00421977777777",
                    "organization": "Mrkva, s.r.o.",
                    "name": "Jonáš Báťka",
                    "email": "jonas.batka@test.sk",
                    "country": "sk",
                    "city": "Detva"
                },
                "parts": 2,
                "parcel_number": "EB534780848SK",
                "note": "Záhradné vybavenie 1542023",
                "insurance": {
                    "value": 36.0,
                    "currency": "eur"
                },
                "id": "64DCAE49BFF7348DD7D66578",
                "handover_period": 10,
                "custom_identifier": "123456789",
                "cod": {
                    "type": "bdnu",
                    "symbol": "1234567890",
                    "iban": "SK5809000000000000000123",
                    "amount": {
                        "value": 35.99,
                        "currency": "eur"
                    }
                },
                "back": {
                    "zip": "96001",
                    "street": "Zeleninová 1786/77",
                    "organization": "Firma ABCD",
                    "name": "Anička Jurkovičová",
                    "country": "sk",
                    "city": "Zvolen"
                }
            },
            {
                "weight": 1.23,
                "services": [
                    "f",
                    "iod",
                    "vr"
                ],
                "routing": {
                    "code": "ZV-OU ZV"
                },
                "recipient": {
                    "zip": "96212",
                    "type": "address",
                    "street": "Fučíkova 1986/99",
                    "phone": "00421977777777",
                    "organization": "Mrkva, s.r.o.",
                    "name": "Jonáš Báťka",
                    "email": "jonas.batka@test.sk",
                    "country": "sk",
                    "city": "Detva"
                },
                "parts": 2,
                "parcel_number": "EB534780896SK",
                "note": "Záhradné vybavenie 1542023",
                "insurance": {
                    "value": 36.0,
                    "currency": "eur"
                },
                "id": "64DCAE49BFF7348DD7D66579",
                "handover_period": 10,
                "custom_identifier": "123456789",
                "cod": {
                    "type": "bdnu",
                    "symbol": "1234567890",
                    "iban": "SK5809000000000000000123",
                    "amount": {
                        "value": 35.99,
                        "currency": "eur"
                    }
                },
                "back": {
                    "zip": "96001",
                    "street": "Zeleninová 1786/77",
                    "organization": "Firma ABCD",
                    "name": "Anička Jurkovičová",
                    "country": "sk",
                    "city": "Zvolen"
                }
            },
            {
                "weight": 3.56,
                "services": [
                    "pr"
                ],
                "routing": {
                    "pudo_name": "Zvolen BalíkoBOX LIDL, Sokolská",
                    "code": "ZV-OSS ZV"
                },
                "recipient": {
                    "zip": "96190",
                    "type": "post",
                    "street": "Sokolská 96",
                    "phone": "00421988888888",
                    "name": "Lenka Malá",
                    "email": "lenka@test.sk",
                    "country": "sk",
                    "city": "Zvolen BalíkoBOX LIDL, Sokolská"
                },
                "parcel_number": "EB534780905SK",
                "note": "Záhradné vybavenie 1552023",
                "insurance": {
                    "value": 158.0,
                    "currency": "eur"
                },
                "id": "64DCAE49BFF7348DD7D6657A",
                "handover_period": 10,
                "custom_identifier": "123456790",
                "cod": {
                    "type": "bdnu",
                    "symbol": "1234567891",
                    "iban": "SK5809000000000000000123",
                    "amount": {
                        "value": 158.0,
                        "currency": "eur"
                    }
                },
                "back": {
                    "zip": "96001",
                    "street": "Zeleninová 1786/77",
                    "organization": "Firma ABCD",
                    "name": "Anička Jurkovičová",
                    "country": "sk",
                    "city": "Zvolen"
                }
            }
        ],
        "parcel_category": "ek",
        "own_parcel_numbers": true,
        "id": "64DCAA7DBFF7348DD7D5E740",
        "ephid": "EPH340560341",
        "contract": true
    }
}

Doplňujúce informácie

Zistenie stavov jednotlivých zásielok – T&T

Realizuje sa prostredníctvom T&T API, ktoré umožňuje automatizované získavanie informácií o stavoch listových a balíkových zásielok. V jednej požiadavke je možné požadovať informáciu až pre 100 zásielok. API poskytuje odpovede so všetkými dostupnými stavmi pre každú zásielku zvlášť za obdobie minimálne 6 mesiacov. Rozsah poskytovaných údajov je rovnaký ako na stránke https://tandt.posta.sk. Dokumentácia na implementáciu API je dostupná TU.

Testovanie ePH REST API

Testovanie je možné vykonávať v produkčnom a aj testovacom prostredí, pričom sa odoslané hárky po desiatich dňoch automaticky zmažú. Testovanie v produkčnom prostredí je dostupné na eph.posta.sk a na testovacom prostredí na ephtest1.posta.sk. Prihlasovacie meno na testovacie prostredie je postaeph. Heslo je inttest7. Registrácia a prihlasovanie sa do jednotlivých inštancií je oddelené a preto je potrebné pre každé prostredie vytvoriť samostatnú registráciu a vygenerovať userId a apiKey.

Nastavenie prihlásenia pre testovacie prostredie v Postman:

Pri testovaní môžete použiť nasledovné rozsahy podacích čísel, pričom prvé dva alfabetické znaky sú prefix (odlišuje sa ním druh zásielky), osem číslic je samotné podacie číslo, deviata číslica je kontrolná a vypočítava sa automatizovane podľa modulo 11. Posledné dva alfabetické znaky sú kód krajiny, odkiaľ sa zásielka posiela, tzn. vždy SK.

Produkčné prostredie (parcel_number)Testovacie prostredie (parcel_number)
Druh zásielkyVnútroštátny stykMedzinárodný stykVnútroštátny stykMedzinárodný styk
Doporučený list rRG364903735SK - RG364913729SKRG364903735SK - RG364913729SKRF991200057SK - RF991210045SKRF991200057SK - RF991210045SK
Poistený list plVC754344975SK - VC754344975SKVC754344975SK - VC754344975SKVC752560075SK - VC752570069SKVC752560075SK - VC752570069SK
Úradná zásielka uzOA577424375SK - OA577424375SKxOA560318347SK - OA560328335SKx
Balík bDA175528553SK - DA175538547SKCA017018028SK - CA017028011SKDA171102218SK - DA171112201SKCA016532165SK - CA016542154SK
Expres kuriér ekEB092799624SK – EB092809613SKxEB534780848SK - EB534790831SKx
EMS zásielka emsxED002674552SK - ED002684546SKxED002515321SK - ED002525315SK
EPG – obchodný balík epgxCI002748224SK - CI002758218SKxCI002635117SK - CI002645105SK
Balík – zmluvní zákazníci zbZB972533255SK - ZB972543244SKxZB971595259SK - ZB971605248SKx
Balík – zmluvní zákazníci – Consignment zbcZP000340018SK - ZP000350001SKxZP001050096SK - ZP001060080SKx
Balíček ltxUA061947186SK - UA061957170SKxUA061832104SK - UA061842092SK