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, szöveges tartalmakat, 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.

Fontos még megjegyezünk, hogy multipart/form-data-t fogadunk el content-typeként a küldés során.

A maximálisan indítható requestek limitje 180/perc Ezt mindenképpen figyelembe kell venni a fejlesztés során. Túllépés esetén 498-as hibakóddal találkozhatunk.

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.

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

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.

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 resurceokkal könnyebb az adatcsere. Jelenleg két ilyen resourceunk van a productExtend és az orderExtend.
Ezeknek a resourceoknak a lényege, hogy a kapcsolódó adataikat is visszaadjuk a response-ban. Tehát például 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.

Sőt ezeket módosíthatjuk is egy resourceon belül egyetlen kéréssel.
Viszont itt merőben más működése van a kérés típusoknak.

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.
Továbbá PUT kéréssel tudjuk azt megoldani, az előző példáknál maradva, ha azt szeretnénk elérni hogy egyetlen kategóriában sem szerepeljen a termék. Akkor a kategóriák helyett egy üres tömböt küldünk. Ekkor a meglévő kategóriáit lecseréljük üresre azaz nem lesznek kategóriái.

 

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.