SOMACRM API kapcsolat - fejlesztői dokumentáció

Státusz: webre kitehető tudásbázis cikk
Rendszer: SOMACRM / CRM Webservice 8.3
Cél: külső rendszerek biztonságos kapcsolása a SOMACRM rendszerhez API-n keresztül.

Rövid áttekintés

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, megrendelés, számla, hibajegy vagy egyedi modul adatainak átadása;
• külső ERP, webáruház, ügyfélportál vagy egyedi alkalmazás összekötése a SOMACRM rendszerrel.

Az API fejlesztőknek és integrátoroknak készült. Nyilvános frontend JavaScriptből közvetlenül nem javasolt hívni, mert az access key nem kerülhet ki a böngészőbe.

Alap végpont

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 adatok:

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

Biztonsági ajánlá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 vagy környezeti változóban legyen, ne 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.
• Csak a szükséges modulokra és műveletekre adjunk jogosultságot.

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. Access key hash 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 getCrmModuleIdPrefix() 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ása előtt, mert a kötelező mezők modulonként és testreszabásonként eltérhetnek.

PHP kliens használata

A csomagban található javított PHP minta:

php-pelda/SomacrmWebserviceClient.php
php-pelda/pelda_hasznalat.php

A minta szerveroldali használatra készült. A belépési adatokat környezeti változókból is tudja olvasni:

export SOMACRM_URL="https://sajat-crm-domain.hu/"
export SOMACRM_USERNAME="api_felhasznalo"
export SOMACRM_ACCESS_KEY="felhasznalo_hozzaferesi_kulcsa"

Adat lekérése CRM-ből

<?php
require_once 'SomacrmWebserviceClient.php';

$client = new SomacrmWebserviceClient(
    'https://sajat-crm-domain.hu/',
    'api_felhasznalo',
    'felhasznalo_hozzaferesi_kulcsa'
);

$record = $client->retrieve(12345, 'Contacts');
var_dump($record);

Ahol:

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

Ha már webservice ID áll rendelkezésre, például 12x12345, azt is meg lehet adni. A minta felismeri, és nem tesz elé új prefixet.

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

<?php
require_once 'SomacrmWebserviceClient.php';

$client = new SomacrmWebserviceClient(
    'https://sajat-crm-domain.hu/',
    'api_felhasznalo',
    'felhasznalo_hozzaferesi_kulcsa'
);

$record = $client->create('Contacts', [
    'lastname' => 'Teszt',
    'firstname' => 'Kapcsolat',
    'assigned_user_id' => '19x1'
]);

var_dump($record);

Megjegyzés: az assigned_user_id értékének olyan felhasználóra kell mutatnia, amelyhez a rekord hozzárendelhető. Sok rendszerben a felhasználói azonosító is webservice formátumú, például 19x1. Egyedi rendszereknél ezt előzetesen egyeztetni kell.

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

<?php
require_once 'SomacrmWebserviceClient.php';

$client = new SomacrmWebserviceClient(
    'https://sajat-crm-domain.hu/',
    'api_felhasznalo',
    'felhasznalo_hozzaferesi_kulcsa'
);

$success = $client->updateFields(12345, 'Contacts', [
    'lastname' => 'Módosított vezetéknév',
    'firstname' => 'Módosított keresztnév'
]);

var_dump($success);

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

$result = $client->query("select * from Contacts where lastname='Teszt';");

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.

cURL példák

Challenge token

curl "https://sajat-crm-domain.hu/webservice.php?operation=getchallenge&username=api_felhasznalo"

Login

curl -X POST "https://sajat-crm-domain.hu/webservice.php" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "operation=login" \
  --data-urlencode "username=api_felhasznalo" \
  --data-urlencode "accessKey=GENERALT_MD5_KULCS"

Modul leírása

curl "https://sajat-crm-domain.hu/webservice.php?sessionName=SESSION_ID&operation=describe&elementType=Contacts"

Rekord lekérése

curl "https://sajat-crm-domain.hu/webservice.php?sessionName=SESSION_ID&operation=retrieve&id=12x12345"

Gyakori modulnevek

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

Mit kell egyeztetni integráció előtt?

Integráció előtt javasolt tisztázni:

1. Melyik CRM rendszerhez kell kapcsolódni?
2. Mely modulokat kell használni?
3. Csak olvasás, csak írás vagy kétirányú kapcsolat kell?
4. Mely mezők kötelezőek?
5. Ki legyen a rekord felelőse (assigned_user_id)?
6. Kell-e duplikáció ellenőrzés e-mail, adószám vagy külső azonosító alapján?
7. Kell-e naplózni a külső rendszerből érkező módosításokat?
8. Kell-e teszt CRM környezet?
9. Milyen adatmennyiség és milyen gyakoriság várható?
10. Szükséges-e egyedi API endpoint vagy elegendő az alap webservice?

Fontos megjegyzés

A SOMACRM rendszerek egyedileg testreszabhatók, ezért az egyes modulok mezői, kötelező mezői és státuszai ügyfelenként eltérhetnek. Éles integráció előtt mindig ellenőrizni kell a konkrét rendszer modulstruktúráját és jogosultságait.