Dokumentace k API rozhraní Zaslat.sk
Dokumentace bude dále vylepšována. V nejbližší době přidáme modelové situace a ukázkové zdrojové kódy pro PHP.
Pokud máte nějaký dotaz, připomínku, námět na zlepšení, nebo jste objevili chybu, neváhejte kontaktovat naše IT oddělení na adrese admin@zaslat.sk.
Autentizace
Autentizace každého požadavku probíhá pomocí API klíče, který získáte v nastavení vašeho účtu. API klíč se přidává
jako parametr x-apikey
do hlavičky požadavku pro každou volanou API metodu.
Odpověď na požadavek
Odpověď na každý požadavek je identifikována stavovým HTTP kódem
odpovídající parametru status
v těle odpovědi a zprávou o provedené akci message
.
Rozlišujeme dva typy odpovědi podle stavu zpracování: v pořádku (kód 200 OK)
nebo chyba (jakýkoliv jiný kód).
V případě chybného zpracování může být v odpovědi kromě příslušného stavového kódu vrácena a chybového hlášení a objekt error s výpisem chybných parametrů.
Pokud proběhne zpracování úspěšně, bude odpověď vrácena s volitelným parametrem odpovídající konkrétní volané metodě.
STRUKTURA ODPOVĚDI
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | string|array | chybová hláška nebo pole objektů error s výpisem jednotlivých chyb | ne |
<parametr> | array | pole objektů či hodnot dle konkrétní metody | ne |
Příklad správného zpracování
{ "status": 200, "message": "Contact succesfully deleted" }
Příklad chybové odpovědi
{ "status": 401, "message": "Unauthorized request" } { "status": 400, "message": "Contact validation error" "errors": [{ "message": "Address line cannot be empty" }] }
Metody
Nabídka přepravy, ceny a termínu dodání
POPIS METODY
Pro zjištění nabídky přepravy slouží metoda, která na základě odeslaných parametrů odkud, kam, specifikace balíků a případných příplatkových služeb, vrátí nabídku dostupných přepravních společností spolu s cenou a předpokládaným termínem doručení. Cena za služby a dostupné přepravní společnosti odpovídají aktuální cenové skupině a povoleným dopravcům pro daný zákaznický účet.
POŽADAVEK
POST https://www.zaslat.sk/api/v1/rates/get
TĚLO POŽADAVKU
Parametr | Typ | Popis | Povinný |
---|---|---|---|
currency | string | kód měny podle ISO 4217, v jaké vrátit ceny služeb | ne |
type | enum shipment type | typ (režim) svozu dle číselníku shipment type | ne |
pickup_date | date | požadované datum vyzvednutí (YYYY-MM-DD) | ne |
pickup_branch | string parcelPoint code | kód podacího místa | ne |
delivery_branch | string parcelPoint code | kód výdejního místa | ne |
from | object contact | povinné je pouze pole "stát" | ano |
to | object contact | povinné je pouze pole "stát" | ano |
services | array of services | pole objektů service s příplatkovými službami | ne |
packages | array of packages | pole objektů package s jednotlivými balíky | ano |
ODPOVĚĎ
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole objektů error s chybovými hláškami | ne |
rates | array of rates | pole objektů rate s nabídkami dopravců | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/rates/get \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "currency": "CZK", "pickup_date": "2016-07-10", "from": { "country": "CZ" }, "to": { "country": "SK" }, "services": [{ "code": "cod", "data": { "value": { "value": 1500, "currency": "CZK" } } }], "packages": [{ "weight": 1, "width": 10, "height": 20, "length": 30 }] }'
Příklad odpovědi
{ "status": 200, "message": "Found 3 offers", "rates": [{ "carrier": "GLS", "service": "Export SK", "service_id": 21, "pickup_date": "2016-07-10", "delivery_date": "2016-07-12", "price": { "value": 178.51, "currency": "CZK" }, "price_vat": { "value": 216, "currency": "CZK" } },{ ... }] }
Operace se zásilkami
Soubor metod pro práci se zásilkami.
Vytvořit novou objednávku
POPIS METODY
Vytvoření nové objednávky s jednou nebo více zásilkami.
REQUEST
POST https://www.zaslat.sk/api/v1/shipments/create
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
currency | string | kód měny podle ISO 4217, v jaké vystavit objednávku | ne*) |
payment_type | enum payment_type | forma platby za tuto dávku/objednávku | ne*) |
shipments | array of shipments | pole objektů shipment | ano |
payer | object contact | objekt contact určující plátce | ne**) |
voucher | string | kód voucheru | ne |
*) Pokud není zadáno, použije se výchozí nastavení pro daný zákaznický účet
**) Pokud je uživatel autentizován (dotaz obsahuje x-apikey), není potřeba objekt payer zadávat. V takovém případě bude plátce přihlášený uživatel.
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/shipments/create \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-ApiKey: secret-api-key" \ -d '{ "currency": "CZK", "payment_type": "online", "shipments": [{ "carrier": "GLS", "pickup_date": 2016-07-11, "from": { "id": 1001 }, "to": { "firstname": "Jaroslav", "surname": "Novotný", "company": "Zaslat s.r.o.", "street": "Jindřišská 12/1027", "city": "Praha 4", "zip": "14000", "country": "CZ", "phone": "+420777152225", "email": "novotny@dummymail.com" }, "services": [{ "code": "cod", "data": { "value": { "value": 1500, "currency": "CZK" } } }, { "code": "ins", "data": { "value": 12500, "currency": "CZK" } }], "packages": [{ "weight": 1, "width": 10, "height": 20, "length": 30 }, { ... druhý balík ... }] }, { ... druhá zásilka ... }], "payer": { "firstname": "Miroslav", "surname": "Novotný", "company": "Zaslat s.r.o.", "tin": "00000000" "vatin": "CZ00000000" "street": "Jindřišská 12/1027", "city": "Praha 4", "zip": "14000", "country": "CZ", "phone": "+420777152225", "email": "novotny@dummymail.com" } }'
Příklad odpovědi
{ "status": 200, "message": "Order was successfully created", "data": { "order": "2eb6987.............5c0f41bfd", "order_number": "OP23100000X", "shipments": [ "IZ0123456789", "IZ1234567890" ] } } { "status": 401, "message": "You are not allowed to use invoice payment method" }
Tisk štítků k zásilce
POPIS METODY
Získání štítků k zadaným zásilkám. Tato metoda je určena pouze pro uživatele, kteří mají zřízený pravidelný svoz balíků.
REQUEST
POST https://www.zaslat.sk/api/v1/shipments/label
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
shipments | array | pole identifikátorů zásilek | ano |
position | integer [1 až 4] | pozice prvního štítku | ne*) |
format | string [pdf , url ] |
formát návratové hodnoty obsahující štítky | ne**) |
paper_size | string [A4 , A6 ] |
formát papíru | ne***) |
*) Pokud není zadáno, použije se jako výchozí hodnota 1
**) Pokud není zadáno, použije se jako výchozí hodnota pdf
**) Pokud není zadáno, bude se aplikovat výchozí velikost A4
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | string | odkaz pro stažení štítků (pro format url ) nebo base64 kódovaný soubor se štítky (pro
format pdf )
|
ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/shipments/label \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "shipments": ["IZ0123456789", "IZ1234567890"], "position": 2, "format": "pdf" }'
Příklad odpovědi
{ "status": 200, "message": "OK. Found 2 label(s).", "data": "data:application/pdf;base64,ZGF0YTphcHBsaWNhdGlvbi9wZGY7YmFz..." } { "status": 404, "message": "No shipments with specified identificators were found." }
Seznam zásilek
POPIS METODY
Získání seznamu zásilek. Metoda vrací vždy maximálně 100 výsledků seřazených podle datumu sestupně.
REQUEST
GET https://www.zaslat.sk/api/v1/shipments/list
Adresu pro volání metody lze dále rozšířit o volitelné parametry:
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | string(20) | stav zásilky; možnosti: OPEN, ACTIVE, DELIVERED, STORNO | ne |
offset | int | posunutí výsledků pro zobrazení starších zásilek | ne |
from_date | date | datum od (YYYY-MM-DD) | ne |
to_date | date | datum do (YYYY-MM-DD) | ne |
reference_number | string | reference zásilky | ne |
tracking_number | string | identifikátor zásilky | ne |
search | string | vyhledávání v reference_number nebo tracking_number |
ne |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of shipments | pole objektů shipment s informacemi o zásilce | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/shipments/list \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key"
Příklad odpovědi
{ "status": 200, "message": "OK. Found 10 shipment(s).", "data": { "IZ076151CA1F": { "carrier": "gls", "service_id": "7", "pickup_date": "2017-02-02 10:24:17", "delivery_date": "2017-02-03 10:24:17", "status": "INTRANSIT", "from": { "firstname": "František", "surname": "Novotný", ... }, "to": { "firstname": "Karel", "surname": "Novotný", ... }, "packages": [{ "status": "INTRANSIT", "weight": 1, "width": 10, "height": 20, "length": 30 }, ... druhý balík ... }] }, "IZ1234567890": { ... druhá zásilka ... } } }
Detail zásilkek
POPIS METODY
Získání detailu zásilek.
REQUEST
POST https://www.zaslat.sk/api/v1/shipments/detail
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
shipments | array of strings | pole identifikátorů zásilek | ano |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of shipments | pole objektů shipment s informacemi o zásilce | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/shipments/detail \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "shipments": ["IZ076151CA1F", "IZ1234567890"] }'
Příklad odpovědi
{ "status": 200, "message": "OK. Found 10 shipment(s).", "data": { "IZ076151CA1F": { "carrier": "gls", "service_id": "21", "pickup_date": "2017-02-02 10:24:17", "delivery_date": "2017-02-03 10:24:17", "status": "INTRANSIT", "from": { "firstname": "František", "surname": "Novotný", ... }, "to": { "firstname": "Karel", "surname": "Novotný", ... }, "packages": [{ "status": "INTRANSIT", "weight": 1, "width": 10, "height": 20, "length": 30 }, ... druhý balík ... }], "services": [{ "code": "ins", "data": { "value": 12000, "currency": "CZK" } }] }, "IZ1234567890": { ... druhá zásilka ... } } }
Sledování zásilky
POPIS METODY
Sledování stavu doručení zásilky.
REQUEST
POST https://www.zaslat.sk/api/v1/shipments/tracking
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
shipments | array of strings | pole identifikátorů zásilek | ano |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of shipments | pole objektů shipment s informacemi o zásilce | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/shipments/tracking \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "shipments": ["IZ076151CA1F", "IZ1234567890"] }'
Příklad odpovědi
{ "status": 200, "message": "OK. Found 1 shipment(s).", "data": { "IZ076151CA1F": { "status": "INTRANSIT", "packages": [ [ { "date": "2016-07-04", "time": "15:00:00", "name": "Balik byl prijat pobockou GLS.", "status": "INTRANSIT", "location": "Ceska Republika" }, { "date": "2016-07-02", "time": "12:00:00", "name": "Udaje k baliku byly zadany do systemu GLS.", "status": "EXPORTED" } ], [ ... druhý balík ... ] ] }, "IZ1234567890": { ... druhá zásilka ... } } }
Žádost o svoz
Přes API lze také sledovat a vytvářet žádosti o svoz.
Seznam žádostí o svoz
POPIS METODY
Získat seznam žádostí o svoz.
REQUEST
GET https://www.zaslat.sk/api/v1/pickups/list
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of pickups | pole objektů pickup | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/pickups/list \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key"
Příklad odpovědi
{ "status": 200, "message": "OK. Found 4 pickup(s).", "data": { "16": { "id": 16, "date": "2017-01-31", "carrier": "DPD", "address_id": 1001 }, { ... } } }
Vytvořit novou žádost o svoz
POPIS METODY
Vytvožit jednu nebo více žádostí o svoz.
REQUEST
POST https://www.zaslat.sk/api/v1/pickups/add
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
pickups | array of pickups | pole objektů pickup | ano |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of integers | pole identifikátorů nově vytvořených kontaktů | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/pickups/add \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "pickups": [{ "date": "2017-02-10", "carrier": "DPD", "address_id": 1001 }, { ... }] }'
Příklad odpovědi
{ "status": 200, "message": "2 pickups successfuly added.", "data": [35, 36] }
Podací/výdejní místa
Přes API lze získat seznam podacích či výdejních míst.
Seznam podacích/výdejních míst
POPIS METODY
Získat seznam podacích/výdejních míst.
REQUEST
GET https://www.zaslat.sk/api/v1/parcelpoints/list
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of parcelPoints | pole objektů parcelPoint | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/parcelpoints/list \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key"
Příklad odpovědi
{ "status": 200, "message": "OK. Found 148 item(s).", "data": { 16604": { "id": 16604, "carrier": "PPL", "code": "KM11730100", "name": "„V Háji“", "street": "28. října 89/51", "city": "Plzeň", "zip": "30100", "country": "CZ", "phone": null, "location": { "lat": "49.778694444444", "lng": "13.409666666667" }, "is_collection": true, "is_locker": 0, "is_depot": 0, "card_payment": 1, "wheelchair_access": 0, "no_lunch_break": 1, "open_saturday": 0, "open_sunday": 0, "opening_hours": { "7": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null }, "1": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null }, "2": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null }, ... "6": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null } }, "distance": 0, "user": null }, { ... } } }
Adresář
Přes API lze také spravovat adresář kontaktů. Odesilatelem nebo příjemcem zásilky pak může výt vybraný kontakt z adresáře identifikovaný unikátním ID. Při zadávání zásilky pak odpadne nutnost zadávání adres a kontaktních údajů.
Seznam kontaktů v adresáři
POPIS METODY
Získat seznam kontaktů z adresáře.
REQUEST
GET https://www.zaslat.sk/api/v1/contacts/list
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of contacts | pole objektů contact | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/contacts/list \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key"
Příklad odpovědi
{ "status": 200, "message": "OK. Found 25 contact(s).", "data": { "1002": { "id": 1002, "firstname": "Alena", "surname": "Šimková", "street": "Jánská 42", "city": "Brno", "zip": "60200", "country": "CZ", "phone": "+420603001552", "email": "simkova.alena@dummymail.com" }, { ... } } }
Vytvořit nový kontakt v adresáři
POPIS METODY
Přidat jeden nebo více kontaktů do adresáře.
REQUEST
POST https://www.zaslat.sk/api/v1/contacts/add
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
contacts | array of contacts | pole objektů contact pro přidání do adresáře | ano |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of integers | pole identifikátorů nově vytvořených kontaktů | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/contacts/add \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "contacts": [{ "firstname": "Jaroslav", "surname": "Novotný", "company": "Zaslat s.r.o.", "street": "Jindřišská 12/1027", "city": "Praha 4", "zip": "14000", "country": "CZ", "phone": "+420777152225", "email": "novotny@dummymail.com" }, { ... }] }'
Příklad odpovědi
{ "status": 200, "message": "2 contacts successfuly added.", "data": [1000, 1001] }
Upravit kontakt v adresáři
POPIS METODY
Upravit jeden nebo více kontaktů do adresáře.
REQUEST
POST https://www.zaslat.sk/api/v1/contacts/edit
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
contacts | array of contacts | pole objektů contact pro přidání do adresáře | ano |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
data | array of integers | pole identifikátorů upravených kontaktů | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/contacts/edit \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "contacts": [{ "id": 1234, "firstname": "Jaroslav", "surname": "Novotný", "company": "Zaslat s.r.o.", "street": "Jindřišská 12/1027", "city": "Praha 4", "zip": "14000", "country": "CZ", "phone": "+420777152225", "email": "novotny@dummymail.com" }, { ... }] }'
Příklad odpovědi
{ "status": 200, "message": "2 contacts successfuly updated.", "data": [1000, 1001] }
Smazat kontakty z adresáře
POPIS METODY
Smazat jeden nebo více kontaktů z adresáře.
REQUEST
POST https://www.zaslat.sk/api/v1/contacts/delete
BODY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
contacts | array of integers | pole s identifikátory kontaktů ke smazání | ano |
RESPONSE
Parametr | Typ | Popis | Povinný |
---|---|---|---|
status | integer | kód stavu odpovědi | ano |
message | string | hlášení o provedené akci | ano |
errors | array | pole s výpisem chyb | ne |
Příklad volání
curl -v https://www.zaslat.sk/api/v1/contacts/delete \ -X "POST" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Apikey: secret-api-key" \ -d '{ "contacts": [1111, 1215] }'
Příklad odpovědi
{ "status": 200, "message": "2 contacts successfuly deleted" }
Objekty
Rate
POPIS OBJEKTU
Datová reprezentace nabídky přepravní společnosti s cenou a termínem vyzvednutí a doručení.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
carrier | string(20) | kód přepravní společnosti podle číslelníku carriers | - |
service | string(20) | název konkrétní služby dopravce | - |
service_id | integer | identifikátor konkrétní služby dopravce | - |
pickup_date | date | nejbližší možné datum vyzvednutí (YYYY-MM-DD) | - |
pickup_from_time | time | vyzvednutí od (H:m:s) | - |
pickup_to_time | time | vyzvednutí do (H:m:s) | - |
delivery_date | date | nejbližší možné datum doručení (YYYY-MM-DD) | - |
price | object money | cena za přepravu bez DPH | - |
price_vat | object money | cena za přepravu včetně DPH | - |
insurance_limit | object money | limit odpovědnosti dopravce včetně DPH | - |
own_invoice_upload | bool | vlastní faktura | - |
weight_limit | int | váhový limit | - |
pickup_branch | bool | možnost předání na podacím místě | - |
pickup_branch_required | bool | nutnost předat zásilku na podací místo | - |
delivery_branch_required | bool | nutnost doručení na výdejní místo | - |
shipment_category | string(20) | kategorie zásilky podle číselníku Shipment Category | - |
trackable | bool | trakování zásilky | - |
printable | bool | tisk štítků | - |
Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.
Příklad
{ "carrier": "GLS", "service": "Business-Parcel", "service_id": 7, "pickup_date": 2016-07-11, "delivery_date": 2016-07-12, "pickup_from_time": "08:00:00", "pickup_to_time": "18:00:00", "price": { "value": 98.35, "currency": "CZK" }, "price_vat": { "value": 119, "currency": "CZK" }, "insurance_limit": { "value": 50000, "currency": "CZK" }, "weight_limit": 15, "pickup_branch": true, "pickup_branch_required": true, "delivery_branch_required": true, "trackable": true, "printable": true, "shipment_category": "domestic" }
Contact
POPIS OBJEKTU
Datová reprezentace kontaktní osoby a místa doručení nebo vyzvednutí zásilky.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
id | integer | identifikátor existujícího kontaktu | ne*) |
company | string(75) | název společnosti | ne |
firstname | string(50) | jméno kontaktní osoby | ano**) |
surname | string(50) | příjmení kontaktní osoby | ano**) |
street | string(100) | ulice s číslem popisným | ano**) |
city | string(50) | obec nebo město | ano**) |
zip | string(12) | poštovní směrovací číslo | ano**) |
country | string(2) | kód země ISO 3166-1 alpha-2 | ano |
phone | string(50) | telefonní kontakt | ano**) |
string(50) | e-mailový kontakt | ne | |
tin | string(50) | identifikační číslo osoby | ne |
vatin | string(50) | daňové identifikační číslo | ne |
*) Pokud předáváme pomocí reference na ID, tak ostatní parametry jsou nepovinné
**) Nepovinné při použití v metodě pro získání nabídky přepravy
Příklad
{ "id": 1001, "firstname": "Jaroslav", "surname": "Novotný", "company": "Zaslat s.r.o.", "street": "Jindřišská 12/1027", "city": "Praha 4", "zip": "14000", "country": "CZ", "phone": "+420777152225", "email": "novotny@dummymail.com" } Lze také předat jako referenci jen pomocí ID: { "id": 1001 }
Shipment
POPIS OBJEKTU
Datová reprezentace zásilky.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
carrier | string(20) | kód přepravní společnosti podle číslelníku carriers | ne |
service_id | integer | identifikátor konkrétní služby dopravce | ne |
type | enum shipment type | typ (režim) svozu dle číselníku shipment type | ne |
pickup_date | date | požadované datum vyzvednutí (YYYY-MM-DD) | ne |
(deprecated) |
string parcelPoint code | kód podacího místa | ne |
(deprecated) |
string parcelPoint code | kód výdejního místa | ne |
pickup_branch_location | integer | ID lokace podacího místa * | ne |
delivery_branch_location | integer | ID lokace výdejního místa * | ne |
from | object contact | objekt contact určující místo vyzvednutí | ano |
to | object contact | objekt contact určující místo doručení | ano |
services | array of service | pole objektů service s příplatkovými službami | ne |
packages | array of package | pole objektů package s jednotlivými balíky | ano |
reference | string(255) | vlastní označení zásilky | ne |
note | string(255) | poznámka pro řidiče | ne |
status | string | stav zásilky | - |
* ID lokace naleznete v mapě podacích a výdejních míst u každého místa v seznamu
Příklad
{ "carrier": "GLS", "pickup_date": 2016-07-11, "from": { "id": 1001 }, "to": { "firstname": "Jaroslav", "surname": "Novotný", "company": "Zaslat s.r.o.", "street": "Jindřišská 12/1027", "city": "Praha 4", "zip": "14000", "country": "CZ", "phone": "+420777152225", "email": "novotny@dummymail.com" }, "services": [{ "code": "cod", "data": { "value": { "value": 1500, "currency": "CZK" } } }, { "code": "ins", "data": { "value": 12500, "currency": "CZK" } }], "packages": [{ "weight": 1, "width": 10, "height": 20, "length": 30 }, { ... }] }
ParcelPoint
POPIS OBJEKTU
Datová reprezentace místa pro předání či vyzvednutí zásilky.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
id | int | identifikátor | - |
carrier | string(20) | dopravce podle číselníku carriers | - |
code | string | kód místa | - |
name | string | název místa | - |
street | string | ulice s číslem popisným | - |
city | string | obec nebo město | - |
zip | string | poštovní směrovací číslo | - |
country | string | kód země ISO 3166-1 alpha-2 | - |
phone | string | kontaktní telefon | - |
location | object | objekt lat , lng " |
- |
is_collection | bool | podací místo | - |
is_locker | int | box 1 ano , 0 ne |
- |
is_depot | int | sklad 1 ano , 0 ne |
- |
card_payment | int | platba kartou 1 ano , 0 ne |
- |
wheelchair_access | int | bezbariérový přístup 1 ano , 0 ne |
- |
no_lunch_break | int | polední přestávka 1 ano , 0 ne |
- |
open_saturday | int | otevřeno v sobotu 1 ano , 0 ne |
- |
open_sunday | int | otevřeno v neděli 1 ano , 0 ne |
- |
opening_hours | object | pole objektů opening hours, index pole udává den v týdnu, pondělí = 1 | - |
Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.
Příklad
{ "id": 16604, "carrier": "PPL", "code": "KM11730100", "name": "„V Háji“", "street": "28. října 89/51", "city": "Plzeň", "zip": "30100", "country": "CZ", "phone": null, "location": { "lat": "49.778694444444", "lng": "13.409666666667" }, "is_collection": true, "is_locker": 0, "is_depot": 0, "card_payment": 1, "wheelchair_access": 0, "no_lunch_break": 1, "open_saturday": 0, "open_sunday": 0, "opening_hours": { "7": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null }, "1": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null }, "2": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null }, ... "6": { "from1": "13:00", "to1": "22:00", "from2": null, "to2": null } }, "distance": 0, "user": null }
Package
POPIS OBJEKTU
Datová reprezentace jednoho balíku v zásilce. Balík je popsán jeho váhou, rozměry a doplňkově popisem a jeho peněžní hodnotou.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
weight | float | hmotnost [kg] | ano |
width | integer | šířka v [cm] | ano |
height | integer | výška v [cm] | ano |
length | integer | délka [cm] | ano |
value | object money | hodnota balíku | ne |
content | string(255) | obsah balíku | ne |
status | enum shipment status | aktuální stav balíku dle číselníku shipment shipment status | ano |
history | array of history | pole typu history reprezentující historii stavů balíku | ne |
carrier_tracking | string | odkaz na sledování balíku | ne |
Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.
Příklad
{ "weight": 7.5, "width": 50, "height": 30, "length": 40, "status": "CREATED", "number": "", "value": { "value": 100, "currency": "EUR" }, "carrier_tracking": "https://www.carrier.com/example-tracking", "content": "popis balíku" }
History
POPIS OBJEKTU
Datová reprezentace historie sledování zásilky.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
date | date | datum vytvoření záznamu v historii balíku | - |
time | time | čas vytvoření záznamu v historii balíku | - |
name | string | textová informace o záznamu v historii balíku | - |
status | string | stav v historii balíku | - |
location | string | Doplňující informace o místě/lokaci balíku | - |
Poznámka: řádky zvýrazněné kurzívou označují parametry odpovědi.
Příklad
{ "date": "2016-07-16", "time": "15:17:00", "name": "Balik byl dorucen", "status": "DELIVERED", "location": "Portugalsko" }
Service
POPIS OBJEKTU
Datová reprezentace příplatkové služby (dobírka, připojištění, atp.)
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
code | string(20) | kód příplatkové služby podle číselníků services | ano |
data | object | parametry pro příplatkovou službu podle číselníků services | ano |
Příklad
{ "code": "cod", "data": { "value": { "value": 100, "currency": "EUR" } } }
Pickup
POPIS OBJEKTU
Datová reprezentace žádosti o svoz.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
id | int | identifikátor žádosti o svoz | ano |
date | date | požadované datum svozu (YYYY-MM-DD) | ano |
carrier | string(20) | kód přepravní společnosti podle číslelníku carriers | ano |
address_id | integer | identifikátor existujícího kontaktu | ano |
Příklad
{ "id": 12354, "date": "2017-01-31", "carrier": "DPD", "address_id": 1001 }
Opening Hours
POPIS OBJEKTU
Data reprezentují otevírací dobu výdejních/podacích míst.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
from1 | time | otevřteno od (H:m) | ano |
to1 | time | otevřteno do (H:m) | ano |
from2 | time | otevřteno od (H:m) | ne*) |
to2 | time | otevřteno do (H:m) | ne*) |
*) V případě uvedení času má výdejní místo polední pauzu.
Příklad
{ "from1": "13:00", "to1": "22:00", "from2": null, "to2": null },
Money
POPIS OBJEKTU
Objekt reprezentující peněžní hodnotu v odpovídající měně. Objekt je využíván tam, kde je potřeba předat číselné vyjádření hodnoty spolu s měnou. Např. dobírka, pojištění, hodnota balíku, atd.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
value | float | částka v příslušné měně | ano |
currency | string(3) | kód měny podle ISO 4217 | ano |
Příklad
{ "value": 1500, "currency": "CZK" }
ServiceCOD
POPIS OBJEKTU
Objekt reprezentující službu dobírky.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
bank_account | string(64) | číslo účtu pro vyplacení dobírky | ne |
bank_code | string(4) | kód banky účtu pro vyplacení dobírky | ne |
bank_variable | string(20) | variabilní symbol použitý při vyplacení dobírky | ne |
value | object money | výše dobírky balíku | ano |
Příklad
{ "bank_account": "12-34567890", "bank_code": "0100", "value": { "value": 1500, "currency": "CZK" } }
Error
POPIS OBJEKTU
Objekt reprezentující chybovou hlášku.
PARAMETRY
Parametr | Typ | Popis | Povinný |
---|---|---|---|
field | string | název parametru, který vyvolal chybu | - |
message | string | textový popis chyby | - |
value | string | zadaná hodnota parametru | - |
Příklad
{ "field": "contacts[0].email", "message": "Invalid e-mail format.", "value": "f.novotny@seznam" }
Číselníky
HTTP status codes
POPIS ČÍSELNÍKU
Číselník HTTP kódu stavů v odpovědi na konkrétní požadavek.
Kód | Stav | Popis |
---|---|---|
200 | OK | Požadavek úspěšně zpracován |
400 | Bad Request | Neplatný požadavek (chyba vstupních dat) |
401 | Unauthorized | Neautorizovaný požadavek (neplatný API klíč) |
404 | Not Found | Požadovaná metoda nebyla nalezena (chybná URL požadavku) |
500 | Internal Server Error | Vnitřní chyba aplikace (chyba na naší straně) |
Carriers
POPIS ČÍSELNÍKU
Seznam kódu přepravních společností, které systém Zaslat.sk integruje.
Kód | Název |
---|---|
PPL | PPL |
DPD | DPD |
GLS | GLS |
TOPTRANS | TOPTRANS |
UPS | UPS |
GLS_SK | GLS_SK |
LIFTAGO | Liftago |
TNT | TNT |
FEDEX | FedEx |
WEDO | WEDO |
BALIKOVNA | Balíkovna |
ZASILKOVNA | Zásilkovna |
Payment type
POPIS ČÍSELNÍKU
Číselník dostupných forem platby za dávku/objednávku. Platba na fakturu je dostupná pouze po předchozí domluvě pro firemní zákazníky s uzavřenou zasilatelskou smlouvou. Chcete také platit na fakturu? Kontaktujte nás.
Kód | Popis |
---|---|
ONLINE | Platba on-line bránou GoPay přes vrácenou URL |
CREDIT | Úhrada z předplaceného kreditu na zákaznickém účtu |
INVOICE | Platba na fakturu pouze pro smluvní zákazníky |
Shipment Status
POPIS ČÍSELNÍKU
Číselník možných stavů v historii zásilky.
Kód | Popis |
---|---|
CREATED | Zásilka byla vytvořena |
EXPORTED | Dopravce potvrdil přijetí dat o zásilce |
ONPICKUP | Zásilka čeká na vyzvednutí kurýrem |
INTRANSIT | Zásilka je na cestě do cílového depa |
ONDELIVERY | Zásilka byla předána kurýrovi na rozvoz |
DELIVERED | Zásilka byla doručena |
CANCELLED | Zásilka byla stornována |
Shipment Type
POPIS ČÍSELNÍKU
Číselník možných režimů svozu.
Kód | Popis |
---|---|
ONDEMAND | Jednorázový svoz - štítky tiskne dopravce. |
OCCASIONAL | Příležitostný svoz - štítky si tiskne zákazník. |
REGULAR | Pravidelný svoz - štítky si tiskne zákazník. |
Shipment Category
POPIS ČÍSELNÍKU
Číselník možných kategorií zásilky.
Kód | Popis |
---|---|
domestic | Doruřování v rámci jedné země |
exportEu | Export zásilky v rámci států EU |
exportWorld | Export zásilky mimo státy EU |
importEu | Import zásilky v rámci států EU |
importWorld | Import zásilky mimo státy EU |
Services
POPIS ČÍSELNÍKU
Číselník příplatkových služeb
Kód | Data | Popis |
---|---|---|
COD | object serviceCOD | Dobírka do vybraných států (CZ, SK) |
INS | object money | Připojištění nad rámec základního pojištění |
DSC | string(20) | Slevový kód |
Příklad: dobírka
{ "code": "cod", "data": { "bank_currency": "CZK", "bank_account": "12-34567890", "bank_code": "0100", "bank_variable": "987654321", "value": { "value": 1500, "currency": "CZK" } } }
Příklad: připojištění
{ "code": "ins", "data": { "value": 500, "currency": "EUR" } }
Pickup Time Range
POPIS ČÍSELNÍKU
Číselník časových oken svozu
Kód | Data |
---|---|
1 | 09:00:00 - 13:00:00 |
2 | 09:30:00 - 13:30:00 |
3 | 10:00:00 - 14:00:00 |
4 | 10:30:00 - 14:30:00 |
5 | 11:00:00 - 15:00:00 |
6 | 11:30:00 - 15:30:00 |
7 | 12:00:00 - 16:00:00 |
8 | 12:30:00 - 16:30:00 |
9 | 13:00:00 - 17:00:00 |
Příklady implementace
V této části budou uvedeny příklady implementace API rozhraní služby Zaslat.sk v programovacím jazyce PHP.
Získání nabídky přepravy
IMPLEMENTACE
Pro získání nabídky přepravy je potřeba odeslat POST požadavek na adresu https://www.zaslat.sk /api/v1/rates/get
.
V těle požadavku je nutno uvést vstupní data tak, jak je to uvedeno v dokumentaci výše.
Příklad v boxu vpravo je uveden v jazyce PHP s využitím zabudované knihovny curl
.
Příklad: získání nabídky přepravy v jazyce PHP
// Nejprve je nutne poskladat data, ktera budou odeslana v tele pozadavku // podle specifikace v dokumentaci. $data = array( "from" => array( "country" => "CZ" ), "to" => array( "country" => "SK" ), "services" => array( array( "code" => "COD", "data" => array( "value" => array( "value" => 1500, "currency" => "CZK" ) ) ) ), "packages" => array( array( "weight" => 1, "width" => 10, "height" => 20, "length" => 30 ) ) ); // Data musi byt v tele pozadavku odeslana ve formatu JSON, // proto je nutno data do daneho formatu prevest. $data = json_encode($data); // Pro odeslani pozadavku pouzijeme PHP knihovnu cURL. // Veskere moznosti nastaveni viz http://php.net/manual/en/book.curl.php // 1. Inicializace knihovny $ch = curl_init(); // 2. Nastaveni URL adresy API volani curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.sk/api/v1/rates/get"); // 3. Urceni HTTP metody volani curl_setopt($ch, CURLOPT_POST, 1); // 4. Nastaveni hlavicek volani. Misto <VAS-API-KLIC> doplnte Vas API klic curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Accept: application/json", "Content-Type: application/json", "X-Apikey: <VAS-API-KLIC>" )); // 5. Naplneni tela pozadavku daty curl_setopt($ch, CURLOPT_POSTFIELDS, $data); // 6. Nastaveni ulozeni odpovedi volani do promenne curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 7. Zavolani API rozhrani Zaslat.sk se zvolenymi parametry $response = curl_exec($ch); // 8. Ukonceni relace a uvolneni zdroju curl_close($ch); // Promenna $response nyni obsahuje odpoved serveru ve formatu JSON. // Prevedeme ji tedy do formatu asociativniho pole pro dalsi praci s daty $response = json_decode($response, true);
Vytvoření nové objednávky
IMPLEMENTACE
Pro vytvoření nové objednávky je potřeba odeslat POST požadavek na adresu https://www.zaslat.sk /api/v1/shipments/create
.
V těle požadavku je nutno uvést vstupní data tak, jak je to uvedeno v dokumentaci výše.
Příklad v boxu vpravo je uveden v jazyce PHP s využitím zabudované knihovny curl
.
Poznámka: pro detailní popis všech metod a volání v kódu se prosím podívejte na ukázku kódu pro získání nabídky přepravy, která je bohatě komentovaná.
Příklad: získání nabídky přepravy v jazyce PHP
// Seskladani dat $data = array( "currency" => "CZK", "payment_type" => "online", "shipments" => array( array( "pickup_date" => "2017-02-10", "from" => array( "id" => 1001 ), "to" => array( "firstname" => "Jaroslav", "surname" => "Novotný", "company" => "Zaslat s.r.o.", "street" => "Jindřišská 12/1027", "city" => "Praha 4", "zip" => "14000", "country" => "CZ", "phone" => "+420777152225", "email" => "novotny@dummymail.com" ), "packages" => array( array( "weight" => 1, "width" => 10, "height" => 20, "length" => 30 ) ) ) ) ); $data = json_encode($data); // Vytvoreni cURL pozadavku $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.sk/api/v1/shipments/create"); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Accept: application/json", "Content-Type: application/json", "X-Apikey: <VAS-API-KLIC>" )); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); // Odpoved serveru $response = json_decode($response, true);
Získání seznamu kontaktů
IMPLEMENTACE
Pro získání nabídky přepravy je potřeba odeslat GET požadavek na adresu https://www.zaslat.sk /api/v1/contacts/list
.
Příklad v boxu vpravo je uveden v jazyce PHP s využitím zabudované knihovny curl
.
Poznámka: pro detailní popis všech metod a volání v kódu se prosím podívejte na ukázku kódu pro získání nabídky přepravy, která je bohatě komentovaná.
Příklad: získání nabídky přepravy v jazyce PHP
$ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://www.zaslat.sk/api/v1/contacts/list"); curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Accept: application/json", "Content-Type: application/json", "X-Apikey: <VAS-API-KLIC>" )); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); // Odpoved serveru $response = json_decode($response, true);