Informování o stavech zásilek - One by Allegro

PUSH stavů

One by Allegro nabízí možnost zasílání stavu formou PUSH - tedy že stavy zásilek jsou zákazníkům reportovany v době jejich vzniku. Odpadá nutnost opakovaného dotazování na stav zásilky. Reportování je možné mnoha způsoby a vždy se přizpůsobuje konkrétnímu zákazníkovi. Ke komunikaci se zákaznickým systémem lze použít RESTAPI, SOAP, XMLRPC, FTP a různé datové typy (CSV, XML, JSON). Tato forma datové výměny se hodí pro větší zákazníky a jejich implementace do systémů.

PULL stavů

Pro běžné použití je připraveno PULL rozhraní, kdy každý zákazník dostane přidělenu unikátní URL pro přístup k stavům zásilek (žádost o toto URL provede zákazník přes svého obchodního zástupce). Pomocí HTTP GET požadavku na toto URL dostane zákazník stavy zásilek, které vznikly od posledního dotazu. Data lze získat i historicky / zpětně, max. ale 90 dni nazpět. Zákazník si může vybrat z formátu CSV, XML nebo JSON.

Základní URL ma tvar: https://bridge.intime.cz/states/__ID_ZAKAZNIKA__

__ID_ZAKAZNIKA__ nahradit identifikátorem, obdrženým při registraci

Historická data od určitého data lze získat po přidání parametru "history" do URL: https://bridge.intime.cz/states/__ID_ZAKAZNIKA__/history/YYYY-MM-DD

YYYY: rok od kdy získat data
MM: měsíc od kdy získat data
DD: den od kdy získat data

Historická data lze získat i v určitém intervalu (OD - DO) a to opět přidáním parametru "history" do URL, následovaným datumy OD:DO: https://bridge.intime.cz/states/__ID_ZAKAZNIKA__/history/YYYY-MM-DD/AAAA-BB-CC

YYYY: rok od kdy získat data
MM: měsíc od kdy získat data
DD: den od kdy získat data
AAAA: rok do kdy získat data
BB: měsíc do kdy získat data
CC: den do kdy získat data

Formát vrácených dat se ovlivňuje přidáním koncovky .csv .xml nebo .json na úplný konec URL (bez uvedení formátu je defaultně použito CSV).

Vrácené stavy:

CANCELED: zásilka stornována
DELIVERED: zásilka doručena
TEMPORARY_FAIL: nedoručení zásilky
RETURNING: zásilka směrována zpět odesílateli
RETURNED: zásilka vrácena odesílateli
DELIVERING: doručování zásilky
MANIFESTED: zásilka založena v systémech One by Allegro
STORED: pohyb zásilky na depu One by Allegro
ON_BRANCH: zásilka připravena k vyzvednutí na výdejním místě

Příklady URL:

https://bridge.intime.cz/states/__ID_ZAKAZNIKA__
https://bridge.intime.cz/states/__ID_ZAKAZNIKA__.csv
https://bridge.intime.cz/states/__ID_ZAKAZNIKA__/history/YYYY-MM-DD.json
https://bridge.intime.cz/states/__ID_ZAKAZNIKA__/history/YYYY-MM-DD/AAAA-BB-CC.xml

Popis datových formátu

CSV

Oddělovač polí je středník
Konec řádku \n

Obsah každého řádku:

timestamp;order;barcode;reference;status;lat;long

timestamp: datum a čas vzniku stavu (formát dle ISO 8601)
order: číslo zakázky
barcode: barkód balíku pro který stav nastal
reference: zákaznická reference zadaná u dané zásilky
status: stav
lat: gps souřadnice (zeměpisná šířka) vzniku stavu
long: gps souřadnice (zeměpisná délka) vzniku stavu

Příklad:

2016-07-04 21:09:57.00;00100076001;001O00076001*001001;8600282;DELIVERED;0.0;0.0
2016-06-30 16:51:30.00;00100079002;001S00079002*001001;32145;DELIVERED;50.75775448;15.07783541
2016-06-30 17:33:05.00;00100079003;001S00079003*001001;SPOTR_MAT;DELIVERED;49.95927413;14.6836223
2016-06-30 17:35:28.00;00100079004;001-00079004*001001;TRANSIT;TEMPORARY_FAIL;50.02075822;15.65415596

JSON

Datový typ objekt s jedním klíčem "data", který má jako hodnotu pole objektů s informacemi o stavech.
barcode: barkód balíku pro který stav nastal
gps_lat: gps souřadnice (zeměpisná šířka) vzniku stavu
gps_lng: gps souřadnice (zeměpisná délka) vzniku stavu
order: číslo zakázky
reference: zákaznická reference zadaná u dané zásilky
status: stav
timestamp: datum a čas vzniku stavu (formát dle ISO 8601)

Příklad:

{
  "data": [
    {
      "barcode": "001-00079001*001001", 
      "gps_lat": 50.02100267, 
      "gps_lng": 15.65398723, 
      "order": "00100079001", 
      "reference": "TRANSIT", 
      "status": "DELIVERED", 
      "timestamp": "2016-07-04 16:51:42.00"
    }, 
    {
      "barcode": "001S00079002*001002", 
      "gps_lat": 0.0, 
      "gps_lng": 0.0, 
      "order": "00100079002", 
      "reference": "30062016", 
      "status": "TEMPORARY_FAIL", 
      "timestamp": "2016-07-04 17:11:20.00"
    }, 
    {
      "barcode": "007S00079003*002002", 
      "gps_lat": 0.0, 
      "gps_lng": 0.0, 
      "order": "00100079003", 
      "reference": "30062016", 
      "status": "RETURNED", 
      "timestamp": "2016-07-04 17:11:23.00"
    }
  ]
}

XML

ROOT element je "data" a poté pro každý stav jednotlivý element "event"
Element "event" obsahuje atribut "timestamp", který obsahuje datum a čas vzniku stavu a atribut "status" se stavem
Element "order" obsahuje číslo zásilky
Element "barcode" obsahuje barkód balíku
Element "reference" obsahuje zákaznickou referenci zadanou u zásilky
Element "gps" obashuje vnořené elementy "lat" (gps souřadnice zeměpisné šířky) a "lng" (gps souřadnice zeměpisné délky) vzniku stavu
XSD není poskytnuto

Příklad:

<data>
  <event timestamp="2016-07-04 16:51:42.00" status="DELIVERED">
    <order>00100079001</order>
    <barcode>001-00079001*001001</barcode>
    <reference>TRANSIT</reference>
    <gps>
      <lat>50.02100267</lat>
      <lng>15.65398723</lng>
    </gps>
  </event>
  <event timestamp="2016-07-04 17:11:20.00" status="TEMPORARY_FAIL">
    <order>00100079002</order>
    <barcode>001S00079002*001002</barcode>
    <reference>30062016</reference>
    <gps>
      <lat>0.0</lat>
      <lng>0.0</lng>
    </gps>
  </event>
  <event timestamp="2016-07-04 17:11:23.00" status="RETURNED">
    <order>00100079003</order>
    <barcode>001S00079003*002002</barcode>
    <reference>30062016</reference>
    <gps>
      <lat>0.0</lat>
      <lng>0.0</lng>
    </gps>
  </event>
</data>