Externý systém API

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 : 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
 "streetDetail": 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.

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

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 zásielky pridelené kuriérom
   "targetState": string | null,     // Identifikátor stavu v externom systéme v prípade záujmu o zmenu stavu  
   "packageCount": number,
   "additionalShippingNumbers": string[] // Dodatočné čísla balíkov bez hlavného čísla balíka, ak ich cieľový kuriér generuje pre každý balík zvlášť
}

Funkcia neočakáva žiadné dáta v odpovedi. Je možné vrátiť odpoveď s kódom 204 no content.

Získanie objednávok podľa stavu objednávky

Funkcia pre vrátenie objednávok podľa zvolených stavov. Adrese sa zadá v aplikácií (napr. /api/shipping-orders/orders-by-states).

Adresa by mala očakávať parametre:

  • Zoznam stavov (string []), názov parametra states

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

Získanie stavov z externého systému

Funkcia pre získanie stavov objednávok z externého systému. Adrese sa zadá v aplikácií (napr. /api/shipping-orders/available-states).

Adresa neočakáva žiadne dodatočné parametre:

Očakávaný formát objektu:

{
   "value": string, // Identifikátor stavu
   "name": string   // Názov (bude zobrazovať v aplikácií)
}