API pro přístup k obsahu a znalostem

InTouch CRM má k dispozici další dvě rozhraní pro přístup k obsahu v systému.

/public/...

/known/...

První rozhraní vám umožní získat obsah dokumentů, které jsou v CRM umístěné v záložce Marketing | Správce obsahu. Druhé je určeno k přístupu ke znalostem. Jelikož Správce obsahu je nástroj pro vytváření veřejných dokumentů, jsou texty zde umístěné automaticky přístupné přes /public/... API. Trochu jinak je to u znalostí, kde mohou být interní dokumenty, u kterých není žádoucí, aby byly dostupné z internetu. Proto je nutné, aby záznam znalosti měl příznak Veřejná (nastavuje se v editaci znalosti).

Použití

Předpokládejme, že váš InTouch CRM je dostupný na adrese https://firma.itcrm.cz a vy chcete přes API získat obsah s adresou newsletter/2019/meetup. V takovém případě provedete HTTP dotaz na:

https://firma.itcrm.cz/public/newsletter/2019/meetup

Rozhraní podporuje několik parametrů, kterými můžete ovlivnit, co přijde v odpovědi. Standardní chování rozhraní je takové, že získáte v odezvě tělo požadovaného obsahu a pokud požadovaný obsah měl titulek a perex (stručný popis), server pošle HTTP hlavičky X-Title resp. X-Perex, které budou titulek a perex obsahovat (URL kódování znáků, které nejsou v US-ASCII).

Je-li požadovaný obsah typu HTML, může vám server vrátit titulek a/nebo perex dokumentu přímo v těle odpovědi, jako součást HTML. K tomu použijte parametr title a perex, jejichž hodnotou bude název HTML tagu, do kterého má server data zabalit. Syntaxe je:

tag[.class1][.class2]...

Na požadavek s parametrem title=h1.shock server pošle na začátku vráceného HTML

<h1 class="shock">Titulek, který je v CRM</h1>

Pokud si titulek nebo perex vyžádáte začleněný do těla HTML, HTTP hlavičky X-Title a X-Perex nebudou součástí odpovědi.

Relativní odkazy

Pokud vrácený dokument obsahuje odkazy na obrázky nebo jiné dokumenty z CRM, jsou tyto odkazy vráceny v absolutní podobě (včetně htts:\\...). Pokud chcete, aby CRM vrátilo relativní odkazy vůči dokumentu, ke kterému přistupujete, musíte použít parametr rel=1 v požadavku na API.

JSON

Další parametr, který rozhraní rozpoznává je json=1. Server v tomto případě vrátí validní JSON dokument s obsahem:

{
	"title": "...titulek...",
	"perex": "...stručný popis...",
	"contentType": "text/html", /* MIME type dat */
	"bodyType": "text|base64", /* base64 se používá pro kódování pole body, pokud se jedná o binární data */
	"body": "..." /* buď přímo text nebo base64 kódovaná binární data */
}

Parametr json neumožňuje vkládání titulku a perexu do těla HTML (viz. výše). Jsou vráceny vždy samostatně v JSON odpovědi.

Výpis položek

Výše popsané API je určené ke stažení jedné konkrétní položky (obsahu nebo znalostí). Pokud potřebujete vypsat dostupné záznamy, lze použít volání:

/public/list
/known/list

Obě volání můžete doplnit o následující parametry:

Parametr	Popis
`order`	Podle jakého údaje seřadit výsledky
`desc`	Je směr řazení "sestupný"? `desc=true` je výchozí hodnota.
`limit`	Maximální počet záznamů, které API vrátí (výchozí hodnota 10).
`offset`	Od kterého záznamu budou data vráceny (výchozí hodnota 0). Lze použít pro stránkování.
`cat`	Pro `/public` volání je možné v tomto parametru uvést čárkou oddělený seznam kategorií. Kategorie obsahu se jmenují `c1`..`c64` a definuje je administrátor v nastavení CRM. Např. volání `/public/list?cat=c3,c6` vrátí záznamy, které jsou v kategorii `c3` nebo `c6`.

Volání /known/list vrací pouze záznamy, které jsou označeny jako Veřejné. Interní znalosti nelze tímto API získat.

Server vrátí přehled záznamů v JSON formátu:

{
	"total": 38,	 /* Celkový počet záznamů v databázi */
	"limit": 10,  /* Omezení počtu vrácených záznamů */
	"offset": 0,  /* Od kterého záznamu jsou položky vráceny */
	"items": [ ]	/* Pole vrácených položek */
}

Každá položka v poli items má následující strukturu:

{
	"title": "Nové kávové automaty",		/* Titulek dokumentu */
	"perex": "V lednu jsme opět naskladnili autom...",	/* Stručný popis */
	"uid": "315",			/* Interní kód záznamu v CRM */
	"contentType": "text/html",	/* MIME typ obsahu */
	"url": "https://crm.dobrynapoj.cz/public/nove-automaty.html", /* Link na celý dokument */
	"path": "/nove-automaty.html",	/* Absolutní cesta k dokumentu v rámci CRM */
	"modified": "2020-07-13T20:33:11"	/* Datum a čas poslední změny dokumentu */
}