ShopRenter API

Az új ShopRenter API alapjaiban változtatja meg a ShopRenterrel való integráció lehetőségét.

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 úgy vélem jól látszik, 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 alábbi oldalon például a fejlesztők számára biztosítunk információkat az API-val kapcsolatban:

https://www.shoprenter.hu/api/doc/

A fejlesztőknek továbbá minta PHP fájlokat is biztosítunk az egyszerűbb beállítás érdekében, melyet ide kattintva érhet el.

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 lehet igényelni és beállítani Gold vagy annál nagyobb csomagos ügyfeleinknek.

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.

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.

Change Log

2017-06-12 Beszédesebb Hibaüzenetek

2017-06-26 OuterID utólag is felvehető és módosítható

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.