Chameleoon dokumentácia Help

Definícia API pre externý systém

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?=

    • 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í) }
Last modified: 12 April 2024
Externý systém FastCentrik