6.5

InTouch CRM REST API

Pokud hledáte starší API na bázi XML, přejděte sem.

Základní informace

Abyste mohli API používat, potřebujete mít funkční instalaci InTouch CRM a uživatelský účet, přes který se budete do CRM připojovat. Většinu požadavků není možné provádět bez řádné HTTP autorizace. Doporučujeme založit nového uživatele s typem přístupu Pouze API a pro vzdálená spojení s CRM nepoužívat běžné uživatelské účty. Díky tomu budete moci snadno rozlišit, které změny v systému udělal člověk, a které udělal váš softwarový klient.

Používejte pouze pouze TLS/SSL (https) a v požadavku posílejte platnou autorizační hlavičku, např.:

Authorization: Basic Z3JlZ29yOjEyMzQ1Ng==

URL

Všechny koncové body API jsou dostupné na URL ...váš server.../api Pokud tedy předpokládáme, že máte svoje CRM nainstalované na adrese https://crm.mycompany.cz, tak kořenové URL pro všechny REST API dotazy bude https://crm.mycompany.cz/api a URL pro přístup k adresáři v CRM bude https://crm.mycompany.cz/api/parties.

Při zasílání požadavků na serveru používejte správnou HTTP metodu (GET, PUT, POST, PATCH). Správná metoda je vždy popsána v dokumentaci. Obecně se dá říct, že jednotlivé metody jsou používány následujícím způsobem:

MetodaObecné použití
GETZískání dat z CRM (čtení)
PUTZměna existujícího záznamu
POSTVytvoření nového záznamu nebo vyvolání určité akce/služby
PATCHZměna existujícího záznamu, přičemž klient nemusí posílat celý záznam, ale pouze údaje, které chce měnit

Stránkování

Pokud má API vrátit větší počet záznamů, používá se stránkování, tj. jsou vraceny bloky dat (stránky). V takovém případě má odpověď obvyklou strákturu:

{
  "total": 360, /* Celkový počet záznamů */
  "position": 60, /* Index, od kterého jsou záznamy v této stránce (od 0) */
  "size": 20, /* Použitá velikost stránky (může být větší než vrácený počet záznamů v "items") */
  "orderBy": "modified", /* Název pole, podle kterého jsou data seřazena (chybí pokud není řazeno) */
  "desc": false, /* Boolean jestli je řazení sestupné (chybí pokud není řazeno) */
  "items": [    /* Pole vrácených záznamů */
    { }, { }, /* ... */
  ]
}

Pro získání dalších záznamů je třeba zaslat nový požadavek s posunutým parametrem position.

Chyba ve formátu JSON

Pokud při zpracování požadavku nastane nějaký problém, vrací API odpovídající HTTP status kód (např. 404 NOT FOUND) a většinou je v těle odpovědi i JSON objekt popisující podrobněji nastalý problém:

{
  "ok": false,
  "status": 404,
  "problems" : [
    {
      "level": "SEVERE", /* Závažnost chyby, "INFO", "WARNING", "SEVERE" */
      "field": "surname", /* Pole, se kterým je problém (volitelně) */
      "message": "This is not human name" /* Popis chyby */
    }
    /* ... */
  ]
}

Pravidla "slušného chování"

Koncové body