Import kontaktů přes Helpdesk API
- Jiri Klofac (Unlicensed)
- 1 Vytvoření integrace snadno a rychle
- 2 Obecně o hromadném importu kontaktů a společností přes API
- 3 Funkce pro import kontaktů a zákazníků
- 4 PATCH api/Account/PatchRequestorUser/{id} (změna vybraných parametrů uživatele/kontaktní osoby)
- 5 Kódy států
- 6 Synchronizace kontaktů zpět do vašeho systému
Vytvoření integrace snadno a rychle
I když to z následujícího textu nemusí být na první pohled zřejmé, vytvoření integrace v podstatě znamená jen:
získání dat o zákaznících a jejich kontaktních osobách z Vašeho CRM/IS
zavolání dvou funkcí na hromadný import do Helpdesk IPEX
Uvedené můžete po provedení prvotního importu dat spouštět v intervalech třeba 15 minut a mít tak téměř online synchronizaci.
Pokud se nechcete programováním synchronizace zabývat, můžete využít naší podpory a vytvořit si ji pomocí Integrační platforma Make (Integromat)
Obecně o hromadném importu kontaktů a společností přes API
Helpdesk API poskytuje bohaté možnosti práce s objekty Uživatelský účet/Kontakt (v dokumentaci API Account/User) nebo Společnost (v dokumentaci API Customer). Pro synchronizaci těchto dat z Vašeho systému do Helpdesku IPEX je však nutné vytvořit na straně Vašeho systému můstek obsahující rozhodovací logiku, jaké záznamy je nutné v Helpdesku založit a updatovat, vytvořit správnou vazbu mezi Společností a jejími Kontakty a realizovat změnu každého objektu přes několik volání API funkcí.
Pro zjednodušení implemetace takového můstku byly vyvinuty dále popsané importní funkce, které velkou část popsané logiky již mají v sobě obsaženu a celý problém by se tak měl zjednodušit na vytažení dat z Vašeho systému. Na jedno zavolání API lze také předat desítky záznamů najednou.
Pojem Zákazník nemusí vždy znamenat objekt Společnost, může jím být i samostaný objekt Uživatelský účet/Kontakt bez Společnosti. Klíčový pro import je objekt Uživatelský účet, který musí existovat vždy. Může být rozšířen o vazbu na Společnost, které hlavním úkolem je spojit více Uživatelských účtů. Atributy Telefonní číslo nebo Email jsou v systému Helpdesk IPEX primárně používány právě z objektu Uživatelský účet/Kontakt. Na základě těchto údajů dochází k identifikaci a přiřazení k ticketům a dalším objektům. Přiřazení Společnosti je pak bráno jen jako doplňující vazba.
Jak předpokládáme, že import budete používat
Obecně při importu potřebujete
synchronizovat údaje o společnostech a jejich kontaktních osobách včetně klíčových příznaků a štítků
řešit logiku, zda má být založen nový záznam nebo zda má být proveden update stávajícího
řešit pod jakým ID je kontakt nebo společnost v Helpdesku uložen, aby bylo jasné pro který záznam má být update proveden
updatovat jen vybrané údaje, aby nedošlo ke ztrátě extra příznaků a štítků na straně Helpdesku existujících záznamů
O konceptu použití hromadných importních funkcí Helpdesk API
K dispozici jsou dvě funkce, které v sobě obsahují řešení výše uvedených předpokladů
import uživatelských účtů/kontaktů (do 100 záznamů)
import společností/zákazníků (do 500 záznamů)
Při importu uživatelských účtů/kontaktů je možné předat v sekci Default Customer identifikaci společnosti. Pokud v Helpdesku tento zákazník existuje, je mu uživatelský účet/kontakt přiřazen. Pokud neexistuje, je společnost v Helpdesku automaticky založena a je jí kontakt ihned přiřazen.
Následně lze provést import společností/zákazníků a doplnit jejich záznamy o vybrané příznaky a štítky.
Pokud použijete External ID u importovaných objektů, lze postupovat i obráceně, tj. nejdříve naimportovat společnosti a poté uživatelské účty/kontakty. Vazba mezi kontaktem a společností se pak vytváří pomocí External ID společnosti.
Prvotní import
Je třeba zmínit, že importní funkce mají limitovaný počet záznamů pro zpracování (viz. výše). Je proto třeba vaše data “rozsekat” na tyto balíčky a volat importní funkci opakovaně. Kvůli zátěži API je také vhodné dělat export vašich dat např. podle počátečního písmene abecedy nebo po jednotlivých měsících/letech podle data vzniku záznamu.
Pro eshopy je dále typické, že v kontaktech jsou uloženy jen tzv. registrované kontakty. Přitom pro zákaznickou péči jsou důležití i tzv. zákazníci bez registrace, kteří mají kontaktní údaje jen v objednávce. Protože bude velmi pravděpodobně nutné komunikovat i s nimi, doporučujeme naimportovat i kontakty z objednávek. Z pohledu Helpdesku se jedná o stejný objekt uživatelský účet/kontakt jako pro registrovaný kontakt, to že se jedná o kontakt z objednávky si můžete rozlišit nastavením definovatelného pole (custom field).
Hromadná periodická synchronizace
Importovací funkce je možné použít i pro průběžnou dávkovou synchronizaci např. 1x/hod, pokud nemáte ve Vašem systému k dispozici posílání webhooků při založení/editaci záznamů kontaktu nebo společnosti. Exportujete pak záznamy u kterých proběhla změna za sledované časové období. Nezatěžujete tak Váš systém ani Helpdesk API při každé změně v těchto objektech a nemusíte implementovat značky ve Vašem systému který záznam byl synchronizován.
Co je External ID
Obecně je External ID vaše značka v objektech Helpdesku, která představuje ID objektu Kontaktní osoba nebo Společnost ve vašem systému.
Tím, že při importu předáváte tyto identifikátory, může importní funkce dělat aktualizaci dat příslušného existujícího objektu na straně Helpdesku aniž byste museli znát nativní ID objektu v Helpdesku.
Myšlenka je taková, že importujete kontakt nebo společnost XY a pokud je v Helpdesku nalezen objekt se stejným External ID, dojde k jeho aktualizaci. Jinak je založen záznam nový, obsahující tento External ID. Při dalším importu tak nevznikne duplicitní záznam, ale je provedena aktualizace.
Pokud na své straně budete uchovávat ID z objektů Helpdesk IPEX, můžete posílat místo External ID tyto nativní ID Helpdesku, ale protože je implementace takového řešení výrazně náročnější, předpokládáme spíše použití External ID. Pro pořádek v níže popsaných funkcích uvádíme i možnost posílání těchto nativních ID.
Co znamená použití metody PATCH
I když v API jsou obě funkce jako metody POST, chovají se ve skutečnosti jako metoda PATCH. Pokud je nalezen existující záznam (podle nativního ID nebo External ID) jsou v objektu změněny jen ty atributy, které jste poslali. Díky tomu nemusíte načíst stávající obsah a posílat celý nový obraz objektu, ale pošlete jen seznam atributů objektu, které chcete ovlivnit. Ostatní zůstanou beze změny.
Například pošlete aktualizaci počtu objednávek, ale přitom se nezmění jiný custom definovaný atribut.
Jednotlivé atributy nejsou do funkcí posílány v pevně dané struktuře, ale jako pole:
"Operation": "Replace",
"Path": "/UserName",
"Value": "nejaky_login"Pro použití funkce tedy potřebujete znát správné “Path” pro daný atribut. Operace “Replace” oproti definici v RFC zajistí, že pokud atribut v cílovém objektu nemá nastavenu hodnotu, je hodnota nastavena a není nutné posílat operaci “Add”. Pokud požadujete nastavení atributu objektu zrušit, můžete změnit u tohoto atributu operaci na “Remove”.
Jediný rozdíl je pro atributy typu pole, kde je třeba posílat na konci Path /- a operaci použít Add, např. /Emails/-
Následující příklad přidá k existujícím telefonním číslům vybraného uživatele navíc čísla 777888999 a 888999111:
https://xxxxxxx.cz/api/Account/PatchRequestorUser/2dbee0de-f947-45b2-808d-446bf8c3dccc
[
{
"op": "add",
"path": "/Phones/-",
"value": "777888999"
},
{
"op": "add",
"path": "/Phones/-",
"value": "888999111"
}
]Více o metodě PATCH naleznete v RFC-5789.
Funkce pro import kontaktů a zákazníků
POST api/Import/SyncRequestorUsers (Uživatelský účet/kontakt )
Provede hromadně založení nebo update objektu Uživatelský účet (Kontaktní osoba). Pro identifikaci záznamu můžete použít External ID nebo nativní ID objektu v Helpdesk IPEX (UserProviderKey).
Pokud je vyplněna sekce DefaultCustomer, je proveden pokus o svázání s objektem Společnost (přes External ID nebo Název společnosti). Pokud Společnost neexistuje, je založena, ale jen se Jménem. Ostatní údaje Společnosti je nutno doplnit následným updatem (je však vyřešeno vytvoření vazby mezi objekty).
Může být přiřazeno více kontaktů pod jednu Společnost, ale není to nutné. Může být pro Vás výhodnější mít naimportovány jen kontakty bez objektu Společnost a výrazně si tak zjednodušit práci jak s importem tak i s následným používáním Helpdesku. Typicky je takový způsob vhodný pro eshopy, protože naprostá většina kontaktů je jen z jedné firmy nebo nefiremní zákazník. V takovém případě může být duplicitně zakládaný objekt Společnost, který je 1:1 stejný se svázaným objektem uživatele/kontaktní osoby, spíše komplikací než přínosem.
V sekci CustomFields můžete předat doplňující atributy do Vámi definovaných polí.
Definice request
[
{
"Operations": [
{
"Operation": "Replace/Add/Remove",
"Path": "/path",
"Value": "value"
},
],
"ExternalId": "text",
"UserProviderKey": "text"
}
]Ukázka request
Ukázka response
GET api/Account/GetUserFields (Popis pro definovatelná pole uživatele/kontaktní osoby)
Pomocí této funkce načtete a zjistíte parametry pro práci s vámi definovanými poli, jako je ID, datový typ, případně ID položek použitelných v daném výběrovém seznamu.
Do Path uvádějte ve formátu /CustomFields/{id}/{dataType}
Ukázka výpisu ID položek custom fieldu typu “Výběrový seznam”
Obecné parametry uživatele/kontaktní osoby
Můžete použít tyto Path:
"/UserName",
"/Password",
"/ChangePasswordAfterLogging",
"/Email",
"/FirstName",
"/LastName",
"/MiddleName",
"/DisplayName",
"/Phone",
"/RoleEndUser" (“Boolean”),
"/RoleSmartUser" (“Boolean”),
"/RoleOperator" (“Boolean”),
"/RoleSuperOperator" (“Boolean”),
"/RoleAdministrator" (“Boolean”),
"/AdminNote" ("Note about the user, for administrators only."),
"/OperatorNote" ("Note about the user, for operators only."),
"/AdditionalInformation",
"/SkypeName",
"/Language" ("Use 0=EN, 1=DE, 2=CZ, 3=SK, 4=PL. If not set, the default language is used."),
"/DefaultCustomer/CustomerName",
"/DefaultCustomer/CustomerId" ("Integer. It is Customer ID in Helpdesk."),
"/DefaultCustomer/CustomerExternalId" ("Text. It is Customer ID in your system."),
"/CustomerIds" ("Array. Use as /CustomerIds/- and operation Add"),
"/InternalGroupIds" ("Array. Use as /InternalGroupIds/- and operation Add"),
"/OperatorGroupIds" ("Array. Use as /OperatorGroupIds/- and operation Add"),
"/Phones" ("Array. Use as /Phones/- and operation Add")
POST api/Import/SyncRequestorCustomers (Společnost)
Provede hromadně založení nebo update objektu Společnost. Pro identifikaci záznamu můžete použít External ID nebo nativní ID objektu v Helpdesk IPEX.
Definice request
Example request
Example response
GET api/Customer/GetCustomerFields (Popis pro definovatelná pole společnosti)
Pomocí této funkce načtete a zjistíte parametry pro práci s vámi definovanými poli, jako je ID, datový typ, případně ID položek použitelných v daném výběrovém seznamu.
Do Path uvádějte ve formátu /CustomFields/{id}/{dataType}
Obecné parametry Společnosti
"/Name",
"/Description",
"/Web" ("Customer Web URL Address"),
"/Location",
"/StreetNo",
"/PostalCode",
"/CountryCode" ("The code is specified by three letters."),
"/City",
"/TimeZoneId",
"/Disabled" ("If true the customer is disabled"),
"/Emails" ("Array.Use as /Emails/- and operation Add"),
"/EmailsDomains" ("Array. Use as /EmailsDomains/- and operation Add"),
"/Phones" ("Array. Use as /Phones/- and operation Add")
PATCH api/Account/PatchRequestorUser/{id} (změna vybraných parametrů uživatele/kontaktní osoby)
Dovoluje měnit parametry bez dopadu na zbytek objektu. Lze tak například dodatečně přidat již existujícímu uživateli/kontaktu ExternalId. Díky tomu pak lze další synchronizace/update kontaktů dělat hromadně pomocí výše uvedených importních funkcí. Pomůže v případě, pokud máte již dříve naimportované kontakty ručně přes CSV soubory, kde nebylo ExternalId naimportováno.
Jako parametr ID je nutno použít UserProviderKey např. 451def09-fbbd-413b-b0e9-2bb040120244
Musíte nastavit Content-Type: application/json-patch+json
Method: PATCH
Body:
Kódy států
{ "AFG", "Afghanistan" },
{ "ALA", "Åland Islands" },
{ "ALB", "Albania" },
{ "DZA", "Algeria" },
{ "ASM", "American Samoa" },
{ "AND", "Andorra" },
{ "AGO", "Angola" },
{ "AIA", "Anguilla" },
{ "ATA", "Antarctica" },
{ "ATG", "Antigua and Barbuda" },
{ "ARG", "Argentina" },
{ "ARM", "Armenia" },
{ "ABW", "Aruba" },
{ "AUS", "Australia" },
{ "AUT", "Austria" },
{ "AZE", "Azerbaijan" },
{ "BHS", "Bahamas" },
{ "BHR", "Bahrain" },
{ "BGD", "Bangladesh" },
{ "BRB", "Barbados" },
{ "BLR", "Belarus" },
{ "BEL", "Belgium" },
{ "BLZ", "Belize" },
{ "BEN", "Benin" },
{ "BMU", "Bermuda" },
{ "BTN", "Bhutan" },
{ "BOL", "Bolivia, Plurinational State of" },
{ "BES", "Bonaire, Sint Eustatius and Saba" },
{ "BIH", "Bosnia and Herzegovina" },
{ "BWA", "Botswana" },
{ "BVT", "Bouvet Island" },
{ "BRA", "Brazil" },
{ "IOT", "British Indian Ocean Territory" },
{ "BRN", "Brunei Darussalam" },
{ "BGR", "Bulgaria" },
{ "BFA", "Burkina Faso" },
{ "BDI", "Burundi" },
{ "KHM", "Cambodia" },
{ "CMR", "Cameroon" },
{ "CAN", "Canada" },
{ "CPV", "Cape Verde" },
{ "CYM", "Cayman Islands" },
{ "CAF", "Central African Republic" },
{ "TCD", "Chad" },
{ "CHL", "Chile" },
{ "CHN", "China" },
{ "CXR", "Christmas Island" },
{ "CCK", "Cocos (Keeling) Islands" },
{ "COL", "Colombia" },
{ "COM", "Comoros" },
{ "COG", "Congo" },
{ "COD", "Congo, the Democratic Republic of the" },
{ "COK", "Cook Islands" },
{ "CRI", "Costa Rica" },
{ "CIV", "Côte d'Ivoire" },
{ "HRV", "Croatia" },
{ "CUB", "Cuba" },
{ "CUW", "Curaçao" },
{ "CYP", "Cyprus" },
{ "CZE", "Czech Republic" },
{ "DNK", "Denmark" },
{ "DJI", "Djibouti" },
{ "DMA", "Dominica" },
{ "DOM", "Dominican Republic" },
{ "ECU", "Ecuador" },
{ "EGY", "Egypt" },
{ "SLV", "El Salvador" },
{ "GNQ", "Equatorial Guinea" },
{ "ERI", "Eritrea" },
{ "EST", "Estonia" },
{ "ETH", "Ethiopia" },
{ "FLK", "Falkland Islands (Malvinas)" },
{ "FRO", "Faroe Islands" },
{ "FJI", "Fiji" },
{ "FIN", "Finland" },
{ "FRA", "France" },
{ "GUF", "French Guiana" },
{ "PYF", "French Polynesia" },
{ "ATF", "French Southern Territories" },
{ "GAB", "Gabon" },
{ "GMB", "Gambia" },
{ "GEO", "Georgia" },
{ "DEU", "Germany" },
{ "GHA", "Ghana" },
{ "GIB", "Gibraltar" },
{ "GRC", "Greece" },
{ "GRL", "Greenland" },
{ "GRD", "Grenada" },
{ "GLP", "Guadeloupe" },
{ "GUM", "Guam" },
{ "GTM", "Guatemala" },
{ "GGY", "Guernsey" },
{ "GIN", "Guinea" },
{ "GNB", "Guinea-Bissau" },
{ "GUY", "Guyana" },
{ "HTI", "Haiti" },
{ "HMD", "Heard Island and McDonald Islands" },
{ "VAT", "Holy See (Vatican City State)" },
{ "HND", "Honduras" },
{ "HKG", "Hong Kong" },
{ "HUN", "Hungary" },
{ "ISL", "Iceland" },
{ "IND", "India" },
{ "IDN", "Indonesia" },
{ "IRN", "Iran, Islamic Republic of" },
{ "IRQ", "Iraq" },
{ "IRL", "Ireland" },
{ "IMN", "Isle of Man" },
{ "ISR", "Israel" },
{ "ITA", "Italy" },
{ "JAM", "Jamaica" },
{ "JPN", "Japan" },
{ "JEY", "Jersey" },
{ "JOR", "Jordan" },
{ "KAZ", "Kazakhstan" },
{ "KEN", "Kenya" },
{ "KIR", "Kiribati" },
{ "PRK", "Korea, Democratic People's Republic of" },
{ "KOR", "Korea, Republic of" },
{ "KWT", "Kuwait" },
{ "KGZ", "Kyrgyzstan" },
{ "LAO", "Lao People's Democratic Republic" },
{ "LVA", "Latvia" },
{ "LBN", "Lebanon" },
{ "LSO", "Lesotho" },
{ "LBR", "Liberia" },
{ "LBY", "Libya" },
{ "LIE", "Liechtenstein" },
{ "LTU", "Lithuania" },
{ "LUX", "Luxembourg" },
{ "MAC", "Macao" },
{ "MKD", "Macedonia, the former Yugoslav Republic of" },
{ "MDG", "Madagascar" },
{ "MWI", "Malawi" },
{ "MYS", "Malaysia" },
{ "MDV", "Maldives" },
{ "MLI", "Mali" },
{ "MLT", "Malta" },
{ "MHL", "Marshall Islands" },
{ "MTQ", "Martinique" },
{ "MRT", "Mauritania" },
{ "MUS", "Mauritius" },
{ "MYT", "Mayotte" },
{ "MEX", "Mexico" },
{ "FSM", "Micronesia, Federated States of" },
{ "MDA", "Moldova, Republic of" },
{ "MCO", "Monaco" },
{ "MNG", "Mongolia" },
{ "MNE", "Montenegro" },
{ "MSR", "Montserrat" },
{ "MAR", "Morocco" },
{ "MOZ", "Mozambique" },
{ "MMR", "Myanmar" },
{ "NAM", "Namibia" },
{ "NRU", "Nauru" },
{ "NPL", "Nepal" },
{ "NLD", "Netherlands" },
{ "NCL", "New Caledonia" },
{ "NZL", "New Zealand" },
{ "NIC", "Nicaragua" },
{ "NER", "Niger" },
{ "NGA", "Nigeria" },
{ "NIU", "Niue" },
{ "NFK", "Norfolk Island" },
{ "MNP", "Northern Mariana Islands" },
{ "NOR", "Norway" },
{ "OMN", "Oman" },
{ "PAK", "Pakistan" },
{ "PLW", "Palau" },
{ "PSE", "Palestinian Territory, Occupied" },
{ "PAN", "Panama" },
{ "PNG", "Papua New Guinea" },
{ "PRY", "Paraguay" },
{ "PER", "Peru" },
{ "PHL", "Philippines" },
{ "PCN", "Pitcairn" },
{ "POL", "Poland" },
{ "PRT", "Portugal" },
{ "PRI", "Puerto Rico" },
{ "QAT", "Qatar" },
{ "REU", "Réunion" },
{ "ROU", "Romania" },
{ "RUS", "Russian Federation" },
{ "RWA", "Rwanda" },
{ "BLM", "Saint Barthélemy" },
{ "SHN", "Saint Helena, Ascension and Tristan da Cunha" },
{ "KNA", "Saint Kitts and Nevis" },
{ "LCA", "Saint Lucia" },
{ "MAF", "Saint Martin (French part)" },
{ "SPM", "Saint Pierre and Miquelon" },
{ "VCT", "Saint Vincent and the Grenadines" },
{ "WSM", "Samoa" },
{ "SMR", "San Marino" },
{ "STP", "Sao Tome and Principe" },
{ "SAU", "Saudi Arabia" },
{ "SEN", "Senegal" },
{ "SRB", "Serbia" },
{ "SYC", "Seychelles" },
{ "SLE", "Sierra Leone" },
{ "SGP", "Singapore" },
{ "SXM", "Sint Maarten (Dutch part)" },
{ "SVK", "Slovakia" },
{ "SVN", "Slovenia" },
{ "SLB", "Solomon Islands" },
{ "SOM", "Somalia" },
{ "ZAF", "South Africa" },
{ "SGS", "South Georgia and the South Sandwich Islands" },
{ "SSD", "South Sudan" },
{ "ESP", "Spain" },
{ "LKA", "Sri Lanka" },
{ "SDN", "Sudan" },
{ "SUR", "Suriname" },
{ "SJM", "Svalbard and Jan Mayen" },
{ "SWZ", "Swaziland" },
{ "SWE", "Sweden" },
{ "CHE", "Switzerland" },
{ "SYR", "Syrian Arab Republic" },
{ "TWN", "Taiwan, Province of China" },
{ "TJK", "Tajikistan" },
{ "TZA", "Tanzania, United Republic of" },
{ "THA", "Thailand" },
{ "TLS", "Timor-Leste" },
{ "TGO", "Togo" },
{ "TKL", "Tokelau" },
{ "TON", "Tonga" },
{ "TTO", "Trinidad and Tobago" },
{ "TUN", "Tunisia" },
{ "TUR", "Turkey" },
{ "TKM", "Turkmenistan" },
{ "TCA", "Turks and Caicos Islands" },
{ "TUV", "Tuvalu" },
{ "UGA", "Uganda" },
{ "UKR", "Ukraine" },
{ "ARE", "United Arab Emirates" },
{ "GBR", "United Kingdom" },
{ "USA", "United States" },
{ "UMI", "United States Minor Outlying Islands" },
{ "URY", "Uruguay" },
{ "UZB", "Uzbekistan" },
{ "VUT", "Vanuatu" },
{ "VEN", "Venezuela, Bolivarian Republic of" },
{ "VNM", "Viet Nam" },
{ "VGB", "Virgin Islands, British" },
{ "VIR", "Virgin Islands, U.S." },
{ "WLF", "Wallis and Futuna" },
{ "ESH", "Western Sahara" },
{ "YEM", "Yemen" },
{ "ZMB", "Zambia" },
{ "ZWE", "Zimbabwe" }
Synchronizace kontaktů zpět do vašeho systému
Pro zápis lze využít automatizaci Helpdesk IPEX, kdy lze při vzniku nebo změně objektu Uživatelský účet/Kontakt nebo objektu Společnost vyvolat tzv. webhook a na své straně si provedete zápis do Vašeho systému.
