MiniCRM API : MiniCRM Ügyfélszolgálat

MiniCRM Súgó/Tippek & Trükkök/Webfejlesztőknek

MiniCRM API

Keszei Csaba
feladva augusztus 01, 2011 15:18

Tartalomjegyzék

MiniCRM API
Elérhető szolgáltatások
PHP Példa Program

MiniCRM API

A MiniCRM értékesítési CRM rendszer nyílt, az abba rögzített adatok MiniCRM API-n keresztül elérhetőek más programok számára, és azok a meglévő adatokat módosíthatják, bővíthetik.

A MiniCRM API egy egyszerű felület, ami használható bármilyen programozási nyelvből (Javascript, PHP, C#, C, Java, stb…), az egyetlen feltétel, hogy a programot futtató számítógép rendelkezzen működő internetkapcsolattal, el tudja érni a MiniCRM API-t, valamint a program használója rendelkezzen érvényes MiniCRM rendszer eléréssel, és abban a MiniCRM API modult bekapcsolja.

Azonosítás szabványos http azonosítással “HTTP Auth” történik. Az azonosításhoz szükséges felhasználói rendszer azonosító (továbbiakban SystemId) és API kulcs jelszó (továbbiakban API-Key) a MiniCRM rendszerén belül a Testreszabás > Beállítások oldalon kérhető le.

A MiniCRM API használható "HTTP Secure" kapcsolaton keresztül is a https:// előtag használatával.

MiniCRM API Url:
http://SystemId:APIKey@api.minicrm.hu/ vagy
https://SystemId:APIKey@minicrm.hu/api/

PHP fejlesztők számára készítettünk egy MiniCRM API PHP klienst, amivel egyszerűen és gyorsan (php tömbök építésével és értelmezésével) lehet a MiniCRM API-t használni.

A MiniCRM API php Kliens és példaprogram leírása és letöltése itt található

A MiniCRM API .NET kliens letölthető innen

Kódlap

A MiniCRM API az UTF-8 kódlapot használja. Minden bejövő paramétert UTF-8 kódolásban vár és minden választ UTF-8 kódlapon ad.

Formátum

Bemeneti adatformátum választható: REST/XML/JSON/PHP serialize. Kimeneti adatformátum választható: XML/JSON/PHP serialize. Kimeneti adatformátum alapesetben XML, állítható a tilde „~” paraméter segítségével, pl.:

http://api.minicrm.hu/partners?Query=pelda&~=json

Elérhető szolgáltatások

Keresés ügyfél adatbázisban

Azonosítás szükséges, példa url:

http://api.minicrm.hu/partners?Email=kapcsolat@cegnev.hu

Használható paraméterek:

Query: szabadszavas keresés névben és leírásban, pl: Query=pelda
Tag: keresés címke alapján, pl: Tag=vip
StatusId: státusz azonosító alapján, akár tartományra is lehet keresni, pl: StatusId=1000-3000
Email: keresés emailcím (céges & kapcsolat) alapján, pl.: Email=cegnev.hu

Válaszban a találatok egy Partners tömbben érkeznek. Azon belül egy-egy elem egy Partner tömbben található. A listába csak a legfőbb adatok kerülnek be. Az egyes partnerekről a teljes elérhető adat lekérdezhető API-n keresztül a Url mezőben kapott címről.

Példa válasz XML formátumban (JSON & PHP esetén tartalom és struktúra megegyezik, csak a formátum változik):

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Ok</Status>
<PartnersCount>2</PartnersCount>
<Partners>
<Partner>
<Id>1</Id>
<Name>Partner 1.</Name>
<Email>partner1@mail.hu</Email>
<Phone></Phone>
<Url>http://api.minicrm.hu/partners/1</Url>
<StatusId>1600</StatusId>
<StatusName>Workshop</StatusName>
<Tags>vip</Tags>
<ContactName>Kiss Geza</ContactName>
<ContactEmail>kiss_geza@mail.hu</ContactEmail>
<ContactMobile>30-123-4567</ContactMobile>
<ContactPhone></ContactPhone>
</Partner>
<Partner>
<Id>2</Id>
<Name>Partner 2.</Name>
<Email>partner2@mail.hu</Email>
<Phone></Phone>
<Url>http://api.minicrm.hu/partners/2</Url>
<StatusId>1100</StatusId>
<StatusName>Hirlevel feliratkozo</StatusName>
<Tags></Tags>
<ContactName>Nagy Geza</ContactName>
<ContactEmail>nagygeza@mail.hu</ContactEmail>
<ContactMobile></ContactMobile>
<ContactPhone></ContactPhone>
</Partner>
</Partners>
</Response>

Ügyfél adatlap letöltés

Egy kiválasztott ügyfél adatainak lekérdezése, ügyfél azonosító alapján. A teljes Url-t visszaadja a MiniCRM API kereső szolgáltatás. Használatához azonosítás szükséges, példa url:

http://api.minicrm.hu/partners/12345678/?Addresses&Contacts

Paraméterek nélkül az ügyfél törzsadatait adja vissza. Opcionálisan az alábbi paraméterek beállíthatóak (egy lekérésben több is), ha további ügyfélhez kapcsolódó adatokat szeretnénk lekérni:

Addresses: címek beillesztése a válaszba
Contacts: kapcsolatok beillesztése a válaszba
ToDos: teendők beillesztése a válaszba
Invoices: számlák beillesztése a válaszba

Válaszban az adatlap egy Partner tömbben érkezik. Azon belül megtalálhatóak a partner adatlap mezői, valamint a bejövő paraméterekhez hasonló nevű tömbökben a kért kapcsolódó elemek. Minden objektum tartalmazza az alap és extra mezőket egyaránt. A maximális teljesítmény érdekében minden lekérdezésben érdemes csak a valóban szükséges & használt adatokat lekérni.

Példa válasz XML formátumban (JSON & PHP esetén tartalom és struktúra megegyezik, csak a formátum változik):

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Ok</Status>
<Partner>
<Id>1</Id>
<Name>Partner 1.</Name>
<StatusId>Hirlevel feliratkozo</StatusId>
...
<Addresses>
<Address>
<Id>1234</Id>
<Type>Szekhely</Type>
...
</Address>
<Address>
<Id>1235</Id>
<Type>Levelezesi cim</Type>
...
</Address>
</Addresses>
<Contacts>
<Contact>
<Id>4321</Id>
<Default>Igen</Default>
<FirstName>Geza</FirstName>
<LastName>Kiss</LastName>
...
</Contact>
</Contacts>
<ToDos>
<Todo>
<Id>1</Id>
<UserId>1</UserId>
...
</Todo>
</ToDos>
<Invoices>
<Invoice>
<Id>1</Id>
...
</Invoice>
</Invoices>
</Partner>
</Response>

Ügyfél adatlap mentés

Meglévő ügyfél adatlap módosítása, vagy új létrehozása. Célszerű csak a módosult adatokat újraküldeni, így hatékonyabban futhatnak a programok, elkerülhető az időközben már módosult adatok visszaállítása korábban letöltött értékre. Azonosítás szükésges, példa URL:

http://api.minicrm.hu/partners/12345678/

A szolgáltatás URL megegyezik az ügyfél adatlap letöltés URL-jével. GET kéréssel ügyfél adatlap letöltés kezdeményezhető, POST kéréssel pedig adatmódosítás. Új ügyfél felvétele az ügyfélazonosító kihagyásával lehetséges (példa url végén található 12345678 lehagyása).

Bemeneten várt adatstruktúra megegyezik az ügyfél adatlap letöltéskor kapott struktúrával. Bemeti formátum lehet POST tömb/XML/JSON/PHP serializált tömb.

Példa bemenő adatokra:

<?xml version="1.0"?>
<Partner>
<Name>Partner Neve</Name>
<Email>felhasznalo@example.com</Email>
<Contacts>
<Contact>
<Id></Id>
<FirstName>Geza</FirstName>
<LastName>Kovacs</LastName>
<Email>kovacs.geza@example.com</Email>
...
</Contact>
</Contacts>
<Addresses>
<Address>
<Id></Id>
<PostalCode>1111</PostalCode>
<City>Budapest</City>
<Address>Kozterulet neve 4.</Address>
</Address>
</Addresses>
<Invoices>
<Invoice>
<Id></Id>
<Issued>2010-05-06</Issued>
<Prompt>2010-06-06</Prompt>
<Amount>123000</Amount>
<Number>HUF-2010/002134</Number>
</Invoice>
</Invoices>
</Partner>

Példa válasz sikeres mentés esetén

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Ok</Status>
<Partner>
<Id>1234</Id>
<Invoices>
<Invoice>
<Id>3214</Id>
<Number>HUF-2010/002134</Number>
</Invoice>
</Invoices>
</Partner>
</Response>

Fájl feltöltése

Ügyfelekhez lehet dokumentumokat csatolni a híváson keresztül. Azonosítás szükséges, URL:

http://api.minicrm.hu/files/

Bemenő paraméterek:

FileName (opcionális): MiniCRM rendszerben használni kívánt fájlnév
PartnerId (kötelező): partner azonosítója
InvoiceId (opcionális): számla azonosítója
file (kötelező): feltöltendő állomány

Feltöltésre példát a MiniCRM API php kliens példában talál.

Példa válasz, sikeres felöltés esetén:

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Ok</Status>
<Url>http://api.minicrm.hu/files/1-123bf436a789dca8d880c04c67cc17ac2<...>
</Response>

Fájl letöltése

Dokumentum letöltése azonosítás nélkül lehetséges, csak a fájl azonosítója kell hozzá, pl:

http://api.minicrm.hu/files/1-19ed67555db2f5521a95c6b18e7aa5e8

Válaszban visszaadja a keresett állományt vagy hibaüzenetet, amennyiben az nem található.

Hibaüzenetek

Hiba esetén a MiniCRM API a válasz tömbben küldi vissza a hiba kódját és leírását. Response->Status == Fail, és megjelenik egy Error tömb.

Példa hibaüzenetre:

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Status>Fail</Status>
<Error>
<Code>103</Code>
<Msg>Ismeretlen metodus: Ehco</Msg>
</Error>
</Response>

Használt hibakódok

101: Hiba a beérkezett adatokban
102: Hiba a válasz formátumában
103: Ismeretlen metódus
110: Üres keresési feltételek
120: Nincs partner ID
121: Hibás partner ID
122: Nem sikerült menteni a partner adatait
130: Hibás dokumentum azonosító
140: Nincs meg a mappa ID
141: A mappa nem talalható
150: Ajánlat ID nem létezik
160: Számla ID nem létezik
170: Nincs feltöltve file
171: Feltöltési hiba
172: Ez a kiterjesztés nem megengedett
173: File feltöltési hiba
174: Szerver hiba!

PHP Példa program

<?php 
require_once 'minicrm.php';
$mc = new MiniCRM('copy-paste-the-api-url-from-your-system(Customization/Settings)(Testreszabás/Beállítások)');
$TempName = tempnam('/tmp', 'minicrm_').'.txt';
file_put_contents($TempName, 'Példa számla kép. Itt egy számlázóprogram egy valódi pdf-et generál.');
$ToDos[0] = array(
'Type' => 'Telefon',
'DeadLine' => '2010-12-24 19:00:00',
'ToDo' => 'Ajándékot leszállítani'   
);
$Invoices[0] = array(
'Amount' => 10000, 
'Issued' => '2010-12-01',
'Performance' => '2010-12-01',
'Prompt' => '2010-12-31',
'Number' => '2010/001/Ft'
);
$Partner = Array(
'Name' => 'Példa ügyfél',
'Email' => 'pelda@minicrm.local',
'Referrer' => 'Más weboldalon látott hivatkozás',
'StatusId' => 'Aktív',
'ToDos' => $ToDos,
'Invoices' => $Invoices
);
//Save Partner
$Response = $mc->SavePartner($Partner);
$PartnerId = $Response['Id'];
$InvoiceId = $Response['Invoices'][0]['Id'];
$Url = $mc->Upload($TempName, 'Számlamásolat-2001-001.txt', 'Számlamásolatok', $PartnerId, $InvoiceId);
echo "Download the new file from: {$Url}<br>";
unlink($TempName);
//Lookup saved Partners
$Partners = $mc->SearchPartner(false, false, false, 'pelda@minicrm.local');
//Get last results PartnerID
$LastId = $Partners[count($Partners)-1]['Id'];
//Download last partner with selected email (should be just what we saved before)
var_dump($mc->GetPartner($LastId, array('ToDos', 'Invoices')));
?>