MiniCRM API

A legfrissebb MiniCRM API dokumentációnk az alábbi linken érhető el Angol nyelven:

MiniCRM API documentation (EN)

Korábbi Magyar nyelvű API dokumentáció:

MiniCRM API dokumentáció

A MiniCRM nyílt, a benne rögzített adatok MiniCRM API-n keresztül elérhetőek más programok számára, és azokkal a meglévő adatokat módosíthatod, bővítheted.

A MiniCRM API egy egyszerű felület, ami használható bármilyen programozási nyelvből (Javascript, PHP, C#, C, Java, stb…). A használat feltétele, hogy a programot futtató számítógép rendelkezzen működő internetkapcsolattal, el tudja érni a MiniCRM API-t, valamint a program rendelkezzen érvényes MiniCRM rendszerrel, és hozzá tartozó API kulccsal.

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, azaz a böngésző címsorában az r3.minicrm.hu/ után látható, maximum 5 jegyű szám)
• és API kulcs (továbbiakban API-Key), amit adminisztrátor jogosultságú felhasználóként tudsz igényelni a Beállítások > Rendszer képernyőn. Ehhez az Új API kulcs készítése gombra kell kattintani. Ha már generáltál API kulcsot, lehetőséged van újat generálni, vagy törölni a meglévőt.

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

MiniCRM API Url:

https://SystemId:APIKey@r3.minicrm.hu/Api/R3

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 és kimeneti adatformátum minden esetben JSON serialized tömb.

Limitáció

R3 API végpontunkon 60 request / perc rate limitáció van életben. Minden ezt meghaladó kérés 429-es „Too many requests” válasszal elutasításra kerül.

API-val elvégezhető műveletek

• Keresés
• Számla műveletek
• Űrlap beküldése
• Adatlap műveletek
• Példaprogramok
• Termékek és sémák lekérdezése
• Kontaktok létrehozása, lekérése, módosítása
• Teendők létrehozása, lekérése, módosítása
• Címek létrehozása, lekérése, módosítása
• Sablonok lekérése, módosítása
• Külső azonosító (ReferenceId) használata
• Hibaüzenetek

Általános tudnivalók a keresésről

A válaszban a találatok egy tömbben érkeznek, melynek Count kulcsán található a talált elemek száma. A Results kulcs alatt egy-egy külön tömbben találhatóak a megtalált elemek. A listába csak a legfőbb adatok kerülnek be. Az egyes elemekről a teljes elérhető adat lekérdezhető API-n keresztül az Url mezőben kapott címről. Az API keresési oldalanként 100 találatot jelenít meg. A találatok lapozhatóak a Page paraméter segítségével, pl:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?Query=Teszt&Page=1

Fontos, hogy a lapozás az API esetében 0-ról indul, tehát a második oldalt a Page=1 paraméterrel lehet elérni!

Mező alapú keresésnél további extra paraméter lehet az UpdatedSince, amivel csak olyan elemek kerülnek listázásra, amik a megadott dátum után lettek módosítva.

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusId=2500&UpdatedSince=2013-03-01+12:00:00

 Szabad szavas keresés Projektek között

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

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?Query=Teszt

Ilyen esetben a szóra releváns projekteket keresi meg a rendszer. Fontos itt megjegyezni, hogy ilyen esetekben csak a Projektek között keres a rendszer!

Szabadszavas keresés Kontaktok között

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

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact?Query=Kovács

Ilyen esetben a szóra releváns kontaktokat keresi meg a rendszer. Fontos itt megjegyezni, hogy ilyen esetekben csak a Kontaktok között keres a rendszer! Telefonszámok keresésére ez a típusú keresés javasolt! Telefonszámok keresésekor a rendszer normalizálja a kapott telefonszámot és az alapján végzi a keresést. A keresés a telefonszámok végéről indul, így elég megadni a telefonszám utolsó számjegyeit, hogy releváns találatokat kapjunk. Példa Url:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact?Query=2345678

Számlázó API

A MiniCRM Számlázó API segítségével más programok számára is elérhetőek a rendszer számlázó funkciói.

Számlázó API Url:

https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice

Elérhető szolgáltatások:

• Számla adatainak lekérdezése
• Számla kiállítás, fizetettre állítás, sztornózás

Számlázó példaprogram:

Az alábbi fejezetben egy php példaprogrammal kerül bemutatásra az API működése, Curl segítségével.

• Rendszer azonosító (SystemId): 50
• API kulcs (APIKey): ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1

//Url összeállítása
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/Invoice/';

//Paraméterek megadása tömb formátumban
$Params = array(
    'CustomerId' => 12,
    'Type' => 'ProForma',
    'PaymentMethod' => 'WiredTransfer',
    'Issued' => '2013-11-27',
    'Performance' => '2013-11-27',
    'Prompt' => '2013-11-27',
    'CurrencyCode' => 'HUF',
    'IsReverseCharge' => 0,
    'Customer' => array(
        'Name' => 'PHP Teszt User',
        'Country' => 'Magyarország',
        'PostalCode' => 1111,
        'City' => 'Budapest',
        'Address' => 'Példa köz 3.',
        'AccountNumber' => '11111111-2222222-3333333',
        'VatNumber' => '13579135-13-5'
    ),
    'Items' => array(
        0 => array(
            'Name' => 'Teszt szolgáltatás',
            'Unit' => 'darab',
            'Quantity' => 1,
            'VAT' => 27,
            'PriceNet' => 5000
        )
    )
);

//Curl inicializálása
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Paraméterek JSON kódolása
$Params = json_encode($Params);

//Fejlécek beállítása (adat típusa, hossza és karakterkódolása)
curl_setopt($Curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Content-Length: '.strlen($Params), 'charset=UTF-8'));

//Kérés típusának átállítása POST-ra
curl_setopt($Curl, CURLOPT_POST, 1);

//Paraméterek átadása a Curl-nek
curl_setopt($Curl, CURLOPT_POSTFIELDS, $Params);

//Url átadása a Curl-nek
curl_setopt($Curl, CURLOPT_URL, $Url);

//Curl kérés lefuttatása
$Response = curl_exec($Curl);

//Curl kérés futtatásában volt-e hiba?
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//API által visszatérített http kód lekérése
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API Hibakód: {$ResponseCode} - Üzenet: {$Response}";

//Curl lezárása
curl_close($Curl);

Űrlap beküldése MiniCRM API-val

Amennyiben egy már meglévő, egyedi űrlapod adatait szeretnéd beküldeni MiniCRM-be, ezt van lehetőséged API-n keresztül is megtenni.

Ehhez szükséges MiniCRM-ben létrehoznod egy űrlapot, amire az adatokat beküldheted.

Ezután az űrlap mezők Name attribútumát szükséges kideríteni, illetve a FormHash paramétert amit az űrlap „Részletesebb leírás itt” gombjára kattintva megtehetsz az űrlap forráskódjából (2. módszer)

Ezután lehetőséged van POST paraméterrel requestet küldeni a „https://r3.minicrm.hu/Api/Signup” végpontra. Paraméter értékként szükséges, hogy szerepeljenek a MiniCRM-beli name attribútumok, értékként a kitöltött űrlapod adatai:

curl --form "FormHash=41516-asdasdasdasdasdasdasd" \
    --form "Contact[1891][FirstName]=John" \
    --form "Contact[1891][LastName]=Doe" \
    --form "Contact[1234][Comment]= Teszt megjegyzés" \ https://r3.minicrm.hu/Api/Signup

Adatlap műveletek

A MiniCRM-ben tárolt adatlapok Project-ként jelennek meg az API-n.

Mező alapú keresés  Projektek között

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

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusId=2500

Ennél a lehetőségnél egyes mezők értékeire végezhetünk kereséseket. Fontos itt megjegyezni, hogy a szűrés azokra a mezőkre is működik, amelyek nem találhatók a keresés eredményében. A mezők lehetséges értékeiről a Sémák lekérése pontban olvashatsz bővebben. Amennyiben részletesebb szűrést szeretnénk, több mező is megadható paraméterként, pl:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusId=2500&UserId=3200

Mező alapú projekt keresésnél használható egy speciális paraméter is, amivel az adott státuszcsoportban található projektek kérhetőek le. A feltétel StatusGroup néven érhető el és a következő értékei lehetnek: Lead, Open, Success, Failed. Pl:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusGroup=Success

Projekt letöltése

Projekt a rendszerből kétféleképpen kérhető le, ProjectId (adatlap azonosító) és ReferenceId (külső rendszer azonosító) alapján.

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

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project/1234

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

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?ReferenceId=123456

A válasz mindkét esetben ugyanaz, egy kiválasztott projekt adatainak lekérdezése.

Válaszban a projekt egy tömbben érkezik, ahol megtalálhatóak a projekt mezőinek adatai.

Projekt adatmódosítás

Meglévő projekt 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ékekre. Azonosítás szükséges, példa url:

$ curl -XPUT https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project/1234 -d '{
 "Name":"Átnevezett projekt",
 "Deleted":"1"
}'

A szolgáltatás URL megegyezik a projekt letöltés URL-jével. GET kéréssel projekt letöltés kezdeményezhető, PUT kéréssel pedig adatmódosítás. Új projekt felvétele az azonosító kihagyásával lehetséges (példa url végén található 1234 lehagyása). Fontos itt megjegyezni, hogy új projekt esetén a CategoryId és ContactId mező küldése kötelező, meglévő projekt esetén a CategoryId és ContactId mező pedig már nem szerkeszthető!

Fájl típusú mezők esetén rendszerünk egy Url-t vár, ahol megtalálható a feltölteni kívánt fájl. Ilyen típus esetén a fájl áttöltésre kerül a MiniCRM szervereire és ott tárolásra kerül.

Amennyiben saját rendszeredben létezik azonosító, amelyet szeretnél rögzíteni rendszerünkben, a ReferenceId nevű mező segítségével rögzítheted!

Bemeneten várt adatstruktúra megegyezik a projekt letöltéskor kapott struktúrával. Bemeneti formátum JSON serialized tömb.

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

{
  "Id":1234
}

Emailek listázása

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

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/EmailList/1234

Egy kiválasztott projekt emailjeinek lekérdezése.

A válaszban a találatok egy tömbben érkeznek, melynek Count kulcsán található a talált sablonok száma. A Results kulcs alatt egy-egy külön tömbben találhatóak a projekt emailjei.

A keresés szűkíthető a CreatedAt paraméter segítségével. Ilyenkor csak azok az emailek kerülnek listázásra, amelyek az adott időpontban vagy az után kerültek rögzítésre a rendszerben. Példa:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/EmailList/1234?CreatedAt=2014-03-20

FONTOS! Amennyiben rendszerünkből nagy darabszámú email kiküldéseket végzel, ezek a lekérdezek hosszabb időt vehetnek igénybe!

Példaprogramok

Php példaprogramokkal látod az API működését, Curl segítségével, ezzel is kiemelve a metódusok közti különbséget.

Példa keresésre (GET):

• Rendszer azonosító (SystemId): 50
• API kulcs (APIKey): ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1
• Keresett projekt: Teszt projekt

//Url összeállítása
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/R3/Project?Query=Teszt projekt';

//Curl inicializálása
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Url átadása a Curl-nek
curl_setopt($Curl, CURLOPT_URL, $Url);

//Curl kérés lefuttatása
$Response = curl_exec($Curl);

//Curl kérés futtatásában volt-e hiba?
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//API által visszatérített http kód lekérése
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API Hibakód: {$ResponseCode} - Üzenet: {$Response}";

//Curl lezárása
curl_close($Curl);

//Válaszban kapott JSON dekódolása és kiíratása
$Response = json_decode($Response, true);
var_export($Response);

Példa letöltésre (GET):

• Rendszer azonosító (SystemId): 50
• API kulcs (APIKey): ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1
• Letöltendő projekt azonosítója: 12345

//Url összeállítása
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/R3/Project/12345';

//Curl inicializálása
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Url átadása a Curl-nek
curl_setopt($Curl, CURLOPT_URL, $Url);

//Curl kérés lefuttatása
$Response = curl_exec($Curl);

//Curl kérés futtatásában volt-e hiba?
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//API által visszatérített http kód lekérése
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API Hibakód: {$ResponseCode} - Üzenet: {$Response}";

//Curl lezárása
curl_close($Curl);

//Válaszban kapott JSON dekódolása és kiíratása
$Response = json_decode($Response, true);
var_export($Response);

Példa feltöltésre (PUT):

• Rendszer azonosító (SystemId): 50
• API kulcs (APIKey): ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1
• Feltöltendő adatok:
  • Projekt neve: Első API projekt
  • Projekt felelőse: Példa Péter (3200)
  • Projekt státusza: Igényfelmérés (2500)
  • Projekt terméke (kötelező új projektnél): 3

//Url összeállítása
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/R3/Project';

//Paraméterek megadása tömb formátumban
$Params = array(
  'Name' => 'Első API projekt',
  'UserId' => 3200,
  'StatusId' => 2500,
  'CategoryId' => 3
);

//Curl inicializálása
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Paraméterek JSON kódolása
$Params = json_encode($Params);

//Fejlécek beállítása (adat típusa, hossza és karakterkódolása)
curl_setopt($Curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Content-Length: '.strlen($Params), 'charset=UTF-8'));

//Kérés típusának átállítása PUT-ra
curl_setopt($Curl, CURLOPT_CUSTOMREQUEST, "PUT"); 

//Paraméterek átadása a Curl-nek
curl_setopt($Curl, CURLOPT_POSTFIELDS, $Params);

//Url átadása a Curl-nek
curl_setopt($Curl, CURLOPT_URL, $Url);

//Curl kérés lefuttatása
$Response = curl_exec($Curl);

//Curl kérés futtatásában volt-e hiba?
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//API által visszatérített http kód lekérése
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API Hibakód: {$ResponseCode} - Üzenet: {$Response}";

//Curl lezárása
curl_close($Curl);

Külső rendszerazonosító (ReferenceId) használata

MiniCRM API képes fogadni külső rendszerazonosítót projektekhez.

Végpont: https://$SystemId:$ApiKey@r3.minicrm.hu/Api/SyncFeed/$SystemId/SetReferenceId

Fenti hivatkozásra kell a rendszerhez tartozó API kulccsal Authentikálva POST-olni References nevű változóban egy JSON tömböt, ami a ProjectId-ket tartalmazza kulcsnak és a ReferenceId-k az értékek.

Példa:

$ curl https://$SystemId:$ApiKey@r3.minicrm.hu/Api/SyncFeed/$SystemId/SetReferenceId --data 'References={"12":123456788,"13":123456789}'

A fenti parancs a 12 & 13-as MiniCRM-es Id-jű projektekre állítja be a kapott külső azonosítókat.

Projekt keresése ReferenceId alapján:

Projekt a rendszerből nem csak ProjectId (adatlap azonosító) alapján kérhető le, lehetőség van a beállított ReferenceId (külső rendszer azonosító) használatára is.

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

$ curl https://$SystemId:$APIKey@r3.minicrm.hu/Api/R3/Project?ReferenceId=123456

A válasz a keresett projekt adatainak lekérdezése.

Válaszban a projekt egy tömbben érkezik, ahol megtalálhatóak a projekt mezőinek adatai.

Contact (kapcsolattartó, cég ) Reference Id

MiniCRM API-n keresztül lehetőség van Contact (személy, cég) külső rendszerazonosító kapcsolására.

A végpont a project típusú Reference Id-hoz hasonló:

„https://$SystemId:$ApiKey@r3.minicrm.hu/Api/SyncFeed/$SystemId/SetReferenceId”

Fenti hivatkozásra kell a rendszerhez tartozó API kulccsal Authentikálva POST-olni JSON bodyba:

Type : „Business” (cég), Type: „Person” (magánszemély) References nevű változóban egy JSON tömböt, ami a ProjectId-ket tartalmazza kulcsnak és a ReferenceId-k az értékek.

Hibaüzenetek

A MiniCRM API http státuszkódokkal válaszol az esetleges hibákra. Amennyiben 200 – OK kóddal tér vissza, a kérés sikeres volt. Ha hiba érkezik az API-tól, akkor a válasz formátuma nem JSON tömb, hanem plain text!

Hibakódok listája és jelentésük:

• 400 – Bad Request: A kérésben olyan paraméter szerepel, ami nem ismerhető fel vagy nem engedélyezett a rendszerben. Továbbá olyankor is ezt a hibát küldi a rendszer, ha az adott metódus paramétert vár, de nem kapott paramétert.
• 404 – Not Found: A megadott URL nem található a rendszerben. Leggyakoribb esetben a hibás / elgépelt URL-ek esetében jöhet elő ez a hiba.
• 405 – Method Not Allowed: Olyan esetben találkozhatunk ezzel a hibával, ha hibás vagy nem engedélyezett metódussal próbálunk meghívni egy URL-t.
• 429 – Too many requrests: Abban az esetben fordul elő a hiba, amikor ideiglenesen átlépi az általunk meghatározott Rate Limitet az API végpontjainkon. (R3 API: 60 requests / perc, XML SyncFeed: 180 requests / óra). Az első ilyen válasz után a kérések nem kerülnek feldolgozásra, a token visszatöltését követően(Token bucket rate limit) szükséges újra beküldeni.
• 500 – Internal Server Error: Belső feldolgozási hiba a rendszerben. Leggyakrabban akkor találkozhatunk vele, ha hibás adatokat próbálunk feltölteni API-n keresztül a rendszerbe, vagy ha például egy adott mezőnek nem található az értéke, amit fel szeretnénk tölteni.