API 3.0 - Chameleoon

Autorizácia

API Key
- V aplikácií bude možnosť zadať statický klúč ktorý sa pošle ako parameter v url adrese alebo sa pridá do hlavičky HTTP požiadavky
- Názov parametra bude možné zadať v aplikácií
- Príklad v url adrese:
  https://www.example.sk/shipping-order?{nazov_parametra}={api-key}
- Príklad v hlavičke:
  headers: {
  "{nazov_parametra}": "{api-key}"
  }
Bearer token
- V aplikácií bude možnosť zadať statický token ktorý sa odošle v hlavičke požiadavky pod klúčom Authorization
- Musí to byť kľúč s dlhou životnosťou
- Príklad:
  headers: {
  "Authorization": "Bearer {token}"
  }
Basic auth
- V aplikácií bude možnosť zadať statické meno a heslo
- Údaje sa môžu odoslať 2 spôsobmi:
  - V hlavičke request pod kľúčom Authorization vo formáte {meno}:{heslo} a zakódované v Base64
  - Pomocou x-www-form-urlencoded pod názvami parametrov ktoré sa definujú v aplikácií

Očakávené API na strane externého systému

Je potrebné aby systém mal zabudované verejné rozhranie pre vrátenie objednávok prepravy, podľa našej schémy, na základe dátumu a vrátenie objednávky prepravy na základe ľubovoľného identifikátora.

Očakávaný dátumový formát 'yyyy-MM-ddTHH:mm:ss'
Očakávaný formát čísiel #.####

Očakávaný formát objednávky prepravy:

{
 "addressee": string | null,            // Príjemca
 "organizationName": string | null,     // Názov spoločnosti
 "street": string | null,               // Ulica a číslo domu pre doručenie
 "street2": string | null,              // Detail miesta doručenia
 "phone": string | null,                // Tel. číslo
 "email": string | null,                // Email
 "city": string | null,                 // Mesto doručenia
 "zipCode": string | null,              // PSČ
 "countryCode": string | null,          // Kód krajiny ISO 3166-1 Alpha 2
 "note": string | null,                 // Poznámka k preprave
 "referenceNumber": string,             // Povinný údaj - Referencia na záznam v externom systéme
 "courierService": string | null,       // Označenie kuriéra v externom systéme
 "weight": decimal | null,              // Celková váha položiek objednávky
 "packageCount": int | null,            // Počet balíkov ak je známy (pozn. ak nie je známy je lepšie  nechať null)
 "codPrice": decimal | null,            // Hodnota dobierky, ak už bola objednávka uhradená kartou, bank. prevodom alebo iným spôsobom nechať null
 "stateId": string | null,              // Stav objednávky v externom systéme
 "createDateTime": string,              // Povinný údaj - Dátum vytvorenia objednávky vo formáte 'yyyy- MM-ddTHH:mm:ss' (napr. 2020-01-31T10:14:13)
 "publicPackagePoint": string | null,   // Id odberného miesta (napr. pri kuriérovi Zásielkovňa alebo DPD pickup point, ...)
 "isBackShipping": boolean,             // Príznak či sa jedná o objednávku vrátenia tovaru
 "orderedShippingDate": string | null,  // Očakávaný dátum doručenia tovaru, ak je známy  vyplniť vo formáte 'yyyy-MM-ddTHH:mm:ss' (napr. 2020-01-31T10:14:13)
 "currency": string,                    // Povinný údaj - Mena dobierky
 "driverNote": string | null,           // Poznámka pre vodiča
 "contactPerson": string | null,        // Kontaktná osoba
 "variableSymbol": string | null,       // Variabilný symbol - ak nie je vyplnený v systéme sa použije referenčné číslo
 "description": string | null,          // Popis tovaru pre kuriéra
 "documentType": "order" | "invoice" | "issue",
 "paymentType": string,                 // Povinný údaj - identifikátor spôsobu úhrady v externom systéme
 "totalPrice": decimal,                 // Povinný údaj - celková suma objednávky
 "items": [
  {
   "id": string,                  // Povinný údaj - identifikátor položky
   "code": string | null,         // Kód produktu
   "eanCode": string | null,      // EAN produktu
   "name": string,                // Povinný údaj - Názov produktu
   "text": string | null,         // Názov položky
   "quantity": decimal,           // Povinný údaj - množstvo
   "measureUnit": string | null   // Merna jednotka
  }
 ]
}

Všeobecné nastavenia

Všeobecné nastavenia budú obsahovať tieto parametre:

Url adresu externého systému
Typ autorizácie
Potrebné parametre pre autorizovanie požiadavky

Vrátenie objednávok prepravy na základe dátumového rozsahu

Funckia pre vrátenie objednávok prepravy na základe dátumového rozsahu može byť na ľubovoľnej adrese. Adrese sa zadá v aplikácií (napr. /api/shipping-orders). Adresa by mala očakávať parametre:

Minimálny dátum, názov parametra date_from
Maximálny dátum, názov parametra date_to
Môže očakávať ľubovoľné parametre ktoré bude možné zadať v aplikácií
- Príklad:
  &stav_objednávky=nova

Funkcia musí vrátiť zoznam objednávok preprav vo formáte application/json.

Vrátenie objednávky prepravy na základe identifikátora

Funkcia pre vrátenie objednávky prepravy na základe identifikátor može byť na ľubovoľnej adrese ale musí obsahovať dynamický parameter (napr. /api/shipping-orders/{0}). Adresa može očakávať parametre:

Môže očakávať ľubovoľné parametre ktoré bude možné zadať v aplikácií
- Príklad:
  &stav_objednávky=nova

Funkcia vráti objednávku prepravy vo formáte application/json.
V prípade že záznam nebol nájdený vráti odpoveď s kódom 404 not found

Zmena stavu objednávky a zapísanie čísla prepravy

Funkcia pre zmenu stavu objednávky a zapísanie čísla prepravy môže byť na ľubovoľnej adrese. Musí obsahovať dynamický parameter (napr. /api/orders/{0}).

Odosielať sa bude požiadavka typu PUT ktorá bude obsahovať dáta v tele požiadavky

{
 "courier": string | null,         // Identifikátor kuriéra v externom systéme, ak sa nezmenil parameter ostane null
 "shippingNumber": string | null,  // Číslo prepravy pridelené kuriérom
 "targetState": string | null,            // Identifikátor stavu v externom systéme v prípade záujmu o zmenu stavu  
 "packageCount": number
   }