Webgalamb 8+ súgó

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.

require_once('restclient.wg.class.php');

$api_url = 'https://www.honlapom.hu/webgalamb/rapi.php'; /* Webgalamb által kiírt API url */
$token   = 'c70a630116cze7b8'; /* Webgalamb által kiírt token */
$secret  = 'zteyyzqwyjiwytnmzgywmwjmytg3mjk1ztjhzduxe44tq5ywi'; /* Webgalamb által kiírt API kulcs */

$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

//
$result = $api->get("ping");
 
// Eredmény kiírása, feldolgozása
var_dump($result);

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

Minta eredmény:

Array
(
	[success] => string 'success'
)

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

$params = [
	// Csoportazonosító, ha nem adsz meg értéket akkor minden csoportra érvényes
	'group_id' => 2, 
	// A kezdő dátum, amelyet követően feliratkozók érdekelnek
	'date'=>'2020-07-13' 
];
 
//
$result = $api->get("GetNewSubscribers", $params);
 
// Eredmény kiírása, feldolgozása
var_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.

Minta eredmény:

Array
(
	[335] => string 'minta@mintakft.hu'
	[336] => string 'example@example.com'
	[337] => string 'example2@example.com'
)

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

$params = [
	// Csoportazonosító, ha nem adsz meg értéket akkor minden csoportra érvényes
	'group_id' => 2, 
	// A kezdő dátum, amelyet követően módosult feliratkozók érdekelnek
	'date'=>'2020-07-13' 
];

//
$result = $api->get('GetUpdatedSubscribers', $params);
 
// Eredmény kiírása, feldolgozása
var_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.

Minta eredmény:

Array
(
    [122] => string 'minta3@mintakft.hu'
    [337] => string 'example3@example.com'
)

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

$params = [
	// Csoportazonosító
	'group_id' => 2, 
];

//
$result = $api->get('GetGroupUserIDs', $params);
 
// Eredmény kiírása, feldolgozása
var_dump($result);

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

Minta eredmény:

Array
(
    [0] => int 337
    [1] => int 276
    [2] => int 275
    [3] => int 277
    [4] => int 278
    [5] => int 279
)

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

$params = [
	// Feliratkozói e-mail cím
	'mail' => 'example@example.com', 
];
 
//
$result = $api->get('GetUserIDs', $params);
 
// Eredmény kiírása, feldolgozása
var_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.

Minta eredmény:

Array
(
    [0] => int 275
    [1] => int 645
    [2] => int 1244
)

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.

$params = [
	// Feliratkozó rögzített e-mail címe (egyszerű változó)
	'subscriber' => 'example@example.com' 
];
 
// vagy
$params = [
	// Feliratkozó Webgalambos azonosítója (tömb)
	'subscriber' => [337, 654] 
];
 
//
$result = $api->get('GetSubscriber', $params);
 
// Eredmény kiírása, feldolgozása
var_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.

Minta eredmény, több találat esetén:

Array
(
    [0] => Array
        (
            [id] => int 337
            [mail] => string 'example@example.com'
            [nmail] => string ''
            [omail] => string ''
            [ip] => string '11.22.33.44'
            [datum] => string '2013-03-10'
            [ipdatum] => string '2014-10-30 13:36:55'
            [mdatum] => string '2014-10-31 08:38:34'
            [verify_code] => string 'kaka96265ke71bf86777bkb1k45b5ad93ef7e5e6'
            [active] => int 1
            [g] => int 1
            [a] => int 1
            [rating] => int 3
            [Feliratkozási URL] => string ''
            [Név] => string 'Teszt Elek'
        )
    [1] => Array
        (
            [id] => int 654
            [mail] => string 'example@example.com'
            [nmail] => string ''
            [omail] => string ''
            [ip] => string '55.66.77.88'
            [datum] => string '2014-07-22'
            [ipdatum] => string '2014-10-30 13:36:55'
            [mdatum] => string '2014-10-31 08:38:34'
            [verify_code] => string 'kaka962s5ke71bf86777bkb1k45b5ad93ef7e5e6'
            [active] => int 1
            [g] => int 2
            [a] => int 1
            [rating] => int 5
            [Feliratkozási URL] => string ''
            [Név] => string 'Teszt Elek'
        )
)

Minta eredmény, egy találat esetén:

Array
(
	[id] => int 337
	[mail] => string 'example@example.com'
	[nmail] => string ''
	[omail] => string ''
	[ip] => string '11.22.33.44'
	[datum] => string '2013-03-10'
	[ipdatum] => string '2014-10-30 13:36:55'
	[mdatum] => string '2014-10-31 08:38:34'
	[verify_code] => string 'kaka96265ke71bf86777bkb1k45b5ad93ef7e5e6'
	[active] => int 1
	[g] => int 1
	[a] => int 1
	[rating] => int 2
	[Feliratkozási URL] => string ''
	[Név] => string 'Teszt Elek'
)

Csoportok lekérdezése

$result = $api->get('GetGroups');

// Eredmény kiírása, feldolgozása.
var_dump($result);

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

Minta eredmény:

Array
(
    [1] => string 'Csoport 1'
    [12] => string 'Csoport 2'
    [32] => string 'Csoport 3'
)

Új feliratkozó felvitele

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

$params = [
	'group_id' => 2, // A feliratkozási csoport csoportazonosítója
	 
	// Rögzítendő adatok
	'subscriber_data' => [
		// E-mail cím
		'mail' => 'example@example.com',   
 
		// Feliratkozási dátum, ha nincs megadva akkor az aktuális dátum kerül be
		'datum' => '2013-03-10',
 
		// Státusz: 1 -> aktív, 0 -> inaktív, 2 -> visszapattant
		// Ha nincs megadva akkor aktív státusszal kerül be
		'active' => 1,                      
		
		// létrehozott feliratkozási mezők értékei (csak minta)
		'Név' => 'Minta János',
		'Telefonszám' => '06-70/123-4567',
		'Cégnév' => 'Minta Kft.'
	]
];

//
$result = $api->post('InsertSubscriber', $params);
 
// Eredmény kiírása, feldolgozása
var_dump($result);

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

Minta eredmény:

Array
(
    [id] => int 891575
)

Feliratkozó adatainak módosítása

$params = [
	// módosítandó adatok
	'subscriber_data' => [
		'Telefonszám' => '06-1/123-4567',
		'Név' => 'Teszt Elek'
	],
	// Feliratkozó rögzített e-mail címe vagy Webgalambos azonosítója
	'subscriber' => 'example2@example.com', 
	// Csoportazonosító (kötelező)
	'group_id' => 2, 
];
 
//
$result = $api->post('EditSubscriber', $params);
 
// Eredmény kiírása, feldolgozása
var_dump($result);

Minta eredmény:

Array
(
    [id] => int 891575
)

Feliratkozó másolása

$params = [
	// Feliratkozó Webgalambos azonosítója
	'subscriber_id' => 197, 
	// A célcsoport(ok) azonosítói (legalább 1 kötelező!)
	'target_groups' => [2, 33] 
];
 
//
$result = $api->post('CopySubscriber', $params);
 
// Eredmény kiírása, feldolgozása
var_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.

Minta eredmény:

Array
(
    [2] => null
    [3] => 624
)

Feliratkozó(k) törlése

$params = [
	// Feliratkozó rögzített e-mail címe vagy Webgalambos azonosítója
	'subscriber' => 'example@example.com', 
	 
	// Csoportazonosító(k), ha nem adsz meg értéket akkor minden csoportra érvényes.
	// Ha feliratkozó azonosításnál id-t használsz akkor ez a paraméter figyelmen kívül lesz hagyva!
	'group_ids' => []
];
 
//
$result = $api->post('DeleteSubscriber', $params);
 
// Eredmény kiírása, feldolgozása
var_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.

Minta eredmény:

Array
(
    [2] => int 126
    [3] => int 264
)