Hogyan állítsd be a webhookokat az easySalesben: rendelések, címkék és készletváltozások a saját rendszereidbe
Küldd el az easySales eseményeit – például az új rendeléseket, a szállítási címkéket, a számlákat és a készletváltozásokat – a saját rendszereidnek abban a pillanatban, amikor megtörténnek, és tartsd működésben a feliratkozásokat.
Mire jók a webhookok
A webhook abban a pillanatban értesít egy másik rendszert, amikor valami történik az easySalesben. Amikor beérkezik egy rendelés, elkészül egy szállítási címke vagy változik egy készlet, az easySales elküldi a részleteket egy általad választott címre. Így az ERP-d, a könyvelőprogramod vagy a webshopod azonnal reagálhat, és nem kell pár percenként lekérdeznie az easySalest.
Bejelentkezve nyisd meg az easy-sales.com/webhooks oldalt. Itt minden sor egy feliratkozás: egy esemény, amely egy címre megy.
Három dolog, amit érdemes előre tudnod:
- Az adatokat fogadó címet neked vagy a fejlesztődnek kell elkészítenie. Az easySales elküldi az adatokat, a címen futó rendszer pedig eldönti, mit kezd velük.
- Az ismételten hibára futó feliratkozás magától kikapcsol. 100 sikertelen próbálkozás után az easySales leállítja a küldést, és e-mailben értesít. Magától nem kapcsol vissza.
- Amíg a feliratkozás ki van kapcsolva, az események nem őrződnek meg. Ha újra bekapcsolod, a küldés attól a pillanattól indul újra.
Feliratkozás egy eseményre
- Kattints a Subscribe to webhook gombra.
- Az Url mezőbe írd be az adatokat fogadó címet. Https-címet használj.
- A HTTP method maradjon POST.
- A Webhook mezőben válaszd ki az eseményt.
- A Secret mezőbe írj be egy legalább 24 karakteres kulcsot. A rendszered ezzel ellenőrzi, hogy az adatok tényleg az easySalestől jönnek.
- Kattints a Save gombra.
A feliratkozás az eseménye neve alatt jelenik meg. Ha ugyanazt az eseményt egy második rendszernek is el akarod küldeni, iratkozz fel újra a másik címmel. Egy címet eseményenként csak egyszer adhatsz hozzá.
| Esemény | Mikor küldi az easySales |
|---|---|
| Order created | Új rendelés érkezik bármelyik csatornáról, vagy valaki kézzel rögzít egyet. |
| Order updated | Bármi változik egy rendelésen, például az állapota, a termékei vagy a címe. Ez az esemény gyakran érkezik. |
| Awb created | Szállítási címke készül egy rendeléshez az easySalesben beállított futárszolgálattal. |
| Delivery status updated | A futár új kézbesítési állapotot jelez egy küldeménynél. |
| Invoice created, Storno invoice created | Számla vagy sztornószámla készül egy rendeléshez. |
| Return created, Return updated | Visszáru jön létre, vagy változik az állapota, a termékei, a megjegyzései, a küldeményei vagy a számlái. |
| Product created, Product updated | Új termék kerül fel, vagy módosul egy termék, az árát is beleértve. |
| Product stock updated | Változik egy termék készlete. |
| Category created / updated, Characteristic created / updated | Új kategória vagy jellemző kerül fel, vagy egy meglévő módosul. |
| Products refresh requested, Stock refresh requested | Egy webshophoz a termékek vagy a készlet frissítését kérik. |
| Ticket created, Ticket updated | Az Ügyfelek → Ticket-ek alatt új beszélgetés indul egy vásárlóval, vagy egy meglévő változik. |
| Account suspended, Account activated | Az easySales-fiókot felfüggesztik vagy újra aktiválják. |
Az elküldött adatok ellenőrzése
Minden feliratkozásnál látod, hogy az utoljára elküldött esemény Success vagy Failed lett, és hogy mikor ment ki. Az esemény megnyitásához kattints a More details... gombra:
- A Payload az easySales által küldött adat.
- A Response a címed válasza, az állapotkóddal együtt.
- Az Attempt 2 of 3 | Next attempt: … azt jelenti, hogy a küldés nem sikerült, és az easySales újra elküldi az eseményt. A Final attempt has been made azt jelenti, hogy arra az eseményre nem lesz több próbálkozás.
Itt minden feliratkozásnak csak az utolsó eseménye látszik.
Feliratkozás módosítása, szüneteltetése vagy törlése
- Az Edit gombbal módosíthatod a címet, a HTTP-metódust vagy a titkos kulcsot. Ha másik eseményt szeretnél küldeni, iratkozz fel arra az eseményre, és töröld a régi feliratkozást.
- A Disable szünetelteti a feliratkozást, az Enable újraindítja. Szüneteltetés alatt semmi sem megy ki, és az ebben az időszakban történt eseményeket később sem küldi el az easySales.
- Az Unsubscribe azonnal törli a feliratkozást.
Mit kell tennie a rendszerednek
| Részletek | |
|---|---|
| Formátum | JSON: az esemény adatai a payload, a feliratkozás azonosítója és az esemény neve a webhook alatt. |
| Aláírás | A Signature fejléc a kérés törzsének HMAC-SHA256 értékét tartalmazza, a titkos kulcsoddal számolva. Pontosan a beérkezett törzsből számold ki. |
| Válasz | Bármilyen 2xx állapotkód 3 másodpercen belül. Előbb válaszolj, és csak utána dolgozd fel az adatokat. |
| Tanúsítvány | A https-címeknek érvényes tanúsítvánnyal kell rendelkezniük. |
| Újrapróbálkozás | Eseményenként három próbálkozás: a második kb. 10 másodperccel az első után, a harmadik kb. 100 másodperccel később. |
| Érkezési sorrend | Az újrapróbálkozások miatt az események más sorrendben is megérkezhetnek. A payload adataira támaszkodj, ne az érkezés idejére. |
Ha egy feliratkozás magától kikapcsol
Minden sikertelen próbálkozás számít: a hibás válasz, ha 3 másodpercen belül nem érkezik válasz, vagy ha gond van a tanúsítvánnyal. 100 sikertelen próbálkozás után a feliratkozás kikapcsol, és megkapod „A webhook le lett tiltva” tárgyú e-mailt. Az e-mail Webhookok megtekintése gombja erre az oldalra visz.
- Javítsd ki a hibát az adatokat fogadó címen.
- Kattints a feliratkozás Enable gombjára.
- Kérd le az easySales API-n keresztül a kimaradt változásokat, például az abban az időszakban módosult rendeléseket.
Csapattagok hozzáférése a webhookokhoz
Az oldal megnyitásához a csapattagnak a Webhooks-ok megtekintése jogosultságra van szüksége. Ezzel feliratkozásokat adhat hozzá, módosíthat, szüneteltethet és törölhet.
Ha valami nem úgy működik, ahogy kellene
| Tünet | Teendő |
|---|---|
| Már semmi sem érkezik, és a feliratkozásnál az Enable látszik | A feliratkozás ismétlődő hibák miatt kikapcsolt. Javítsd ki a címet, kattints az Enable gombra, majd kérd le az API-n a kimaradt változásokat. |
| Az utolsó eseménynél Failed látszik | Nyisd meg a More details... részt, és nézd meg az állapotkódot és a címed válaszát. |
| „The secret must be at least 24 characters.” | Adj meg legalább 24 karakteres titkos kulcsot. |
| „The url has already been taken.” | Ez a cím már megkapja ezt az eseményt. Új feliratkozás helyett a meglévőt módosítsd. |
| Nem érkeznek meg a sztornószámlák | Iratkozz fel a Storno invoice created eseményre; az Invoice created csak a normál számlákra vonatkozik. |
| A fogadó rendszert elárasztják a rendelésfrissítések | Az Order updated minden változásnál érkezik. Válaszolj gyorsan, és a háttérben dolgozd fel az adatokat. |