Balíkonoš API - dokumentace RESTful zdrojů

Pro testování využívejte výhradně testovací prostředí na doméně https://test.balikonos.cz!

Diagram práce se zásilkami:

Pro správnou funkčnost metod je nutné udržet posloupnost dle diagramu. To znamená, že je nutné nejdříve zásilky vložit (v této fázi můžete zásilky rušit a editovat), a poté zásilky uzavřít. Tisk štítků a svozových protokolů lze realizovat pouze pro uzavřené zásilky.


Balíkonoš REST API - diagram zdrojů

/

Popis zdroje Speciální neverzovaný testovací zdroj bez nutné autentizace.
Úplná adresa zdroje https://balikonos.cz/api/
Podporované HTTP metody GET

/deliveries

Popis zdroje Práce s několika zásilkami najednou.
Úplná adresa zdroje https://balikonos.cz/api/v3/deliveries
OAuth 2.0 scope deliveries
Podporované HTTP metody
  • POST - import nových zásilek
  • GET - získání informací o zásilkách
  • PATCH - uzavření zásilek
  • PUT - úprava zásilek
  • DELETE - rušení zásilek

POST /deliveries

Importování nových zásilek

HTTP požadavek:
POST /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
Content-type: application/json
                
                    {
    "deliveries": [
        {
            "variableSymbol": "12345678",
            "cod": 1200,
            "codCurrency": "CZK",
            "value": 2000,
            "valueCurrency": "CZK",
            "packages": [
                {
                    "weight": "3,2",
                    "height": "20",
                    "length": "15",
                    "width": "10"
                }
            ],
            "agent": "GLS",
            "deliveryType": "BP",
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "my-identifier"
            },
            "recipient": {
                "type": "address",
                "surname": "Společnost s.r.o.",
                "phone": "+420 777 111 000",
                "email": "email@example.com",
                "address": {
                    "street": "Revoluční 11",
                    "state": "CZ",
                    "city": "Praha",
                    "postalCode": "11000"
                }
            },
            "extraServices": [
                {
                    "code": "email_advice_unload",
                    "arguments": {
                        "email": "email@example.com"
                    }
                },
                {
                    "code": "sms_advice_unload",
                    "arguments": {
                        "phone": "+420 777 111 000"
                    }
                }
            ]
        }
    ]
}
                
HTTP odpověď:
HTTP/1.1 201 Created
Content-type: application/json; charset=UTF-8
Location: https://balikonos.cz/api/v3/deliveries?deliveryId=275053
ETag: "314d2962b90789a7517603b01d16f79f"
                
{
    "code": 201,
    "status": "success",
    "message": "Deliveries successfully created",
    "data": [
        {
            "agent": "GLS",
            "closed": null,
            "cod": 1200,
            "codCurrency": "CZK",
            "created": "2016-04-21T13:21:08+02:00",
            "deliveryId": 275053,
            "deliveryNumber": null,
            "deliveryState": 0,
            "deliveryStateName": "Připravená",
            "deliveryType": "BP",
            "externalId": null,
            "extraServices": [
                {
                    "code": "email_advice_unload",
                    "arguments": {
                        "email": "email@example.com"
                    }
                },
                {
                    "code": "sms_advice_unload",
                    "arguments": {
                        "phone": "+420777111000"
                    }
                },
                {
                    "code": "cod",
                    "arguments": []
                }
            ],
            "packages": [
                {
                    "barcode": null,
                    "weight": 3.2,
                    "length": 15,
                    "width": 10,
                    "height": 20
                }
            ],
            "recipient": {
                "firstname": null,
                "surname": "Společnost s.r.o.",
                "contactPerson": null,
                "phone": "+420777111000",
                "email": "email@example.com",
                "address": {
                    "city": "Praha",
                    "street": "Revoluční 11",
                    "postalCode": "11000",
                    "state": "CZ"
                }
            },
            "sender": {
                "firstname": "Ondřej",
                "surname": "Kypr",
                "contactPerson": null,
                "phone": "721000892",
                "email": "joecipra@gmail.com",
                "address": {
                    "city": "Vyškov",
                    "street": "Dobrovského 409/1",
                    "postalCode": "68201",
                    "state": "CZ"
                }
            },
            "source": 3,
            "sourceName": "API",
            "ticketNote": null,
            "value": 2000,
            "valueCurrency": "CZK",
            "variableSymbol": "12345678"
        }
    ]
}
                
HTTP požadavek:
POST /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
Content-type: application/xml
                
                    <?xml version="1.0" encoding="UTF-8"?>
<root>
  <deliveries>
    <variableSymbol>12345678</variableSymbol>
    <cod>1200</cod>
    <codCurrency>CZK</codCurrency>
    <value>2000</value>
    <valueCurrency>CZK</valueCurrency>
    <packages>
      <weight>3,2</weight>
      <height>20</height>
      <length>15</length>
      <width>10</width>
    </packages>
    <agent>GLS</agent>
    <deliveryType>BP</deliveryType>
    <sender>
      <type>collectionPlace</type>
      <collectionPlace>my-identifier</collectionPlace>
    </sender>
    <recipient>
      <type>address</type>
      <surname>Společnost s.r.o.</surname>
      <phone>+420 777 111 000</phone>
      <email>email@example.com</email>
      <address>
        <street>Revoluční 11</street>
        <state>CZ</state>
        <city>Praha</city>
        <postalCode>11000</postalCode>
      </address>
    </recipient>
    <extraServices>
      <code>email_advice_unload</code>
      <arguments>
        <email>email@example.com</email>
      </arguments>
    </extraServices>
    <extraServices>
      <code>sms_advice_unload</code>
      <arguments>
        <phone>+420 777 111 000</phone>
      </arguments>
    </extraServices>
  </deliveries>
</root>
                
HTTP odpověď:
HTTP/1.1 201 Created
Content-type: application/xml; charset=UTF-8
Location: https://balikonos.cz/api/v3/deliveries?deliveryId=275053
ETag: "314d2962b90789a7517603b01d16f79f"
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>201</code>
  <status>success</status>
  <message>Deliveries successfully created</message>
  <data>
    <agent>GLS</agent>
    <closed></closed>
    <cod>1200</cod>
    <codCurrency>CZK</codCurrency>
    <created>2016-04-21T13:21:08+02:00</created>
    <deliveryId>275053</deliveryId>
    <deliveryNumber></deliveryNumber>
    <deliveryState>0</deliveryState>
    <deliveryStateName>Připravená</deliveryStateName>
    <deliveryType>BP</deliveryType>
    <externalId></externalId>
    <extraServices>
      <code>email_advice_unload</code>
      <arguments>
        <email>email@example.com</email>
      </arguments>
    </extraServices>
    <extraServices>
      <code>sms_advice_unload</code>
      <arguments>
        <phone>+420777111000</phone>
      </arguments>
    </extraServices>
    <extraServices>
      <code>cod</code>
    </extraServices>
    <packages>
      <barcode></barcode>
      <weight>3,2</weight>
      <length>15</length>
      <width>10</width>
      <height>20</height>
    </packages>
    <recipient>
      <firstname></firstname>
      <surname>Společnost s.r.o.</surname>
      <contactPerson></contactPerson>
      <phone>+420777111000</phone>
      <email>email@example.com</email>
      <address>
        <city>Praha</city>
        <street>Revoluční 11</street>
        <postalCode>11000</postalCode>
        <state>CZ</state>
      </address>
    </recipient>
    <sender>
      <firstname>Ondřej</firstname>
      <surname>Kypr</surname>
      <contactPerson></contactPerson>
      <phone>721000892</phone>
      <email>joecipra@gmail.com</email>
      <address>
        <city>Vyškov</city>
        <street>Dobrovského 409/1</street>
        <postalCode>68201</postalCode>
        <state>CZ</state>
      </address>
    </sender>
    <source>3</source>
    <sourceName>API</sourceName>
    <ticketNote></ticketNote>
    <value>2000</value>
    <valueCurrency>CZK</valueCurrency>
    <variableSymbol>12345678</variableSymbol>
  </data>
</root>
                
HTTP požadavek:
POST /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
Content-type: application/x-www-form-urlencoded
                
                    deliveries%5B0%5D%5BvariableSymbol%5D=12345678&deliveries%5B0%5D%5Bcod%5D=1200&deliveries%5B0%5D%5BcodCurrency%5D=CZK&deliveries%5B0%5D%5Bvalue%5D=2000&deliveries%5B0%5D%5BvalueCurrency%5D=CZK&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bweight%5D=3%2C2&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bheight%5D=20&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Blength%5D=15&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bwidth%5D=10&deliveries%5B0%5D%5Bagent%5D=GLS&deliveries%5B0%5D%5BdeliveryType%5D=BP&deliveries%5B0%5D%5Bsender%5D%5Btype%5D=collectionPlace&deliveries%5B0%5D%5Bsender%5D%5BcollectionPlace%5D=my-identifier&deliveries%5B0%5D%5Brecipient%5D%5Btype%5D=address&deliveries%5B0%5D%5Brecipient%5D%5Bsurname%5D=Spole%C4%8Dnost+s.r.o.&deliveries%5B0%5D%5Brecipient%5D%5Bphone%5D=%2B420+777+111+000&deliveries%5B0%5D%5Brecipient%5D%5Bemail%5D=email%40example.com&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstate%5D=CZ&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bcity%5D=Praha&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5BpostalCode%5D=11000&deliveries%5B0%5D%5BextraServices%5D%5B0%5D%5Bcode%5D=email_advice_unload&deliveries%5B0%5D%5BextraServices%5D%5B0%5D%5Barguments%5D%5Bemail%5D=email%40example.com&deliveries%5B0%5D%5BextraServices%5D%5B1%5D%5Bcode%5D=sms_advice_unload&deliveries%5B0%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5Bphone%5D=%2B420+777+111+000
                
HTTP odpověď:
HTTP/1.1 201 Created
Content-type: application/x-www-form-urlencoded; charset=UTF-8
Location: https://balikonos.cz/api/v3/deliveries?deliveryId=275053
ETag: "314d2962b90789a7517603b01d16f79f"
                
code=201&status=success&message=Deliveries+successfully+created&data%5B0%5D%5Bagent%5D=GLS&data%5B0%5D%5Bcod%5D=1200&data%5B0%5D%5BcodCurrency%5D=CZK&data%5B0%5D%5Bcreated%5D=2016-04-21T13%3A21%3A08%2B02%3A00&data%5B0%5D%5BdeliveryId%5D=275053&data%5B0%5D%5BdeliveryState%5D=0&data%5B0%5D%5BdeliveryStateName%5D=P%C5%99ipraven%C3%A1&data%5B0%5D%5BdeliveryType%5D=BP&data%5B0%5D%5BextraServices%5D%5B0%5D%5Bcode%5D=email_advice_unload&data%5B0%5D%5BextraServices%5D%5B0%5D%5Barguments%5D%5Bemail%5D=email%40example.com&data%5B0%5D%5BextraServices%5D%5B1%5D%5Bcode%5D=sms_advice_unload&data%5B0%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5Bphone%5D=%2B420777111000&data%5B0%5D%5BextraServices%5D%5B2%5D%5Bcode%5D=cod&data%5B0%5D%5Bpackages%5D%5B0%5D%5Bweight%5D=3,2&data%5B0%5D%5Bpackages%5D%5B0%5D%5Blength%5D=15&data%5B0%5D%5Bpackages%5D%5B0%5D%5Bwidth%5D=10&data%5B0%5D%5Bpackages%5D%5B0%5D%5Bheight%5D=20&data%5B0%5D%5Brecipient%5D%5Bsurname%5D=Spole%C4%8Dnost+s.r.o.&data%5B0%5D%5Brecipient%5D%5Bphone%5D=%2B420777111000&data%5B0%5D%5Brecipient%5D%5Bemail%5D=email%40example.com&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bcity%5D=Praha&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5BpostalCode%5D=11000&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstate%5D=CZ&data%5B0%5D%5Bsender%5D%5Bfirstname%5D=Ond%C5%99ej&data%5B0%5D%5Bsender%5D%5Bsurname%5D=Kypr&data%5B0%5D%5Bsender%5D%5Bphone%5D=721000892&data%5B0%5D%5Bsender%5D%5Bemail%5D=joecipra%40gmail.com&data%5B0%5D%5Bsender%5D%5Baddress%5D%5Bcity%5D=Vy%C5%A1kov&data%5B0%5D%5Bsender%5D%5Baddress%5D%5Bstreet%5D=Dobrovsk%C3%A9ho+409%2F1&data%5B0%5D%5Bsender%5D%5Baddress%5D%5BpostalCode%5D=68201&data%5B0%5D%5Bsender%5D%5Baddress%5D%5Bstate%5D=CZ&data%5B0%5D%5Bsource%5D=3&data%5B0%5D%5BsourceName%5D=API&data%5B0%5D%5Bvalue%5D=2000&data%5B0%5D%5BvalueCurrency%5D=CZK&data%5B0%5D%5BvariableSymbol%5D=12345678
                

Popis polí požadavku

Dle příkladu výše se v těle požadavku se mohou objevit údaje z následující tabulky. Pořadí polí v jednotlivých zásilkách není zaručeno a může se měnit. Typy hodnot v požadavku jsou pouze informativní, tedy je jedno zda je v JSON požadavku 2.3 nebo "2.3".

K URI lze připojit query parametr fields a specifikovat jaká data zásilek se mají objevit v odpovědi stejně jako u metody GET.

Klíč Typ Povinné Komentář
(recipient|sender).type string Ano typ příjemce nebo odesílate, povolené hodnoty jsou: address, collectionPlace, pickUpPlace, více informací níže
(recipient|sender).address string[] Podm. pole adresy pokud je příjemce či odesílatel na běžné adresa
(recipient|sender).collectionPlace string Podm. identifikátor svozového místa pokud je příjemce či odesílatel svozové místo
recipient.pickUpPlace string Podm. identifikátor odběrného místa pokud je příjemce odběrné místo (kód poštomatu, PSČ balíku na poštu, ...)
(recipient|sender).firstname string Ne jméno (vynechte, pokud jde o firmu)
(recipient|sender).surname string Ano jméno nebo název firmy
(recipient|sender).contactPerson string Ne jméno a příjmení kontaktní osoby (pokud jde o firmu)
(recipient|sender).address.street string Ano název ulice (musí obsahovat číslo popisné, pokud není v streetNumber)
(recipient|sender).address.streetNumber string Ne číslo popisné (pokud není ve street)
(recipient|sender).address.city string Ano město
(recipient|sender).address.postalCode string Ano PSČ
(recipient|sender).address.state string Ano stát ve formátu ISO 3166-2, tedy například CZ či SK
(recipient|sender).email string Podm. email (nemusí být vyplněno, pokud je vyplněn telefon)
(recipient|sender).phone string Podm. telefon (nemusí být vyplněno, pokud je vyplněn email)
value float Ano hodnota zásilky v měně uvedené v klíči valueCurrency
valueCurrency string Ano měna hodnoty zásilky ve formátu ISO 4217, tedy například CZK či EUR
cod float Ne výše dobírky zásilky v měně uvedené v klíči codCurrency
codCurrency string Podm. měna dobírky zásilky ve formátu ISO 4217, tedy například CZK či EUR, povinné, pokud je vyplněna dobírka
variableSymbol string Podm. variabilní symbol pro platbu dobírky (povinné, pokud je vyplněna dobírka)
packages.weight float Ano hmotnost balíku v kg
packages.height int Podm. výška balíku v cm
packages.length int Podm. délka balíku v cm
packages.width int Podm. šířka balíku v cm
deliveryType string Ano typ zásilky, výčet možných hodnot je v klienstké zóně
agent string Ano přepravce, výčet možných hodnot je v klienstké zóně
extraServices.code string Ano zkratka požadované doplňkové služby, výčet je v klienstké zóně
extraServices.arguments string Ne argumenty pro doplňkovou službu, výčet klíčů pro jednotlivé doplňkové služby je v klienstké zóně
ticketNote string Ne poznámka na štítek
externalId string Ne externí identifikátor zásilky, slouží k Vaší identifikaci zásilky

Typ příjemce či odesílatele

Pole (recipient|sender).type rozhoduje o dalších polích, které je nutné pro příjemce nebo odesílatele uvést.

  • Pokud uvedete address je nutné specifikovat všechny údaje dané osoby (adresa, jméno, příjmení, telefon, ...).
  • Pokud uvedete collectionPlace je nutné specifikovat pouze identifikátor svozového místa (klíč collectionPlace).
  • Pokud uvedete pickUpPlace je nutné specifikovat identifikátor odběrného místa (klíč pickUpPlace) a údaje příjemce (jméno, příjmení, telefon, ...) bez adresy.

Tyto typy rozhodují o implicitním použití doplňkových služeb přímá a zpětná zásilka:

  • Běžné svozové zásilky jsou ze svozového místa na adresu (recipient.type je address a sender.type je collectionPlace).
  • Přímé zásilky jsou z adresy na adresu (recipient.type a sender.type je address).
  • Zpětné zásilky jsou z adresy na svozové místo. (recipient.type je collectionPlace a sender.type je address).

Aby k aplikaci zpětné a přímé zásilky došlo dle výše uvedených pravidel, je nutné mít pro daného přepravce u svozového místa vyplněný typ svozu. Svozové místo bez typu svozu se chová stejně jako obyčejná adresa - například přeprava ze svozového místa bez typu svozu na adresu použije přímou zásilku. Výjimkou jsou přepravci, kteří nerozlišují svozové a nesvozové zásilky (například TNT) - u nich vůbec neexistují doplňkové služby zpětná a přímá zásilka.

Popis polí úspěšné odpovědi

Odpověď zachovává standardní strukturu. V poli data naleznete údaje z požadavku + další doplňkové informace jako nevyplněné položky a další. Údaje v odpovědi se mohou mírně lišit od těch, jenž byly v požadavku. Například mohlo dojít k odebranání mezer, změně typu hodnoty či podobným změnám. Doplněné údaje jsou:

Klíč Typ Komentář
deliveryId int interní číslo zásilky, používá se v adresách zdrojů jiných metod této API
deliveryNumber string číslo zásilky přepravce - je doplněno až po uzavření zásilky
deliveryStateName string název stavu vytvořené zásilky
deliveryState int id stavu vytvořené zásilky, možné hodnoty jsou:
  • 0 – Připravená
  • 1 – Neodeslaná
  • 2 – Odeslaná
  • 3 – Doručená
  • 4 – Vrácená
  • 5 – Vyúčtovaná
  • 6 – Vyúčtovaná vrácená
  • 10 – Zrušená
sourceName string pojmenování původu vzniku zásilky
source int id původu vzniku zásilky, možné hodnoty jsou:
  • prázdné – Neznámý
  • 1 – Manuální
  • 2 – Csv
  • 3 – API
packages.barcode string čárový kód balíku - doplněno až po uzavření zásilky
created string datum vytvoření zásilky
Validace a chybové kódy

V případě validační chyby je vrácena odpověď s HTTP kódem 422 a popisem chyb se standardní strukturou, viz následující příklad. V takovém případě nedojde k vložení žádné z vkládaných zásilek a je nutné chyby opravit a pokusit se o vložení znovu. Díky chybové odpovědi můžete snadno detekovat, u jakých zásilek k chybě došlo (dle čísla v závorce u položky field) a zbylé zásilky vložit v dalším požadavku. Ty zásilky, u kterých došlo k chybě si pravděpodobně budete ve svém systému chtít označit jako chybné a opravit je. Většina chyb má překlad do češtiny - tu lze vyžádat použitím HTTP hlavičky accept-language: cs.

Pokud dojde k dosažení limitu zásilek dle aktuální licence, je vrácen HTTP kód 403.

{
    "code": 422,
    "status": "error",
    "message": "Validation failed",
    "errors": [
        {
            "message": "Unknown extra service \"email_advice\" for given delivery type and address combination. Allowed codes are: email_advice_unload, sms_advice_unload",
            "field": "[0].extraServices[0].code",
            "value": "email_advice"
        }
    ]
}
                    
Vkládání více zásilek v jednom požadavku

Je velmi nevhodné vkládat více zásilek pomocí několika HTTP požadavků. Raději využijte jeden požadavek s více položkami uvnitř pole deliveries. To samozřejmě znamená, že ošetření údajů Vašich zásilek musí být dostatečně striktní, aby zásilky prošly validačními kontrolami v našem API. Pokud přecijen k validační chybě dojde, je možné z odpovědi získat konkrétní zásilky, kde se vložení nezdařilo a pro zbylé zásilky požadavek zopakovat.

Další informace k odpovědi

V odpovědi naleznete hlavičku Location, která vede na stránku s právě vytvořenými zásilkami. Taktéž je přítomna hlavička ETag sloužící ke cacheování GET požadavků.

GET /deliveries

Získání informací o hledaných zásilkách.

HTTP požadavek:
GET /api/v3/deliveries?deliveryId=10441,10442&fields=deliveryId,deliveryNumber,deliveryState,value HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
ETag: "314d2962b90789a7517603b01d16f79f"
                
{
    "code": 200,
    "status": "success",
    "message": "Deliveries successfully retrieved",
    "data": [
        {
            "deliveryId": 10441,
            "deliveryNumber": "M9900002297",
            "deliveryState": 1,
            "value": 489
        },
        {
            "deliveryId": 10442,
            "deliveryNumber": "M9900002302",
            "deliveryState": 2,
            "value": 4999
        }
    ]
}
                
HTTP požadavek:
GET /api/v3/deliveries?deliveryId=10441,10442&fields=deliveryId,deliveryNumber,deliveryState,value HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
ETag: "314d2962b90789a7517603b01d16f79f"
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Deliveries successfully retrieved</message>
  <data>
    <deliveryId>10441</deliveryId>
    <deliveryNumber>M9900002297</deliveryNumber>
    <deliveryState>1</deliveryState>
    <value>489</value>
  </data>
  <data>
    <deliveryId>10442</deliveryId>
    <deliveryNumber>M9900002302</deliveryNumber>
    <deliveryState>2</deliveryState>
    <value>4999</value>
  </data>
</root>
                
HTTP požadavek:
GET /api/v3/deliveries?deliveryId=10441,10442&fields=deliveryId,deliveryNumber,deliveryState,value HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
ETag: "314d2962b90789a7517603b01d16f79f"
                
code=200&status=success&message=Deliveries+successfully+retrieved&data%5B0%5D%5BdeliveryId%5D=10441&data%5B0%5D%5BdeliveryNumber%5D=M9900002297&data%5B0%5D%5BdeliveryState%5D=1&data%5B0%5D%5Bvalue%5D=489&data%5B1%5D%5BdeliveryId%5D=10442&data%5B1%5D%5BdeliveryNumber%5D=M9900002302&data%5B1%5D%5BdeliveryState%5D=2&data%5B1%5D%5Bvalue%5D=4999
                

Popis parametrů požadavku

Nejčastější a nejrychlejší je hledání dle parametru deliveryId. Tento parametr musí obsahovat interní čísla zásilek vrácené v POST odpovědi ve stejnojmenném klíči. Jednotlivá čísla zásilek musejí být oddělena čárkou. Pořadí čísel zásilek v tomto parametru neurčuje pořadí zásilek v odpovědi!

Pomocí query parametru fields můžete definovat jaké parametry zásilky chcete v odpovědi. Více hodnot je opět odděleno čárkou. Seznam možných hodnot tohoto parametru je: deliveryId, externalId, deliveryNumber, deliveryState, deliveryStateName, value, valueCurrency, closed, cod, codCurrency, source, sourceName, variableSymbol, ticketNote, created, agent, deliveryType, extraServices, recipient, sender, packages . Neplatné hodnoty jsou ignorovány. Pořadí polí v tomto parametru neurčuje pořadí polí v odpovědi! Pokud je tento parametr vynechán, jsou vráceny všechny údaje o zásilce.

Validace a chybové kódy

V případě nenalezení žádné vlastní zásilky dle hledacích kritérií je vrácen HTTP kód 404. Pozor na případy, kdy vyhledáváte například podle několika deliveryId a některé z nich jsou platné a jiné neplatné - v takovém případě je vrácen HTTP kód 200 a v odpovědi jsou pouze existující zásilky.

Při získávání informací o velkém množství zásilek mějte na paměti, že délka URL je omezena na cca 8000 bytů. V takovém případě je vrácena chyba s HTTP kódem 414 a obsah není v požadovaném formátu. Pro požadavky na velké množství zásilek se i čas zpracování může výrazně prodloužit, doporučujeme tedy dotazovat se pouze na potřebné zásilky a pouze na potřebné položky.

Omezení počtu vrácených zásilek

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

Hledání dle ostatních parametrů zásilky

V případě, že potřebujete přesnější vyhledávání zásilek je možné hledat i podle dalších parametrů. Všechny požadovaná kritéria jsou vyhodnocena s logickým operátorem AND. Parametry jsou hledány fulltextově nebo výčtem hodnot - v tabulce níže vidíte klíče s jejich předdefinovaným způsobem hledání. Hledání dle výčtu dosáhnete oddělením hodnot čárkou, stejně jako u standardního parametru deliveryId. Navíc je možné libovolný z těchto klíčů hledat porovnáním s nějakou hodnotou pomocí prefixu > nebo <, viz příklady níže. Tedy například všechny zásilky s výší dobírky přesahující hodnotu 5000. Toto hledání potlačuje výchozí způsob hledání - nedochází tedy k fulltextovému hledání ani nelze použít výčet.

Typ hledání Klíče
fulltextové (sender|recipient).contactPerson, (sender|recipient).firstname, (sender|recipient).surname, (sender|recipient).email, (sender|recipient).phone, ticketNote, created
výčtem deliveryId, externalId, agent, deliveryType, deliveryNumber, deliveryState, value, valueCurrency, deliveryId, packages.weight, packages.width, packages.height, packages.length, cod, codCurrency, source, variableSymbol
Příklady hledání
?deliveryId=>10441 Všechny zásilky s vyšším interním id než 10441 (tzn. novější než daná zásilka) - vhodné pro synchronizaci zásilek vložených manuálně či pomocí csv s vaším systémem
?externalId=>B5007 Všechny zásilky s vyšším externím identifikátorem než B5007 (lexikograficky)
?created=2014-12-24 Zásilky vytvořené na štědrý den v libovolný čas
?deliveryNumber=M89 Fulltextové hledání dle čísla zásilky přepravce
?value=>10000&valueCurrency=CZK Zásilky s hodnotou vyšší než 10 000 Kč
?value[]=>10000&value[]=<20000&valueCurrency=CZK Zásilky s hodnotou v rozmezí 10 000 - 20 000 Kč
?variableSymbol=1234567890,9876543210 Zásilky s variabilním symbolem 1234567890 nebo 9876543210
HTTP Cacheování

V případě, že se opakovaně dotazujete na stejný zdroj se stejným nastavením filtrování i parametru fields, doporučujeme uvádět dříve získaný obsah hlavičky ETag (je součástí odpovědi na všechny GET požadavky) v hlavičce If-None-Match. V takovém případě, pokud nedošlo od Vašeho posledního dotazu k žádné změně zásilky, bude vrácen HTTP kód 304 a nebudou zbytečně přenášena žádná data (tělo odpovědi bude prázdné). Princip je totožný jako u kořenového zdroje.

PATCH /deliveries

Uzavírání zásilek v rámci jednoho svozového místa.

HTTP požadavek:
PATCH /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
Content-type: application/json
                
                    {
    "deliveries": [
        {
            "deliveryId": 275053,
            "closed": true
        }
    ]
}
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Deliveries successfully closed!",
    "data": {
        "collectionOrders": [
            {
                "agent": "GLS",
                "scheduled": "2016-04-22",
                "collectionPlace": "my-identifier"
            }
        ],
        "deliveries": [
            {
                "agent": "GLS",
                "closed": "2016-04-21T15:05:40+02:00",
                "cod": 1200,
                "codCurrency": "CZK",
                "created": "2016-04-21T13:21:08+02:00",
                "deliveryId": 275053,
                "deliveryNumber": "12859588454",
                "deliveryState": 1,
                "deliveryStateName": "Neodeslaná",
                "deliveryType": "BP",
                "externalId": null,
                "extraServices": [
                    {
                        "code": "email_advice_unload",
                        "arguments": {
                            "email": "email@example.com"
                        }
                    },
                    {
                        "code": "sms_advice_unload",
                        "arguments": {
                            "phone": "+420777111000"
                        }
                    },
                    {
                        "code": "cod",
                        "arguments": []
                    }
                ],
                "packages": [
                    {
                        "barcode": "12859588454",
                        "weight": 3.2,
                        "length": 15,
                        "width": 10,
                        "height": 20
                    }
                ],
                "recipient": {
                    "firstname": null,
                    "surname": "Společnost s.r.o.",
                    "contactPerson": null,
                    "phone": "+420777111000",
                    "email": "email@example.com",
                    "type": "address",
                    "address": {
                        "city": "Praha",
                        "street": "Revoluční 11",
                        "postalCode": "11000",
                        "state": "CZ"
                    }
                },
                "sender": {
                    "type": "collectionPlace",
                    "collectionPlace": "my-identifier"
                },
                "source": 3,
                "sourceName": "API",
                "ticketNote": null,
                "value": 2000,
                "valueCurrency": "CZK",
                "variableSymbol": "12345678"
            }
        ]
    }
}
                
HTTP požadavek:
PATCH /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
Content-type: application/xml
                
                    <?xml version="1.0" encoding="UTF-8"?>
<root>
  <deliveries>
    <deliveryId>275053</deliveryId>
    <closed>1</closed>
  </deliveries>
</root>
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Deliveries successfully closed!</message>
  <data>
    <collectionOrders>
      <agent>GLS</agent>
      <scheduled>2016-04-22</scheduled>
      <collectionPlace>my-identifier</collectionPlace>
    </collectionOrders>
    <deliveries>
      <agent>GLS</agent>
      <closed>2016-04-21T15:05:40+02:00</closed>
      <cod>1200</cod>
      <codCurrency>CZK</codCurrency>
      <created>2016-04-21T13:21:08+02:00</created>
      <deliveryId>275053</deliveryId>
      <deliveryNumber>12859588454</deliveryNumber>
      <deliveryState>1</deliveryState>
      <deliveryStateName>Neodeslaná</deliveryStateName>
      <deliveryType>BP</deliveryType>
      <externalId></externalId>
      <extraServices>
        <code>email_advice_unload</code>
        <arguments>
          <email>email@example.com</email>
        </arguments>
      </extraServices>
      <extraServices>
        <code>sms_advice_unload</code>
        <arguments>
          <phone>+420777111000</phone>
        </arguments>
      </extraServices>
      <extraServices>
        <code>cod</code>
      </extraServices>
      <packages>
        <barcode>12859588454</barcode>
        <weight>3,2</weight>
        <length>15</length>
        <width>10</width>
        <height>20</height>
      </packages>
      <recipient>
        <firstname></firstname>
        <surname>Společnost s.r.o.</surname>
        <contactPerson></contactPerson>
        <phone>+420777111000</phone>
        <email>email@example.com</email>
        <type>address</type>
        <address>
          <city>Praha</city>
          <street>Revoluční 11</street>
          <postalCode>11000</postalCode>
          <state>CZ</state>
        </address>
      </recipient>
      <sender>
        <type>collectionPlace</type>
        <collectionPlace>my-identifier</collectionPlace>
      </sender>
      <source>3</source>
      <sourceName>API</sourceName>
      <ticketNote></ticketNote>
      <value>2000</value>
      <valueCurrency>CZK</valueCurrency>
      <variableSymbol>12345678</variableSymbol>
    </deliveries>
  </data>
</root>
                
HTTP požadavek:
PATCH /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
Content-type: application/x-www-form-urlencoded
                
                    deliveries%5B0%5D%5BdeliveryId%5D=275053&deliveries%5B0%5D%5Bclosed%5D=1
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Deliveries+successfully+closed%21&data%5BcollectionOrders%5D%5B0%5D%5Bagent%5D=GLS&data%5BcollectionOrders%5D%5B0%5D%5Bscheduled%5D=2016-04-22&data%5BcollectionOrders%5D%5B0%5D%5BcollectionPlace%5D=my-identifier&data%5Bdeliveries%5D%5B0%5D%5Bagent%5D=GLS&data%5Bdeliveries%5D%5B0%5D%5Bclosed%5D=2016-04-21T15%3A05%3A40%2B02%3A00&data%5Bdeliveries%5D%5B0%5D%5Bcod%5D=1200&data%5Bdeliveries%5D%5B0%5D%5BcodCurrency%5D=CZK&data%5Bdeliveries%5D%5B0%5D%5Bcreated%5D=2016-04-21T13%3A21%3A08%2B02%3A00&data%5Bdeliveries%5D%5B0%5D%5BdeliveryId%5D=275053&data%5Bdeliveries%5D%5B0%5D%5BdeliveryNumber%5D=12859588454&data%5Bdeliveries%5D%5B0%5D%5BdeliveryState%5D=1&data%5Bdeliveries%5D%5B0%5D%5BdeliveryStateName%5D=Neodeslan%C3%A1&data%5Bdeliveries%5D%5B0%5D%5BdeliveryType%5D=BP&data%5Bdeliveries%5D%5B0%5D%5BextraServices%5D%5B0%5D%5Bcode%5D=email_advice_unload&data%5Bdeliveries%5D%5B0%5D%5BextraServices%5D%5B0%5D%5Barguments%5D%5Bemail%5D=email%40example.com&data%5Bdeliveries%5D%5B0%5D%5BextraServices%5D%5B1%5D%5Bcode%5D=sms_advice_unload&data%5Bdeliveries%5D%5B0%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5Bphone%5D=%2B420777111000&data%5Bdeliveries%5D%5B0%5D%5BextraServices%5D%5B2%5D%5Bcode%5D=cod&data%5Bdeliveries%5D%5B0%5D%5Bpackages%5D%5B0%5D%5Bbarcode%5D=12859588454&data%5Bdeliveries%5D%5B0%5D%5Bpackages%5D%5B0%5D%5Bweight%5D=3,2&data%5Bdeliveries%5D%5B0%5D%5Bpackages%5D%5B0%5D%5Blength%5D=15&data%5Bdeliveries%5D%5B0%5D%5Bpackages%5D%5B0%5D%5Bwidth%5D=10&data%5Bdeliveries%5D%5B0%5D%5Bpackages%5D%5B0%5D%5Bheight%5D=20&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Bsurname%5D=Spole%C4%8Dnost+s.r.o.&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Bphone%5D=%2B420777111000&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Bemail%5D=email%40example.com&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Btype%5D=address&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bcity%5D=Praha&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Baddress%5D%5BpostalCode%5D=11000&data%5Bdeliveries%5D%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstate%5D=CZ&data%5Bdeliveries%5D%5B0%5D%5Bsender%5D%5Btype%5D=collectionPlace&data%5Bdeliveries%5D%5B0%5D%5Bsender%5D%5BcollectionPlace%5D=my-identifier&data%5Bdeliveries%5D%5B0%5D%5Bsource%5D=3&data%5Bdeliveries%5D%5B0%5D%5BsourceName%5D=API&data%5Bdeliveries%5D%5B0%5D%5Bvalue%5D=2000&data%5Bdeliveries%5D%5B0%5D%5BvalueCurrency%5D=CZK&data%5Bdeliveries%5D%5B0%5D%5BvariableSymbol%5D=12345678
                
Popis požadavku

Každá zásilka musí obsahovat id zásilky a požadavek o uzavření s kladnou hodnotou true. Tedy klíče deliveryId a closed. Při této akci může na základě nastavení Vašeho účtu dojít k objednání svozu u přepravce.

K URI lze připojit query parametr fields a specifikovat jaká data zásilek se mají objevit v odpovědi stejně jako u metody GET.

Popis odpovědi

Všechny objednané svozy jsou uvedeny v odpovědi a jsou v ní také zahrnuta data všech uzavíraných zásilek včetně doplněných čísel zásilek přepravců viz příklad výše. Struktura výpisu zásilek je totožná jako u odpovědi POST požadavku.

  • collectionOrders.agent je zkratka přepravce, u něhož byl svoz objednán
  • collectionOrders.scheduled je datum objednání svozu ve formátu YYYY-MM-DD, o přesném času svozu budete informováni kurýrem
  • collectionOrders.collectionPlace je identifikátor svozového místa, na jehož adresu byl objednán svoz

Validace a chybové kódy

Uzavírat lze pouze zásilky ze stejného svozového místa a stejného přepravce. Všechny zásilky musejí být neuzavřené a nezrušené. Při této operaci se odesílají data k jednotlivým přepravcům.

V případě nenalezení nějaké zásilky je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Pokud dojde validační chybě (ať již u nás nebo na straně přepravce), je vrácen kód 422.

PUT /deliveries

Úprava neuzavřených zásilek

HTTP požadavek:
PUT /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
Content-type: application/json
                
                    {
    "deliveries": [
        {
            "deliveryId": "16253",
            "variableSymbol": "12345678",
            "cod": 1200,
            "codCurrency": "CZK",
            "value": 2000,
            "valueCurrency": "CZK",
            "packages": [
                {
                    "weight": "3,2",
                    "height": "20",
                    "length": "15",
                    "width": "10"
                }
            ],
            "agent": "GLS",
            "deliveryType": "BP",
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "my-identifier"
            },
            "recipient": {
                "type": "address",
                "surname": "Společnost s.r.o.",
                "phone": "+420 777 111 000",
                "email": "email@example.com",
                "address": {
                    "street": "Revoluční 11",
                    "state": "CZ",
                    "city": "Praha",
                    "postalCode": "11000"
                }
            },
            "extraServices": [
                {
                    "code": "email_advice_unload",
                    "arguments": {
                        "email": "email@example.com"
                    }
                },
                {
                    "code": "sms_advice_unload",
                    "arguments": {
                        "phone": "+420 777 111 000"
                    }
                }
            ]
        }
    ]
}
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Deliveries successfully edited",
    "data": [
        {
            "agent": "GLS",
            "closed": null,
            "cod": 1200,
            "codCurrency": "CZK",
            "created": "2016-04-21T13:21:08+02:00",
            "deliveryId": 275053,
            "deliveryNumber": null,
            "deliveryState": 0,
            "deliveryStateName": "Připravená",
            "deliveryType": "BP",
            "externalId": null,
            "extraServices": [
                {
                    "code": "email_advice_unload",
                    "arguments": {
                        "email": "email@example.com"
                    }
                },
                {
                    "code": "sms_advice_unload",
                    "arguments": {
                        "phone": "+420777111000"
                    }
                },
                {
                    "code": "cod",
                    "arguments": []
                }
            ],
            "packages": [
                {
                    "barcode": null,
                    "weight": 3.2,
                    "length": 15,
                    "width": 10,
                    "height": 20
                }
            ],
            "recipient": {
                "firstname": null,
                "surname": "Společnost s.r.o.",
                "contactPerson": null,
                "phone": "+420777111000",
                "email": "email@example.com",
                "address": {
                    "city": "Praha",
                    "street": "Revoluční 11",
                    "postalCode": "11000",
                    "state": "CZ"
                }
            },
            "sender": {
                "firstname": "Ondřej",
                "surname": "Kypr",
                "contactPerson": null,
                "phone": "721000892",
                "email": "joecipra@gmail.com",
                "address": {
                    "city": "Vyškov",
                    "street": "Dobrovského 409/1",
                    "postalCode": "68201",
                    "state": "CZ"
                }
            },
            "source": 3,
            "sourceName": "API",
            "ticketNote": null,
            "value": 2000,
            "valueCurrency": "CZK",
            "variableSymbol": "12345678"
        }
    ]
}
                
HTTP požadavek:
PUT /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
Content-type: application/xml
                
                    <?xml version="1.0" encoding="UTF-8"?>
<root>
  <deliveries>
    <deliveryId>16253</deliveryId>
    <variableSymbol>12345678</variableSymbol>
    <cod>1200</cod>
    <codCurrency>CZK</codCurrency>
    <value>2000</value>
    <valueCurrency>CZK</valueCurrency>
    <packages>
      <weight>3,2</weight>
      <height>20</height>
      <length>15</length>
      <width>10</width>
    </packages>
    <agent>GLS</agent>
    <deliveryType>BP</deliveryType>
    <sender>
      <type>collectionPlace</type>
      <collectionPlace>my-identifier</collectionPlace>
    </sender>
    <recipient>
      <type>address</type>
      <surname>Společnost s.r.o.</surname>
      <phone>+420 777 111 000</phone>
      <email>email@example.com</email>
      <address>
        <street>Revoluční 11</street>
        <state>CZ</state>
        <city>Praha</city>
        <postalCode>11000</postalCode>
      </address>
    </recipient>
    <extraServices>
      <code>email_advice_unload</code>
      <arguments>
        <email>email@example.com</email>
      </arguments>
    </extraServices>
    <extraServices>
      <code>sms_advice_unload</code>
      <arguments>
        <phone>+420 777 111 000</phone>
      </arguments>
    </extraServices>
  </deliveries>
</root>
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Deliveries successfully edited</message>
  <data>
    <agent>GLS</agent>
    <closed></closed>
    <cod>1200</cod>
    <codCurrency>CZK</codCurrency>
    <created>2016-04-21T13:21:08+02:00</created>
    <deliveryId>275053</deliveryId>
    <deliveryNumber></deliveryNumber>
    <deliveryState>0</deliveryState>
    <deliveryStateName>Připravená</deliveryStateName>
    <deliveryType>BP</deliveryType>
    <externalId></externalId>
    <extraServices>
      <code>email_advice_unload</code>
      <arguments>
        <email>email@example.com</email>
      </arguments>
    </extraServices>
    <extraServices>
      <code>sms_advice_unload</code>
      <arguments>
        <phone>+420777111000</phone>
      </arguments>
    </extraServices>
    <extraServices>
      <code>cod</code>
    </extraServices>
    <packages>
      <barcode></barcode>
      <weight>3,2</weight>
      <length>15</length>
      <width>10</width>
      <height>20</height>
    </packages>
    <recipient>
      <firstname></firstname>
      <surname>Společnost s.r.o.</surname>
      <contactPerson></contactPerson>
      <phone>+420777111000</phone>
      <email>email@example.com</email>
      <address>
        <city>Praha</city>
        <street>Revoluční 11</street>
        <postalCode>11000</postalCode>
        <state>CZ</state>
      </address>
    </recipient>
    <sender>
      <firstname>Ondřej</firstname>
      <surname>Kypr</surname>
      <contactPerson></contactPerson>
      <phone>721000892</phone>
      <email>joecipra@gmail.com</email>
      <address>
        <city>Vyškov</city>
        <street>Dobrovského 409/1</street>
        <postalCode>68201</postalCode>
        <state>CZ</state>
      </address>
    </sender>
    <source>3</source>
    <sourceName>API</sourceName>
    <ticketNote></ticketNote>
    <value>2000</value>
    <valueCurrency>CZK</valueCurrency>
    <variableSymbol>12345678</variableSymbol>
  </data>
</root>
                
HTTP požadavek:
PUT /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
Content-type: application/x-www-form-urlencoded
                
                    deliveries%5B0%5D%5BdeliveryId%5D=16253&deliveries%5B0%5D%5BvariableSymbol%5D=12345678&deliveries%5B0%5D%5Bcod%5D=1200&deliveries%5B0%5D%5BcodCurrency%5D=CZK&deliveries%5B0%5D%5Bvalue%5D=2000&deliveries%5B0%5D%5BvalueCurrency%5D=CZK&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bweight%5D=3%2C2&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bheight%5D=20&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Blength%5D=15&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bwidth%5D=10&deliveries%5B0%5D%5Bagent%5D=GLS&deliveries%5B0%5D%5BdeliveryType%5D=BP&deliveries%5B0%5D%5Bsender%5D%5Btype%5D=collectionPlace&deliveries%5B0%5D%5Bsender%5D%5BcollectionPlace%5D=my-identifier&deliveries%5B0%5D%5Brecipient%5D%5Btype%5D=address&deliveries%5B0%5D%5Brecipient%5D%5Bsurname%5D=Spole%C4%8Dnost+s.r.o.&deliveries%5B0%5D%5Brecipient%5D%5Bphone%5D=%2B420+777+111+000&deliveries%5B0%5D%5Brecipient%5D%5Bemail%5D=email%40example.com&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstate%5D=CZ&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bcity%5D=Praha&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5BpostalCode%5D=11000&deliveries%5B0%5D%5BextraServices%5D%5B0%5D%5Bcode%5D=email_advice_unload&deliveries%5B0%5D%5BextraServices%5D%5B0%5D%5Barguments%5D%5Bemail%5D=email%40example.com&deliveries%5B0%5D%5BextraServices%5D%5B1%5D%5Bcode%5D=sms_advice_unload&deliveries%5B0%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5Bphone%5D=%2B420+777+111+000
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Deliveries+successfully+edited&data%5B0%5D%5Bagent%5D=GLS&data%5B0%5D%5Bcod%5D=1200&data%5B0%5D%5BcodCurrency%5D=CZK&data%5B0%5D%5Bcreated%5D=2016-04-21T13%3A21%3A08%2B02%3A00&data%5B0%5D%5BdeliveryId%5D=275053&data%5B0%5D%5BdeliveryState%5D=0&data%5B0%5D%5BdeliveryStateName%5D=P%C5%99ipraven%C3%A1&data%5B0%5D%5BdeliveryType%5D=BP&data%5B0%5D%5BextraServices%5D%5B0%5D%5Bcode%5D=email_advice_unload&data%5B0%5D%5BextraServices%5D%5B0%5D%5Barguments%5D%5Bemail%5D=email%40example.com&data%5B0%5D%5BextraServices%5D%5B1%5D%5Bcode%5D=sms_advice_unload&data%5B0%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5Bphone%5D=%2B420777111000&data%5B0%5D%5BextraServices%5D%5B2%5D%5Bcode%5D=cod&data%5B0%5D%5Bpackages%5D%5B0%5D%5Bweight%5D=3,2&data%5B0%5D%5Bpackages%5D%5B0%5D%5Blength%5D=15&data%5B0%5D%5Bpackages%5D%5B0%5D%5Bwidth%5D=10&data%5B0%5D%5Bpackages%5D%5B0%5D%5Bheight%5D=20&data%5B0%5D%5Brecipient%5D%5Bsurname%5D=Spole%C4%8Dnost+s.r.o.&data%5B0%5D%5Brecipient%5D%5Bphone%5D=%2B420777111000&data%5B0%5D%5Brecipient%5D%5Bemail%5D=email%40example.com&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bcity%5D=Praha&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5BpostalCode%5D=11000&data%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstate%5D=CZ&data%5B0%5D%5Bsender%5D%5Bfirstname%5D=Ond%C5%99ej&data%5B0%5D%5Bsender%5D%5Bsurname%5D=Kypr&data%5B0%5D%5Bsender%5D%5Bphone%5D=721000892&data%5B0%5D%5Bsender%5D%5Bemail%5D=joecipra%40gmail.com&data%5B0%5D%5Bsender%5D%5Baddress%5D%5Bcity%5D=Vy%C5%A1kov&data%5B0%5D%5Bsender%5D%5Baddress%5D%5Bstreet%5D=Dobrovsk%C3%A9ho+409%2F1&data%5B0%5D%5Bsender%5D%5Baddress%5D%5BpostalCode%5D=68201&data%5B0%5D%5Bsender%5D%5Baddress%5D%5Bstate%5D=CZ&data%5B0%5D%5Bsource%5D=3&data%5B0%5D%5BsourceName%5D=API&data%5B0%5D%5Bvalue%5D=2000&data%5B0%5D%5BvalueCurrency%5D=CZK&data%5B0%5D%5BvariableSymbol%5D=12345678
                
Popis požadavku

V požadavku je nutné vyplnit všechny povinné údaje zásilky jako u POST metody a přidat klíč deliveryId.

K URI lze připojit query parametr fields a specifikovat jaká data zásilek se mají objevit v odpovědi stejně jako u metody GET.

Validace a chybové kódy

Validace je totožná jako u metody POST s tím, že se ještě validuje klíč deliveryId. Validační chyby jsou označeny HTTP kódem 422. Odpověď má stejnou strukturu jako u vkládání zásilek. Nelze upravovat uzavřené a zrušené zásilky.

Popis odpovědi

V poli data jsou totožné údaje jako u POST metody. V případě, že uvedete v hlavičce If-Match hodnotu ETagu pro editované zásilky a v došlo ke změně dat zásilky od doby získání daného ETagu, úprava nebude provedena a bude vrácen HTTP kód 412. Díky tomuto mechanizmu je možné kontrolovat neočekávané změny zásilek na straně webové aplikace. Pro správné fungování je třeba použít ETag získaný pro všechna data zásilky či zásilek (ETag byl získán GET požadavkem bez query parametru fields).

DELETE /deliveries

Rušení neuzavřených zásilek.

HTTP požadavek:
DELETE /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
Content-type: application/json
                
                    {
    "deliveries": [
        {
            "deliveryId": 10441
        },
        {
            "deliveryId": 10442
        }
    ]
}
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Deliveries successfully canceled"
}
                
HTTP požadavek:
DELETE /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
Content-type: application/xml
                
                    <?xml version="1.0" encoding="UTF-8"?>
<root>
  <deliveries>
    <deliveryId>10441</deliveryId>
  </deliveries>
  <deliveries>
    <deliveryId>10442</deliveryId>
  </deliveries>
</root>
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Deliveries successfully canceled</message>
</root>
                
HTTP požadavek:
DELETE /api/v3/deliveries HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
Content-type: application/x-www-form-urlencoded
                
                    deliveries%5B0%5D%5BdeliveryId%5D=10441&deliveries%5B1%5D%5BdeliveryId%5D=10442
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Deliveries+successfully+canceled
                
Popis požadavku

Každá zásilka musí obsahovat id zásilky dle příkladu výše. Lze rušit pouze neuzavřené a nezrušené zásilky.

Validace a chybové kódy

V případě validační chyby je vrácen kód 422.

/transports

Popis zdroje Vyhledávání možných přeprav včetně cen a doplňkových služeb.
Úplná adresa zdroje https://balikonos.cz/api/v3/transports
OAuth 2.0 scope transports
Podporované HTTP metody GET

GET /transports

Vyhledávání přeprav reflektující první a druhý krok manuálního zadávání zásilek v klientské zóně.

HTTP požadavek:
GET /api/v3/transports HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
Content-type: application/json
                
                    {
    "deliveries": [
        {
            "cod": 1200,
            "codCurrency": "CZK",
            "value": 2000,
            "valueCurrency": "CZK",
            "packages": [
                {
                    "weight": "3,2",
                    "height": "20",
                    "length": "15",
                    "width": "10"
                }
            ],
            "sender": {
                "type": "collectionPlace",
                "collectionPlace": "my-identifier"
            },
            "recipient": {
                "type": "address",
                "address": {
                    "street": "Revoluční 11",
                    "state": "CZ",
                    "city": "Praha",
                    "postalCode": "11000"
                }
            }
        }
    ]
}
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Transports successfully found",
    "data": [
        {
            "delivery": 0,
            "transports": [
                {
                    "agent": {
                        "code": "PPL",
                        "name": "PPL"
                    },
                    "deliveryType": {
                        "code": "FB",
                        "name": "Firemní balík",
                        "phoneRequired": false,
                        "dimensionsRequired": false
                    },
                    "deliveryTime": {
                        "pickUpFrom": "2016-11-28T08:00:00+01:00",
                        "pickUpTo": "2016-11-28T18:00:00+01:00",
                        "minDeliveryFrom": "2016-11-29T08:00:00+01:00",
                        "minDeliveryTo": "2016-11-29T18:00:00+01:00",
                        "maxDeliveryFrom": "2016-11-29T08:00:00+01:00",
                        "maxDeliveryTo": "2016-11-29T18:00:00+01:00"
                    },
                    "insurance": {
                        "description": "50 000 CZK"
                    },
                    "extraServices": []
                },
                {
                    "agent": {
                        "code": "GLS",
                        "name": "GLS"
                    },
                    "deliveryType": {
                        "code": "BP",
                        "name": "Business-Parcel",
                        "phoneRequired": false,
                        "dimensionsRequired": false
                    },
                    "deliveryTime": {
                        "pickUpFrom": "2016-11-28T08:00:00+01:00",
                        "pickUpTo": "2016-11-28T17:00:00+01:00",
                        "minDeliveryFrom": "2016-11-29T08:00:00+01:00",
                        "minDeliveryTo": "2016-11-29T17:00:00+01:00",
                        "maxDeliveryFrom": "2016-11-29T08:00:00+01:00",
                        "maxDeliveryTo": "2016-11-29T17:00:00+01:00"
                    },
                    "insurance": {
                        "description": "50 000 CZK/balík"
                    },
                    "extraServices": [
                        {
                            "code": "direct_delivery",
                            "name": "Přímá zásilka",
                            "description": "Vyzvednutí balíku na vybrané adrese a doručení na libovolnou adresu.",
                            "implicit": true,
                            "bans": [
                                "guaranteed_24",
                                "addressee_only",
                                "day_definite",
                                "back_delivery",
                                "sms_service"
                            ],
                            "arguments": [],
                            "price": {
                                "total": 2,
                                "currency": "CZK"
                            }
                        },
                        {
                            "code": "sms_advice_unload",
                            "name": "SMS avízo před doručením",
                            "description": "SMS avizace před doručením zásilky.",
                            "implicit": false,
                            "bans": [
                                "back_delivery"
                            ],
                            "arguments": [
                                {
                                    "name": "Telefon",
                                    "identifier": "phone",
                                    "example": "+420777111000"
                                }
                            ],
                            "price": {
                                "total": 2,
                                "currency": "CZK"
                            }
                        },
                        {
                            "code": "email_advice_unload",
                            "name": "Email avízo před doručením",
                            "description": "Email avizace před doručením zásilky.",
                            "implicit": false,
                            "bans": [
                                "day_definite",
                                "back_delivery"
                            ],
                            "arguments": [
                                {
                                    "name": "Email",
                                    "identifier": "email",
                                    "example": "example@example.com"
                                }
                            ],
                            "price": {
                                "total": 0,
                                "currency": "CZK"
                            }
                        }
                    ],
                    "price": {
                        "base": 78,
                        "total": 80.16,
                        "currency": "CZK",
                        "fees": [
                            {
                                "categoryName": "Mýtný",
                                "category": 1,
                                "fee": 2.16
                            }
                        ]
                    }
                }
            ]
        }
    ]
}
                
HTTP požadavek:
GET /api/v3/transports HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
Content-type: application/xml
                
                    <?xml version="1.0" encoding="UTF-8"?>
<root>
  <deliveries>
    <cod>1200</cod>
    <codCurrency>CZK</codCurrency>
    <value>2000</value>
    <valueCurrency>CZK</valueCurrency>
    <packages>
      <weight>3,2</weight>
      <height>20</height>
      <length>15</length>
      <width>10</width>
    </packages>
    <sender>
      <type>collectionPlace</type>
      <collectionPlace>my-identifier</collectionPlace>
    </sender>
    <recipient>
      <type>address</type>
      <address>
        <street>Revoluční 11</street>
        <state>CZ</state>
        <city>Praha</city>
        <postalCode>11000</postalCode>
      </address>
    </recipient>
  </deliveries>
</root>
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Transports successfully found</message>
  <data>
    <delivery>0</delivery>
    <transports>
      <agent>
        <code>PPL</code>
        <name>PPL</name>
      </agent>
      <deliveryType>
        <code>FB</code>
        <name>Firemní balík</name>
        <phoneRequired></phoneRequired>
        <dimensionsRequired></dimensionsRequired>
      </deliveryType>
      <deliveryTime>
        <pickUpFrom>2016-11-28T08:00:00+01:00</pickUpFrom>
        <pickUpTo>2016-11-28T18:00:00+01:00</pickUpTo>
        <minDeliveryFrom>2016-11-29T08:00:00+01:00</minDeliveryFrom>
        <minDeliveryTo>2016-11-29T18:00:00+01:00</minDeliveryTo>
        <maxDeliveryFrom>2016-11-29T08:00:00+01:00</maxDeliveryFrom>
        <maxDeliveryTo>2016-11-29T18:00:00+01:00</maxDeliveryTo>
      </deliveryTime>
      <insurance>
        <description>50 000 CZK</description>
      </insurance>
    </transports>
    <transports>
      <agent>
        <code>GLS</code>
        <name>GLS</name>
      </agent>
      <deliveryType>
        <code>BP</code>
        <name>Business-Parcel</name>
        <phoneRequired></phoneRequired>
        <dimensionsRequired></dimensionsRequired>
      </deliveryType>
      <deliveryTime>
        <pickUpFrom>2016-11-28T08:00:00+01:00</pickUpFrom>
        <pickUpTo>2016-11-28T17:00:00+01:00</pickUpTo>
        <minDeliveryFrom>2016-11-29T08:00:00+01:00</minDeliveryFrom>
        <minDeliveryTo>2016-11-29T17:00:00+01:00</minDeliveryTo>
        <maxDeliveryFrom>2016-11-29T08:00:00+01:00</maxDeliveryFrom>
        <maxDeliveryTo>2016-11-29T17:00:00+01:00</maxDeliveryTo>
      </deliveryTime>
      <insurance>
        <description>50 000 CZK/balík</description>
      </insurance>
      <extraServices>
        <code>direct_delivery</code>
        <name>Přímá zásilka</name>
        <description>Vyzvednutí balíku na vybrané adrese a doručení na libovolnou adresu.</description>
        <implicit>1</implicit>
        <bans>guaranteed_24</bans>
        <bans>addressee_only</bans>
        <bans>day_definite</bans>
        <bans>back_delivery</bans>
        <bans>sms_service</bans>
        <price>
          <total>2</total>
          <currency>CZK</currency>
        </price>
      </extraServices>
      <extraServices>
        <code>sms_advice_unload</code>
        <name>SMS avízo před doručením</name>
        <description>SMS avizace před doručením zásilky.</description>
        <implicit></implicit>
        <bans>back_delivery</bans>
        <arguments>
          <name>Telefon</name>
          <identifier>phone</identifier>
          <example>+420777111000</example>
        </arguments>
        <price>
          <total>2</total>
          <currency>CZK</currency>
        </price>
      </extraServices>
      <extraServices>
        <code>email_advice_unload</code>
        <name>Email avízo před doručením</name>
        <description>Email avizace před doručením zásilky.</description>
        <implicit></implicit>
        <bans>day_definite</bans>
        <bans>back_delivery</bans>
        <arguments>
          <name>Email</name>
          <identifier>email</identifier>
          <example>example@example.com</example>
        </arguments>
        <price>
          <total>0</total>
          <currency>CZK</currency>
        </price>
      </extraServices>
      <price>
        <base>78</base>
        <total>80,16</total>
        <currency>CZK</currency>
        <fees>
          <categoryName>Mýtný</categoryName>
          <category>1</category>
          <fee>2,16</fee>
        </fees>
      </price>
    </transports>
  </data>
</root>
                
HTTP požadavek:
GET /api/v3/transports HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
Content-type: application/x-www-form-urlencoded
                
                    deliveries%5B0%5D%5Bcod%5D=1200&deliveries%5B0%5D%5BcodCurrency%5D=CZK&deliveries%5B0%5D%5Bvalue%5D=2000&deliveries%5B0%5D%5BvalueCurrency%5D=CZK&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bweight%5D=3%2C2&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bheight%5D=20&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Blength%5D=15&deliveries%5B0%5D%5Bpackages%5D%5B0%5D%5Bwidth%5D=10&deliveries%5B0%5D%5Bsender%5D%5Btype%5D=collectionPlace&deliveries%5B0%5D%5Bsender%5D%5BcollectionPlace%5D=my-identifier&deliveries%5B0%5D%5Brecipient%5D%5Btype%5D=address&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bstate%5D=CZ&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5Bcity%5D=Praha&deliveries%5B0%5D%5Brecipient%5D%5Baddress%5D%5BpostalCode%5D=11000
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Transports+successfully+found&data%5B0%5D%5Bdelivery%5D=0&data%5B0%5D%5Btransports%5D%5B0%5D%5Bagent%5D%5Bcode%5D=PPL&data%5B0%5D%5Btransports%5D%5B0%5D%5Bagent%5D%5Bname%5D=PPL&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryType%5D%5Bcode%5D=FB&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryType%5D%5Bname%5D=Firemn%C3%AD+bal%C3%ADk&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryType%5D%5BphoneRequired%5D=0&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryType%5D%5BdimensionsRequired%5D=0&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryTime%5D%5BpickUpFrom%5D=2016-11-28T08%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryTime%5D%5BpickUpTo%5D=2016-11-28T18%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryTime%5D%5BminDeliveryFrom%5D=2016-11-29T08%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryTime%5D%5BminDeliveryTo%5D=2016-11-29T18%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryTime%5D%5BmaxDeliveryFrom%5D=2016-11-29T08%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B0%5D%5BdeliveryTime%5D%5BmaxDeliveryTo%5D=2016-11-29T18%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B0%5D%5Binsurance%5D%5Bdescription%5D=50+000+CZK&data%5B0%5D%5Btransports%5D%5B1%5D%5Bagent%5D%5Bcode%5D=GLS&data%5B0%5D%5Btransports%5D%5B1%5D%5Bagent%5D%5Bname%5D=GLS&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryType%5D%5Bcode%5D=BP&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryType%5D%5Bname%5D=Business-Parcel&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryType%5D%5BphoneRequired%5D=0&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryType%5D%5BdimensionsRequired%5D=0&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryTime%5D%5BpickUpFrom%5D=2016-11-28T08%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryTime%5D%5BpickUpTo%5D=2016-11-28T17%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryTime%5D%5BminDeliveryFrom%5D=2016-11-29T08%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryTime%5D%5BminDeliveryTo%5D=2016-11-29T17%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryTime%5D%5BmaxDeliveryFrom%5D=2016-11-29T08%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B1%5D%5BdeliveryTime%5D%5BmaxDeliveryTo%5D=2016-11-29T17%3A00%3A00%2B01%3A00&data%5B0%5D%5Btransports%5D%5B1%5D%5Binsurance%5D%5Bdescription%5D=50+000+CZK%2Fbal%C3%ADk&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bcode%5D=direct_delivery&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bname%5D=P%C5%99%C3%ADm%C3%A1+z%C3%A1silka&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bdescription%5D=Vyzvednut%C3%AD+bal%C3%ADku+na+vybran%C3%A9+adrese+a+doru%C4%8Den%C3%AD+na+libovolnou+adresu.&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bimplicit%5D=1&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bbans%5D%5B0%5D=guaranteed_24&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bbans%5D%5B1%5D=addressee_only&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bbans%5D%5B2%5D=day_definite&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bbans%5D%5B3%5D=back_delivery&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bbans%5D%5B4%5D=sms_service&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bprice%5D%5Btotal%5D=2&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B0%5D%5Bprice%5D%5Bcurrency%5D=CZK&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bcode%5D=sms_advice_unload&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bname%5D=SMS+av%C3%ADzo+p%C5%99ed+doru%C4%8Den%C3%ADm&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bdescription%5D=SMS+avizace+p%C5%99ed+doru%C4%8Den%C3%ADm+z%C3%A1silky.&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bimplicit%5D=0&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bbans%5D%5B0%5D=back_delivery&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5B0%5D%5Bname%5D=Telefon&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5B0%5D%5Bidentifier%5D=phone&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Barguments%5D%5B0%5D%5Bexample%5D=%2B420777111000&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bprice%5D%5Btotal%5D=2&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B1%5D%5Bprice%5D%5Bcurrency%5D=CZK&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bcode%5D=email_advice_unload&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bname%5D=Email+av%C3%ADzo+p%C5%99ed+doru%C4%8Den%C3%ADm&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bdescription%5D=Email+avizace+p%C5%99ed+doru%C4%8Den%C3%ADm+z%C3%A1silky.&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bimplicit%5D=0&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bbans%5D%5B0%5D=day_definite&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bbans%5D%5B1%5D=back_delivery&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Barguments%5D%5B0%5D%5Bname%5D=Email&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Barguments%5D%5B0%5D%5Bidentifier%5D=email&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Barguments%5D%5B0%5D%5Bexample%5D=example%40example.com&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bprice%5D%5Btotal%5D=0&data%5B0%5D%5Btransports%5D%5B1%5D%5BextraServices%5D%5B2%5D%5Bprice%5D%5Bcurrency%5D=CZK&data%5B0%5D%5Btransports%5D%5B1%5D%5Bprice%5D%5Bbase%5D=78&data%5B0%5D%5Btransports%5D%5B1%5D%5Bprice%5D%5Btotal%5D=80,16&data%5B0%5D%5Btransports%5D%5B1%5D%5Bprice%5D%5Bcurrency%5D=CZK&data%5B0%5D%5Btransports%5D%5B1%5D%5Bprice%5D%5Bfees%5D%5B0%5D%5BcategoryName%5D=M%C3%BDtn%C3%BD&data%5B0%5D%5Btransports%5D%5B1%5D%5Bprice%5D%5Bfees%5D%5B0%5D%5Bcategory%5D=1&data%5B0%5D%5Btransports%5D%5B1%5D%5Bprice%5D%5Bfees%5D%5B0%5D%5Bfee%5D=2,16
                
Popis požadavku

Struktura požadavku je shodná s vkládáním zásilek s několika málo rozdíly: není nutné vyplňovat pole agent, deliveryType, extraServices, variableSymbol, osobní údaje příjemce a odesílatele, ticketNote a externalId. Vždy je však nutné uvádět rozměry balíků.

Pokud má Váš klient problémy s posíláním HTTP body pro GET požadavek (například POSTman), můžete využít POST s hlavičkou X-HTTP-Method-Override: GET.

Popis odpovědi

Klíč Typ Komentář
delivery int index zásilky z požadavku pro které se vypisují přepravy, začíná nulou
transports array pole možných přeprav
transports.agent array pole údajů o přepravci
transports.agent.code string zkratka přepravce, používá se při vkládání zásilek
transports.agent.name string název přepravce
transports.deliveryType.code string zkratka typu zásilky, používá se při vkládání zásilek
transports.deliveryType.name string název typu zásilky
transports.deliveryType.phoneRequired bool je pro tento typ zásilky při vkládání zásilky vyžadován telefon příjemce?
transports.deliveryType.dimensionsRequired bool jsou pro tento typ zásilky při vkládání zásilky vyžadovány rozměry balíků?
transports.deliveryTime array pole údajů o časových možnostech vyzvednutí a doručení
transports.deliveryTime.pickUpFrom datetime|null počátek intervalu pro nejbližší vyzvednutí
transports.deliveryTime.pickUpTo datetime|null konec intervalu pro nejbližší vyzvednutí
transports.deliveryTime.minDeliveryFrom datetime|null počátek intervalu pro nejbližší doručení
transports.deliveryTime.minDeliveryTo datetime konec intervalu pro nejbližší doručení
transports.deliveryTime.maxDeliveryFrom datetime|null počátek intervalu pro nejpozdější doručení
transports.deliveryTime.maxDeliveryTo datetime|null konec intervalu pro nejpozdější doručení
transports.insurance.description string popis zahrnutého pojištění
transports.extraServices array pole možných doplňkových služeb
transports.extraServices.code string zkratka doplňkové služby, využívá se při vkládání zásilek
transports.extraServices.name string název doplňkové služby
transports.extraServices.description string popis doplňkové služby
transports.extraServices.implicit bool je doplňková služba automaticky zahrnuta v přepravě?*
transports.extraServices.bans string[] pole zkratek doplňkových služeb, se kterými tato nejde kombinovat
transports.extraServices.arguments array pole argumentů vyžadovaných touto doplňkovou službou
transports.extraServices.arguments.name string název argumentu
transports.extraServices.arguments.identifier string identifikátor argumentu, využívá se při vkládání zásilek
transports.extraServices.arguments.example string příklad hodnoty argumentu
transports.extraServices.price array pole údajů o ceně doplňkové služby, celý element chybí pro neplacenou službu
transports.extraServices.price.total float cena doplňkové služby
transports.extraServices.price.currency string měna ceny doplňkové služby
transports.price array pole údajů o ceně přepravy, celý element chybí pro neplacenou službu
transports.price.base float základ ceny přepravy bez poplatků a doplň. služeb
transports.price.total float plná ceny přepravy bez doplň. služeb
transports.price.currency string měna ceny přepravy
transports.price.fees array pole poplatků
transports.price.fees.categoryName string kategorie poplatku
transports.price.fees.category int id kategorie poplatku
transports.price.fees.fee float výše poplatku

* Pro výpočet finální ceny je tedy nutné k hodnotě transports.price.total připočíst ceny všech implicitních doplňkových služeb. Implicitními doplňkovými službami může být zpětná zásilka, přímá zásilka a dobírka. Informace o tom, kdy je implicitně zahrnuta přímá nebo zpětná zásilka jsou popsány v sekci o typech příjemce a odesílatele.

Validace a chybové kódy

Validace se shoduje s vkládáním zásilek, validační chyby jsou tradičně indikovány kódem 422.

/deliveries/tickets

Popis zdroje Vygenerování štítků k několika zásilkám od stejného přepravce s volbou počáteční pozice
Úplná adresa zdroje https://balikonos.cz/api/v3/deliveries/tickets
OAuth 2.0 scope deliveries
Podporované HTTP metody GET

GET /deliveries/tickets

Vygenerování štítků do PDF souboru.

HTTP požadavek:
GET /api/v3/deliveries/tickets?deliveryId=10441,10442&position=2&printFormat=default HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Tickets successfully generated",
    "data": [
        {
            "created": "2014-06-11T14:21:31+02:00",
            "size": 68,
            "contents": "JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4="
        }
    ]
}
                
HTTP požadavek:
GET /api/v3/deliveries/tickets?deliveryId=10441,10442&position=2&printFormat=default HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Tickets successfully generated</message>
  <data>
    <created>2014-06-11T14:21:31+02:00</created>
    <size>68</size>
    <contents>JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=</contents>
  </data>
</root>
                
HTTP požadavek:
GET /api/v3/deliveries/tickets?deliveryId=10441,10442&position=2&printFormat=default HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Tickets+successfully+generated&data%5B0%5D%5Bcreated%5D=2014-06-11T14%3A21%3A31%2B02%3A00&data%5B0%5D%5Bsize%5D=68&data%5B0%5D%5Bcontents%5D=JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10%2BPl0%2BPj4%2BPj4%3D
                
Popis požadavku

Štítky lze generovat na Vámi definované pozice na A4, výchozí je první pozice na stránce. Požadované zásilky definujte query parameterem deliveryId podobně jako při získávání zásilek, tedy více čísel oddělte čárkou. Počáteční pozice prvního štítku je určena volitelným query parametrem position. Tento parametr může nabývat hodnot od jedné do maxima dle daného přepravce:

  • Intime - maximální pozice je 8
  • Česká pošta - maximální pozice je 4
  • PPL - maximální pozice je 4
  • GLS - maximální pozice je 4
  • Zásilkovna - maximální pozice je 4
  • Uloženka - maximální pozice je 4

Dalším volitelným parametrem je printFormat. Možné hodnoty jsou:

  • default - tisk na formát A4 (výchozí hodnota při neuvedení parametru)
  • single - tisk štítků na kotouč, tedy formát o velikosti štítku
Popis odpovědi

Jako všechny odpovědi, i tato respektuje požadovaný formát dle hlavičky Accept. Binární data vygenerovaného PDF souboru jsou vrácena ve formátu base64 dle specifikace MIME. Ve vaší aplikaci je tedy nutné před uložením souboru dekódovat obsah zpět do binárních dat. Ve většině jazyků toto není problém, viz PHP a Java. V odpovědi naleznete ještě datum vytvoření PDF souboru a jeho originální velikost:

  • created - je datum vytvoření PDF souboru
  • size - určuje velikost souboru v bytech před zakódováním do base64
  • contents - obsah PDF souboru ve formátu base64 MIME

Mějte na paměti, že generování velkých PDF souborů je časově náročná operace a celkové zpracování může trvat několik vteřin.

Validace a chybové kódy

Štítky lze generovat pouze pro uzavřené zásilky. V případě nenalezení některé ze zásilek je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Ostatní validační chyby, například pokus o tisk neuzavřené zásilky, jsou indikovány kódem 422. Nelze tisknout štítky pro zásilky s doplňkovou službou "Zpětná zásilka". Není možné generovat štítky pro několik přepravců najednou, jelikož každý z nich má jiné štítky.

/deliveries/zpl

Popis zdroje Získání ZPL štítků k několika zásilkám od stejného přepravce
Úplná adresa zdroje https://balikonos.cz/api/v3/deliveries/zpl
OAuth 2.0 scope deliveries
Podporované HTTP metody GET

GET /deliveries/zpl

Získání štítků ve formátu ZPL.

HTTP požadavek:
GET /api/v3/deliveries/zpl?deliveryId=10441,10442&size=10x17 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "ZPL tickets successfully retrieved",
    "data": [
        {
            "deliveryId": 10441,
            "zplCodes": [
                "\n^XA\n^LH20,20^MD16\n ... code for 1st colli ...",
                "\n^XA\n^LH20,20^MD16\n ... code for 2nd colli ..."
            ]
        },
        {
            "deliveryId": 10442,
            "zplCodes": [
                "\n^XA\n^LH20,20^MD16\n ... code ...\n"
            ]
        }
    ]
}
                
HTTP požadavek:
GET /api/v3/deliveries/zpl?deliveryId=10441,10442&size=10x17 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>ZPL tickets successfully retrieved</message>
  <data>
    <deliveryId>10441</deliveryId>
    <zplCodes>
^XA
^LH20,20^MD16
 ... code for 1st colli ...</zplCodes>
    <zplCodes>
^XA
^LH20,20^MD16
 ... code for 2nd colli ...</zplCodes>
  </data>
  <data>
    <deliveryId>10442</deliveryId>
    <zplCodes>
^XA
^LH20,20^MD16
 ... code ...
</zplCodes>
  </data>
</root>
                
HTTP požadavek:
GET /api/v3/deliveries/zpl?deliveryId=10441,10442&size=10x17 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=ZPL+tickets+successfully+retrieved&data%5B0%5D%5BdeliveryId%5D=10441&data%5B0%5D%5BzplCodes%5D%5B0%5D=%0A%5EXA%0A%5ELH20%2C20%5EMD16%0A+...+code+for+1st+colli+...&data%5B0%5D%5BzplCodes%5D%5B1%5D=%0A%5EXA%0A%5ELH20%2C20%5EMD16%0A+...+code+for+2nd+colli+...&data%5B1%5D%5BdeliveryId%5D=10442&data%5B1%5D%5BzplCodes%5D%5B0%5D=%0A%5EXA%0A%5ELH20%2C20%5EMD16%0A+...+code+...%0A
                
Popis požadavku

Požadované zásilky definujte query parameterem deliveryId podobně jako při získávání zásilek, tedy více čísel oddělte čárkou. Generovat štítky lze pouze pro přepravce níže. Velikost štítku (v cm, 300 dpi) definujte parametrem size, kde možné hodnoty jsou následující:

  • Česká pošta: 10x17(výchozí)
  • GLS: 10x5(výchozí), 10x17
  • Intime: 8x5(výchozí)
  • Zásilkovna: 10x17(výchozí)
Popis odpovědi

Odpověď obsahuje data všech štítků k požadovaným zásilkám. V případě, že zásilka je vícekusá, naleznete v odpovědi štítky pro každý kus.

Validace a chybové kódy

Štítky lze generovat pouze pro uzavřené zásilky. V případě nenalezení některé ze zásilek nebo štítku ZPL je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Ostatní validační chyby, například pokus o tisk neuzavřené zásilky, jsou indikovány kódem 422.

/deliveries/traces

Popis zdroje Získání detailních stavů k vybraným zásilkám.
Úplná adresa zdroje https://balikonos.cz/api/v3/deliveries/traces
OAuth 2.0 scope deliveries
Podporované HTTP metody GET

GET /deliveries/traces

Track and trace k vybraným zásilkám.

HTTP požadavek:
GET /api/v3/deliveries/traces?deliveryId=10441,10442 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Traces successfully retrieved",
    "data": [
        {
            "deliveryId": 10441,
            "lastChecked": "2014-12-30T10:30:00+02:00",
            "traces": [
                {
                    "date": "2014-12-29T19:30:21+02:00",
                    "text": "Přeprava objednána, data k zásilce přijata"
                },
                {
                    "date": "2014-12-30T09:30:21+02:00",
                    "text": "Zásilka doručena na dodací adrese - převzal: Novák"
                }
            ]
        },
        {
            "deliveryId": 10442,
            "lastChecked": null,
            "traces": []
        }
    ]
}
                
HTTP požadavek:
GET /api/v3/deliveries/traces?deliveryId=10441,10442 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Traces successfully retrieved</message>
  <data>
    <deliveryId>10441</deliveryId>
    <lastChecked>2014-12-30T10:30:00+02:00</lastChecked>
    <traces>
      <date>2014-12-29T19:30:21+02:00</date>
      <text>Přeprava objednána, data k zásilce přijata</text>
    </traces>
    <traces>
      <date>2014-12-30T09:30:21+02:00</date>
      <text>Zásilka doručena na dodací adrese - převzal: Novák</text>
    </traces>
  </data>
  <data>
    <deliveryId>10442</deliveryId>
    <lastChecked></lastChecked>
  </data>
</root>
                
HTTP požadavek:
GET /api/v3/deliveries/traces?deliveryId=10441,10442 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Traces+successfully+retrieved&data%5B0%5D%5BdeliveryId%5D=10441&data%5B0%5D%5BlastChecked%5D=2014-12-30T10%3A30%3A00%2B02%3A00&data%5B0%5D%5Btraces%5D%5B0%5D%5Bdate%5D=2014-12-29T19%3A30%3A21%2B02%3A00&data%5B0%5D%5Btraces%5D%5B0%5D%5Btext%5D=P%C5%99eprava+objedn%C3%A1na%2C+data+k+z%C3%A1silce+p%C5%99ijata&data%5B0%5D%5Btraces%5D%5B1%5D%5Bdate%5D=2014-12-30T09%3A30%3A21%2B02%3A00&data%5B0%5D%5Btraces%5D%5B1%5D%5Btext%5D=Z%C3%A1silka+doru%C4%8Dena+na+dodac%C3%AD+adrese+-+p%C5%99evzal%3A+Nov%C3%A1k&data%5B1%5D%5BdeliveryId%5D=10442
                
Popis požadavku

Požadované zásilky definujte query parameterem deliveryId podobně jako při získávání zásilek, tedy více čísel oddělte čárkou.

Popis odpovědi

V odpovědi naleznete stavy ke všem požadovaným zásilkám v klíči traces. Čas poslední kontroly daných stavů je uložena pod klíčem lastChecked u dané zásilky (před první kontrolou nemusí obsahovat žádnou hodnotu). V případě, že zásilka ještě nebyla odeslána, může být pole traces prázdné.

Validace a chybové kódy

Stavy lze získávat pouze pro uzavřené zásilky. V případě nenalezení některé ze zásilek je vrácen HTTP kód 404. Při pokusu o přístup k zásilce s nedostatečným oprávněním je vrácen HTTP kód 403. Ostatní validační chyby, například pokus o získání stavu u neuzavřené zásilky, jsou indikovány kódem 422.

/collection-protocols

Popis zdroje Práce se svozovými protokoly.
Úplná adresa zdroje https://balikonos.cz/api/v2/collection-protocols
OAuth 2.0 scope collection-protocols
Podporované HTTP metody POST GET

POST /collection-protocols

Vytvoření svozového protokolu včetně vygenerování PDF souboru.

HTTP požadavek:
POST /api/v2/collection-protocols HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
Content-type: application/json
                
                    {
    "agent": "IT",
    "collectionPlace": "MujIdentifikator"
}
                
HTTP odpověď:
HTTP/1.1 201 Created
Content-type: application/json; charset=UTF-8
Location: /api/v2/collection-protocols?id=1425
                
{
    "code": 201,
    "status": "success",
    "message": "Collection protocol successfully created!",
    "data": {
        "collectionProtocolId": 1425,
        "agent": "IT",
        "collectionPlace": "MujIdentifikator",
        "protocol": "JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=",
        "created": "2014-06-24T08:07:45+02:00",
        "deliveries": [
            10316,
            10317,
            10412,
            10416,
            10451
        ]
    }
}
                
HTTP požadavek:
POST /api/v2/collection-protocols HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
Content-type: application/xml
                
                    <?xml version="1.0" encoding="UTF-8"?>
<root>
  <agent>IT</agent>
  <collectionPlace>MujIdentifikator</collectionPlace>
</root>
                
HTTP odpověď:
HTTP/1.1 201 Created
Content-type: application/xml; charset=UTF-8
Location: /api/v2/collection-protocols?id=1425
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>201</code>
  <status>success</status>
  <message>Collection protocol successfully created!</message>
  <data>
    <collectionProtocolId>1425</collectionProtocolId>
    <agent>IT</agent>
    <collectionPlace>MujIdentifikator</collectionPlace>
    <protocol>JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=</protocol>
    <created>2014-06-24T08:07:45+02:00</created>
    <deliveries>10316</deliveries>
    <deliveries>10317</deliveries>
    <deliveries>10412</deliveries>
    <deliveries>10416</deliveries>
    <deliveries>10451</deliveries>
  </data>
</root>
                
HTTP požadavek:
POST /api/v2/collection-protocols HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
Content-type: application/x-www-form-urlencoded
                
                    agent=IT&collectionPlace=MujIdentifikator
                
HTTP odpověď:
HTTP/1.1 201 Created
Content-type: application/x-www-form-urlencoded; charset=UTF-8
Location: /api/v2/collection-protocols?id=1425
                
code=201&status=success&message=Collection+protocol+successfully+created%21&data%5BcollectionProtocolId%5D=1425&data%5Bagent%5D=IT&data%5BcollectionPlace%5D=MujIdentifikator&data%5Bprotocol%5D=JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10%2BPl0%2BPj4%2BPj4%3D&data%5Bcreated%5D=2014-06-24T08%3A07%3A45%2B02%3A00&data%5Bdeliveries%5D%5B0%5D=10316&data%5Bdeliveries%5D%5B1%5D=10317&data%5Bdeliveries%5D%5B2%5D=10412&data%5Bdeliveries%5D%5B3%5D=10416&data%5Bdeliveries%5D%5B4%5D=10451
                
Popis požadavku

Svozový protokol slouží jako přehled zásilek, které předáváte přepravci v rámci daného svozu. Pro vytvoření tohoto protokolu tedy stačí definovat identifikátor svozového místa (collectionPlace) a přepravce (agent). Hodnoty polí jsou totožné jako při vkládání zásilek.

Popis odpovědi

V hlavičce Location naleznete odkaz na právě vytvořený protokol, nicméně data protokolu jsou vrácena i v této odpovědi. V odpovědi v klíči data naleznete všechny potřebné údaje o vytvořeném protokolu, včetně obsahu PDF souboru.

  • collectionProtocolId - je id svozového protokolu, používá se v URL zdroje pro získání informací o protokolu (viz níže)
  • agent - zkratka přepravce, pro kterého byl protokol vygenerován
  • collectionPlace - identifikátor svozového místa, ke kterému byl protokol vygenerován
  • protocol - obsah PDF souboru v base64 MIME
  • created - datum vytvoření protokolu
  • deliveries - pole id zásilek, které jsou v protokolu zahrnuty

Validace a chybové kódy

Svozový protokol lze generovat pouze pokud v daném svozovém místě existují nějaké neodeslané uzavřené zásilky daného přepravce bez vytvořeného protokolu. Všechny validační chyby vracejí kód 422 s polem errors se standardní strukturou a totožnými chybovými kódy jako u vkládání zásilek. Pro obecné chyby jako je špatné použití metody (například pokud neexistují zásilky pro daný protokol) však není pole errors dostupné. Lze generovat pouze jeden protokol v jednom požadavku.

GET /collection-protocols

Získání informací o svozovém protokolu včetně obsahu PDF souboru.

HTTP požadavek:
GET /api/v2/collection-protocols?collectionProtocolId=1425 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Protocol successfully fetched!",
    "data": {
        "collectionProtocolId": 1425,
        "agent": "IT",
        "collectionPlace": "MujIdentifikator",
        "protocol": "JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=",
        "created": "2014-06-24T08:07:45+02:00",
        "deliveries": [
            10316,
            10317,
            10412,
            10416,
            10451
        ]
    }
}
                
HTTP požadavek:
GET /api/v2/collection-protocols?collectionProtocolId=1425 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Protocol successfully fetched!</message>
  <data>
    <collectionProtocolId>1425</collectionProtocolId>
    <agent>IT</agent>
    <collectionPlace>MujIdentifikator</collectionPlace>
    <protocol>JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10+Pl0+Pj4+Pj4=</protocol>
    <created>2014-06-24T08:07:45+02:00</created>
    <deliveries>10316</deliveries>
    <deliveries>10317</deliveries>
    <deliveries>10412</deliveries>
    <deliveries>10416</deliveries>
    <deliveries>10451</deliveries>
  </data>
</root>
                
HTTP požadavek:
GET /api/v2/collection-protocols?collectionProtocolId=1425 HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Protocol+successfully+fetched%21&data%5BcollectionProtocolId%5D=1425&data%5Bagent%5D=IT&data%5BcollectionPlace%5D=MujIdentifikator&data%5Bprotocol%5D=JVBERi0xLg0KdHJhaWxlcjw8L1Jvb3Q8PC9QYWdlczw8L0tpZHNbPDwvTWVkaWFCb3hbMCAwIDMgM10%2BPl0%2BPj4%2BPj4%3D&data%5Bcreated%5D=2014-06-24T08%3A07%3A45%2B02%3A00&data%5Bdeliveries%5D%5B0%5D=10316&data%5Bdeliveries%5D%5B1%5D=10317&data%5Bdeliveries%5D%5B2%5D=10412&data%5Bdeliveries%5D%5B3%5D=10416&data%5Bdeliveries%5D%5B4%5D=10451
                
Popis požadavku

Jako query parametr collectionProtocolId uveďte hodnotu klíče collectionProtocolId získanou v odpovědi při vytváření svozového protokolu. Lze získat obsah pouze jednoho protokolu.

Popis odpovědi

Odpověď v klíči data je totožná s odpovědí při vytvoření svozového protokolu. Popis viz výše.

Validace a chybové kódy

V případě dotazu na neexistující protokol je vrácen kód 404 a při pokusu o neoprávněný přístup je vrácen kód 403.

/collection-places

Popis zdroje Práce se svozovými místy.
Úplná adresa zdroje https://balikonos.cz/api/v2/collection-places
OAuth 2.0 scope collection-places
Podporované HTTP metody GET

GET /collection-places

Získání informací o všech aktivních svozových místech.

HTTP požadavek:
GET /api/v2/collection-places HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/json
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
                
{
    "code": 200,
    "status": "success",
    "message": "Active collection places successfully fetched",
    "data": [
        {
            "identificator": "nova-39-1",
            "name": "Nová 39/1",
            "email": "jan.novak@example.com",
            "phone": "123872649",
            "contactPerson": "Ing. Jan Novák",
            "state": "CZ",
            "city": "Brno-Kníničky",
            "street": "Nová 39/1",
            "postalCode": "63500"
        },
        {
            "identificator": "revolucni-11",
            "name": "Revoluční 11",
            "email": "jarda.novy@example.com",
            "phone": "123649872",
            "contactPerson": "Ing. Jaroslav Nový",
            "state": "CZ",
            "city": "Praha",
            "street": "Revoluční 11",
            "postalCode": "11000"
        }
    ]
}
                
HTTP požadavek:
GET /api/v2/collection-places HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/xml
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/xml; charset=UTF-8
                
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <code>200</code>
  <status>success</status>
  <message>Active collection places successfully fetched</message>
  <data>
    <identificator>nova-39-1</identificator>
    <name>Nová 39/1</name>
    <email>jan.novak@example.com</email>
    <phone>123872649</phone>
    <contactPerson>Ing. Jan Novák</contactPerson>
    <state>CZ</state>
    <city>Brno-Kníničky</city>
    <street>Nová 39/1</street>
    <postalCode>63500</postalCode>
  </data>
  <data>
    <identificator>revolucni-11</identificator>
    <name>Revoluční 11</name>
    <email>jarda.novy@example.com</email>
    <phone>123649872</phone>
    <contactPerson>Ing. Jaroslav Nový</contactPerson>
    <state>CZ</state>
    <city>Praha</city>
    <street>Revoluční 11</street>
    <postalCode>11000</postalCode>
  </data>
</root>
                
HTTP požadavek:
GET /api/v2/collection-places HTTP/1.1
Host: balikonos.cz
Authorization: Bearer bacffecfc1bd349b85e51b37a542aed57f457a8e
Accept: application/x-www-form-urlencoded
                
HTTP odpověď:
HTTP/1.1 200 OK
Content-type: application/x-www-form-urlencoded; charset=UTF-8
                
code=200&status=success&message=Active+collection+places+successfully+fetched&data%5B0%5D%5Bidentificator%5D=nova-39-1&data%5B0%5D%5Bname%5D=Nov%C3%A1+39%2F1&data%5B0%5D%5Bemail%5D=jan.novak%40example.com&data%5B0%5D%5Bphone%5D=123872649&data%5B0%5D%5BcontactPerson%5D=Ing.+Jan+Nov%C3%A1k&data%5B0%5D%5Bstate%5D=CZ&data%5B0%5D%5Bcity%5D=Brno-Kn%C3%ADni%C4%8Dky&data%5B0%5D%5Bstreet%5D=Nov%C3%A1+39%2F1&data%5B0%5D%5BpostalCode%5D=63500&data%5B1%5D%5Bidentificator%5D=revolucni-11&data%5B1%5D%5Bname%5D=Revolu%C4%8Dn%C3%AD+11&data%5B1%5D%5Bemail%5D=jarda.novy%40example.com&data%5B1%5D%5Bphone%5D=123649872&data%5B1%5D%5BcontactPerson%5D=Ing.+Jaroslav+Nov%C3%BD&data%5B1%5D%5Bstate%5D=CZ&data%5B1%5D%5Bcity%5D=Praha&data%5B1%5D%5Bstreet%5D=Revolu%C4%8Dn%C3%AD+11&data%5B1%5D%5BpostalCode%5D=11000
                
Popis odpovědi

V klíči data naleznete informace o aktivních svozových místech s následujícími daty.

  • identificator - unikátní identifikace svozového místa, používá se například při tisku svozových protokolů
  • name - pojmenování svozového místa
  • email - email kontaktní osoby
  • phone - telefon kontaktní osoby
  • contactPerson - kontaktní osoba
  • state - stát ve formátu ISO 3166-2, tedy například CZ
  • city - město
  • street - ulice a číslo popisné
  • postalCode - PSČ