SOMACRM API kapcsolat – CRM Webservice fejlesztői útmutató

Mire használható a SOMACRM API?

A SOMACRM webservice segítségével külső rendszerek kapcsolhatók a CRM-hez. Tipikus felhasználási esetek:

• új vevőjelölt, kapcsolat vagy cég rögzítése weboldalról, webshopból vagy külső űrlapból;
• meglévő CRM rekord adatainak lekérése;
• meglévő rekord módosítása;
• ajánlat, rendelés, számla vagy hibajegy adatainak átadása;
• külső ERP, webáruház, ügyfélportál vagy egyedi alkalmazás összekötése a SOMACRM-mel.

Az API-t fejlesztőknek és integrátoroknak ajánljuk. Nyilvános frontend JavaScriptből közvetlenül ne hívják meg, mert a hozzáférési kulcs nem kerülhet ki a böngészőbe.

Alap adatok

A webservice végpont minden SOMACRM rendszerben az adott CRM domain alatt érhető el:

https://sajat-crm-domain.hu/webservice.php

A kapcsolódáshoz szükséges:

Adat	Leírás
CRM URL	A SOMACRM rendszer alap URL-je vagy közvetlenül a webservice.php végpont.
Felhasználónév	A CRM-ben létrehozott felhasználó neve.
Hozzáférési kulcs	A felhasználó profil oldalának alján található access key.
Modulnév	Annak a CRM modulnak az API neve, amelyben dolgozni szeretnénk. Például Leads, Accounts, Contacts.

A hozzáférési kulcs jelszóként kezelendő. Ne kerüljön GitHubra, weboldal forrásába, böngészőbe vagy e-mailben továbbított nyílt kódba.

Javasolt biztonsági beállítások

Éles kapcsolathoz javasolt külön integrációs felhasználót létrehozni. Ennek csak azokhoz a modulokhoz és mezőkhöz legyen joga, amelyekre az integrációnak ténylegesen szüksége van.

Javasolt szabályok:

• HTTPS használata kötelező.
• Az access key titkos konfigurációban legyen, ne a publikus kódban.
• Frontendből ne legyen közvetlen API-hívás, használjon saját backend proxyt.
• Éles PHP kódban ne legyen kikapcsolva az SSL tanúsítvány ellenőrzése.
• Nagy mennyiségű adatmozgásnál legyen naplózás és hibakezelés.
• Érdemes teszt CRM rendszerben kezdeni az integrációt.

Bejelentkezési folyamat

A SOMACRM webservice kétlépcsős azonosítást használ.

1. Challenge token lekérése

GET /webservice.php?operation=getchallenge&username=FELHASZNALONEV

A válaszban érkezik egy token érték.

2. AccessKey előállítása

A belépéshez nem a nyers hozzáférési kulcsot kell beküldeni, hanem az alábbi MD5 hash-t:

$generatedKey = md5($token . $accesskey);

3. Login kérés

POST /webservice.php
operation=login
username=FELHASZNALONEV
accessKey=GENERALT_MD5_KULCS

Sikeres válasz esetén a rendszer visszaadja a sessionName értéket. A további API műveletekhez ezt kell használni.

Rekordazonosító formátum

A CRM rekordok webservice azonosítója nem csak a sima CRM ID. A formátum:

modulPrefixxCRMID

Példa:

13x746840

A modul prefix a modul leírásából kérdezhető le describe művelettel. A mellékelt PHP osztály ezt automatikusan kezeli a getCrmModuleIds() metódussal.

Modul leírásának lekérése

A modul mezőinek, kötelező mezőinek és prefixének ellenőrzésére használható:

GET /webservice.php?sessionName=SESSION_ID&operation=describe&elementType=Contacts

Ez különösen fontos új rekord létrehozás előtt, mert a kötelező mezők modulonként eltérhetnek.

Adat lekérése CRM-ből

PHP példa:

<?php
include_once('CRMWebservice.php');

$url = 'https://sajat-crm-domain.hu/';
$username = 'api_felhasznalo';
$accesskey = 'felhasznalo_hozzaferesi_kulcsa';

$CRMWebservice = new CRMWebservice($username, $accesskey, $url);

$crmid = 12345;
$modulename = 'Contacts';

$record = $CRMWebservice->getCrm($crmid, $modulename);

echo '<pre>';
var_dump($record);
echo '</pre>';

Ahol:

• $crmid: a lekérendő adat CRM ID-ja;
• $modulename: a modul API neve, amelyből a lekérés történik.

Új adat rögzítése CRM-be

PHP példa kapcsolattartó létrehozására:

<?php
include_once('CRMWebservice.php');

$url = 'https://sajat-crm-domain.hu/';
$username = 'api_felhasznalo';
$accesskey = 'felhasznalo_hozzaferesi_kulcsa';

$CRMWebservice = new CRMWebservice($username, $accesskey, $url);

$modulename = 'Contacts';

$recordData = array(
    'lastname' => 'Teszt',
    'firstname' => 'Kapcsolat',
    'assigned_user_id' => '1'
);

$record = $CRMWebservice->createCrm($recordData, $modulename);

echo '<pre>';
var_dump($record);
echo '</pre>';

Ahol:

• $recordData: a rögzítendő adatok tömbje;
• $modulename: a modul API neve, amelybe a rekord létrejön.

Megjegyzés: az assigned_user_id értékének olyan felhasználóra kell mutatnia, amelyhez a rekord hozzárendelhető. Egyedi rendszereknél ezt előzetesen egyeztetni kell.

Meglévő adat módosítása CRM-ben

PHP példa:

<?php
include_once('CRMWebservice.php');

$url = 'https://sajat-crm-domain.hu/';
$username = 'api_felhasznalo';
$accesskey = 'felhasznalo_hozzaferesi_kulcsa';

$CRMWebservice = new CRMWebservice($username, $accesskey, $url);

$crmid = 12345;
$modulename = 'Contacts';

$recordData = array(
    'lastname' => 'Módosított vezetéknév',
    'firstname' => 'Módosított keresztnév'
);

$success = $CRMWebservice->editCrm($recordData, $crmid, $modulename);

var_dump($success);

Ahol:

• $recordData: a módosítandó mezők tömbje;
• $crmid: a módosítandó CRM rekord ID-ja;
• $modulename: a modul API neve, amelyben a rekord található.

A módosítás előtt a minta osztály lekéri az aktuális rekordot, ráírja a megadott mezőket, majd teljes rekordként küldi vissza az update művelethez.

Query alapú lekérdezés

A webservice támogat lekérdezéseket is. Példa:

$query = "select * from Contacts where lastname='Teszt';";
$result = $CRMWebservice->getCrmQuery($query, array(
    'url' => 'https://sajat-crm-domain.hu/webservice.php'
));

Javaslat: query használatakor minden külső bemenetet validálni és tisztítani kell. Ne építsünk ellenőrizetlen felhasználói adatból közvetlen query-t.

Gyakori modulnevek

Modulnév	SOMACRM jelentés
Calendar	Naptár, teendők, események
Leads	Vevőjelöltek
Accounts	Cégek
Contacts	Kapcsolatok
Potentials	Lehetőségek
Products	Termékek
Documents	Dokumentumok
Emails	E-mailek
HelpDesk	Ügyfélszolgálati kérések / hibajegyek
Faq	Tudásbázis / GYIK
Vendors	Beszállítók
PriceBooks	Árlisták
Quotes	Ajánlatok
PurchaseOrder	Beszerzési rendelések
SalesOrder	Megrendelések
Invoice	Számlák / díjbekérők, rendszerbeállítástól függően
Campaigns	Kampányok
Events	Események
Users	Felhasználók
Groups	Felhasználói csoportok
Currency	Pénznemek

Egyedi SOMACRM moduloknál az API modulnevet külön egyeztetni kell, mert az eltérhet a képernyőn látható magyar megnevezéstől.

Tipikus hibák és ellenőrzési pontok

Hiba	Lehetséges ok	Teendő
Sikertelen login	Rossz felhasználónév vagy access key	Ellenőrizze a CRM felhasználói profilban az access key-t.
ACCESS_DENIED vagy jogosultsági hiba	Az API felhasználónak nincs joga a modulhoz vagy mezőhöz	Jogosultság ellenőrzése a CRM-ben.
Rekord létrehozás sikertelen	Hiányzik kötelező mező	describe művelettel ellenőrizze a kötelező mezőket.
Update sikertelen	Nem teljes vagy rossz rekordazonosító	Ellenőrizze a modulPrefixxCRMID formátumot.
SSL/cURL hiba	Tanúsítvány, URL vagy szerverbeállítás gond	Éles rendszerben az SSL ellenőrzést javítani kell, nem kikapcsolni.
Hibás karakterek	Nem UTF-8 adatküldés	Küldés előtt minden szöveget UTF-8 formátumban kezeljen.

Minimális integrációs folyamat

1. Integrációs felhasználó létrehozása a SOMACRM-ben.
2. Jogosultságok beállítása csak a szükséges modulokra.
3. Access key lekérése a felhasználói profilból.
4. Teszt login a getchallenge és login művelettel.
5. Modulmezők ellenőrzése describe művelettel.
6. Teszt rekord létrehozása teszt rendszerben.
7. Teszt rekord lekérése és módosítása.
8. Hibakezelés, naplózás, jogosultságok ellenőrzése.
9. Élesítés előtt biztonsági felülvizsgálat.

Letölthető PHP mintaosztály

A SOMACRM webservice használatához adható egy PHP mintaosztály is. A minta célja a kapcsolódás, lekérdezés, létrehozás és módosítás bemutatása. Élesítés előtt a fejlesztőnek a saját rendszeréhez kell igazítania, különösen a hibakezelést, naplózást, jogosultságokat és SSL beállításokat.

Letöltés

Kapcsolat

Integrációs kérdés vagy egyedi API kapcsolat esetén keressen minket:

SOMACRM
Web: https://www.somacrm.hu
E-mail: [email protected]