Balíkonoš API - dokumentace RESTful zdrojů
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.
/
| Popis zdroje | Speciální neverzovaný testovací zdroj bez nutné autentizace. |
|---|---|
| Úplná adresa zdroje | http://18.157.217.252/api/ |
| Podporované HTTP metody | GET |
/deliveries
| Popis zdroje | Práce s několika zásilkami najednou. |
|---|---|
| Úplná adresa zdroje | http://18.157.217.252/api/v3/deliveries |
| OAuth 2.0 scope | deliveries |
| Podporované HTTP metody |
|
POST /deliveries
Importování nových zásilek
HTTP požadavek:
POST /api/v3/deliveries HTTP/1.1
Host: 18.157.217.252
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: http://18.157.217.252/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: 18.157.217.252
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: http://18.157.217.252/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: 18.157.217.252
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: http://18.157.217.252/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
addressje nutné specifikovat všechny údaje dané osoby (adresa, jméno, příjmení, telefon, ...). - Pokud uvedete
collectionPlaceje nutné specifikovat pouze identifikátor svozového místa (klíčcollectionPlace). - Pokud uvedete
pickUpPlaceje 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.typejeaddressasender.typejecollectionPlace). - Přímé zásilky jsou z adresy na adresu (
recipient.typeasender.typejeaddress). - Zpětné zásilky jsou z adresy na svozové místo. (
recipient.typejecollectionPlaceasender.typejeaddress).
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:
|
sourceName | string | pojmenování původu vzniku zásilky |
source | int | id původu vzniku zásilky, možné hodnoty jsou:
|
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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.agentje zkratka přepravce, u něhož byl svoz objednáncollectionOrders.scheduledje datum objednání svozu ve formátu YYYY-MM-DD, o přesném času svozu budete informováni kurýremcollectionOrders.collectionPlaceje 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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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 | http://18.157.217.252/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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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 | http://18.157.217.252/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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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:
- WE|DO (Intime) - maximální pozice je 4
- Č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
- DHL - 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 souborusize- určuje velikost souboru v bytech před zakódováním do base64contents- 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 | http://18.157.217.252/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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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 -
WE|DO (Intime):
10x15(výchozí) -
Zásilkovna:
10x17(výchozí) -
Uloženka:
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 | http://18.157.217.252/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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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 | http://18.157.217.252/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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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áncollectionPlace- identifikátor svozového místa, ke kterému byl protokol vygenerovánprotocol- obsah PDF souboru v base64 MIMEcreated- datum vytvoření protokoludeliveries- 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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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 | http://18.157.217.252/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: 18.157.217.252
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: 18.157.217.252
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: 18.157.217.252
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ístaemail- email kontaktní osobyphone- telefon kontaktní osobycontactPerson- kontaktní osobastate- stát ve formátu ISO 3166-2, tedy například CZcity- městostreet- ulice a číslo popisnépostalCode- PSČ