API 3rd party áruk

Az API-t a megrendelésekkel kapcsolatos információk átvitelére használják a Discount Machine és az üzleti partner rendszere között. Az API kétirányú kommunikáció megvalósítását igényli – a Discount Machine rendszer meghívja a partner API-ját, a partner pedig a Discount Machine API-ját.

A partner API-ba exportált rendelések már nem módosíthatók a Zlavomat partner felületén, csak megtekinthetők. Az exportált rendelések mostantól csak az API-n keresztül módosíthatók.

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

API-akadálymentesítés

Az API-t a partneri felület Beállítások lapján érheti el. Az adatok lekéréséhez meg kell adnia az API partner részének gyökér URL-címét a Zlavomat → Partner irányban történő használathoz, pl.

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

A hozzáférési adatok csak akkor jelennek meg, amikor az API-hoz hozzáférnek, ezért őrizze meg azokat biztonságos helyen.

Amint az API elérhetővé válik, a rendszer elkezdi exportálni az újonnan létrehozott rendeléseket rá.

Kezdeti adatexport

A meglévő megrendelések átviteléhez az API elérhetővé tételének pillanatában lehetőség van egyszeri CSV exportálásra a partnerfelületen.

Ha már vannak meglévő rendelései (amelyeket az API elérhetővé tétele előtt hozott létre) a saját rendszerében, és az API-n keresztül szeretne velük dolgozni, használja a „Megjelölt rendelésekkel való munka megkezdése API-n keresztül” funkciót a „Rendelésekkel végzett tömeges műveletek” menüben.

Gyakori HTTP-válaszok leírása

• 200 OK – a kérés feldolgozása sikeresen megtörtént
• 204 No Content – a kérés feldolgozása sikeresen megtörtént, a válasznak nincs tartalma
• 400 Bad Request – a kérés érvénytelen – hiányozhatnak vagy érvénytelen paraméterek lehetnek a specifikációhoz képest
• 403 Forbidden – kliens hitelesítése sikertelen
• 404 Not Found – végpont vagy a kért adat nem található
• 405 Method Not Allowed – a végpont nem támogatja ezt a HTTP protokoll módszert
• 422 Unprocessable Entity – várható hiba a kérés feldolgozása során (lásd a Hibaállapotok részt)
• 500 Internal Server Error – hiba történt a szerveroldalon
• 502 Bad Gateway – hiba történt a szerveroldalon
• 503 Service Unavailable – a szerver karbantartási módban van (új verzió telepítése vagy tervezett leállás folyamatban lehet)
• 504 Gateway Timeout – hiba történt a szerveroldalon

A HTTP 5×x válaszoknak nem kell JSON formátumot használniuk.

Hibák esetén4xx Hiba van a kimenő kérésben, és azt ki kell javítani, mielőtt újra próbálkozna.

Hibák5xx szerverhibákat jelez, és a kérés módosítás nélkül megismételhető. Abban az esetben, ha503 a hívónak tiszteletben kell tartania a válasz fejlécétRetry-After és csak a fejlécben megadott idő letelte után ismételje meg a következő kísérletet.

Rendelési állapotok

A megrendelés mindig az alábbi állapotok egyikében van:

Az ügyfél e‑mailben kap értesítést az állapotváltozásról.

Egy rendelésnek nem feltétlenül kell minden státuszon átmennie a sikeres kézbesítéshez; az „Új, kifizetett rendelés” státuszból közvetlenül az „Úton van” / „Személyes átvételre kész” állapotba, majd a „Vásárlónak kézbesítve – vevői visszaigazolásra vár” állapotba lehet lépni. Az összes állapot használata azonban jobb ügyfélinformációt eredményez a rendelés állapotáról, és ezt javasoljuk.

Hibaállapotok

HTTP 4×x kódok esetén a válasz mindig tartalmaz egy kulcsot.status (lásd az alábbi kódlistát) és mezőmessages a hibák szöveges leírásával.

Minta:

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

Adattípusok

A kérésekben és válaszokban található egyes kulcsok adattípusai mindig az adott végpontokra vonatkoznak. Hacsak másképp nem jelezzük, az idézőjelek között lévő érték"" mindig kötelező karakterlánc. Hacsak másképp nincs feltüntetve, a numerikus érték mindig kötelező egész szám.

Kommunikációs Kedvezményautomata ⇒ Partner

Az API ezen részét a partner oldalán implementálják, és a Zlavovamat hívja meg.

A szükséges API gyökér URL-t a partner fogja megosztani, a következő formátumban kell lennie:

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

Kérések engedélyezése

Amikor az API be van kapcsolva, a partner megkapja apartner_api_se­cret , ami bizonyítja, hogy a bejövő kérések valóban a Zlavomattól érkeznek.

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

Tesztelési felület

A kedvezménygép rendelkezik olyan funkcióval, amely lehetővé teszi az API meghívását a partneroldalon, és megjeleníti a választ. A partner által az API elérhetővé tételekor megadott gyökér URL csatolva van a következőhöz:-test , tehát a tesztelés részeként az API-t például a következő helyen hívják meg:

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

hogy elkerüljük a tesztadatok és az élő megrendelések keverését.

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

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Új rendelés

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

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

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

   – A rendelés állapotának módosítása „Kiszállítva a vevőnek – vevői visszaigazolásra vár” értékre

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

   – A rendelés állapotának módosítása „Személyes átvételre kész” értékre

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Szállítás visszaigazolása

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Elfogadás megtagadása

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Mégsem

Az URL egy része<orderId> bármilyen rendelési számmal lecserélve, a partner API-hoz intézett kérések ezzel a rendelési számmal lesznek elküldve.

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

Partner API-hívás tesztelésekor a rendszer egy fejlécet küldX-PartnerApiSecret akárcsak éles üzemben.

Az új rendeléssel küldött adatok teszt jellegűek és véletlenszerűen generáltak.

Megrendelés lemondásának küldése esetén a POST kérés törzsében szükséges a JSON mező belefoglalása.items (ugyanabban a formátumban, mint ahogyan az API küldi), amelyet a tesztfelület validál és ugyanebben a formában továbbít a partner API-nak.

Új rendelés

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

A megrendelések mindig egyediekzlavomatId Ha duplikátum érkezik az API-bazlavomatId , a partner API-nak figyelmen kívül kell hagynia a kérést (a Zľavomat által küldött első kérés sikertelennek lett értékelve, ezért megismételjük), és szintén HTTP 204-gyel kell válaszolnia.

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

productId tartalmazza a művelet azonosítóját, variantId A megvásárolt változat azonosítója.

VálaszthatóinternalId a partnerfelületen létrehozott műveletváltozathoz megadott belső azonosítót jelenti. Ez a partnerrendszerben a termék azonosítására szolgál.

BebillingAddress (számlázási cím) csak a név megadása kötelezőname ) az ügyfél.

BeshippingAddress (szállítási cím) egy opcionális cég (company ). Címre történő kézbesítés eseténshippingAddress tartalmazza a vásárló címét, személyes átvétel esetén annak az üzletnek a címét, ahol a vásárló átveszi az árut.

Kulcsfontosságúdelivery .type értékeket tud felvenniaddress (szállítás a címre) vagypickup (személyes gyűjtemény).delivery .name tartalmazza a szállítás vagy a művelet nevét.

delivery .expec­tedShippingDa­te (a feladás várható dátuma) ésdelivery .expec­tedDeliveryDa­te (becsült szállítási dátum) a formátumú adatYYYY-MM-DD .

Kulcsfontosságúweight a rendelés súlyát tartalmazza kilogrammban. Ha nem ismerjük a rendelésben szereplő összes tétel súlyát, akkor a következő értéket veszi fel:null .

POST /megrendelés/$slevomatAzonosító

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "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–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

POST /megrendelés/$slevomatAzonosító

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "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–07", "expectedDeli­veryDate": "2021–09–07", "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 üzletkezelő a partner kérésére tömegesen módosítja a kiválasztott megrendelések szállítási dátumát, a rendszer tájékoztatja a partner API-ját erről a frissítésről.

Az elküldött adatok tartalmaznak egy mezőt a rendelési azonosítóval és az új várható szállítási dátummal.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Mégsem

A lemondások mind a Zlavomat oldalon, mind a partnerrendszeren létrehozhatók. Ez a végpont kezeli a lemondások létrehozását a Zlavomat oldalon, és azok továbbítását a partnerrendszerbe.

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

Az egyes tételek részlegesen is lemondhatók (pl. kettőből 1 darab).

Lemondási értesítés (note ) opcionális.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Szállítási visszaigazolás

Miután a megrendelést „Ügyfélnek kézbesítve”-ként jelöli meg, megerősítést kérünk az ügyféltől, hogy valóban megkapta-e azt. Amikor egy megrendelést átvettként jelölünk meg, a rendszer meghívja ezt a végpontot.

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

{}

Elfogadás megtagadása

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

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

A rendelés állapotának módosítása „Személyes átvételre kész” értékre

Ez a végpont akkor lesz meghívva, ha az előző „Személyes átvételre készül” állapot értéke voltautoMarkRea­dyForPickuptrue és a Zlavomat oldalán a rendelés automatikusan „Személyes átvételre kész” státuszba került.

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

{}

A rendelés állapotának módosítása „Kiszállítva a vevőnek – vevői visszaigazolásra vár” értékre

Ez a végpont akkor kerül meghívásra, ha az előző állapot „Úton van”, „Személyes átvételre készül” vagy „Személyes átvételre kész” volt a következővel:autoMarkDeli­veredtrue és a Zlavomat oldalán a megrendelés automatikusan „Vásárlónak kézbesítve – a vevő visszaigazolására vár” státuszba került.

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

{}

Kommunikációs partner ⇒ Diszkontáromaták

Az API ezen részét a Zľavomat oldalán implementálták, és a partnerrendszer hívja meg.

Az API gyökér URL-címe:

https://www.zlavomat.sk/zbozi-api/v1

PHP könyvtár

Ennek az API oldalnak a megvalósításához használhatsz egy kész PHP könyvtárat. A könyvtár jelenleg a PHP 5.4-es vagy újabb verzióját igényli, és feltételezi a Composer eszköz használatát.

A könyvtár utasításai és forráskódja a GitHubon található .

Kérések engedélyezése

Amikor az API be van kapcsolva, a partner megkapja apartner_token ésapi_secret , amelyet a Zlavomat API hívásakor bizonyításra használunk.

Ezek a paraméterek a fejlécekben kerülnek átadásra.X-PartnerToken ésX-ApiSecret .

Tesztelési felület

A tesztfelület gyökér URL-címe:

https://www.zlavomat.sk/zbozi-api/v1-test

Az összes művelet meghívható rajta, mint a másik felületen.

A teszt interfész ellenőrzi a kérések jogosultságát (a partner token és az API titok helyességét) és a bejövő kéréstörzsek (JSON) érvényességét. E tekintetben azonosan viselkedik, mint az élő API.

A tesztfelület azonban nem működik valódi megrendelésekkel. Nem ellenőrzi, hogy a megrendelés a megfelelő állapotok között vált-e, és hogy tartalmazza-e a megadott azonosítójú tételeket. Miután a kérésűrlap engedélyezése és validálása sikeres volt, a tesztfelület mindig 200-as vagy 204-es sikerkóddal válaszol.

Lemondás létrehozása

Hozzon létre megadott mennyiségű rendeléslemondási tételeket. Ha a teljes rendelést törölni kell, akkor a megfelelő mennyiségű összes tétel listázásra kerül.

Az egyes tételek részlegesen is lemondhatók (pl. kettőből 1 darab).

Lemondási értesítés (note ) opcionális.

POST /megrendelés/$slevomatAzonosító/mégsem

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

A rendelés állapotának módosítása „Feldolgozás alatt” értékre

POST /order/$slevomatId/mark-pending

{}

A rendelés állapotának módosítása „Úton van”-ra

Rendeléskor a paraméter a következő:autoMarkDelivered határozza meg, hogy a státusz automatikusan „Ügyfélnek kézbesítve – ügyfél visszaigazolására vár” értékre váltson-e a beállított szállítási időszak („A szállítástól a kézbesítésig eltelt idő”) után

A válasz tartalmazza a frissített várható kézbesítési dátumot.

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

{ "autoMarkDeli­vered": true }

200. válasz

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

A rendelés állapotának módosítása „Személyes átvételre készül”-re

Rendeléskor a paraméter a következő:autoMarkReady­ForPickup határozza meg, hogy az állapot automatikusan „Személyes átvételre kész” értékre váltson-e, miután letelt az adott típusú átvételi ponthoz tartozó szállítástól a kézbesítésig eltelt idő.

Rendeléskor a paraméter a következő:autoMarkDelivered határozza meg, hogy az adott típusú átvételi ponton a beállított számú nap elteltével az állapot automatikusan átváltson-e „Személyes átvételre kész” állapotról „Ügyfélnek kézbesítve – ügyfél visszaigazolására vár” állapotra.

ParaméterkombinációautoMarkReady­ForPickup hamis ésautoMarkDelivered A „true” érték nem megengedett. Ebben az esetben a rendszer 9-es hibakódot ad vissza.

A válasz tartalmazza a frissített várható kézbesítési dátumot.

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

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

200. válasz

{ "expectedDeli­veryDate": "2021–09–06" }

A rendelés állapotának módosítása „Személyes átvételre kész” értékre

Rendeléskor a paraméter a következő:autoMarkDelivered határozza meg, hogy az adott átvételi ponttípushoz tartozó átvételi idő elteltével az állapot automatikusan „Ügyfélnek kézbesítve – ügyfél visszaigazolására vár” értékre váltson-e.

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

{ "autoMarkDeli­vered": true }

A rendelés állapotának módosítása „Kiszállítva a vevőnek – vevői visszaigazolásra vár” értékre

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

{}

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

A szállítási cím csak a címre történő kézbesítéskor módosítható (azaz a hasonló átvételi hely nem módosítható).

Minden kulcs, kivévecompany kötelezőek.

A kulcs érvényes értékeistate vannakcz (Cseh Köztársasá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" }