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

API 3rd party áruk

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

Az API-t a Discountomat és a Discountomat közötti megrendelési információk átvitelére használják. a kereskedelmi partner rendszere között. Az API egy kétoldalú kommunikáció – a partner API-ját hívja meg a Discount rendszer, a partner pedig az API-t hívja meg. Discount.

A partner API-ba exportált megrendelésekkel már nem lehetséges manipulálható a partner felületén, csak megtekinthető. Az exportált megbízások manipulálása csak a következőkön keresztül végezhető el API-N KERESZTÜL.

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

API elérhetőség

Az API-t a Beállítások fülön keresztül érheti el a Partner felületén. Az adatok lekérdezéséhez a gyökérkódot kell megadnia. Az API partneri részének URL-címe a Zlevomat → Partner irányába történő használathoz, pl.

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

A hozzáférési adatok csak az API elérésekor jelennek meg, figyelmesen olvassa el azokat gondosan őrizze meg őket.

Az API elérését követően az újonnan létrehozott megrendeléseket a rendszer beviszi oda. Megkezdődik a megrendelések exportálása a rendszerbe.

Kezdeti adatexport

A meglévő megrendelések túlcsordulása az API elérhetőségének pillanatában CSV formátumba történő egyszeri exportálás a partnerfelületen használható.

Abban a pillanatban, amikor a meglévő megrendelések (amelyeket azelőtt hoztak létre, hogy API-hozzáférés előtt) a saját rendszerében, és el szeretné kezdeni a munkát velük a API-n keresztül, 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é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 nem érvényes – lehet hiányozhatnak vagy érvénytelenek lehetnek a specifikációval ellentétes paraméterek.
  • 403 Forbidden – az ügyfél engedélyezése sikertelen
  • 404 Not Found – kért végpont vagy adat nem találták meg
  • 405 Method Not Allowed – a végpont nem támogatja ezt. HTTP protokoll módszer
  • 422 Unprocessable Entity – várható hiba a kérés feldolgozása (lásd a Hibakörülmények című szakaszt)
  • 500 Internal Server Error – hiba történt az oldalon szerver
  • 502 Bad Gateway – szerveroldali hiba történt
  • 503 Service Unavailable – a szerver karbantartási üzemmódban van (új verzió telepítése vagy tervezett leállás lehet folyamatban)
  • 504 Gateway Timeout – hiba történt a szerveroldalon. szerver

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

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

A 5xx hibák a szerver hibáit jelzik, és a kérés a módosítás nélkül újra meg lehet próbálni. A 503 esetében a hívónak a következő feladatokat kell elvégeznie tiszteletben kell tartania a Retry-After válaszfejlécet, és a következő próbálkozásnál újrapróbálását csak a fejlécben megadott idő letelte után.

A sorrend állapota

Egy megbízás mindig az alábbi állapotok egyikében van:

Állapotérték Leírás
1 Új fizetett megrendelés
2 Feldolgozás alatt
3 Útközben (csak szállításos megrendelés)
4 Személyes átvételre előkészítés alatt – pl. szállítás alatt a következő címre
5 Személyes átvételre készen
6 Kiszállítva az ügyfélnek – az ügyfél visszaigazolására várva
7 Kiszállítva és az ügyfél által visszaigazolva
8 A megrendelő megtagadta a megrendelés átvételének visszaigazolását
9 A megrendelést törölték

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

A megrendelésnek nem feltétlenül kell minden státuszon végigmennie ahhoz, hogy sikeres legyen. kiszállítás, lehetséges, hogy egyenesen az "Új fizetett rendelés" státuszból induljon az "Úton" / "Átvételre kész", majd az "Átvételre kész" állapotba. "Kiszállítva az ügyfélnek – az ügyfél megerősítésére vár". A használata az összes státusz használata azonban jobb ügyfél-tájékoztatást eredményez a megrendelőnek a megrendelés előrehaladásáról. a megrendelés feldolgozásáról, ezért ezt ajánljuk.

Hibaállapotok

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

Állapot értéke Leírás
1 Érvénytelen kérés – hiányzó vagy érvénytelen értékek.
2 Érvénytelen hitelesítő adatok
3 Nem létező megrendelés
4 Nem létező rendelési tétel
5 A megbízás átmenete nem engedélyezett állapotba
6 Érvénytelen törlés – több tétel törlése, mint ahány tétel van létezik
7 Egyéb hiba
8 A megrendelés még nem került exportálásra a partner API-ba – nincs nem lehet az API-n keresztül manipulálni
9 Az "Áru kiszállítása a vevőnek" státusz automatikus beállításához szükséges, hogy a küldemény automatikusan "áru kész" státuszba kerüljön. átvételre kész"

Példa:

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

Adattípusok

A kérések és válaszok egyes kulcsainak adattípusai a következők 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. Hacsak nem másképp nincs megadva, a numerikus érték mindig kötelezően egész szám.

Kommunikációs diszkontomat ⇒ Partner

Az API ezen része a partner oldalán van implementálva, és a Zlevomat használja. hívásokat.

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

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

Engedélyezés kérése

Az API engedélyezése esetén a partner a partner_api_se­cret címen kapja meg a , amely a bejövő kéréseket ellenőrzik, hogy azok valóban a Kedvezmény.

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

Teszt-interfész

A Discountomat tartalmaz olyan funkciókat, amelyekkel az API-t meg lehet hívni a partner oldalán és a válasz megjelenítése. A partner által az API elérésekor megadott gyökér-URL-re. A -test a partner URL-hez kapcsolódik, így a tesztelés során a API pl.

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

hogy elkerülhető legyen a tesztadatok keveredése az éles megbízásokkal.

A partner API tesztelése POST kérésekkel történik az alábbi címre irányuló kérésekkel a következő címekre:

Helyettesítse az URL <orderId> részét tetszőleges számmal. rendelésszám, ezzel a rendelésszámmal a kérések a következő címre kerülnek továbbításra API-partnerhez.

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

Amikor a partner API-hoz teszthívás érkezik, a rendszer a következő fejlécet küldi el X-PartnerApiSecret fejlécet, ugyanúgy, mint az éles üzemben.

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

Megrendelés törlésének elküldése esetén a POST body a kérés JSON mezőjében tartalmazza a items mezőt (ugyanabban a formátumban, mint a az API által küldött), amelyet a tesztelési felület validál és elküld a partner API-nak. API ugyanabban a formátumban továbbítja.

Új megrendelés

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

A megrendelések mindig egyedi zlavomatId címmel rendelkeznek. Ha az API egy duplikátum érkezik zlavomatId, a kérést meg kell figyelmen kívül hagyni (az első átalakított kérést a Discountomat sikertelennek értékelte és a ezért megismételjük), és szintén HTTP 204-es válasszal válaszolunk.

Acreated egy dátum ISO 8601 formátumban, tehát YYYY-MM-DD'T'HH:mm:ss­+zz:zz .

AproductId tartalmazza az esemény azonosítóját, a variantId az azonosítót. a megvásárolt variánsé.

Az opcionális internalId a belső azonosítót jelöli, amelyet akkor adtunk meg, amikor egy művelet változatának létrehozásakor a partnerfelületen. Kiszolgálja a a termék azonosítására a partner rendszerében.

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

A shippingAddress (szállítási cím) esetében a cég nem kötelező. (company). A következő címre történő szállítás esetén shippingAddress tartalmazza az ügyfél címét, személyes cím esetén a személyes kézbesítés esetén annak a létesítménynek a címét, ahol a vásárló átveszi az árut.

A delivery.type kulcs a következő értékeket veheti fel address (címre történő szállítás) vagy pickup (személyes átvétel). átvétel). delivery.name tartalmazza a fuvarozó vagy a címzett nevét. a művelet neve.

delivery.expec­tedShippingDa­te (várható szállítás dátuma) és delivery.expec­tedDeliveryDa­te (a kézbesítés várható időpontja) a következő formátumú adatok YYYY-MM-DD .

A weight kulcs a megrendelés súlyát tartalmazza kilogrammban. Abban az esetben, ha nem ismerjük a rendelés összes tételének súlyát, ez az érték a null.

POST /rendelés/$slevomatId

{ "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 /rendelés/$slevomatId

{ "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 üzletkötések kezelője a partner kérésére a tömeges adatokat tolja ki szállítási dátumokat a kiválasztott megrendelésekhez, a rendszer erről tájékoztatja a partner API-t. frissítésről.

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

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

Lemondások

Lemondások mind a Kedvezmény, mind a partner oldalán létrehozhatók. rendszerben. Ez a végpont kezeli a lemondások létrehozását a Zlavomat oldalon és annak partneri rendszerbe történő átvitelét.

Létrehozza a megadott mennyiségű rendelési tételek törlését. Ha a a teljes rendelés törlésre kerül, az összes tétel a megfelelő mennyiséggel.

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

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ě" }

Szállítási visszaigazolás

Miután a megrendelést "Kiszállítva a vevőnek" jelzéssel látta el, Ön visszaigazolást kérünk a vevőtől arról, hogy valóban átvette a terméket. 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 "Átvételre kész" állapotra.

Ez a végpont akkor hívódik meg, ha a previous végpontot "Személyes átvételre kész" státusz került beállításra a autoMarkRea­dyForPickuptrue és a Kedvezmény oldalon a megrendelés automatikusan átváltott a "Kész" státuszra. személyes átvételre"

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

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

Ez a végpont akkor kerül meghívásra, ha a previous "Úton", "Személyes átvételre kész" vagy "Készen áll" státuszú megrendelés esetén. személyes átvételre" beállításra került a autoMarkDeli­veredtrue oldalon és a Kedvezmény oldalon a megrendelés automatikusan átváltott a "Kiszállítva" állapotra. a megrendelőnek – a megrendelői visszaigazolásra vár".

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

Kommunikációs partner ⇒ Zľavomat

Az API ezen része a Discountomat oldalán van implementálva, és a következő hívásokat tartalmazza partner rendszerét.

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

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

PHP könyvtár

Az API ezen oldalának megvalósításához az előkészített PHP-könyvtárat lehet használni. könyvtárat. A könyvtárhoz jelenleg a PHP 5.4-es vagy magasabb verziója és a a Composer eszköz használatát feltételezi.

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

Engedélyezési kérelmek

Ha az API engedélyezve van, a partner a partner_token és a api_secret , amelyek a Zlavomat API-hívás hitelesítésére szolgálnak.

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

Teszt-interfész

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

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

Ezen a felületen ugyanúgy meg lehet hívni minden műveletet, mint a többi felületen.

A tesztinterfész ellenőrzi a kérések jogosultságát (helyességét partner token és API-titok) és a beérkező kérések testének érvényességét. (JSON) ELLENŐRZÉSÉT. Ezekben a vonatkozásokban ugyanúgy viselkedik, mint a crisp API.

A teszt-interfész azonban nem működik tényleges megrendelésekkel. Így nem érvényesíti, hogy egy megbízás a helyes állapotok között átmegy-e, és hogy tartalmaz-e adott azonosítóval rendelkező tételeket. Ha az engedélyezés és az érvényesítés sikeres a kérés formái, a teszt interfész mindig sikeres kóddal válaszol. 200 vagy 204.

Lemondás létrehozása

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

Az egyes tételek részlegesen is törölhetők (pl. 1 tétel kettőből).

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 "Folyamatban" állapotra

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

{}

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

A megrendelés leadásakor a autoMarkDelivered paramétert arra használjuk, hogy meghatározzuk, hogy a beállított szállítási időszak ("A feladástól a kiszállításig eltelt idő") után kell-e automatikusan átálljon a "Kiszállítva a vevőnek – várakozás a megrendelésre vevői visszaigazolásra".

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

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ész" állapotra.

Amikor a megrendelés átmegy a autoMarkReady­ForPickup paraméter megadására, hogy a feladástól a kézbesítésig eltelt idő az adott típusú gyűjtőhelyen automatikusan át kell állítani a "Kész átvételre" státuszra. Személyes átvételre".

A megrendelés során a autoMarkDelivered paraméter határozza meg, hogy az adott típusú gyűjtőpontra vonatkozóan az átvételre beállított napok száma után a gyűjtőpont automatikusan átálljon a "Személyes átvételre kész" állapotból. "Kiszállítva a vevőnek – visszaigazolásra várva" állapotba. a megrendelőtől".

A autoMarkReady­ForPickup false és a false paraméterek kombinációja autoMarkDelivered true kombinációja nem megengedett. Ebben az esetben 9-es hibakódot kapunk vissza.

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

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

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

Válasz 200

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

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

A megrendelés leadásakor a autoMarkDelivered paramétert arra használjuk, hogy meghatározzuk, hogy egy adott átvételi típus esetében az átvételre meghatározott számú nap elteltével a gyűjtőhely automatikusan átálljon a "Kiszállítva a vevőnek" állapotra. vevői visszaigazolásra várva".

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 – várakozásra vevői visszaigazolásra"

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

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

A szállítási cím csak egy címre történő kiszállításkor módosítható (pl. Az átvételi hely nem módosítható).

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

A state kulcs érvényes értékei: cz (cseh). Köztársaság) és a 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" }
Vissza a cikkek listájára

Kapcsolódó cikkek
Nahoru