REST API
UCS poskytuje backend REST API prostřednictvím služby ucs-api, routing zajišťuje NGINX.
Pro přístup je vyžadováno OAuth přihlášení prostřednictvím existujícího uživatele (uživatel
musí být členem role, která má oprávnění superuser a uživatel nesmí být public).
Pro testování je možné OAuth vypnout v souboru /etc/ucs.api.conf
, v sekci [oauth]
,
parametrem enabled = 0
.
Komunikační protokol
Volání iniciovaná směrem do UCS REST API jsou realizována s následujícími parametry:
- Přenosový protokol: HTTPS
- Zabezpečení: OAuth 2.0 (client_credentials, access token)
- Architektura rozhraní: REST
- Formát dat: JSON
- Kódování: UTF-8
- URL: https://ucs.example.com/api/v1.0
Úspěšná volání i očekávané chyby jsou potvrzovány odpovědí s HTTP status 2XX. Výjimky:
- OAuth vrací HTTP status 400 v případě špatného požadavku nebo 401 v případě špatných credentials
- Neočekávané výjimky (exception na straně UCS) vrací HTTP status 500
OAuth přihlášení
POST /login/oauth2/token
Pro volání API metod je požadován B2B OAuth token. Metoda pro získání tokenu vyžaduje jako payload
client_id, client_secret a grant_type. V odpovědi se vrátí access token, který je platný 1 hodinu
(resp. jak je nastaveno v /etc/ucs.api.conf
, v sekci [oauth]
, parametrem expires = 3600
).
Příklad získání OAuth tokenu
Požadavek:
POST https://ucs.example.com/login/oauth2/token
Content-Type: application/json
{
"client_id": "jmeno_servisniho_uctu_v_ucs",
"client_secret": "heslo_servisniho_uctu_v_ucs",
"grant_type": "client_credentials"
}
Odpověď:
200 OK
Content-Type: application/json
{
"access_token": "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz",
"token_type": "Bearer",
"expires_in": "3610"
}
Další endpointy REST API vyžadují Authorization hlavičku s platným access tokenem.
Příklad volání metody se získaným access tokenem
Požadavek
GET https://ucs.example.com/api/v1.0/status
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Pokud selže pokus o získání OAuth tokenu, pak je vrácen HTTP status 400 nebo 401.
Příklad neúspěšného pokusu o získání access tokenu
Odpověď na špatný požadavek
400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "We support only \"client_credentials\" grant type",
"error_uri": "https://www.oauth.com/oauth2-servers/access-tokens"
}
Odpověď na špatné credentials
401 Unauthorized
Content-Type: application/json
{
"error": "invalid_client",
"error_description": "Invalid username or password",
"error_uri": "https://www.oauth.com/oauth2-servers/access-tokens"
}
Stav a číselníky
Následující metody poskytují aktuální stav UCS a číselníky pro získání interních ID objektů v UCS, které jsou požadovány jako atributy dalších metod.
Status
GET /api/v1.0/status
Stav systému UCS, SIP trunků a telefonů.
Příklad získání stavu systému UCS
Požadavek
GET https://ucs.example.com/api/v1.0/status
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"trunks": {
"1": {
"name": "SIPY",
"status": 1,
"rtt": 1
},
"2": {
"name": "external",
"status": 0,
"rtt": 0
}
},
"phones": {
"1": {
"name": "System",
"configured": 279,
"configured_ipphones": 16,
"configured_softphones": 263,
"available": 0,
"available_ipphones": 0,
"available_softphones": 0,
"dead": 11,
"dead_ipphones": 2,
"dead_softphones": 9,
"paired": 11,
"paired_ipphones": 2,
"paired_softphones": 9
},
"3": {
"name": "Testik",
"configured": 2,
"configured_ipphones": 1,
"configured_softphones": 1,
"available": 0,
"available_ipphones": 0,
"available_softphones": 0,
"dead": 0,
"dead_ipphones": 0,
"dead_softphones": 0,
"paired": 0,
"paired_ipphones": 0,
"paired_softphones": 0
}
},
"ucs": 0,
"api": 0,
"postgres": 14,
"asterisk": 1,
"light-log": 0,
"tftp": 1,
"stunserver": 1,
"webserver": 3,
"nats-server": 1
}
Fronty
GET /api/v1.0/queues
Výpis nastavených front (příchozích i odchozích kampaní) a jejich aktuální stav. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.
Příklad získání přehledu front
Požadavek
GET https://ucs.example.com/api/v1.0/queues
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": [
{
"id": 74,
"active": true,
"group_id": 11,
"type": 1,
"number": "10099",
"name": "NONLIFE CZ",
"callers_waiting": 0,
"callers_ringing": 0,
"callers_talking": 0,
"agents_idle": 0,
"agents_ringing": 0,
"agents_talking": 0,
"agents_acw": 0,
"agents_aux": 0,
"answered": 1567,
"overflowed": 1,
"abandoned": 336,
"talktime": 314549,
"waittime": 270986,
"answered_wait_time": 227409.22137379646,
"answered_in_service": 740,
"answered_in_work_hours": 0,
"answered_in_work_and_sl": 0,
"abandoned_in_threshold": 140,
"abandoned_in_work_hours": 0,
"abandoned_in_work_and_sl": 0,
"abandoned_full": 0,
"sl": {
"day": [
740,
1763
],
"week": [
4184,
9405
],
"month": [
17929,
28297
],
"quarter": [
44922,
69392
]
},
"sl_work": {
"day": [
0,
0
],
"week": [
0,
0
],
"month": [
0,
0
],
"quarter": [
0,
0
]
},
"last_call_enter": 1724428798.475978,
"last_call_answer": 1724428717.4761183,
"callers": []
},
...
]
}
Skupiny
GET /api/v1.0/groups
Skupiny v UCS slouží pro organizaci nastavení (odráží organizační strukturu společnosti) a řízení přístupu (na základě rolí). Většina objektů (uživatelé, telefony, fronty, atd.) má atribut group_id, který určuje do jaké skupiny daný objek patří. Pokud objekt nemá tento atribut, pak je pro jeho editaci vyžadováno superuser oprávnění. UCS garantuje, že vždy existuje skupina ID 1. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.
Příklad získání číselníku organizačních skupin UCS
Požadavek
GET https://ucs.example.com/api/v1.0/groups
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": [
{
"id": 1,
"name": "System",
"external_id": null
},
{
"id": 3,
"name": " Testik",
"external_id": "1234"
},
{
"id": 7,
"name": " Test2",
"external_id": "2222"
},
{
"id": 9,
"name": " NN - Brokerska",
"external_id": "broker1"
},
{
"id": 10,
"name": " Markuv Servicedesk",
"external_id": "service1"
}
]
}
Role
GET /api/v1.0/roles
Role je sada oprávnění, která dovoluje uživatelům využívat služby UCS (a případně editovat nastavení). Typickým příkladem role je např. Administrátor, Běžný uživatel, Supervizor, Agent, atp. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.
Příklad získání číselníku uživatelských rolí UCS
Požadavek
GET https://ucs.example.com/api/v1.0/roles
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": [
{
"id": 1,
"group_id": 1,
"name": "Administrator"
},
{
"id": 6,
"group_id": 1,
"name": "Alice"
},
{
"id": 7,
"group_id": 1,
"name": "Bob"
},
{
"id": 9,
"group_id": 10,
"name": "Bot"
},
{
"id": 8,
"group_id": 1,
"name": "Charlie"
}
]
}
Týmy
GET /api/v1.0/teams
Tým je sada nastavení vlastností call centra, nastavují se zde barvy jednotlivých stavů, důvody neodstupnosti agentů, výchozí hodnoty pro členství ve frontách, atd. Metoda neakceptuje žádné parametry. Odpověď je pole asociativních polí.
Příklad získání číselníku týmů call centra UCS
Požadavek
GET https://ucs.example.com/api/v1.0/teams
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": [
{
"id": 8,
"group_id": 1,
"name": "Markuv Team",
"note": "Team TEAM TEAM!!!!",
"aux_reasons": [
{
"reason": "Nemám rád šmouly",
"break": false,
"color": "ff0000",
"limit": null,
"hidden": false
}
],
"contacts": [],
"tasks": {
"person": 0,
"person_url": null,
"call": 0,
"call_url": null,
"email": 0,
"email_url": null
},
"maximum_assigned_emails": null,
"default_inbound_priority": 100,
"default_inbound_acw": false,
"default_inbound_acw_timeout": null,
"default_inbound_busy": null,
"default_inbound_busy_timeout": null,
"default_outbound_acw": false,
"default_outbound_acw_timeout": null,
"default_email_priority": 100,
"default_email_languages": {
"cs_CZ": 100,
"en_US": 100,
"de_DE": 100,
"ru_RU": 100
},
"default_email_assigned": null,
"default_task_priority": 100,
"color_agent_offline": null,
"color_agent_ready": "188b35",
"color_agent_acw": "ffda1f",
"color_agent_aux": "ff9500",
"color_agent_ringing": "a1ff2e",
"color_agent_talking": "a1ff29",
"color_phone_offline": null,
"color_phone_idle": "00bfff",
"color_phone_ringing": "ff00ea",
"color_phone_talking": "ff00ea",
"breaks_limit": null,
"transfer_to_agent": false,
"transfer_to_queue": false,
"channels": {
"inbound": false,
"task": false,
"email": false,
"chat": false,
"dialer": false
}
},
...
]
}
Hovory
UCS poskytuje CDR (Call Detail Records) o proběhlých hovorech. Každý hovor má stringové unikátní ID, které se skládá z UNIX timestampu zahájení hovoru a tečkou odděleným číslem hovoru od restartu komponenty Asterisk.
Informace o hovoru
GET /api/v1.0/call/{uniqueid}
Metoda umožňuje získání všech uložených dat o proběhlém hovoru. Směr hovoru je dán kombinací atributů src_internal a dst_internal. Detailní informace o tom, jak hovor procházel ústřednou je zaznamenána v atributu path. Pokud byl hovor přepojen, pak dst_ atributy odpovídají cílovému číslu. Pozor, pokud přepojí volající, pak je založen další CDR záznam pro daný hovor.
Příklad získání informací o proběhlém hovoru (Call Detail Record)
Požadavek
GET https://ucs.example.com/api/v1.0/call/1723018607.115
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": {
"price": 0,
"duration": 524,
"src_number": "+420776000001",
"src_name": "",
"dst_number": "1800",
"dst_name": " Bob",
"src_internal": false,
"dst_internal": true,
"calldate": "2024-08-07 10:17:04",
"connected": "2024-08-07 10:17:07",
"disconnected": "2024-08-07 10:25:51",
"src_extension_id": null,
"dst_extension_id": 75,
"src_user_id": null,
"dst_user_id": 11,
"src_type": "trunk",
"dst_type": "phone",
"xfer_users": null,
"trunk_id": null,
"uniqueid": "1723018607.115",
"metadata": {
"ucrm_interaction_id": 30391,
"outbound_id": 0
},
"src_group_id": 1,
"dst_group_id": 1,
"pilot_number": "0776000001",
"ring_time": 4,
"talk_time": 524,
"hold_time": 0,
"cause": 3,
"recording": true,
"recording_duration": 523,
"path": [
{
"date": "2024-08-07 10:16:47",
"type": 1,
"number": "0776000001",
"name": "SIPY"
},
{
"date": "2024-08-07 10:17:04",
"type": 10000,
"number": "1800",
"name": "Bob SP"
},
{
"date": "2024-08-07 10:17:04",
"type": 10711,
"number": "1800",
"name": " Bob"
},
{
"date": "2024-08-07 10:17:04",
"type": 10001,
"number": "1800",
"name": "Bob SP"
},
{
"date": "2024-08-07 10:17:07",
"type": 10002,
"number": "1800",
"name": "Bob SP"
},
{
"date": "2024-08-07 10:25:51",
"type": 10720,
"number": "0776000001",
"name": ""
},
{
"date": "2024-08-07 10:25:51",
"type": 10,
"number": "0776000001",
"name": ""
}
]
}
}
Získání metadat hovoru
Metadata připojená k hovoru je asociativní pole libovolných klíčů a hodnot. Metadata lze získat k aktivnímu hovoru i zpětně po jeho ukončení.
GET /api/v1.0/metadata/{uniqueid}
Příklad získání metadat k aktivnímu nebo proběhlému hovoru
Požadavek
GET https://ucs.example.com/api/v1.0/metadata/1723018607.115
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": {
"ucrm_interaction_id": 30391,
"outbound_id": 0
}
}
Nastavení metadat hovoru
Metoda umožňuje rozdílovou aktualizaci metadat hovoru. Předané klíče se v metadatech hovoru vytvoří nebo přepíší. Pokud stávající klíč metadat neexistuje v payloadu, pak je tento klíč ponechán beze změny. Pro smazání klíče se jeho hodnota nastaví na null. Metoda vrací výsledná metadata hovoru.
POST /api/v1.0/metadata/{uniqueid}
Příklad aktualizace metadat aktivního nebo proběhlého hovoru
Požadavek
POST https://ucs.example.com/api/v1.0/metadata/1723018607.115
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"outbound_id": null,
"pokus": "hokus"
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": {
"ucrm_interaction_id": 30391,
"pokus": "hokus"
}
}
Sdílená data
Data předávaná z jiných systémů, která se zobrazují na wallboardech, nebo pomocí kterých se řídí směrování hovorů, přehrávání hlášek, atp.
Zobrazení hodnot
GET /api/v1.0/shared/{identificator}
Získání aktuální hodnoty sdílených dat daného identifikátoru.
Příklad získání aktuální hodnoty sdílených dat
Požadavek
GET https://ucs.example.com/api/v1.0/shared/osl_chats
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": {
"type": "osl",
"data": {
"SWS": {
"OneSolution": {
"Waiting": 5,
"Processed": 0
}
},
"KPK": {
"OneSolution": {
"Waiting": 2,
"Doing": 4
}
}
}
}
}
Aktualizace hodnot
POST /api/v1.0/shared/{identificator}
Přepsání hodnoty sdílených dat daného identifikátoru.
Příklad aktualizace sdílených dat
Požadavek
POST https://ucs.example.com/api/v1.0/shared/osl_chats
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"type": "osl",
"data": {
"SWS": {
"OneSolution": {
"Waiting": 4,
"Processed": 1
}
},
"KPK": {
"OneSolution": {
"Waiting": 2,
"Doing": 4
}
}
}
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}
Uživatelé
Synchronizace uživatelských účtů.
Výpis uživatelů
GET /api/v1.0/users
Vrátí seznam uživatelů v UCS jako pole objektů. Metoda nemá žádné parametry.
Příklad získání všech existujících uživatelů v UCS
Požadavek
GET https://ucs.example.com/api/v1.0/users
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": [
{"id": 1, "name": "admin", "external_id": "asdf"},
{"id": 10, "name": "Alice", "external_id": null},
{"id": 11, "name": "Bob", "external_id": "2468"}
]
}
Detail uživatele
GET /api/v1.0/user/{user_id}
nebo
GET /api/v1.0/user/external/{external_id}
Metoda vrátí kompletní strukturu atributů objektu uživatele User.
Příklad získání všech atributů uživatelského účtu
Požadavek
GET https://ucs.example.com/api/v1.0/user/external/asdf
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": {
"id": 1,
"active": true,
"external_id": "asdf",
"group_id": 1,
"role_id": 1,
"team_id": null,
"locale": "en_US",
"username": "admin",
"firstname": "null",
"lastname": null,
"displayname": "admin",
...
}
}
User
Struktura objektu uživatele:
Klíč | Typ | Význam |
---|---|---|
id | int | unikátní ID uživatele (primární klíč) |
username | str | přihlašovací jméno (case-insensitive) |
password | str | heslo v plaintextu (do DB je hashována algoritmem PBKDF2) |
locale | enum[str] | jazyk uživatelského rozhraní cs_CZ: český en_US: anglický sk_SK: slovenský |
str | e-mailová adresa uživatele (může být použita pro přihlášení) | |
primary_extension | int | ID primární linky uživatele |
pin | str | kód pro přístup k hlasové schránce |
firstname | str | křestní jméno uživatele |
lastname | str | příjmení uživatele |
public | bool | servisní účty mají tento atribut nastaven na false |
group_id | int | ID organizační skupiny UCS do které uživatel patří |
identificator | str | identifikátor uživatele pro funkci User Mobility |
external_id | str | identifikátor uživatele v externím IS (pozor, je case-sensitive) |
filter_id | int | ID filtru odchozích volání pro volání na externí číslo |
number | str | externí číslo na které je uživateli voláno v případě odpárování linky |
data | json | libovolná metadata vázaná k uživateli ve formátu asociativního pole |
team_id | int | ID týmu call centra do kterého uživatel patří |
active | bool | příznak zda je uživatelský účet aktivní |
wssip_device_id | int | ID softwarového telefonu |
certificate | bool | příznak zda se má uživateli vytvořit klientský SSL certifikát |
role_id | int | ID role oprávnění do které uživatel patří |
channels | json | aktivní kanály pro funkci Omnichannel |
clid_number | str | telefonní číslo volajícího pro externí odchozí hovory |
Vytvoření uživatele
POST /api/v1.0/user
Založí uživatele v UCS. Povinné atributy jsou username a group_id (v UCS vždy existuje group ID 1). Jako palyload je v požadavku předán uživatelský objekt User. Návratová hodnota je ID nově založeného uživatele.
Příklad založení nového uživatelského účtu
Požadavek
POST https://ucs.example.com/api/v1.0/user
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"username": "test",
"group_id": 1
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": 123
}
Interní ID UCS nově založeného účtu je 123.
Aktualizace uživatele
PATCH /api/v1.0/user/{user_id}
nebo
PATCH /api/v1.0/user/external/{external_id}
Aktualizuje atributy uživatelského objektu User. Pokud není atribut v payloadu specifikován, pak je zachována jeho stávající hodnota.
Příklad aktualizace atributů existujícího uživatelského účtu
Požadavek
PATCH https://ucs.example.com/api/v1.0/user/123`
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"external_id": "T1000",
"password": "1pokus+Hokus2",
"team_id": 1,
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}
V případě chybné hodnoty některého z atributů, je vráceno asociativní pole s danými atributy.
PATCH https://ucs.example.com/api/v1.0/user/external/T1000`
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"external_id": "t123456",
"number": "cislo",
"filter_id": "PSTN",
}
Chybná hodnota v atributu number a filter_id. Chybně zadané atributy zablokují aktualizaci, tzn. ikdyž je hodnota external_id validní, nedojde k jejímu přepsání.
200 OK
Content-Type: application/json
{
"success": false,
"data": {
"number": "contain invalid character (invalid character \"c\")",
"filter_id": "value must be integer number"
}
}
Smazání uživatele
DELETE /api/v1.0/user/{user_id}
nebo
DELETE /api/v1.0/user/external/{external_id}
Vymaže uživatele. V historii hovorů dojde ke zrušení reference, ale záznamy vč. nahrávek zůstanou nedotčeny. Pro deaktivaci uživatele lze alternativně nastavit atribut active na hodnotu false, pak zůstává uživatel v DB, ale nemůže se přihlásit.
Příklad smazání uživatelského účtu
Požadavek
DELETE https://ucs.example.com/api/v1.0/user/external/T1000
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}
µCRM
Synchronizace zákazníků do UCS mikro CRM.
Seznam kontaktních osob
GET /api/v1.0/crm/persons
Metoda akceptuje nepovinné parametry limit a offset v URL.
Návratová hodnota je pole Person objektů.
Příklad získání 50 kontaktních osob s offsetem 100
Požadavek
GET https://ucs.example.com/api/v1.0/crm/persons?limit=50&offset=100
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": [
{
"id": 26920,
"group_id": 1,
"displayname": "Abrhám Václav",
"firstname": "Václav",
"lastname": "Abrhám",
"external_id": "16943"
},
{
"id": 13270,
"group_id": 1,
"displayname": "Adamec Lukáš",
"firstname": "Lukáš",
"lastname": "Adamec",
"external_id": "20451"
},
{
"id": 25677,
"group_id": 1,
"displayname": "Albert Antonín",
"firstname": "Antonín",
"lastname": "Albert",
"external_id": "23393"
},
...
],
"total": 26907
}
V µCRM je celkem 26907 osob.
Detail kontaktní osoby
GET /api/v1.0/crm/person/{person_id}
nebo
GET /api/v1.0/crm/person/external/{external_id}
Příklad získání detailu kontaktní osoby z µCRM
Požadavek
GET https://ucs.example.com/api/v1.0/crm/person/59233
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
nebo
GET https://ucs.example.com/api/v1.0/crm/person/external/abc123
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": {
"id": 59233,
"group_id": 1,
"displayname": "Ing. Petr Novák VIP",
"firstname": "Petr",
"lastname": "Novák",
"note": "Pozor, je to převelice důležitý zákoš…",
"external_id": "abc123",
"data": {
"expires": "2025-01-01 00:00:00"
},
"contacts": [
{
"id": 71615,
"type": 2,
"contact": "a@b.cd",
"label": "e-mail"
},
{
"id": 71616,
"type": 1,
"contact": "+420654321987",
"label": "mobil"
},
],
"interactions": [ ],
"companies": [ ],
"tasks": [ ]
}
}
Person
Struktura objektu uživatele:
Klíč | Typ | Význam |
---|---|---|
id | int | unikátní ID osoby (primární klíč) |
group_id | int | ID skupiny jejíž je osoba členem |
displayname | str | zobrazované jméno osoby |
firstname | str | jméno |
lastname | str | příjmení |
note | str | libovolná poznámka ke kontaktní osobě |
external_id | str | identifikátor uživatele v externím IS |
data | object | asociativní pole klíč/hodnota pro libovolná data |
contacts | array | pole kontaktních údajů (objekt Contact) |
interactions | array | historie komunikace s klientem (read-only) |
companies | array | společnosti ve kterých je osoba zařazena (read-only) |
tasks | array | tickety spojené s danou osobou (read-only) |
Contact
Struktura objektu kontaktu:
Klíč | Typ | Význam |
---|---|---|
id | int | unikátní ID asociace (primární klíč) |
type | enum[int] | typ kontaktu 0: obecný kontakt 1: telefonní číslo 2: e-mailová adresa 3: webová URL |
contact | str | kontakt (adresa, telefonní číslo, e-mail, URL) |
label | str | popis k danému kontaktnímu údaji |
Vložení nové osoby
POST /api/v1.0/crm/person
Jako tělo požadavku se předá struktura objektu Person. Je povinný pouze atribut group_id.
Návratová hodnota je ID nově vytvořeného záznamu.
Příklad vložení nové osoby do µCRM
Požadavek
POST https://ucs.example.com/api/v1.0/crm/person
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"group_id": 1,
"displayname": "Martin Dvořák",
"external_id": "321654987",
"contacts": [
{
"type": 1,
"contact": "+420222333444",
"label": "kancelář"
}
]
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": 123456
}
Interní ID UCS nově založené osoby µCRM je 123456.
Aktualizace existující osoby
PATCH /api/v1.0/crm/person/{person_id}
Jako tělo požadavku se předá struktura objektu Person s atributy, které mají být aktualizovány. Atribut contacts je nepovinný, pokud nemají být aktualizovány kontakty osoby. Pokud je atribut contacts předán, pak jsou kontakty přepsány podle předaného obsahu.
Návratová hodnota metody je prázdná.
Příklad aktualizace dat existující osoby v µCRM
Požadavek
PATCH https://ucs.example.com/api/v1.0/crm/person/123456
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"firstname": "Martin",
"lastname": "Dvořák"
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}
Smazání osoby
DELETE /api/v1.0/crm/person/{person_id}
Vymaže osobu z UCS.
Návratová hodnota metody je prázdná.
Příklad smazání existující osoby z µCRM
Požadavek
DELETE https://ucs.example.com/api/v1.0/crm/person/123456
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}
Seznam společností
GET /api/v1.0/crm/companies
Kontaktní osoby v µCRM mohou být zastřešeny společností. Metoda akceptuje nepovinné parametry limit a offset v URL. Návratová hodnota je pole Company objektů.
Příklad získání 50 zastřešujících organizací na offsetu 100
Požadavek
GET https://ucs.example.com/api/v1.0/crm/companies?limit=50&offset=100
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
{
"success": true,
"data": [
{
"id": 5313,
"group_id": 1,
"name": "Acme inc.",
"external_id": "74"
},
{
"id": 2919,
"group_id": 1,
"name": "All happy, ltd.",
"external_id": "13873"
},
{
"id": 1677,
"group_id": 1,
"name": "AZ s.r.o.",
"external_id": "6694"
},
...
],
"total": 10611
}
Celkem je v µCRM 10611 společností.
Detail společnosti
GET /api/v1.0/crm/company/{company_id}
GET /api/v1.0/crm/company/external/{external_id}
Příklad získání detailu společnosti v µCRM
Požadavek
GET https://ucs.example.com/api/v1.0/crm/company/10764
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
nebo
GET https://ucs.example.com/api/v1.0/crm/company/external/ins
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
success: true,
data: {
"id: 10764,
"group_id: 1,
"name: "INSOFT s.r.o.",
"external_id": "ins",
"data": {
"ico": "04110889"
},
"persons": [
{
"person_id": 123456,
"role": "majitel"
}
],
"tasks": [ ]
}
}
Company
Struktura objektu společnosti:
Klíč | Typ | Význam |
---|---|---|
id | int | unikátní ID společnosti (primární klíč) |
group_id | int | ID skupiny jejíž je společnost členem |
name | str | název společnosti |
external_id | str | identifikátor uživatele v externím IS |
data | object | asociativní pole klíč/hodnota pro libovolná data |
persons | array | pole osob patřících do společnosti (objekt CompanyPerson) |
tasks | array | tickety spojené s danou společností (read-only) |
CompanyPerson
Struktura objektu asociace osoby do společnosti:
Klíč | Typ | Význam |
---|---|---|
person_id | int | unikátní ID osoby (objektu Person) |
role | str | popis role osoby ve společnosti |
Vložení nové společnosti
POST /api/v1.0/crm/company
Jako tělo požadavku se předá struktura objektu Company. Je povinný pouze atribut group_id.
Návratová hodnota je ID nově vytvořeného záznamu.
Příklad vytvoření nové společnosti v µCRM
Požadavek
POST https://ucs.example.com/api/v1.0/crm/company
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"group_id": 1,
"name": "Společnost a.s."
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": 10765
}
Aktualizace společnosti
PATCH /api/v1.0/crm/company/{company_id}
Jako tělo požadavku se předá struktura objektu Company s atributy, které maj í být aktualizovány. Atribut persons je nepovinný, pokud nemají být aktualizovány asociované osoby. Pokud je atribut persons předán, pak jsou osoby přepsány podle předaného obsahu.
Návratová hodnota metody je prázdná.
Příklad úpravy atributů společnosti v µCRM
Požadavek
PATCH https://ucs.example.com/api/v1.0/crm/company/123456
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Content-Type: application/json
{
"persons": [
{
"person_id": 123456,
"role": "dodavatel"
},
{
"person_id": 123457,
"role": "jednatel"
}
]
}
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}
Smazání společnosti
DELETE /api/v1.0/crm/company/{company_id}
Vymaže společnost z UCS.
Návratová hodnota metody je prázdná.
Příklad smazání společnosti z µCRM
Požadavek
DELETE https://ucs.example.com/api/v1.0/crm/company/10764
Authorization: Bearer AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
Odpověď
200 OK
Content-Type: application/json
{
"success": true,
"data": null
}