Harmadik fél API

Az API a rendelési információk átvitelére szolgál a Slevomat és kereskedelmi partnerünk rendszere között. Az API megköveteli a kétirányú kommunikáció megvalósítását – a Slevomat rendszer a partner API-ját, a partner pedig a Slevomat API-t hívja meg.

A partner API-ba exportált rendelések a Slevomat partner felületén már nem manipulálhatók, csak megtekinthetők. Az exportált rendelések manipulálása csak az API-n keresztül történhet.

Minden kérést HTTPS-en kell benyújtani, és minden adat JSON formátumban van.

API hozzáférés

Az API hitelesítő adatait a partnerfelület Beállítások lapjáról érheti el. Az adatok beszerzéséhez meg kell adnia az API partner részének gyökér URL-jét a Slevomat → Partner irányba való használathoz, pl.

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

A hozzáférési adatok csak egyszer jelennek meg, amikor belép az API-ba, gondosan mentse el.

Az API elérése után a rendszer megkezdi az újonnan létrehozott rendelések exportálását.

Kezdeti adatexportálás

Az API hozzáférés pillanatában meglévő rendelések átviteléhez a partner felületén egyszeri exportálást használhat CSV-be.

Ha a saját rendszerében vannak már meglévő (az API elérhetővé tétele előtt létrehozott) rendelései, és az API-n keresztül szeretne velük dolgozni, használja a "Munka indítása megjelölt rendelésekkel API-n keresztül" funkciót a "Tömeges műveletek rendelésekkel" részben. menü.

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

• 200 OK – a kérést sikeresen feldolgoztuk
• 204 No Content – a kérést feldolgozták, a válasznak nincs tartalma
• 400 Bad Request – a kérés nem érvényes – előfordulhat, hogy hiányzó vagy érvénytelen paraméterek szerepelnek a specifikációban
• 403 Forbidden – az ügyfél hitelesítés sikertelen
• 404 Not Found – a végpont vagy a szükséges adat nem található
• 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 Hibafeltételek részt)
• 500 Internal Server Error – hiba történt a szerver oldalon
• 502 Bad Gateway – szerveroldali hiba történt
• 503 Service Unavailable – a szerver karbantartási módban van (lehet, hogy az új verzió telepítése folyamatban van, vagy tervezett leállás)
• 504 Gateway Timeout – szerveroldali hiba történt

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

Abban az esetben4xx hibák esetén a kimenő kérés hibás, és ki kell javítani az újrapróbálkozás előtt.

Hibák5xx jelzi a szerverhibákat, és a kérés megváltoztatása nélkül újra megpróbálható. Abban az esetben503 , a hívónak tiszteletben kell tartania aRetry-After válaszfejlécet, és csak a fejlécben megadott idő letelte után próbálkozzon újra.

Rendelési állapotok

A megrendelés mindig a következő állapotok valamelyikében van:

A vásárlót e‑mailben értesítjük az állapotváltozásról.

A sikeres kézbesítéshez nem kell feltétlenül minden státuszt átmennie a megrendelésnek, az „Új rendelés fizetve” lehetőségből közvetlenül az „Áru feladva” / „Személyes átvételre készen”, majd a „Kézbesítés a vevőnek – vásárlói visszaigazolásra várva” menüpontra lehet lépni. ". Az összes állapot használata azonban jobb tájékoztatást ad az ügyfeleknek a megrendelés folyamatáról, ezért ajánlott.

Hibaállapotok

4×x HTTP kódok esetén a válasz mindig tartalmazza a kulcsotstatus (lásd az alábbi kódkönyvet) és a mezőtmessages a hibák szöveges leírásával.

Példa:

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

Adattípusok

A kérésekben és válaszokban szereplő kulcsok adattípusai mindig meghatározott végpontokhoz vannak leírva. Eltérő rendelkezés hiányában az érték idézőjelben"" mindig kötelező karakterlánc. Ha nincs másképp megadva, a numerikus érték mindig egy kötelező egész szám.

Kommunikáció Slevomat ⇒ Partner

Az API ezen része a partner oldalon van implementálva, és a Slevomat ezt hívja.

A szükséges API gyökér URL-t a partner biztosítja, és az űrlapon kell szerepelnie

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

Engedélyezés kérése

Ha az API engedélyezve van, a partner megkapjapartner_api_se­cret , ami azt bizonyítja, hogy a bejövő kérések valóban a Slevomattól származnak.

Ezt a paramétert a HTTP fejléc adja átX-PartnerApiSecret .

Teszt felület

A Slevomat olyan funkciókat tartalmaz, amelyek segítségével meghívhatja az API-t a partner oldalon, és megtekintheti a választ. A partner által az API elérhetővé tételekor megadott gyökér URL hozzá van fűzve-test , így a tesztelés során az API-t pl

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

hogy elkerüljük a tesztadatok és az élő rendelések keveredését.

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 rend

• 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 

   – Módosítsa a megrendelés állapotát "Kézbesítve az ügyfélnek – ügyfél megerősítésére vár"-ra

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

   – Módosítsa a rendelés állapotát "Személyes átvételre kész"-re

• 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 átvétel megtagadása

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

   – Törlés

Helyettesíteni a<orderId> az URL része bármilyen rendelési számmal, a partner API-hoz intézett kérések ezzel a rendelési számmal készülnek.

A tesztfelületre irányuló kéréseket a fejlécekkel kell engedélyezniX-PartnerToken ésX-ApiSecret .

Amikor teszthívást kezdeményez a partner API-nak, a rendszer elküldi aX-PartnerApiSecret fejlécet, mint élő üzemmódban.

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

Rendelés törlés elküldése esetén aitems mező a kérelem POST törzsében JSON-ban (az API által küldött formátumban), amelyet a tesztelési felület érvényesít és ugyanabban a formában továbbít a partner API-nak.

Új rend

A kérelem tartalmazza az újonnan létrehozott rendelés adatait.

A rendelések mindig egyediekslevomatId . Ha az API másolatot kapslevomatId , 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ételte), és a választ isHTTP 204 .

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

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

Az opcionálisinternalId jelzi a műveletváltozathoz megadott belső azonosítót, amikor az létrejön a partner felületen. A termék azonosítására szolgál a partner rendszerében.

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

Ban benshippingAddress (szállítási cím) a cég (company ) nem kötelező. címre történő szállítás eseténshippingAddress tartalmazza a vevő címét, személyes átvétel esetén annak a telephelynek a címét, ahol a vásárló az árut átveszi.

A kulcsdelivery .type felveheti az értéketaddress (címre szállítás) illpickup (személyes átvétel).delivery .name tartalmazza a szállítmány vagy a létesítmény nevét.

delivery .expec­tedShippingDa­te (becsült szállítási dátum) ésdelivery .expec­tedDeliveryDa­te (becsült szállítási dátum) formátumú adatokYYYY-MM-DD .

A kulcsweight tartalmazza a rendelés súlyát kilogrammban. Ha nem ismerjük a rendelésben szereplő összes tétel súlyát, akkor az értéket veszinull .

POST /rend/$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 /rend/$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 áthelyezi a kiválasztott rendelések szállítási dátumait, a rendszer tájékoztatja a partner API-t erről a frissítésről.

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

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Törlés

Lemondások mind a Slevomat oldalon, mind a partnerrendszeren létrehozhatók. Ez a végpont kezeli a törlés létrehozását a Slevomat oldalon és annak átvitelét a partner rendszerébe.

Létrehozza a rendelési tételek törlését a megadott mennyiségben. Ha a teljes rendelést törölni kell, akkor az összes megfelelő mennyiséggel rendelkező tétel megjelenik.

Az egyes tételek részben is lemondhatók (pl. 1/2).

Lemondási nyilatkozat (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ě" }

A kézbesítés visszaigazolása

Miután megjelölte a megrendelés "Kézbesítve az ügyfélnek" jelzést, megkérjük a vásárlót, hogy erősítse meg, hogy valóban megkapta. Amikor a megrendelés beérkezettként van megjelölve, ez a végpont meghívásra kerül.

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

{}

Az átvétel megtagadása

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Módosítsa a rendelés állapotát "Személyes átvételre kész"-re

Ez a végpont akkor kerül meghívásra, ha az előző „Személyes átvételre kész” állapot be volt állítvaautoMarkRea­dyForPickuptrue és a rendelés automatikusan átváltott "Személyes átvételre kész"-re a Slevomat oldalon.

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

{}

Módosítsa a rendelés állapotát "Kézbesítve a vevőnek – ügyfél megerősítésére vár"-ra

Ez a végpont akkor hívódik meg, ha az előző „Útközben”, „Személyes átvételre kész” vagy „Személyes átvételre kész” állapot be volt állítvaautoMarkDeli­veredtrue és a rendelés automatikusan átváltott a Slevomat oldalon "Kézbesítve a vevőnek – vásárlói visszaigazolásra vár" státuszra.

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

{}

Kommunikációs partner ⇒ Slevomat

Az API ezen része a Slevomat oldalon van implementálva, és a partnerrendszer hívja meg.

Az API gyökér URL-je

 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ár jelenleg PHP 5.4 vagy újabb verziót igényel, és a Composer használatát igényli.

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

Engedélyezés kérése

Ha az API engedélyezve van, a partner megkapjapartner_token ésapi_secret , amelyek a Slevomat API hívásakor önmaguk hitelesítésére szolgálnak.

Ezeket a paramétereket aX-PartnerToken ésX-ApiSecret fejlécek.

Teszt felület

A tesztfelület gyökér URL-je a

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

Minden művelet meghívható rajta, mint az élő felületen.

A tesztfelület ellenőrzi a kérelmek jogosultságát (a partner token és az API-titok helyességét), valamint a bejövő kéréstestek (JSON) érvényességét. Ebből a szempontból ugyanúgy viselkedik, mint az élő API.

A tesztelési felület azonban nem működik tényleges rendelésekkel. Így nem ellenőrzi, hogy egy rendelés átmenet-e a megfelelő állapotok között, és tartalmaz-e adott azonosítójú tételeket. Amint a kérelem engedélyezése és űrlapellenőrzése sikeres, a tesztfelület mindig megfelel a 200-as vagy 204-es sikerkódnak.

Lemondás létrehozása

Létrehoz egy törlést a rendelési tételekről a megadott mennyiségben. Ha a rendelést teljes egészében törölni kell, akkor az összes megfelelő mennyiségű tétel megjelenik.

Az egyes tételek részben is lemondhatók (pl. 1/2).

Lemondási nyilatkozat (note ) nem kötelező.

POST /order/$slevomatId/cancel

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

A megrendelés állapotának módosítása "Függőben"-re

POST /order/$slevomatId/mark-pending

{}

A megrendelés állapotának módosítása "Áruk kiszállítva"-ra

Megrendeléshez aautoMarkDelivered paraméterrel megadható, hogy egy beállított szállítási idő után ("Kiszállítástól kézbesítésig eltelt idő") automatikusan átváltson-e "Kézbesítve a vevőnek – ügyfél megerősítésére vár" állapotra.

A válasz frissített becsült kézbesítési dátumot tartalmaz.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

200-as válasz

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

Módosítsa a rendelés állapotát "Személyes átvételre kész"-re

Használhatja a paramétertautoMarkReady­ForPickup megadni, hogy egy adott típusú átvételi pontnál a feladástól a kézbesítésig eltelt idő után a megrendelés automatikusan átváltson-e "Személyes átvételre kész" állapotba.

Megrendeléshez aautoMarkDelivered paraméterrel megadható, hogy a „Személyes átvételre kész” állapotból automatikusan átváltson-e „Vevőhöz kézbesítve – ügyfél megerősítésére vár” állapotra egy beállított számú átvételi nap elteltével az adott típusú átvételi ponton.

A paraméterek kombinációjaautoMarkReady­ForPickup hamis ésautoMarkDelivered igaz nem megengedett. Ebben az esetben a 9-es hibakód kerül visszaadásra.

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

POST /order/$slevomatId/mark-getting-ready-for-pickup

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

200-as válasz

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

Módosítsa a rendelés állapotát "Személyes átvételre kész"-re

AautoMarkDelivered paraméterrel megadható, hogy a megrendelés adott számú átvételi ponton meghatározott számú nap elteltével automatikusan „Kézbesítve a vevőnek – vevői visszaigazolásra vár” állapotba kerüljön-e.

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Módosítsa a rendelés állapotát "Kézbesítve a vevőnek – ügyfél megerősítésére vár"

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

{}

Szállítási cím módosítása

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ó).

Minden kulcs, kivévecompany szükségesek.

Érvényes értékek astate kulcsokcz (Csehország) éssk (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" }

Változási napló