Dokumentace k InTouch CRM

Tmavý režim

InTouch CRM REST API ​

TIP

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:

json5
{
  "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:

json5
{
  "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í" ​

  • Snažte se minimalizovat množství dotazů do systému, např. pomocí cache.
  • Neprovádějte větší počet paralelních dotazů do systému (např. získání více stránek dat současně, viz. výše).
  • Připravte se na obvyklé scénáře, ve kterých může zápis do CRM skončit chybou (pokus zapsat nevalidní údaj, zápis duplicitního záznamu).
  • Každý server občas prochází údržbou a je down. Reagujte vhodně na takovou situaci (opakování zápisu za pár minut).

Koncové body ​