Rest API

A Rest API használatához minimum 8.0.3-as verziójú Webgalambra van szükség!

A korábbi verziójú Webgalamb API-tól eltérően már nincs szükség adatbázis kapcsolódási adatokra, helyette a Webgalambodban a "Beállítások" menüpont alján a REST API résznél lévő 3 adat segítségével hozható létre kapcsolat a Webgalambbal.

Az API, különböző programozási nyelvű kiegészítők készítésére alkalmas, szakszerű használatához a használt programozási nyelv ismerete feltétlenül szükséges. A súgóban a csak php alapú megoldásokra térünk ki.

Amit fontos tudni

  • A csoportok mindegyike saját azonosítóval rendelkezik, ami egy szám.
  • A feliratkozók minden feliratkozás alkalmával új feliratkozóként kerülnek rögzítésre, ezen okból ha egy cím többször is szerepel a Webgalambban, akkor mindegyik saját feliratkozói azonosítóval rendelkezik.

Mintafájlok letöltése

Laravel-hez készült minta controller: letöltöm
php api class és minta: letöltöm

Kezdeti lépések

Minden kéréshez az alábbi inicializációs részre van szükség.
Az API használatához szükséges adatokat a Webgalambodban a "Beállítások" menüpont alján a REST API résznél találod.

view source
print?
1require_once('restclient.wg.class.php');
2 
3$api_url = 'https://www.honlapom.hu/webgalamb/rapi.php'; /* Webgalamb által kiírt API url */
4$token   = 'c70a630116cze7b8'; /* Webgalamb által kiírt token */
5$secret  = 'zteyyzqwyjiwytnmzgywmwjmytg3mjk1ztjhzduxe44tq5ywi'; /* Webgalamb által kiírt API kulcs */
6 
7$api = new WebgalambRestClient($api_url, $token, $secret);

A kérések elnevezései és a kapott válaszok felépítése megegyezik a korábbi Webgalamb API-nál megszokottal.

Hibák

Hiba esetén a visszatérési tömb része egy "error" nevű kulcs, melynek értéke tartalmazza a hiba okát szövegesen. A további elemek esetenként kisegítő információkat is tartalmaznak a hibával kapcsolatban.

Kapcsolat tesztelése

view source
print?
1//
2$result = $api->get("ping");
3  
4// Eredmény kiírása, feldolgozása
5var_dump($result);

Eredményként vagy a hibaüzenetet vagy pedig success üzenetet ad vissza.

view source
print?
1Minta eredmény:
2 
3Array
4(
5    [success] => string 'success'
6)

Új feliratkozók lekérdezése egy megadott dátumhoz viszonyítva

view source
print?
01$params = [
02    // Csoportazonosító, ha nem adsz meg értéket akkor minden csoportra érvényes
03    'group_id' => 2,
04    // A kezdő dátum, amelyet követően feliratkozók érdekelnek
05    'date'=>'2020-07-13'
06];
07  
08//
09$result = $api->get("GetNewSubscribers", $params);
10  
11// Eredmény kiírása, feldolgozása
12var_dump($result);

Az eredményként kapott tömb az új feliratkozók Webgalambos azonosítóját (kulcs) és csoportok nevét (érték) tartalmazza.

view source
print?
1Minta eredmény:
2 
3Array
4(
5    [335] => string 'minta@mintakft.hu'
6    [336] => string 'example@example.com'
7    [337] => string 'example2@example.com'
8)

Módosult adatokkal rendelkező feliratkozók lekérdezése egy megadott dátumhoz viszonyítva

view source
print?
01$params = [
02    // Csoportazonosító, ha nem adsz meg értéket akkor minden csoportra érvényes
03    'group_id' => 2,
04    // A kezdő dátum, amelyet követően módosult feliratkozók érdekelnek
05    'date'=>'2020-07-13'
06];
07 
08//
09$result = $api->get('GetUpdatedSubscribers', $params);
10  
11// Eredmény kiírása, feldolgozása
12var_dump($result);

Az eredményként kapott tömb az új feliratkozók Webgalambos azonosítóját (kulcs) és csoportok nevét (érték) tartalmazza.

1Minta eredmény:
2 
3Array
4(
5    [122] => string 'minta3@mintakft.hu'
6    [337] => string 'example3@example.com'
7)

Egy adott csoporthoz tartozó feliratkozók azonosítóinak lekérdezése

view source
print?
01$params = [
02    // Csoportazonosító
03    'group_id' => 2,
04];
05 
06//
07$result = $api->get('GetGroupUserIDs', $params);
08  
09// Eredmény kiírása, feldolgozása
10var_dump($result);

Az eredményként kapott tömb az új feliratkozók Webgalambos azonosítóját (érték) tartalmazza.

01Minta eredmény:
02 
03Array
04(
05    [0] => int 337
06    [1] => int 276
07    [2] => int 275
08    [3] => int 277
09    [4] => int 278
10    [5] => int 279
11)

Adott e-mail címhez tartozó Webgalambos azonosítók lekérése

view source
print?
01$params = [
02    // Feliratkozói e-mail cím
03    'mail' => 'example@example.com',
04];
05  
06//
07$result = $api->get('GetUserIDs', $params);
08  
09// Eredmény kiírása, feldolgozása
10var_dump($result);

Az eredményként kapott tömb a megadott e-mail cím összes előfordulásának azonosítóját (érték) tartalmazza.

1Minta eredmény:
2 
3Array
4(
5    [0] => int 275
6    [1] => int 645
7    [2] => int 1244
8)

Feliratkozó adatainak lekérése

Ha e-mail cím alapján kérsz le adatokat, akkor az összes ezen címhez tartozó feliratkozó adatát megkapod, csoporttól függetlenül. Az adataiban azonban szerepel a csoportazonosító is amelyhez tartozik, így könnyen be lehet azonosítani.

Ha a feliratkozó azonosítójával kérdezed le az adatokat, akkor a konkrét feliratkozó adatait kapod meg.

view source
print?
01$params = [
02    // Feliratkozó rögzített e-mail címe (egyszerű változó)
03    'subscriber' => 'example@example.com'
04];
05  
06// vagy
07$params = [
08    // Feliratkozó Webgalambos azonosítója (tömb)
09    'subscriber' => [337, 654]
10];
11  
12//
13$result = $api->get('GetSubscriber', $params);
14  
15// Eredmény kiírása, feldolgozása
16var_dump($result);

Az eredményként kapott tömb a megadott e-mail címhez vagy Webgalambos azonosítóhoz tartozó összes előfordulásának adatait tartalmazza.

01Minta eredmény, több találat esetén:
02 
03Array
04(
05    [0] => Array
06        (
07            [id] => int 337
08            [mail] => string 'example@example.com'
09            [nmail] => string ''
10            [omail] => string ''
11            [ip] => string '11.22.33.44'
12            [datum] => string '2013-03-10'
13            [ipdatum] => string '2014-10-30 13:36:55'
14            [mdatum] => string '2014-10-31 08:38:34'
15            [verify_code] => string 'kaka96265ke71bf86777bkb1k45b5ad93ef7e5e6'
16            [active] => int 1
17            [g] => int 1
18            [a] => int 1
19            [rating] => int 3
20            [Feliratkozási URL] => string ''
21            [Név] => string 'Teszt Elek'
22        )
23    [1] => Array
24        (
25            [id] => int 654
26            [mail] => string 'example@example.com'
27            [nmail] => string ''
28            [omail] => string ''
29            [ip] => string '55.66.77.88'
30            [datum] => string '2014-07-22'
31            [ipdatum] => string '2014-10-30 13:36:55'
32            [mdatum] => string '2014-10-31 08:38:34'
33            [verify_code] => string 'kaka962s5ke71bf86777bkb1k45b5ad93ef7e5e6'
34            [active] => int 1
35            [g] => int 2
36            [a] => int 1
37            [rating] => int 5
38            [Feliratkozási URL] => string ''
39            [Név] => string 'Teszt Elek'
40        )
41)
42 
43Minta eredmény, egy találat esetén:
44 
45Array
46(
47    [id] => int 337
48    [mail] => string 'example@example.com'
49    [nmail] => string ''
50    [omail] => string ''
51    [ip] => string '11.22.33.44'
52    [datum] => string '2013-03-10'
53    [ipdatum] => string '2014-10-30 13:36:55'
54    [mdatum] => string '2014-10-31 08:38:34'
55    [verify_code] => string 'kaka96265ke71bf86777bkb1k45b5ad93ef7e5e6'
56    [active] => int 1
57    [g] => int 1
58    [a] => int 1
59    [rating] => int 2
60    [Feliratkozási URL] => string ''
61    [Név] => string 'Teszt Elek'
62)

Csoportok lekérdezése

view source
print?
1$result = $api->get('GetGroups');
2 
3// Eredmény kiírása, feldolgozása.
4var_dump($result);

Az eredményül kapott tömb a csoportok Webgalambos azonosítóját (kulcs) és csoportok nevét (érték) tartalmazza.

1Minta eredmény:
2 
3Array
4(
5    [1] => string 'Csoport 1'
6    [12] => string 'Csoport 2'
7    [32] => string 'Csoport 3'
8)

Új feliratkozó felvitele

A rögzítendő adatok az e-mail címet lászámítva opcionálisak, megadásuk nem kötelező.

view source
print?
01$params = [
02    'group_id' => 2, // A feliratkozási csoport csoportazonosítója
03      
04    // Rögzítendő adatok
05    'subscriber_data' => [
06        // E-mail cím
07        'mail' => 'example@example.com',  
08  
09        // Feliratkozási dátum, ha nincs megadva akkor az aktuális dátum kerül be
10        'datum' => '2013-03-10',
11  
12        // Státusz: 1 -> aktív, 0 -> inaktív, 2 -> visszapattant
13        // Ha nincs megadva akkor aktív státusszal kerül be
14        'active' => 1,                     
15         
16        // létrehozott feliratkozási mezők értékei (csak minta)
17        'Név' => 'Minta János',
18        'Telefonszám' => '06-70/123-4567',
19        'Cégnév' => 'Minta Kft.'
20    ]
21];
22 
23//
24$result = $api->post('InsertSubscriber', $params);
25  
26// Eredmény kiírása, feldolgozása
27var_dump($result);

Sikeres rögzítés esetén a Webgalambos azonosítóval tér vissza.

1Minta eredmény:
2 
3Array
4(
5    [id] => int 891575
6)

Feliratkozó adatainak módosítása

view source
print?
01$params = [
02    // módosítandó adatok
03    'subscriber_data' => [
04        'Telefonszám' => '06-1/123-4567',
05        'Név' => 'Teszt Elek'
06    ],
07    // Feliratkozó rögzített e-mail címe vagy Webgalambos azonosítója
08    'subscriber' => 'example2@example.com',
09    // Csoportazonosító (kötelező)
10    'group_id' => 2,
11];
12  
13//
14$result = $api->post('EditSubscriber', $params);
15  
16// Eredmény kiírása, feldolgozása
17var_dump($result);

 

1Minta eredmény:
2 
3Array
4(
5    [id] => int 891575
6)

Feliratkozó másolása

view source
print?
01$params = [
02    // Feliratkozó Webgalambos azonosítója
03    'subscriber_id' => 197,
04    // A célcsoport(ok) azonosítói (legalább 1 kötelező!)
05    'target_groups' => [2, 33]
06];
07  
08//
09$result = $api->post('CopySubscriber', $params);
10  
11// Eredmény kiírása, feldolgozása
12var_dump($result);

A visszatérési érték egy tömb a sikeres másolás adataival, ahol a kulcs a csoportazonosítót az érték pedig az adott csoportba történő másolás eredményét tartalmazza.
Alapból minden érték az újonnan létrejött feliratkozó adott csoportban használt Webgalambos azonosítóját jelzi.
Ha null az érték akkor nem sikerült a felvitel, már van ilyen e-mail cím a csoportban.

1Minta eredmény:
2 
3Array
4(
5    [2] => null
6    [3] => 624
7)

Feliratkozó(k) törlése

view source
print?
01$params = [
02    // Feliratkozó rögzített e-mail címe vagy Webgalambos azonosítója
03    'subscriber' => 'example@example.com',
04      
05    // Csoportazonosító(k), ha nem adsz meg értéket akkor minden csoportra érvényes.
06    // Ha feliratkozó azonosításnál id-t használsz akkor ez a paraméter figyelmen kívül lesz hagyva!
07    'group_ids' => []
08];
09  
10//
11$result = $api->post('DeleteSubscriber', $params);
12  
13// Eredmény kiírása, feldolgozása
14var_dump($result);

A visszatérési érték egy tömb a sikeres törlések adataival, ahol a kulcsok a csoportazonosítókat, az értékek pedig a feliratkozó adott csoporthoz tartozó azonosítóját tartalmazza.
Ha nincs visszatérési érték akkor nem törölt senkit, a megadott paramétereknek nem felelt meg egyik feliratkozó sem.

1Minta eredmény:
2 
3Array
4(
5    [2] => int 126
6    [3] => int 264
7)