REST API

Endpointy

Adresy API endpointu záměrně nejsou zveřejněny - předává je obchodní zástupce při akvizici.
Existuje jedno testovací prostředí a jedno produkční prostředí (bez ohledu na státy/produkty/služby).

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

/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",
  "box": "kod boxu",
  "box_contact": "mobilni tel. cislo prijemce",
  "additional_service": {...} // vybrane doplnkove sluzby
}

Možné datové prvky:

Název		Typ	Povinný	Popis
receiver		object		definuje příjemce zásilky; v případě, že není použit One by Allegro produkt box nebo výdejní místo, je tento element povinný
	external_id	string(255)	ne	identifikátor adresy z Aplikace Zásilky
	name	string(100)	ano	označení příjemce zásilky
	street	string(100)	ano	ulice + číslo popisné
	city	string(50)	ano	město
	postal_code	string(5)	ano	PSČ
	state	string(2)	ano	kód země dle ISO 3166-1; obchodní oddělení One by Allegro dodá seznam možných zemí
	firstname	string(30)	ne	křestní jméno
	surname	string(30)	ne	příjmení
	email	string(50)	ne	email
	phone	string(15)	ne	telefon
	mobile	string(15)	ne	mobilní telefon
	fax	string(15)	ne	fax
	note	string(75)	ne	poznámka
sender		object		povinný element v případě přímé zásilky (direct_order), definuje odesílatele zásilky
	external_id	string(255)	ne	identifikátor adresy z Aplikace Zásilky
	name	string(100)	ano	označení příjemce zásilky
	street	string(100)	ano	ulice + číslo popisné
	city	string(50)	ano	město
	postal_code	string(5)	ano	PSČ
	state	string(2)	ano	kód země dle ISO 3166-1; obchodní oddělení One by Allegro dodá seznam možných zemí
	firstname	string(30)	ne	křestní jméno
	surname	string(30)	ne	příjmení
	email	string(50)	ne	email
	phone	string(15)	ne	telefon
	mobile	string(15)	ne	mobilní telefon
	fax	string(15)	ne	fax
	note	string(75)	ne	poznámka
reference_number		string(20)	ne	referenční číslo/ID zásilky
reference_number2		string(50)	ne	druhé referenční číslo/ID zásilky
package_count		integer	ano	počet balíků v zásilce
package_number		string(50)	ne	volitelné čí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
weight		float	ano	celková váha zásilky v kg
volumetric_weight		float	ne	celková volumetrická váha zásilky v kg
value		float	ano	celková hodnota zásilky v CZK
comment		string(255)	ne	poznámka
additive		bool	ne	pož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
product		string(255)		One by Allegro 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í One by Allegro
pup_branch		string(10)		Kód výdejního místa; povinné pole, pokud je produktem doručení na výdejní místo
pup_contact		string(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
box		string(10)		Kód boxu; povinné pole, pokud je produktem doručení do boxu
box_contact		string(15)		Mobilní telefon příjemce zásilky doručené na výdejní místo; povinné pole, pokud je produktem doručení do boxu
additional_service		object		seznam doplňkových služeb
	cash_on_delivery	float	ne	hodnota dobírky v CZK
	reverse_order	bool	ne	požadavek na službu „zpětná zásilka“
	direct_order	bool	ne	požadavek na službu „přímá zásilka“
	exchange_order	bool	ne	požadavek na službu „výměnná zásilka“
	exchange_order_note	string(255)	ne	poznámka ke službě výměnná zásilka
	document_back	bool	ne	požadavek na službu „dokumenty zpět“
	dokument_back_note	string(255)	ne	poznámka ke službě „dokumenty zpět“
	insurance	bool	ne	požadavek na službu „připojištění“
	phone_notification	bool	ne	požadavek na službu „telefonické potvrzení doručení zásilky“
	phone_notification_number	string(15)	ne	telefonní číslo pro „telefonické potvrzení doručení zásilky“ příjemci v mezinárodním formátu (např. 00420123456789)
	phone_notification_number_direct	string(15)	ne	telefonní čí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_note	string(255)	ne	poznámka ke službě „telefonické potvrzení doručení zásilky“
	sms_notification	bool	ne	požadavek na službu „SMS potvrzení doručení zásilky“
	sms_notification_number	string(15)	ne	telefonní číslo pro „SMS potvrzení doručení zásilky“ příjemci v mezinárodním formátu (např. 00420123456789)
	sms_notification_number_direct	string(15)	ne	telefonní čí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_notification	bool	ne	požadavek na službu „emailové potvrzení doručení zásilky“
	email_notification_address	string(50)	ne	adresa pro „emailové potvrzení doručení zásilky“ příjemci
	email_notification_address_direct	string(50)	ne	adresa pro „emailové potvrzení vyzvednutí zásilky u odesílatele“; využívá se pouze v případě přímé zásilky (direct_order)
	carry	bool	ne	požadavek na službu „donos“
	loss	bool	ne	požadavek na službu odnos
	pay_by_receiver	bool	ne	požadavek na službu „dopravu platí příjemce“
	authentication	bool	ne	požadavek na službu „ověření totožnosti příjemce“
	authentication_note	string(255)	ne	poznámka ke službě „ověření totožnosti příjemce“
	takeover	bool	ne	požadavek na službu „osobní odběr“
	takeover_place	integer	ne	identifikátor požadovaného místa pro osobní odběr

Odpověd obsahuje pole prvků:

{
  "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
}

Doplňujicí informace:

Typy výdejních míst:

• intime
• ulozenka
• boxcz - pro boxy umístěné v ČR
• boxsk - pro boxy umístěné na slovensku

Pozn. Označení - PUP/BOXCZ/BOXSK je označení produktu

Limity - Počet balíků v zásilce je omezena na 99. Max. hmotnost, dobírka apod. je omezena dle jednotlivých produktů a VOP.

Dobírka - Vyplácení probíhá dvěma způsoby (způsob vypláceni nastavuje obchodní zástupce při akvizici zákazníka.)

1. Hromadná platba
2. Zákazník vždy obdrží report se souhrnem zísilek a jejich VS. U platby po zásilce se většinou použije identifikace VS uvedená v poli reference_number (což je obecne reference zákazníka).

/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 (pdf, zpl).

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.

Limity:
Štítky lze získat vždy pro celou zásilku. Nelze vrátit štítek pro konkrétní balík v zásilce. Lze max. určit pozici na archu štítků, které se na daném archu mají vynechat.

/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.