Přístup k adresáři

GET /api/parties

Získání kontaktů z adresáře firem a osob.

Požadavek

Příklad: /api/parties?orderBy=modified&desc=true
Získá naposledy změněné kontakty z adresáře.

Odpověď (application/json)

200 OK

Stránka se záznamy typu party.

{
  "items": [
    {
      "id": 370,
      "type": "INDIVIDUAL",
      "firstname": "Karel",
      /* ... */
    }
    /* ... */
  ]
}

GET /api/members

Získání všech vztahů nadřazené/podřazené kontakty. Toto volání můžete použít například pro načtení (cache) vazeb

Odpověď (application/json)

200 OK

Stránka se záznamy typu propojení kontaktů.

{
  "items": [
    {
      "org": 370,
      "member": 1050,
      "priority": 1,
      "forContact" : false,
      /* ... */
    }
    /* ... */
  ]
}

POST /api/parties

Vytvoření nového kontaktu v adresáři CRM. Mějte na paměti, že v CRM není možné vytvořit záznam, který by obsahoval současně údaje o firmě a údaje o zaměstnanci firmy. Pokud chcete do systému vložit záznam o firmě (např. Firma s.r.o.) a jejím zaměstnanci (např. Jan Novák), musíte udělat dva zápisy kontaktu (jeden pro firmu a jeden pro osobu) a následně je propojit vztahem (viz. koncový bod connect-member popsaný níže).

Zápis podléhá přísné validaci dat, takže nelze zapsat nevalidní nebo duplicitní data. Pokud se obáváte, že by už kontakt mohl v databázi existovat, doporučujeme koncový bod /api/parties/import.

Požadavek (application/json)

Tělo požadavku musí být JSON objekt, reprezentující nový kontakt. Neměl by obsahovat parametr id. ID bude novému kontaktu přiděleno při úspěšném zápisu.

Odpověď (application/json)

201 OK CREATED

Tělo odpovědi bude tentýž kontakt, ale už v podobě, jak byl zapsán do databáze a s přiděleným kódem.

V http hlavičce Location bude URL k získání kontaktu v pozdějších dotazech.

400 BAD REQUEST

Zaslaný objekt neprošel validací a nemůže být zapsán do databáze. Tělo obsahuje standardní chybový JSON s popisem nalezených chyb.

POST /api/parties/import

Vytvoření nového kontaktu v adresáři nebo aktualizace existujícího. Tento koncový bod se od předchozího liší tím, že se před pokusem o vytvoření nového kontaktu systém pokouší vyhledat, jestli už takový kontakt neexistuje a pokud ano, provede aktualizaci existujícího kontaktu. Detailní popis toho, podle jakých kritérií se existující kontakt vyhledává zde záměrně neuvádíme, protože se mohou v budoucnu měnit, jak budeme algoritmus vylepšovat. Primárně se ale používají pole "rodné číslo", "IČO", "název společnosti", telefony a e-maily pro detekci existence kontaktu.

Jak požadavek, tak odpověď je ve stejném formátu, jako POST /api/parties.

GET /api/parties/{id}

Získání jednoho kontaktu s konkrétním ID. ID je v InTouch CRM celé číslo, takže požadavkem:

GET /api/parties/2314

získáte kontakt s kódem 2314 (pokud takový existuje).

Odpověď (application/json)

200 OK

Tělo odpovědi bude kontakt s požadovaným ID.

404 NOT FOUND

Požadovaný kontakt v adresáři neexistuje.

PUT /api/parties/{id}

Aktualizace kontaktu. Existující kontakt s ID id bude přepsán daty v těle požadavku.

Požadavek (application/json)

Tělo požadavku musí být JSON objekt, reprezentující nový kontakt. Neměl by obsahovat parametr id. ID bude novému kontaktu přiděleno při úspěšném zápisu.

Odpověď (application/json)

200 OK

Tělo odpovědi bude nová verze kontaktu, jak jej systém zapsal do databáze.

400 BAD REQUEST

Zaslaný objekt neprošel validací a nemůže být zapsán do databáze. Tělo obsahuje standardní chybový JSON s popisem nalezených chyb.

404 NOT FOUND

Požadovaný kontakt v adresáři neexistuje.

PATCH /api/parties/{id}

Aktualizace kontaktu. Existující kontakt s ID id bude aktualizován pomocí dat v těle požadavku. Na rozdíl o předchozího volání metodou PUT nemusíte u metody PATCH zasílat kompletní JSON s kontaktem, ale stačí poslat jen ty údaje, které hodláte změnit.

Příklad:

    PATCH /api/parties/350

    { "titleBefore": "Ing." }

U kontaktu s kódem 350 se nastaví titul před jménem na "Ing.".

Odpověď (application/json)

200 OK

Tělo odpovědi bude nová verze kontaktu, jak jej systém zapsal do databáze.

400 BAD REQUEST

Zaslaný objekt neprošel validací a nemůže být zapsán do databáze. Tělo obsahuje standardní chybový JSON s popisem nalezených chyb.

404 NOT FOUND

Požadovaný kontakt v adresáři neexistuje.

POST /api/parties/{id}/connect-member/{member}

Propojení dvou identit pomocí "membership" vztahu. Typicky se požívá pro připojení zaměstnance k firmě nebo provozovně. Jak {id}, tak {member} musí být kódy existující kontaktů a jejich propojení musí dávat smysl (např. nemůžete připojit právnickou osobu pod fyzickou osobu, ale naopak to lze).

Pokud už jsou kontakty propojené, dojde k aktualizaci propojení (např. můžete aktualizovat název pracovní pozice nebo datum odchodu).

Požadavek (application/json)

V těle požadavku musí být JSON v následujícím tvaru, přičemž všechna pole jsou nepovinná:

{
    "role": "Technický ředitel",  /* prac. pozice */
    "pr": 0,                      /* priorita vztahu, int (určuje pořadí, v jakém se propojení 
                                    na firmy zobrazí na formuláři při otevření {member} kontaktu */
    "enter": "2020-07-13",        /* datum nástupu nebo null */
    "leave": null,                /* datum odchodu nebo null */
    "fc": false,     /* boolean - {member} je hlavní kontaktní osobou v {id} */
    "fb": true,      /* boolean - {member} je odpovědný v obchodních záležitostech u {id} */
    "ft": false,     /* boolean - {member} je odpovědný v technických záležitostech u {id} */
    "fi": false,     /* boolean - {member} je odpovědný v otázkách fakturace u {id} */
    "au": false,     /* boolean - {member} má právo jednat a podepisovat za {id} */
}

Odpověď (application/json)

201 OK CREATED

Tělo odpovědi bude vytvořený vztah. Bude obsahovat dvě další pole org (stejné jako {id}) a member s kódy nadřazeného a podřazeného kontaktu.

400 BAD REQUEST

Zaslaný objekt neprošel validací a nemůže být zapsán do databáze.

404 NOT FOUND

Nadřazený nebo podřazený kontakt není v databázi.

GET /api/parties/{id}/ea

Získání kontaktních údajů ke kontaktu s kódem {id}. Kontaktními údaji se rozumí seznam telefonů, e-mailů a webových adres, kterým také v dokumentaci říkáme "e-adresy".

Odpověď (application/json)

200 OK

V těle odpovědi je stránka s e-adresami.

GET /api/parties/{id}/members

Získání podřazených kontaktů ke kontaktu s kódem {id}. Podřazené kontakty jsou všechny kontakty připojené pod hlavní kontakt s kódem {id}.

Odpověď (application/json)

200 OK

V těle odpovědi je seznam podřazených kontaktů.

GET /api/parties/{id}/orgs

Získání nadřazených kontaktů ke kontaktu s kódem {id}. Nadžazené kontakty jsou všechny kontakty ke kterým je připojený kontakt s kódem {id}.

Odpověď (application/json)

200 OK

V těle odpovědi je seznam nadřazených kontaktů.

Práce se soubory

Kontakt může k sobě mít připojené soubory. Detailní práce se soubory je popsaná v samostatné kapitole zde, přičemž tzv. <record_endpoint> bude /api/parties/{id}.

Práce s poznámkami

Kontakt může k sobě mít připojené poznámky. Detailní práce s poznámkami je popsaná zde, přičemž tzv. <record_endpoint> bude /api/parties/{id}.