REST API

Autentizace

Klient se autentizuje HTTP Basic autentizací s použitím jména a hesla pro Aplikaci Zásilky.

Návratové hodnoty

Server na úspěsně provedený požadavek reaguje kódem:

  • 200 OK pokud vrací nějaká data
  • 201 Created spolu s hlavičkou Location, pokud došlo k vytvoření nové entity a žádná jiná data se nevrací
  • případně 204 No Content pokud byl požadavek přijat a není potřeba vracet žadná data

Chyby 400 Bad Request případně 415 Unsupported Media Type indikují, že tělo požadavku není platný JSON.

Chyba ve vnitřní logice požadavku je indikována chybou 403 Forbidden, v těle chybové odpovědi je potom přítomna následující struktura:

{
  "error_code": "KOD",
  "message": "Textova (podrobnejsi) zprava"
}

Volitelné hlavičky:

  • X-InTime-Transaction – pokud je nastaveno na yes, musí požadavek uspět jako celek
  • X-InTime-Auto-Complete – pokud nastaveno na yes, vytvářené zásilky jsou rovnou odeslány v nové dávce ke zpracovaní
  • X-InTime-Customer – kód zákazníka, pokud ma uživatel přiřazeno více zákazníků
  • X-InTime-Department – kód svozového místa, pokud ma uživatel přiřazeno více svozových míst

/raw_request

Jako POST data přijímá dávkový požadavek jako JSON ve formátu vycházejícím z XML pro Aplikaci Zásilky.

/package

GET

Vrací seznam vlastních zásilek. V URL je možné použít filtrační parametry:

  • sent – 1/0 – Je zásilka odeslána ke zpracování?
  • delivered – 1/0 – Je zásilka doručena?
  • created_before – ISO8601 – datum vytvoření zásilky do
  • created_after – ISO8601 – datum vytvoření zásilky od

POST

Vytvoří novou zásilku. V těle požadavku je datová struktura:

{
  "receiver": {...}, // prijemce zasilky, adresa (Povinne)
  "sender": {...}, // odesilatel zasilky, adresa
  "reference_number": "referencni cislo",
  "reference_number2": "druhe referencni cislo",
  "package_count": 1, // pocet colli v zasilce
  "package_number": [], // zakaznicke oznaceni baliku (stejne prvku jako package_count)
  "weight": 1.23, // v kg
  "volumentric_weight": 1.23,
  "value": 1.23, // v CZK
  "comment": "poznamka",
  "product": "produkt intime",
  "pup_branch": "kod vydejniho mista",
  "pup_contact": "ceske mobilni tel. cislo prijemce",
  "additional_service": {...} // vybrane doplnkove sluzby
}

Možné datové prvky:

NázevTypPovinnýPopis
receiverobjectdefinuje příjemce zásilky; v případě, že není použit IN TIME produkt poštomat, je tento element povinný
external_idstring(255)neidentifikátor adresy z Aplikace Zásilky
namestring(100)anooznačení příjemce zásilky
streetstring(100)anoulice + číslo popisné
citystring(50)anoměsto
postal_codestring(5)anoPSČ
statestring(2)anokód země dle ISO 3166-1; obchodní oddělení IN TIME dodá seznam možných zemí
firstnamestring(30)nekřestní jméno
surnamestring(30)nepříjmení
emailstring(50)neemail
phonestring(15)netelefon
mobilestring(15)nemobilní telefon
faxstring(15)nefax
notestring(75)nepoznámka
senderobjectpovinný element v případě přímé zásilky (direct_order), definuje odesílatele zásilky
external_idstring(255)neidentifikátor adresy z Aplikace Zásilky
namestring(100)anooznačení příjemce zásilky
streetstring(100)anoulice + číslo popisné
citystring(50)anoměsto
postal_codestring(5)anoPSČ
statestring(2)anokód země dle ISO 3166-1; obchodní oddělení IN TIME dodá seznam možných zemí
firstnamestring(30)nekřestní jméno
surnamestring(30)nepříjmení
emailstring(50)neemail
phonestring(15)netelefon
mobilestring(15)nemobilní telefon
faxstring(15)nefax
notestring(75)nepoznámka
reference_numberstring(20)nereferenční číslo/ID zásilky
reference_number2string(50)nedruhé referenční číslo/ID zásilky
package_countintegeranopočet balíků v zásilce
package_numberstring(50)nevolitelné číslo balíku zákazníka; pokud je uvedeno, je nutné aby počet elementů odpovídal počtu balíku v elementu package_count
weightfloatanocelková váha zásilky v kg
volumetric_weightfloatnecelková volumetrická váha zásilky v kg
valuefloatanocelková hodnota zásilky v CZK
commentstring(255)nepoznámka
additiveboolnepožadavek na umožnění dodatečného přidání/odebrání balíku do zásilky; pokud je uvedena hodnota Y, lze k této zásilce v budoucnu přidávat/odebírat balíky speciálním XML požadavkem
productstring(255)IN TIME produkt, který má být použit při doručení zásilky; v případě, že element není vyplněn, je vybrán automaticky produkt odpovídající parametrům zásilky; seznam možných produktů lze vyžádat na obchodním oddělení IN TIME
pup_branchstring(9)Kód výdejního místa; povinné pole, pokud je produktem doručení na výdejní místo
pup_contactstring(15)české mobilní telefon příjemce zásilky doručené na výdejní místo; povinné pole, pokud je produktem doručení na výdejní místo
additional_serviceobjectseznam doplňkových služeb
cash_on_deliveryfloatnehodnota dobírky v CZK
reverse_orderboolnepožadavek na službu „zpětná zásilka“
direct_orderboolnepožadavek na službu „přímá zásilka“
exchange_orderboolnepožadavek na službu „výměnná zásilka“
exchange_order_notestring(255)nepoznámka ke službě výměnná zásilka
document_backboolnepožadavek na službu „dokumenty zpět“
dokument_back_notestring(255)nepoznámka ke službě „dokumenty zpět“
insuranceboolnepožadavek na službu „připojištění“
phone_notificationboolnepožadavek na službu „telefonické potvrzení doručení zásilky“
phone_notification_numberstring(15)netelefonní číslo pro „telefonické potvrzení doručení zásilky“ příjemci v mezinárodním formátu (např. 00420123456789)
phone_notification_number_directstring(15)netelefonní číslo pro „telefonické potvrzení vyzvednutí zásilky u odesílatele“ v mezinárodním formátu (např. 00420123456789); využívá se pouze v případě přímé zásilky (direct_order)
phone_notification_notestring(255)nepoznámka ke službě „telefonické potvrzení doručení zásilky“
sms_notificationboolnepožadavek na službu „SMS potvrzení doručení zásilky“
sms_notification_numberstring(15)netelefonní číslo pro „SMS potvrzení doručení zásilky“ příjemci v mezinárodním formátu (např. 00420123456789)
sms_notification_number_directstring(15)netelefonní číslo pro „SMS potvrzení vyzvednutí zásilky u odesílatele“ v mezinárodním formátu (např. 00420123456789); využívá se pouze v případě přímé zásilky (direct_order)
email_notificationboolnepožadavek na službu „emailové potvrzení doručení zásilky“
email_notification_addressstring(50)neadresa pro „emailové potvrzení doručení zásilky“ příjemci
email_notification_address_directstring(50)neadresa pro „emailové potvrzení vyzvednutí zásilky u odesílatele“; využívá se pouze v případě přímé zásilky (direct_order)
carryboolnepožadavek na službu „donos“
lossboolnepožadavek na službu odnos
pay_by_receiverboolnepožadavek na službu „dopravu platí příjemce“
authenticationboolnepožadavek na službu „ověření totožnosti příjemce“
authentication_notestring(255)nepoznámka ke službě „ověření totožnosti příjemce“
takeoverboolnepožadavek na službu „osobní odběr“
takeover_placeintegerneidentifikátor požadovaného místa pro osobní odběr

Odpověd obsahuje:

{
  "order_number": "cislo zasilky intime",
  "reference_number": "",
  "barcode": [], //seznam carovych kodu baliku
  "sorting_code": "smerovy kod",
  "product_name": "nazev produktu",
  "delivery_price": 1.23, // cena za doruceni
}

/package/:order_number

GET

Vrátí informace o existující zásilce.

PUT

Úprava detailu zásilky (dobírka, váha, …)

Obsah JSON požadavku obsahuje slovník s těmi poli, která chcete měnit:

{
  "weight": 12.34, // v KG
  "value": 2134.56, // v CZK
  "cash_on_delivery": 1234.56 // v CZK
}

DELETE

Zruší zasilku, která ještě nebyla odeslána ke zpracování.

/package/:order_number/colli/add

POST

Přidá balíky k existující zásilce.

Obsahem požadavku je:

{
  "colli_count": 3 // pocet colli
}

/package/:order_number/colli/remove

POST

Odebere balíky ze zásilky.

Obsahem požadavku je:

{
  "colli_count": 3 // pocet colli
}

/package/:id/labels.{pdf|zpl}

GET

Získá štítky pro zásilku v zadaném formátu.

GET parametr skip_first určuje, kolik pozicí na archu se přeskočí.

GET parametr format určuje velikost štítku pro formát PDF. Možné varianty jsou: label, a4_2x2, a4, a6.

/batch

POST

Vytvoří a odešle dávku zásilek ke zpracování.

Obsahem požadavku je:

{
  "articles": ["Seznam", "cisel", "zasilek"]
}

/batch/:number

GET

Získá detaily o odeslané dávce (seznam zásilek v dávce, odkazy na svozový protokol a štítky).

/batch/:number/manifest.pdf

GET

Získá svozový protokol pro zadanou dávku jako PDF.

/batch/:number/labels.pdf

GET

Získa štítky pro zadanou dávku jako PDF.

GET parametr skip_first určuje, kolik pozicí na archu se přeskočí.

GET parametr format určuje velikost štítku pro formát PDF. Možné varianty jsou: label, a4_2x2, a4, a6.