Interogarea și modificarea cardurilor

Cardurile din MiniCRM sunt tratate ca și proiecte (project) în API.

Căutarea cardurilor pe baza unui câmp

Este necesară autentificarea:

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

Această funcționalitate îți permite să cauți după valori ale câmpurilor. Pentru mai multe informații legate de valorile câmpurilor, consultă pagina legată de preluarea produselor și a structurii acestora.

În căutare poți specifica mai multe câmpuri ca și parametri, de exemplu:

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

Când se folosește căutarea pe baza unui câmp, se poate folosi un parametru special pentru a prelua cardurile care aparțin unui anumit grup. Această condiție se numește StatusGroup și poate avea una din următoarele valori: Lead, Open, Succes, Failed.

Exemplu de interogare:

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

Exemplu de răspuns:

{
  "Count": 1,
  "Results": {
    "1234": {
      "Id": "1234",
      "Name": "Card test",
      "Url": "https://r3.minicrm.hu/Api/R3/Project/1234",
      "StatusId": "2500",
      "UserId": "3200",
      "Deleted": "0"
    }
  }
}

Preluarea datelor unui proiect (card)

Există două posibilități de preluare a informațiilor unui card din sistem, pe baza ProjectId (identificatorul cardului) sau pe baza ReferenceId (identificator extern).

Folosirea ProjectId
Este necesară autentificarea:

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

Folosirea ReferenceId
Este necesară autentificarea:

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

Răspunsul va fi același în ambele cazuri și va fi reprezentat de interogarea detaliilor cardului selectat. Acesta este compus dintr-un array care conține informații despre card precum și câmpurile acestuia.

Exemplu de răspuns:

{
  "Id": 1234,
  "CategoryId": 3,
  "ContactId": 12345,
  "StatusId": "Test status",
  "UserId": "Bogdan Burciu",
  "Name": "Nume card",
  "Deleted": "0",
  "Enum1016": "Valoare 1",
  "Set1035": "Valoarea exemplu",
  "Text1105": "Un exemplu de text",
  "Int1107": 12500,
  "File1103": "http://cdn.minicrm.hu/doc/2013/04-25/A/Q/AQFwQq7Os0kE5ykH_GSJfg-1"
}

Adăugarea unui card nou

Poți crea noi carduri în sistem via API folosind o cerere de tip PUT:

$ curl -XPUT https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project -d '{
"CategoryId": 123, 
"ContactId": 123, 
"UserId": "Bogdan Burciu", 
"Name": "Numele cardului",
...
}'

Unde CategoryId reprezintă id-ul produsului în care se vor crera cardurile, ContactId este id-ul contactului caruia i se va asocia cardul nou creat, UserId este numele deținătorului cardului, Name este numele cardului.

În acest fel se pot adăuga și alte câmpuri precum și valorile acestora specificând numele câmpurilor din sistem. De exemplu, dacă în sistem există un câmp Data ofertei a cărui valoare doresc să o setez prin API, se va specifica numele acestui câmp – DataOfertei în JSON-ul trimis către MiniCRM.

Exemplu de răspuns în cazul în care cardul s-a creat cu succes:

{
  "Id":1234
}

Modificarea datelor de pe un card

Se pot modifica datele de pe un card existent sau se poate crea unul nou. Este necesară autentificarea. Exemplu de URL:

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

Preluarea datelor poate fi inițializată cu cereri de tip GET iar cele de modificare cu cereri de tip PUT. Adăugarea unui nou card este posibilă prin omiterea identificatorului (1234 în exemplul de URL de mai sus). Este important de menționat faptul că este obligatorie specificarea CategoryId-ului (id-ul produsului) și a ContactId-ului (id-ul contactului) pentru un card nou în timp ce pentru un card deja existent aceste valori nu mai pot fi modificate.

Pentru câmpurile de tip fișiere atașate sistemul se așteaptă să primească un URL. Fișierele încărcate în câmpuri de acest tip vor fi încărcate și stocate pe serverele MiniCRM.

Dacă folosești Id-uri în sistemul tău pe care vrei să le asociezi sistemului MiniCRM, poți folosi ReferenceId-uri pentru aceasta.

Structura datelor așteptată pentru input este aceeași ca cea obținută atunci când se obțin detaliile proiectului și este în format de array JSON serializat.

Exemplu răspuns pentru salvarea cu succes:

{
  "Id":1234
}

Afișarea listei de emailuri

Autentificarea este necesară:

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

Această funcționalitate permite interogarea listei emailurilor pentru cardul al cărui Id este specificat.

Răspunsul va returna un array care va afișa în cheia Count numărul de email-uri găsite. Dedesubt cheia Results va afișa emailurile în array-uri separate.

Poți restrânge căutarea folosind parametrul CreatedAt. În acest caz, doar emailuri înregistrate în sistem după data specificată vor fi afișate.

Exemplu de interogare:

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

IMPORTANT! Dacă ai un număr mare de emailuri în sistemul tău, interogarea va dura mai mult.

Exemplu de răspuns:

{
   "Count":1,
   "Results":[
      {
         "Id":3333,
         "TemplateId":1479,
         "From":"help@minicrm.hu",
         "To":"user@example.com",
         "Subject":"Email de test",
         "Status":"Sent",
         "CreatedAt":"2013-03-20 12:35:24",
         "OpenedAt":"2013-03-20 15:12:00",
         "ClickedAt":""
      }
   ]
}