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í)
}