Balíkonoš.cz

Hlavní rozdíly

K zásadním změnám došlo u práce se zásilkami. Ostatní zdroje by měly být plně kompatibilní. Stuktura dat vkládaných zásilek se změnila z:

{
    "recipFirstname": "Jan",
    "recipSurname": "Malý",
    "recipStreet": "Revoluční 11",
    "recipCity": "Praha",
    "recipPostalCode": "11000",
    "recipState": "CZ",
    "recipEmail": "email@example.com",
    "recipPhone": "+420 608 111 000",
    "value": 1340,
    "currency": "CZK",
    "cod": 2000,
    "codCurrency": "CZK",
    "packagesCount": 1,
    "variableSymbol": "00015504",
    "deliveryType": "BP",
    "agent": "GLS",
    "weight": 3.1,
    "collectionPlace": "my-identifier",
    "extraServices": [
        "ECOL"
    ]
}
                    

Na následující (v závorkách je původní název klíče či vysvětlení):

{
    "variableSymbol": "00015504", (variableSymbol)
    "value": 1340, (value)
    "valueCurrency": "CZK", (currency)
    "cod": 2000, (cod)
    "codCurrency": "CZK", (codCurrency)
    "packages": [
        {
            "weight": 3.1, (weight)
            "height": 20, (nové, povinné jen pro některé nové přepravce)
            "width": 10, (nové, povinné jen pro některé nové přepravce)
            "lenght": 8, (nové, povinné jen pro některé nové přepravce)
        }
    ],
    "agent": "GLS", (agent)
    "deliveryType": "BP", (deliveryType)
    "sender": {
        "type": "collectionPlace", (nové, odlišení typu odesílatele: address, collectionPlace)
        "collectionPlace": "my-identifier", (collectionPlace)
    },
    "recipient":  {
        "type": "address", (nové, odlišení typu příjemce: address, collectionPlace, pickUpPlace)
        "firstname": "Jan", (recipFirstname)
        "surname": "Malý", (recipSurname)
        "phone": "+420 608 111 000", (recipPhone)
        "email": "email@example.com", (recipEmail)
        "address": {
            "street": "Revoluční 11", (recipStreet)
            "state": "CZ", (recipState)
            "city": "Praha", (recipCity)
            "postalCode": "11000" (recipPostalCode)
        }
    },
    "extraServices": [
        {
            "code": "sms_advice_unload" (extraServices)
            "arguments": {
                "phone": "222 111 000" (nové, některé doplňkové služby vyžadují argumenty)
            }
        },
        {
            "code": "think_green" (extraServices)
        }
    ]
}
                    

• (sender|recipient).type - rozhoduje o struktuře požadovaných dat, více ve standardní dokumentaci
• senderXxx - nyní je přímá zásilka specifikována pokud je recipient.type i sender.type hodnota address (v takovém případě vyžaduje pole sender stejné údaje jako recipient výše)
• extraServices - dříve šlo o výčet identifikátorů, nyní se identifikátory specifikují v objektech pod klíčem code a některé nově vyžadují argumenty (typicky avíza)
• weight - dříve šlo o hmotnost nejtěžšího balíku, nyní jsou vyžadovány hmotnosti jednotlivých balíků
• packmachine - dříve šlo o samostatné pole, nyní se identifikátor uvádí do recipient.pickUpPlace pokud je recipient.type hodnota pickUpPlace

Automatické doplňkové služby

Dříve se avíza zdarma (telefonní, emailové, sms) doplňovala automaticky ke každé zásilce, pokud byl uveden telefon či email. To však způsobovalo, že klient nikdy nevěděl, zda je avízo u zásilky objednané či nikoliv (například avíza po ČR byla u některých přepravců zdarma, ale do zahraničí nikoli). Proto je v nové verzi nutné specifikovat všechny doplňkové služby včetně avíz.

Doplňování čísel zásilek

Ve verzi 2 docházelo k doplňování čísel zásilek u některých přepravců ihned po vytvoření zásilky. Nově jsou čísla zásilek dostupná konzistentně pro všechny přepravce až po jejich uvažení. Součástí odpovědi při uzavírání zásilek jsou nyní všechny informace o zásilce (i právě přiřazené číslo zásilky), takže již není nutné provádět další GET požadavek pro jeho zjištění.

Validace telefonů

Nově jsou striktněji validovány telefonní čísla. Validace bere v potaz stát odesílatele/příjemce, takže není možné zaslat zásilku na slovensko a uvést Afghánské telefonní číslo. Pokud není vyplněna předvolba čísla, předpokládá se právě stát příjemce/odesílatele.

Uzavírání zásilek

Nyní lze uzavírat zásilky pouze stejného přepravce. Díky tomu už nebude docházet k napůl úspěšným operacím, kdy zásilky jednoho přepravce byly uzavřeny a zásilky jiného ne.

České chybové hlášky

Nyní můžete vyžádat překlad chybových hlášek v poli errors.message pomocí hlavičky accept-language: cs.

Testování

Demo účet již není dostupný. Lze však testovat v testovacím prostředí (https://test.balikonos.cz) nad standardní registrací. Je však nutné vytvořit testovací přihlašovací údaje a případně typ svozu. Více ve standardní dokumentaci.

Zpětná a přímá zásilka

Tyto dvě doplňkové služby již nelze vyžádat (dříve BACK a DRCT). Jejich použití implikuje přímo odeslaný požadavek. Například přímá zásilka je použije, pokud odesíláte z adresy na adresu (recipient.type a sender.type je address). Více informací o těchto doplňkových službách je ve standardní dokumentaci.

Zásilka na poštu (NP)

Pošty jsou nyní odběrnými místy, takže není nutné specifikovat celou adresu pošty, ale stačí uvést PSČ pošty v poli recipient.pickUpPlace (stejně jako například pro poštomaty).

Omezení hledaných zásilek

Maximální počet vrácených zásilek je nyní 100.

Identifikátory

Zkratky přepravců, typů zásilek, doplňkových služeb a jejich argumentů najdete v klienstké zóně v sekci API. Zobrazují se pouze používaní přepravci (ti, kde jsou dostupné autentizační údaje).

Došlo ke změně identifikátorů doplňkových služeb, nicméně staré identifikátory stále fungují. Pokud však migrujete, mapování je následující. Všechny ostatní identifikátory jsou totožné jako ve verzi 2.

• BACK => back_delivery
• EXCH => exchange_delivery
• DOCS => documents_back
• INSR => insurance
• CRRY => carry
• LOSS => loss
• AUTH => authentication
• CALL => call_advice_unload
• CMPL => completation
• SATR => saturday_delivery
• FRAG => fragile
• SUND => sunday_delivery
• FIRM => company_delivery
• NGHT => evening_delivery
• DRCT => direct_delivery
• IN24 => guaranteed_24
• ECOL => think_green
• INS1 => insurance
• INS2 => insurance
• INS3 => insurance
• INS4 => insurance
• PVER => addressee_only
• SMAL => sms_advice_unload
• MAIL => email_advice_unload
• SMDE => sms_preadvice