Definícia API pre externý systém

Autorizácia

Z dôvodu bezpečnosti je potrebné implementovať autorizáciu API, ktorú môžete vykonať následujúcimi spôsobmi:

API key

V aplikácii 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ácii.

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ácii 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é
Pomocou ``x-www-form-urlencoded`` pod názvami parametrov, ktoré sa definujú v aplikácii

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

Je potrebné, aby mal systém 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🇲🇲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 v kg
 "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
  }
 ],
 "packages": [ // Atribút "packages" predstavuje počet balíkov, ktoré budú odovzdané kuriérovi. Počet položiek na objednávke sa nemusí rovnať počtu balíkov, ktoré sa odovzdajú kuriérovi (používa sa iba pri niektorých dopravcov, predovšetkým pri paletových). Tento atribút vypĺňajte len po konzultácií s podporou.
    {
        "cover": string | null, // Kód obalu (pre získanie zoznamu kódov kontaktujte podporu)
        "weight": decimal | null, // Váha balíka v kg
        "width": decimal | null, // Šírka balíka v cm
        "height": decimal | null, // Výška balíka v cm
        "length": decimal | null, // Dĺžka balíka v cm
        "description": string | null, // Popis obsahu tovaru
        "volume": decimal | null // Objem balíka v m3
    }
 ]
}

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

Implementácia funkcii

Aby ste mohli plne využívať hromadnú expedíciu, kontrolu výdaja alebo automatickú zmenu stavu objednávok vo Vašom e-shope, je potrebné, aby ste implementovali následovné funkcie:

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. Adresa sa zadá v aplikácii.

Príklad:
/api/shipping-orders

Adresa by mala očakávať parametre:

1. Minimálny dátum, názov parametra date_from

2. Maximálny dátum, názov parametra date_to

Môže očakávať ľubovoľné parametre, ktoré bude možné zadať v aplikácii.

Príklad:
&stav_objednávky=nova

POZOR: 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átorov može byť na ľubovoľnej adrese, ale musí obsahovať dynamický parameter.

Príklad:
/api/shipping-orders/{0}

Adresa môže očakávať ľubovoľné parametre, ktoré bude možné zadať v aplikácii

Príklad:
&stav_objednávky=nova

POZOR:

Funkcia musí 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.

Príklad:
/api/orders/{0})

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

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

Očakávaný formát:

        {
           "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ášť
        }
        

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

Funkcia pre vrátenie objednávok podľa zvolených stavov. Adresa sa zadá v aplikácii.

Príklad:
/api/shipping-orders/orders-by-states

Adresa by mala očakávať parametre:

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

POZOR: Funkcia musí vrátiť zoznam objednávok prepráv 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. Adresa sa zadá v aplikácii.

Príklad:
/api/shipping-orders/available-states

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

Očakávaný formát:

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

Last modified: 26 November 2024