PARTNER-KALAUZ
Čeština Němčina Angličtina Chorvatština Maďarština Polština Slovenština Vietnamština
Bevezetés Gyakorlati utasítások Informatikai támogatás Harmadik fél API

Harmadik fél API

Ez a cikk gépi fordítású.

Az API a Slevomat és a kereskedési partner rendszere közötti megrendelési információk átvitelére szolgál. Az API kétirányú kommunikáció megvalósítását igényli – a Slevomat rendszere hívja a partner API-ját, a partner pedig a Slevomat API-ját.

A partner API-ba exportált megbízásokat a Slevomat partnerfelületén már nem lehet manipulálni, csak megtekinteni. Az exportált megbízások manipulálása csak az API-n keresztül történhet.

Minden kérést HTTPS-en keresztül kell végrehajtani, és minden adat JSON formátumban van.

API hozzáférés

Az API hitelesítő adatokat a partner felületének Beállítások fülén keresztül érheti el. Az adatok lekérdezéséhez meg kell adnia az API partneri részének gyökér URL-jét a Slevomat → Partner irányban, pl. 

https://example­.com/slevomat-zbozi-api

A hozzáférési adatok csak egyszer jelennek meg az API-hoz való hozzáféréskor, ezért kérjük, gondosan tárolja azokat.

Az API elérését követően a rendszer elkezdi az újonnan létrehozott megrendelések exportálását az API-ba.

Kezdeti adatexport

A meglévő megrendelések átviteléhez az API-hozzáférés pillanatában egyszeri CSV exportálást használhat a partnerfelületen.

Ha meglévő (az API elérhetővé tétele előtt létrehozott) megrendelései vannak a saját rendszerében, és az API-n keresztül szeretne velük dolgozni, használja a "Megjelölt megrendelésekkel való munka megkezdése API-n keresztül" funkciót a "Tömeges műveletek megrendelésekkel" menüben.

A gyakori HTTP-válaszok leírása

  • 200 OK – a kérést sikeresen feldolgozták
  • 204 No Content – a kérés feldolgozása megtörtént, a válasznak nincs tartalma
  • 400 Bad Request – a kérés érvénytelen – a specifikációval ellentétes paraméterek hiányozhatnak vagy érvénytelenek lehetnek.
  • 403 Forbidden – az ügyfél engedélyezése sikertelen
  • 404 Not Found – a végpont vagy a szükséges adatok nem találhatók
  • 405 Method Not Allowed – a végpont nem támogatja ezt a HTTP-módszert
  • 422 Unprocessable Entity – várható hiba a kérés feldolgozása során (lásd a Hibakörülmények című részt).
  • 500 Internal Server Error – hiba történt a szerveroldalon
  • 502 Bad Gateway – szerveroldali hiba történt
  • 503 Service Unavailable – a szerver karbantartási üzemmódban van (új verzió telepítése folyamatban van, vagy tervezett leállás van)
  • 504 Gateway Timeout – szerveroldali hiba történt

A HTTP 5×x válaszok nem használhatnak JSON formátumot.

A 4xx hiba esetén a kimenő kérés hibás, és az újbóli próbálkozás előtt ki kell javítani.

A 5xx hibák szerverhibát jeleznek, és a kérés módosítás nélkül újrapróbálható. A 503 esetében a hívónak tiszteletben kell tartania a Retry-After válaszfejlécet, és csak a fejlécben megadott idő elteltével szabad újrapróbálkoznia.

Rendelési állapotok

Egy megrendelés mindig a következő állapotok egyikében van:

Állapot értéke Leírás
1 Új fizetett megrendelés
2  Kezelt
3  Úton (csak a szállításos rendelések)
4  Személyes átvétel előkészítése – pl. szállítás a fiókba
5  Személyes átvételre kész
6  Kiszállítva a megrendelőnek – a megrendelői visszaigazolásra várva
7  Kiszállítva és a megrendelő által visszaigazolva
8  Az ügyfél megtagadta a megrendelés átvételének visszaigazolását
9  Törölt megrendelés

A megrendelőt e‑mailben értesítjük a státusz változásáról.

A megrendelésnek nem feltétlenül kell végigmennie az összes státuszon a sikeres kiszállításhoz, az "Új megrendelés kifizetve" állapotból egyenesen az "Úton" / "Személyes átvételre kész", majd a "Kiszállítva az ügyfélnek – az ügyfél megerősítésére vár" állapotba lehet lépni. Az összes státusz használata azonban jobb ügyfél-tájékoztatást eredményez a megrendelés előrehaladásáról, ezért ajánlott.

Hibaállapotok

A 4×x HTTP-kódok esetében a válasz mindig tartalmazza a status kulcsot (lásd az alábbi kódkönyvben) és a messages mezőt a hibák szöveges leírásával.

Állapot érték Leírás
1  Érvénytelen kérés – hiányzó vagy érvénytelen értékek
2  Érvénytelen bejelentkezési adatok
3  Nem létező sorrend
4  Nem létező rendelési tétel
5  A megbízás engedély nélküli állapotba való átmenete
6  Érvénytelen törlés – több tétel törlése, mint amennyi létezik
7  Egyéb hiba
8  A megrendelés még nem került exportálásra a partner API-ba – az API-n keresztül nem lehet manipulálni.
9  A "Vevőnek kézbesített áru" státusz automatikus beállításához a küldeményt automatikusan "Átvételre kész áru" állapotba kell állítani.

Példa: 

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Adattípusok

Az egyes kulcsok adattípusai a kérésekben és válaszokban mindig az adott végpontokhoz vannak leírva. Eltérő rendelkezés hiányában a "" idézőjelben megadott érték mindig kötelező karakterlánc. Eltérő rendelkezés hiányában a numerikus érték mindig kötelező egész szám.

Kommunikáció Slevomat ⇒ Partner

Az API ezen része a partner oldalán van implementálva, és a Slevomat hívja meg.

A szükséges API gyökér URL-t a partner adja meg, és a következő formájúnak kell lennie 

 https://www.example.com/slevomat-zbozi-api/v1

Engedélyezés kérése

Ha az API engedélyezve van, a partner megkapja a partner_api_se­cret címet, amely bizonyítja, hogy a bejövő kérések valóban a Slevomat-tól származnak.

Ez a paraméter a X-PartnerApiSecret HTTP fejlécben kerül átadásra.

Teszt interfész

A Slevomat tartalmaz olyan funkciókat, amelyekkel az API-t a partneroldalon meg lehet hívni és a választ meg lehet tekinteni. A partner által az API elérhetővé tételekor megadott gyökér-URL a -test címhez van csatolva, így a tesztelés során az API meghívása pl. a következő címen történik. 

https://example­.com/slevomat-zbozi-api-test

hogy a tesztadatok ne keveredjenek az éles megbízásokkal.

A partner API tesztelése a következő címekre küldött POST kérésekkel történik: 

  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order
    - Új rendelés 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates
    - A várható szállítási dátumok tömeges frissítése 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered
    - A megrendelés státuszának módosítása "Kiszállítva a vevőnek – vevői visszaigazolásra várva" 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup
    - A megrendelés státuszának módosítása "Személyes átvételre kész". 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery
    - Szállítási visszaigazolás 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery
    - Az elfogadás megtagadása 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel
    - Lemondás

Helyettesítse az URL <orderId> részét bármilyen rendelésszámmal, a partner API-hoz intézett kérések ezzel a rendelésszámmal történnek.

Az ehhez a tesztinterfészhez érkező kéréseket a X-PartnerToken és a X-ApiSecret fejlécekkel kell engedélyezni.

A partner API teszthívásakor a rendszer a X-PartnerApiSecret fejlécet küldi, ahogyan az éles üzemben is.

Az új megrendeléssel együtt küldött adatok tesztadatok és véletlenszerűen generáltak.

A rendelés törlésének elküldése esetén a kérés POST testébe JSON-ban (az API által küldött formátumban) be kell illeszteni a items mezőt, amelyet a tesztelési felület validál és ugyanebben a formában továbbít a partner API-nak.

Új megrendelés

A kérés az újonnan létrehozott megrendelés adatait tartalmazza.

A megrendelések mindig egyedi slevomatId címmel rendelkeznek. Ha az API duplikált slevomatId kap, a kérést a partner API-nak figyelmen kívül kell hagynia (az első kérést a Slevomat sikertelennek értékelte, ezért megismétli), és a válasznak is HTTP 204 kell lennie.

created a dátum ISO 8601 formátumban, azaz YYYY-MM-DD'T'HH:mm:ss­+zz:zz.

productId tartalmazza az esemény azonosítóját, variantId a megvásárolt változat azonosítóját.

Az opcionális internalId az akcióváltozatnak a partnerfelületen történő létrehozásakor megadott belső azonosítóját jelzi. Ez a termék azonosítására szolgál a partner rendszerében.

A billingAddress (számlázási cím) alatt csak az ügyfél neve (name) kötelező.

A shippingAddress (szállítási cím) alatt a cég (company) megadása nem kötelező. A shippingAddress címre történő szállítás esetén az ügyfél címét tartalmazza, személyes átvétel esetén annak a létesítménynek a címét, ahol az ügyfél az árut átveszi.

A delivery.type kulcs a address (szállítás címre) vagy a pickup (személyes átvétel) értéket veheti fel. delivery.name tartalmazza a szállítás vagy a telephely nevét.

delivery.expec­tedShippingDa­te (várható szállítási dátum) és delivery.expec­tedDeliveryDa­te (várható szállítási dátum) a YYYY-MM-DD.

A weight kulcs a megrendelés súlyát tartalmazza kilogrammban. Ha nem ismerjük a rendelés összes tételének súlyát, akkor a null értéket veszi fel.

POST /rendelés/$slevomatId 

{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /rendelés/$slevomatId 

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShip­pingDate": "2021–09–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

A várható szállítási dátumok tömeges frissítése

Ha az ügyletkezelő a partner kérésére a kiválasztott megrendelések szállítási dátumait tömegesen áthelyezi, a rendszer tájékoztatja a partner API-t erről a frissítésről.

A küldött adatok tartalmazzák a megrendelés azonosító mezőjét és az új várható szállítási dátumot. 

POST /update-shipping-dates
{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Lemondás

A lemondásokat a Slevomat oldalán és a partner rendszerében is létre lehet hozni. Ez a végpont kezeli a törlés létrehozását a Slevomat oldalán és annak átvitelét a partner rendszerébe.

Létrehozza a megadott mennyiségű rendelési tételek törlését. Ha a teljes megrendelést kell törölni, akkor a megfelelő mennyiséggel rendelkező összes tétel felsorolásra kerül.

Egyes tételek részlegesen is törölhetők (pl. 2 tételből 1).

A törlési megjegyzés (note) nem kötelező. 

POST /order/$slevo­matId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Kézbesítési visszaigazolás

Miután a megrendelést "Kiszállítva a vevőnek" jelzéssel látja el, megkérjük a vevőt, hogy erősítse meg, hogy valóban megkapta a megrendelést. Amikor a megrendelés átvettnek van jelölve, ez a végpont meghívásra kerül. 

POST /order/$slevo­matId/confirm-delivery
{}

Az elfogadás megtagadása 

POST /order/$slevo­matId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

A megrendelés státuszának módosítása "Személyes átvételre kész" státuszra.

Ez a végpont akkor hívódik meg, ha a previous "Személyes átvételre kész" státuszt a autoMarkRea­dyForPickuptrue segítségével állította be, és a Slevomat oldalán a megrendelés automatikusan "Személyes átvételre kész" státuszra változott. 

POST /order/$slevo­matId/delivery-ready-for-pickup
{}

A megrendelés státuszának módosítása "Kiszállítva a vevőnek – vevői visszaigazolásra várva"

Ez a végpont akkor hívódik meg, ha a previous "Úton", "Személyes átvételre kész" vagy "Személyes átvételre kész" státusz lett beállítva a autoMarkDeli­veredtrue segítségével, és a megrendelés automatikusan átváltott a "Kiszállítva az ügyfélnek – ügyfél megerősítésre vár" státuszra a Slevomat oldalán. 

POST /order/$slevo­matId/mark-delivered
{}

Kommunikációs partner ⇒ Slevomat

Az API ezen része a Slevomat oldalán van implementálva, és a partner rendszer hívja meg.

Az API gyökér URL címe a következő 

 https://www.slevomat.cz/zbozi-api/v1

PHP könyvtár

Az API ezen oldalának megvalósításához használhatja az előkészített PHP-könyvtárat. A könyvtárhoz jelenleg PHP 5.4 vagy magasabb verziószámú PHP szükséges, és a Composer használata szükséges.

A könyvtár használatára vonatkozó utasítások és a forráskód a GitHubon található.

Engedélyezés kérése

Ha az API engedélyezve van, a partner megkapja a partner_token és a api_secret címeket, amelyekkel a Slevomat API hívásakor hitelesíti magát.

Ezeket a paramétereket a X-PartnerToken és a X-ApiSecret fejlécekben adják át.

Teszt interfész

A teszt interfész gyökér URL címe a következő 

https://www.slevomat.cz/zbozi-api/v1-test

Minden művelet ugyanúgy meghívható rajta, mint az éles felületen.

A tesztfelület ellenőrzi a kérések jogosultságát (a partner token és az API-titok helyességét) és a beérkező kérések testének (JSON) érvényességét. Ezekben a vonatkozásokban ugyanúgy viselkedik, mint az éles API.

A tesztelési felület azonban nem működik tényleges megrendelésekkel. Így nem ellenőrzi, hogy egy megrendelés a megfelelő állapotok között átmegy-e, és hogy tartalmaz-e a megadott azonosítókkal rendelkező tételeket. Miután a kérés engedélyezése és űrlap-érvényesítése sikerül, a tesztfelület mindig 200-as vagy 204-es sikerkóddal egyezik meg.

Lemondás létrehozása

Létrehozza a megadott mennyiségű rendelési tételek törlését. Ha a megrendelés teljes egészében törlésre kerül, akkor a megfelelő mennyiséggel rendelkező összes tétel felsorolásra kerül.

Egyes tételek részlegesen is törölhetők (pl. 2-ből 1).

A törlési megjegyzés (note) nem kötelező.

POST /order/$slevomatId/cancel 

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

A megrendelés státuszának módosítása "Függőben"

POST /rendelés/$slevomatId/mark-pending 

{}

A megrendelés státuszának módosítása "Úton"

Egy megrendelés esetében a autoMarkDelivered paraméterrel megadható, hogy a megrendelés egy meghatározott szállítási idő ("A feladástól a szállításig eltelt idő") után automatikusan átálljon-e a "Kiszállítva az ügyfélnek – az ügyfél megerősítésére vár" státuszra.

A válasz egy frissített becsült szállítási dátumot tartalmaz.

POST /rendelés/$slevomatId/mark-en-route 

{ "autoMarkDeli­vered": true }

Válasz 200 

{ "expectedDeli­veryDate": "2021–08–25" }

A megrendelés státuszának módosítása "Személyes átvételre készen".

A autoMarkReady­ForPickup paraméterrel megadhatja, hogy a megrendelés a feladástól a kézbesítésig eltelt idő után automatikusan "Személyes átvételre kész" státuszra váltson-e egy adott típusú átvételi pont esetében.

Egy megrendelés esetében a autoMarkDelivered paraméterrel megadható, hogy a megrendelés a "Személyes átvételre kész" státuszból automatikusan a "Kiszállítva a vevőnek – vevői visszaigazolásra vár" státuszba váltson-e egy adott típusú átvételi ponton történő átvételre meghatározott számú nap elteltével.

A autoMarkReady­ForPickup false és a autoMarkDelivered true paraméterek kombinációja nem megengedett. Ebben az esetben a 9-es hibakód kerül visszaküldésre.

A válasz tartalmazza a frissített várható szállítási dátumot.

POST /rendelés/$slevomatId/mark-getting-ready-for-pickup 

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Válasz 200 

{ "expectedDeli­veryDate": "2021–08–25" }

A megrendelés státuszának módosítása "Személyes átvételre kész" státuszra

A autoMarkDelivered paraméterrel megadható, hogy a megrendelés egy meghatározott számú nap elteltével automatikusan átálljon-e a "Kiszállítva a vevőnek – vevői visszaigazolásra várva" státuszba, egy adott típusú gyűjtőhelyen történő átvételre. 

POST /order/$slevo­matId/mark-ready-for-pickup
{ "autoMarkDeli­vered": true }

A megrendelés státuszának módosítása "Kiszállítva a vevőnek – vevői visszaigazolásra várva" státuszra. 

POST /order/$slevo­matId/mark-delivered
{}

Változtassa meg a szállítási címet

A szállítási cím csak címre történő kézbesítés esetén módosítható (azaz a személyes átvétel helye nem módosítható).

A company cím kivételével minden kulcsra szükség van.

A state kulcs érvényes értékei: cz (Cseh Köztársaság) és sk (Szlovákia). 

POST /order/$slevo­matId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }

Changelog

Vissza a cikkek listájára

Kapcsolódó cikkek
Nahoru