Jak na zápis dat z webového formuláře

Pro mnoho firem je typické, že sbírají poptávky ze svého webu. Obvykle je žádoucí, aby se tyto poptávky dostaly do InTouch CRM. Zde je několik tipů, jak používat naše REST API, pro zápis dat do CRM, a přitom se vyhnout duplicitám.

Web by měl při zápisu do CRM provést následující kroky (pokud jsou pro vás relevantní):

Validovat data na webu.
Rozdělit data na osobní, firemní a další informace.
Ověřit, jestli již kontakty existují v CRM.
Založit nové kontakty (pokud neexistují), aktualizovat kontakty (pokud existují).
Propojit osobu a firmu, pokud máte oboje.
Aktualizovat souhlasy (GDPR)
Zapsat poptávku (kategorie 'další informace') navázanou na kontakty.
Zapsat aktivity (pokud není řešeno na straně CRM).

Validace dat na webu

CRM se snaží, aby se do databáze nedostaly úplně nesmyslné údaje. Proto je vhodné otestovat validitu dat ještě dřív, než se pokusíte o zápis přes API. Doporučujeme ověřit:

Validní formát e-mailů (např. regulárním výrazem).
Validní formát telefonů (alespoň počet čílic, mnohem lépe pomocí nástojů, jako např. libphonenumber-js).
Nesmyslné znaky ve jménech nebo názvech firem (číslice, speciální znaky, emotikony).
Jména s jedním písmenem ("X Y").
Jméno a příjmení jsou stejné ("Bob Bob").
E-mail je na doméně, která poskytuje jednorázové e-maily.
Formát rodného čísla (pokud sbíráte).
Formát IČO, DIČ, ...

Tip: Můžete zvážit ověření kvality dat pomocí externí AI, pokud to dovolují vaše pravidla pro ochranu soukromí.

Rozdělení dat

Pokud na vašem webovém formulář sbíráte současně firemní i osobní údaje, doporučujeme jej navrhnout tak, aby bylo zřejmé, jestli zadávané údaje patří k osobě nebo k firmě. Příklad:

Firma:    [____________]
IČO:      [____________]
Jméno:    [____________]
Příjmení: [____________]
Telefon:  [____________]   <--- Je firemní telefon nebo mobil osoby?
E-mail:   [____________]   <--- E-mail na firmu (info@...) nebo osobu (novak@...)

Zvažte design formuláře upravit tak, aby bylo i pro uživatele zřejmé, k čemu které údaj patří. Příklad (jen ukázka):

Jméno*:      [____________]   Firma:    [____________]
Příjmení*:   [____________]   IČO:      [____________]
Mobil*:      [____________]
Váš e-mail*: [____________]

Lidé si často neuvědomí, že jedna vizitka obsahuje údaje o dvou osobách, jedné právnické a druhé fyzické. Je užitečné vědět už na vstupu, k jaké patří každý jednotlivý údaj.

Tip: Knihovna libphonenumber-js dovoluje otestovat, jestli je telefon mobil nebo pevná linka.

Ověření existence dat

Předpokládejme, že jste z formuláře sesbírali následující údaje ke dvěma subjektům (osoba a firma):

nazev = "MegaCorp, a.s.", ičo = "25874123", tel = 215478963, ulice = "Dlouhá 15", ...
jméno = "Karel", příjmení = "Gregor", tel = 732252114, email = gregor@megacorp.cz, ...

V tomto kroku je vhodné ověřit, jestli už data v CRM máte, a to pro každý subjekt nebo kontaktní údaj zvlášť. Doporučujeme použít API /api/isknown v následující sekvenci:

/api/isknown?ico=25874123
/api/isknown?phone=215478963	/* Pouze pokud se nenašlo nic podle IČO */
/api/isknown?email=gregor@megacorp.cz
/api/isknown?phone=732252114	/* Pouze pokud se nenašlo nic podle e-mailu */

Pokud vám všechna volání výše potvrdí, že záznam neexistuje (exists = false), mělo by být bezpečné zapsat nový záznam. V opačném případě budete aktualizovat existující záznam.

`GET /api/isknown`

Ověření existence kontaktu v databázi pro prevenci duplicit.

Požadavek

Query parametr	Typ	Popis	Výchozí
`email`	string	e-mailová adresa k ověření	-
`phone`	string	telefon k ověření	-
`bornNumber`	string	rodné číslo	-
`ico`	string	IČO	-
`dic`	string	DIČ	-

Příklad: /api/isknown?email=gregor@megacorp.cz
Ověří, jestli se v databázi CRM nachází kontakt s e-mailem gregor@megacorp.cz.

Poznámka: V jednom dotazu můžete poslat buď parametry email, phone NEBO parametry ze skupiny bornNumber, ico, dic. Tyto dvě skupiny parametrů vzájemně nekombinujte. Odpověď se bude lišit podle toho, jaké parametry pošlete.

Odpověď (`application/json`)

200 OK

Formát odpovědi respektuje následující typ:

// Pokud byl dotaz na email, phone
interface IsKnownContactResponse {
	exists?: boolean;

	party?: number;		// ID existujícího kontaktu
	name?: string;		// Název existujícího kontaktu
	type?: string;		// Platný typ kontaktu v adresáři (viz. reference)
	
	customer?: number;
	customerName?: string;
	customerType?: string;
	
	branch?: number;
	branchName?: string;
	branchType?: string;
	
	individual?: number;
	individualName?: string;
	individualType?: string;
	
	email?: string;		// e-mail u kterého byla potvrzena existence nebo...
	phone?: string;		// ...telefon, u kterého byla potvrzena existence.
	
	cookieId?: string;	// Doplňující údaje pro správu souhlasů (pro ověření existence
	frontKey?: string;  // je možné ignorovat)
	frontPath?: string;
}

// Vráceno, pokud byl email nebo phone ve špatném formátu
interface InvalidContactResponse {
	error: string;
}

// Pokud byl dostaz na ico, dic, bornNumber
interface IsKnownPartyResponse {
	exists: boolean;
	party?: number;	// ID existujícího kontaktu
	name?: string;	// Název existujícího kontaktu
	type?: string;	// Platný typ kontaktu v adresáři (viz. reference)
}

type IsKnownResponse = IsKnownContactResponse | IsKnownPartyResponse;

Ukázková odpověď - neexistující e-mail:

{
	"email": "gregor@megacorp.cz",
	"exists": false,
	"cookieId": null
}

Ukázková odpověď - existující e-mail:

{
	"customer": 254,
	"customerName": "MegaCorp, a.s.",
	"customerType": "ORGANIZATION",
	"individual": 1663,
	"individualName": "Bc. Karel Gregor",
	"individualType": "INDIVIDUAL",
	"party": 1663,
	"name": "Bc. Karel Gregor",
	"type": "INDIVIDUAL",
	"email": "gregor@megacorp.cz",
	"exists": true,
	"cookieId": "1GGD3F3",
	"frontKey": "6a1b58a61c2e46996a1b9004",
	"frontPath": "https://crm.firma.cz/customerFront.do?id=6a1b58a61c2e46996a1b9004&crmID=SAMPLE"
}

Zápis a aktualizace kontaktů

Jednodušší případ je situace, kdy vám API potvrdí, že kontakty v databázi ještě nejsou a je třeba je pouze zapsat.

Vytvoření nových kontaktů

Pro zápis každého kontaktu použijete API POST /api/parties, které je popsáno zde.

Aktualizace kontaktů

Kontakt je možné načíst z CRM pomocí GET /api/parties/{id} a následně částečně aktualizovat pomocí PATCH /api/parties/{id} (popsáno zde) nebo aktualizovat celý záznam pomocí PUT /api/parties/{id}.

Zvláštní pozornost si zaslouží aktualizace telefonů a e-mailů kontaktu. Může se stát, že budete chtít přidat e-mail nebo změnit pořadí telefonů. Automatizované procesy které posílaní e-maily kontaktům v CRM upřednostňují adresu, která je jako první v pořadí, a proto je nutné věnovat správné sekvenci e-mailů a telefonů náležitou pozornost.

Ať už budete provádět částečnou PATCH nebo plnou PUT aktualizaci, musíte poslat vždy kompletní seznam e-mailů a telefonů. Tomuto seznamu interně říkáme "elektronické adresy" a posílají se jako JSON pole ve vlastnosti objektu eaddresses. Předpokládejme, že jste ze serveru zíslali existující seznam e-adres:

{
	/* ... */
	"eaddresses": [
		{
			"id": 573,
			"type": 1,
			"junk": false,
			"priority": 1,
			"value": "karel@firma.cz"
		},
		{
			"id": 574,
			"type": 2,
			"junk": false,
			"priority": 2,
			"value": "602 123 456",
			"raw": "+420602123456"
		}
	],
	/* ... */
}

Pokud chcete tento seznam změnit, musíte pole poslat přesně v tom pořadí, v jakém údaje chcete mít (na priority nezáleží). Zopakujte údaje, které chcete zachovat. Vynechejte údaje, které chcete smazat. Doplňte na správné místo nové údaje. Dejme tomu, že chceme na začátek přidat nový e-mail karel555@gmail.com a odstranit stávající karel@firma.cz. Musíte tedy poslat pole v tomto tvaru:

{
	/* ... */
	"eaddresses": [
		{
			/* Nový e-mail, záznam nemá existující ID */
			"type": 1,
			"value": "karel555@gmail.com"
		},
		{
			"id": 574,
			"type": 2,
			"junk": false,
			"priority": 2,
			"value": "602 123 456",
			"raw": "+420602123456"
		}
	],
	/* ... */
}

Pokud byste nezopakovali i mobilní číslo 602 123 456 v zaslaném JSONu, bylo by vymazáno z databáze (což obvykle nechcete).

Propojení firmy a osoby

Tento krok je pro vás relevantní pouze tehdy, pokud současně pracujete s údaji osoby a údaji firmy. V takovém případě máte nyní dva vytvořené (aktualizované) záznamy v CRM, ale musíte je ještě vzájemně propojit. Toho lze dosáhnout pomocí API POST /api/parties/{id}/connect-member/{member}, které je popsané zde.

Aktualizace souhlasů

Pokud budete zapisovat nebo aktualizovat fyzickou osobu, budete nejspíš také chtít zapsat souhlas (např. GDPR souhlas se zpracováním osobních údajů). Popis najdete zde.

Zápis poptávky (příležitosti)

Při zápisu příležitosti uveďte korektní propojení na kontakt(y). Pokud zapisujete příležitost s vazbou pouze na osobu, bude v JSONu reprezentujícím příležitost vlastnost customer:

{
	/* ... */
	"customer":516,		/* Příležitost bude propojena na osobu nebo firmu s kódem 516 */
	/* ... */
}

Pokud má být příležitost navázána na obojí - firmu i osobu, musíte zapsat oba kódy:

{
	/* ... */
	"customer":2440,	/* Příležitost bude propojena na firmu s kódem 2440 */
	"person":2617,		/* a osobu s kódem 2617 */
	/* ... */
}

Více informací o zápisu příležitostí naleznete zde.