ShopRenter API

gomb.png

Bevezető

A ShopRenter API segítségével a ShopRenter rendszerében megoldható, hogy akár az egész webáruház tartalmát (így például a termékeket, kategóriákat, felhasználókat, rendeléseket) külső rendszerből lehessen menedzselni. Mindezt automatizált módon, pár másodperc alatt.

Az API segít webáruházát összeintegrálni külső rendszerekkel, például készletkezelő rendszerrel. Így amennyiben Ön korábban olyan rendszerrel szerette volna összekötni webáruházát, melyhez nem készült külön integráció, az API hasznos megoldásként szolgálhat a továbbiakban.

Például ha Ön egy külső rendszerben módosított árat, akkor emiatt a változtatás miatt át kellett írnia a webáruházból kinyert XLS fájlt, majd azt beimportálnia a webáruházba az Export/import funkció segítségével. Az API segítségével viszont erre nincs szükség, hiszen a kétoldalú kommunikációnak köszönhetően a külső rendszerben történő változás pár másodpercen belül a webáruházban is megjelenik.

De ugyanígy mást is meg lehet változtatni. Az API-n keresztül ugyanis az alábbi 4 művelet hajtható végre:

  • az adatok lekérése,
  • módosítása,
  • új adat létrehozása,
  • adat törlése.

Ebből jól látható, hogy milyen lehetőségeket biztosít ez a funkció, hiszen elég csupán a termékek menedzselésére gondolnia.

Fontosnak tartjuk viszont leszögezni, hogy az API használatához fejlesztői ismeretek szükségesek, ugyanis nem mondható egyszerűnek egy laikus felhasználó számára. Tehát amennyiben szeretné kihasználni az API képességeit, úgy ennek konkrét beállítását sajnos nem tudjuk vállalni, Önnek saját fejlesztőre lesz szüksége. Ám igyekszünk minden segítséget megadni az API használatához.

Az API használatához először is szüksége lesz egy felhasználónévre és egy jelszóra. Ezek az adatok a bolt admin felületén Beállítások/Integrációk/ShopRenter API menüpont alatt érhetőek el. A beállítás Gold vagy annál nagyobb csomaggal rendelkező ügyfeleinknek érhető el.

Az API hívásokat pedig az alábbi URL-en lehet végrehajtani:

http://shopname.api.shoprenter.hu/

Itt a "shopname" az Ön webáruházának neve lesz, amely nem az egyedi domain név amit megadott, hanem az a név, melyet a webáruház létrehozásánál választott (azaz amelyet átirányított a saját domain nevére - a korábbi shoprenteres aldomain. Ez az információ is megtalálható pontosan az admin menüpontban.

Amit mindenképpen tudni kell az API-val kapcsolatban, hogy alapvetően 4 parancsot lehet vele végrehajtani, illetve azt, hogy a belső ID-kat hash kódokká átalakítva használjuk:

  • GET - Egy konkrét elem lekérésére szolgál.

    Például a rendelések lekéréshez az alábbi URL-t adjuk meg: /orders?page=0&limit=5
    Ha mondjuk egy adott megrendelés adatait szeretnénk lekérni, úgy mondjuk az alábbi URL-t kell meghívni:   /orders/b3JkZXItb3JkZXJfaWQ9Mw==

    Itt jól látható, hogy nem az admin felületen is látható ID szerepel, hanem annak egy átalakított változata.
  • POST -  Létrehozásra és módosításra is szolgál.
  • PUT - Létrehozásra és módosításra is szolgál.

    A POST és a PUT közötti legfőbb különbség, hogy az előbbi használatával módosítható például egy termék egyetlen paramétere (például ár) anélkül, hogy minden más változna. Ezzel szemben ha PUT paranccsal szeretnénk árat módosítani, úgy egy árváltoztatás esetén a termék minden egyéb paramétere NULL értéket kap majd.
  • DELETE - Törlésre szolgál.

 

API hívásokkal kapcsolatos követelmények és korlátozások

Lehetséges válaszkódok és hibaüzenetek

A következő linken található meg az API összes olyan hibaüzenete, amely előfordulhat a rendszer használata során:

API hibaüzenetek és válaszkódok

Full=1 paraméter

A Resource-okból való lekérdezés során visszatérő feladat, hogy a visszakapott link-lista feldolgozásához további API hívást kell intézni, azért hogy visszakapjuk a Resource-hoz tartozó adatokat.

Például: a terméklista lekérdezése során az alábbi eredménnyel találkozhatunk:

method: GET
url: http://shopname.api.shoprenter.hu/products

<response>
..
<items>
<item>
<href>
<![CDATA[http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTQ5]]>
</href>
</item>
<item>
<href>
<![CDATA[http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTUw]]>
</href>
</item>
...
</response>

A kevesebb API hívások érdekében minden Resource GET-es hívás esetén rendelkezik egy full nevű paraméterrel. A full=1 paraméter alkalmazásával a link-lista helyett a meghívott linkek tartalma jelenik meg.

method: GET
url: http://shopname.api.shoprenter.hu/products?full=1

<response>
...
<items>
<item>
<href>
<![CDATA[http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTQ5]]>
</href>
<id>
<![CDATA[cHJvZHVjdC1wcm9kdWN0X2lkPTQ5]]>
</id>
<innerId>
<![CDATA[49]]>
</innerId>
<sku>
<![CDATA[9789639884328]]>
</sku>
...
</item>
<item>
<href>
<![CDATA[http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTQ5]]>
</href>
<id>
<![CDATA[cHJvZHVjdC1wcm9kdWN0X2lkPTQ5]]>
</id>
<innerId>
<![CDATA[49]]>
</innerId>
<sku>
<![CDATA[9789639884328]]>
</sku>
...
</item>
</items>
...
</response>

 

Használata gyorsabb és átláthatóbb kódot eredményez.

 

API batch feldolgozó

Az API kérések számának csökkentése, valamint a kérések gyorsabb kiszolgálása érdekében, az API kéréseket kötegelt (batch) módon is fel tudjuk dolgozni. Ahhoz, hogy a batch feldolgozót igénybe tudjuk venni, egy speciális szerkezetű tömböt kell elküldenünk POST metódussal, az [API_DOMAIN]/batch URL-re.

Működés

  1. A kliens elküldi POST metódus segítségével, a kéréseket tartalmazó tömböt a [API_DOMAIN]/batch URL-re.
  2. Az API ellenőrzi hogy a kliens rendelkezik-e megfelelő jogosultsággal a kérések kiszolgáláshoz, valamint hogy a kérések megfelelő szerkezetűk-e. Ha igen, akkor megkezdődik a kérések feldolgozása, ellenkező esetben a válasz valamilyen hibaüzenet formájában, a válaszoknak megfelelő struktúrában kerül visszaküldésre a kliensnek.
  3. Egy ciklusban feldolgozza a szerver a kéréseket és egy speciális szerkezetű tömbben összegyűjti a kapott válaszokat.
  4. Miután lefutott az összes kérés feldolgozása, a válaszokat tartalmazó tömböt a kérésnek megfelelő formátumban (javasoltan JSON, esetleg XML) a kimenetre küldi a szerver, amit aztán a kliens megkap és feldolgoz.

Batch kérés esetén az ajánlott request szám 1000 legyen.
Egy post mérete (max_post_size) 32MB lehet. Érdemes figyelni kép feltöltés esetén, hogy ezt ne lépjük túl.

API kérés

AZ API kérés a következő struktúrát kell hogy kövesse:

array(
    'requests' => array(
        0 => array(
            'method' => ...,
            'uri' => ...,
        ),
        1 => array(
            'method' => ...,
            'uri' => ...,
            'data' => array(...)
        ),
        ...
    )
)
  • method: GET, POST, PUT, DELETE
  • uri: A resource-okhoz kapcsolódó API URI
  • data: POST vagy PUT esetén az adatokat tartalmazó tömb

API válasz

<requests>
    <request>
        <method>GET</method>
        <uri>...</uri>
        <response>
            <header>
                <statusCode>...</statusCode>
            </header>
            <body>
                ...
            </body>
        <response>
    </request>
    <request>
        ...
    </request>
    ...
</requests>
  • statusCode: HTTP státusz kódja. Ha rendben volt a kérés kiszolgálása, ennek az értéke 200, 201 vagy 204 egyébként a hibára utaló státuszkód
  • body: a választ tartalmazza, hiba esetén a hiba szöveges üzenete

Az API batch url technikai okok miatt minden esetben 200-as státuszkóddal tér vissza, így a batch requestekben szereplő statusCode-okat a kliens alkalmazásban kell vizsgálni.

További gyakorlati példák a tömeges küldés használatára.

Gyakori problémák

  • Üres válasz (</response>), vagy "Data parameter not found in POST/PUT!" hibaüzenet 400-as státusz kóddal:

Értelemszerűen nem található data paraméter a küldött tömbben. Ilyen formában küldjük el az adatok a /batch-re:

data[requests][0][method]=GET
 
data[requests][1][method]=GET

 

API Outer ID használata

Felmerült az igény, hogy egyes ügyfeleink saját egyedi azonosítókkal (OUTER_ID) szeretnék ellátni és használni a resource-okat, az általunk generáltakkal (API_ID) szemben, erre az alább ismertetett módon biztosítunk lehetőséget.

Az OuterID használatát csak batch kérés esetén javasoljuk, hogy a batch kérés ideéig lehetséges legyen hivatkozni egy adott resource-ra. Kliens oldali tárolását nem javasoljuk, mert egyrészt felülírható, így más integráció felülírhatja, másrészt az OuterID nem törlődik az adott resource törlése esetén. Ezért a kérések alkalmával félrevezető lehet hogy nem létező resource-ra érkezik módosítás, ami hibára fut vagy más resource-ra fog mutatni az OuterID mint amihez eredetileg fel lett véve. A fentiek miatt csak batch kérés esetén javasoljuk a használatát és az egyes batch kérések alkalmával egyedi OuterID használata javallott.

Resource létrehozásakor

POST: POST esetén, ha nem adunk meg ID-t, akkor a rendszer létrehoz egyet és ezt adja vissza válaszként. Ha megadunk ID-t, akkor azt a rendszer OUTER_ID-ként tárolja le és ezt rendeli a resourcehoz. A későbbiekkel erre az azonosítóra lehet hivatkozni GET, PUT, DELETE metódus során.

Például OUTER_ID használata nélkül egy termékhívás:

Array
(
    [sku] => SKU-11
    [modelNumber] => 0
    [orderable] => 1
    [price] => 139900.0000
    [multiplier] => 1.0000
    [multiplierLock] => 0
    [loyaltyPoints] => 
...
)

Válasz:

HTTP STATUS CODE: 200 vagy 201
<response>
    <href><![CDATA[http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTI0NTE=]]></href>
    <id><![CDATA[cHJvZHVjdC1wcm9kdWN0X2lkPTI0NTE=]]></id>
    <innerId><![CDATA[1]]></innerId>
    <sku><![CDATA[SKU-11]]></sku>
...
</response>

 

OUTER_ID használatával:

uri => http://shopname.api.shoprenter.hu/products/SKU-11
data => Array ( [sku] => SKU-11 [modelNumber] => 0 [orderable] => 1 [price] => 139900.0000 [multiplier] => 1.0000 [multiplierLock] => 0 [loyaltyPoints] =>
...
)

Válasz:

HTTP STATUS CODE: 200 vagy 201
<response>
    <href><![CDATA[http://shopname.api.shoprenter.hu/products/SKU-11]]></href>
    <innerId><![CDATA[1]]></innerId>
<id><![CDATA[SKU-11]]></id> <sku><![CDATA[SKU-11]]></sku>
...
</response>

PUT: PUT esetében kötelező megadni vagy API_ID-t vagy OUTER_ID-t az URI-ban. Ha ez az ID OUTER_ID, akkor megköveteli a rendszer, hogy már létezzen hozzá resource, egyéb tekintetben minden a POST-nál ismertetett módon zajlik. Ez azt jelenti, hogy PUT-tal és OUTER_id-val nem tudunk új resource-ot létrehozni, ellentétben az API_ID-val történő létrehozással szemben.

GET: GET esetén hivatkozhatunk a kérés során az URI-ben OUTER_ID-ra, ha korábban már létrehoztuk a resourcet OUTER_ID-val ellátva.

DELETE: Törlés esetén ha létezik a resource-hoz OUTER_ID, azt töröljük vele egyetemben.

Létező resource esetén

Amennyiben már egy létező resource-ot szeretnénk ellátni OUTER_ID-val vagy éppen a meglévőt szeretnénk módosítani, ezentúl erre is biztosítunk lehetőséget. Minden resource tartalmaz egy id property-t, amely az OUTER_ID amennyiben létezik, ha nem akkor pedig az általunk generált API_ID, példa egy resource-ra:

<response>
<href><![CDATA[http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTk2]]></href>
<id><![CDATA[cHJvZHVjdC1wcm9kdWN0X2lkPTk2]]></id>
<innerId><![CDATA[96]]></innerId>
<sku><![CDATA[BI-NAT004HU30]]></sku>
<price><![CDATA[2759]]></price>
<stock1><![CDATA[10]]></stock1>
<stock2><![CDATA[20]]></stock2>
<stock3><![CDATA[0]]></stock3>
<stock4><![CDATA[0]]></stock4>
...
</response>

POST/PUT: POST és PUT kérés esetén egyszerűen a küldött adatokban szerepelni kell az id property-nek. Amennyiben az adott resourcehoz nem létezik OUTER_ID, akkor létrehozzuk azt. Ha pedig létezik, akkor felülírjuk.
Példa egy POST/PUT kérésre:

uri => http://shopname.api.shoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTk2
data => Array ( [id] => TesztOuterID [price] => 2760
[stock1] => 12
...
)

Ebben az esetben az id property-ként elküldtük a TesztOuterID-t. Így az adott resource megkapja az OUTER_ID-nak. Tehát az API válaszban már az id property az újonnan beálított OUTER_ID lesz. Továbbá az adott resource elérése is megváltozik.

<response>
<href><![CDATA[http://shopname.api.shoprenter.hu/products/TesztOuterID]]></href>
<id><![CDATA[TesztOuterID]]></id>
<innerId><![CDATA[96]]></innerId>
<sku><![CDATA[BI-NAT004HU30]]></sku>
<price><![CDATA[2760]]></price>
<stock1><![CDATA[12]]></stock1>
...
</response>

GET: GET kérés esetén hivatkozhatunk az URI-ben OUTER_ID-ra:

/products/TesztOuterID

DELETE: Törlés esetén ha létezik a resource-hoz OUTER_ID, azt töröljük vele egyetemben.

 

Kiterjesztett Resourceok (Extend Resource)


A kiterjesztett resource-okkal könnyebb az adatcsere. Az API fejlesztői dokumentációban a resource nevek mögötti Extend szó jelzi, mely resource-ok rendelkeznek ezzel a funkcionalitással.
Tehát a resource-oknak lényege, hogy a kapcsolódó adataikat is lekérdezhessük a közvetlenül response-ban. Így egy termék esetén nem kell külön kéréseket indítani, ha le akarjuk kérni a leírását, akcióit, vevőcsoportárait, stb.

Ezeket módosíthatjuk is egy resource-on belül egyetlen kéréssel, viszont itt merőben más működése van a kérés típusoknak attól függően, hogy a kapcsolt resource-ok milyen kapcsolatban állnak az aktuális resource-szal.

OneToMany kapcsolat

Pl.: Egy termékhez több termékleírás tartozhat. Product Extend esetén a Product Descriptions

POST kérés esetén a kapcsolódó adatokat (Resource dokumentációban * Kapcsolódó Resource jelölés) mindig létrehozzuk.
Egy példán keresztül szemléltetve: Egy termék 2 kategóriában van. POST kéréssel küldünk 3 kategóriát, akkor azokat pluszban vesszük fel, tehát a termék már 5 kategóriában fog szerepelni. Ha valamelyik kategória kapcsolata már létezett, akkor nem fogjuk végrehajtani a POST kérést azzal a hibaüzenettel, hogy az adott kategória kapcsolat már létezik.

PUT kérés esetén a kapcsolódó adatokat (Resource dokumentációban * Kapcsolódó Resource jelölés) felülírjuk.
Egy hasonló példán bemutatva: Egy termék 2 kategóriában van. PUT kéréssel küldünk 3 kategóriát, akkor a meglévő 2 kategóriát felül fogjuk írni a küldött 3 kategóriával. Tehát a sikeres kérés után a termék csak abban a 3 kategóriában fog szerepelni, amelyik a kérésben szerepelt. Ekkor nincs hibaüzenet akkor sem, ha meglévő kategóriákat küldtünk. Egyszerűen a meglévőek le vannak cserélve a küldöttre.
Ha azt szeretnénk elérni, hogy egyetlen kategóriában sem szerepeljen a termék azt PUT kéréssel tudjuk megoldani. Ekkor a kategóriák helyett egy üres tömböt küldünk, tehát az adott termék meglévő kategóriáit lecseréljük üresre így nem lesznek kategóriái.

OneToOne

Pl.: Egy termék egy gyártó alá tartozhat. Product Extend esetén a Manufacturer. (Egyenlőre ez az egyetlen ilyen kinyitott, OneToOne kapcsolat)

POST és PUT működése megegyezik egy ilyen tipusú, Extend resoruce-hoz tartozó mező esetén.

  1. Ha a OneToOne mezőhöz tartozó, elküldött adattömb csak egy resource id-t tartalmaz,
    úgy a kapcsolt resource egyed létezése esetén, erre cseréljük ki az előző resource id-t.
    Pl.: Ha az Product Extend resoruce-ra POST-ot küldünk, melyben a manufacturer-el kapcsolatos adatokban csak egy resource id található,
    akkor a rendszer megpróbálja lecserélni az előző gyártót az újonnan elküldöttel.

  2. Ha a OneToOne mezőhöz tartozó, elküldött adattömb csak mezőket és hozzá tartozó értékeket tartalmaz, de resouce id-t nem,
    úgy új kapcsolt resource egyedet hozunk létre, és ezt kötjük az eredeti Extend resourcehoz.
    Pl.: Ha az Product Extend resoruce-ra POST-ot küldünk, melyben a manufacturer-el kapcsolatos adatok találhatóak, de resource id nem,
    akkor a rendszer létrehozza az új gyártót, és a terméhez kapcsolja.

  3. Ha a OneToOne mezőhöz tartozó, elküldött adattömb resource id-t, mezőket és hozzá tartozó értékeket tartalmaz, úgy a resource id-hoz tartozó, létező resource egyedet próbálja a rendszer frissíteni, egyébként létrehozza azt.

Van még kérdése? Kérelem beküldése

4 Megjegyzések

  • Avatar
    Takó Kornél

    Sziasztok!

    Kérlek titeket, hogy ha új infók kerülnek fel az apival kapcsolatban, akkor értesítsetek emailben. Köszi.

  • Avatar
    Gulyás Zsolt
    Sziasztok! API-n keresztül lehet új rendelést és/vagy termékeket felvenni? Köszi! G. Zsolt
  • Avatar
    Valkai József

    Van ennek angol nyelvu forditasa? Kellene nagyon!

  • Avatar
    averp

    Van itt fentebb két példa (egy bekezdésen belül!!), ami ellentmond egymásnak:
    1) /orders?page=0&limit=5
    2) /orders/b3JkZXItb3JkZXJfaWQ9Mw==
    Most akkor kell az orders után / karakter vagy nem?
    Milyen kódolás van a 2. példában? A 2. példában szereplő kód Base64 kikódolás után: order-order_id=3
    Ez végképp nem stimmel egyik említett példával sem.

Kérjük, Belépés után hagyjon megjegyzést.