SCC API – dane kontaktów
pliki do pobrania
Ważne
Chcąc uzyskać dostęp do API integracyjnego, konieczne jest posiadanie tokena autoryzacyjnego.
Za pośrednictwem API integracyjnego masz możliwość:
1. dodawać kontakty do bazy SCC;
2. pobierać listę pól danych kontaktu – to potrzebne aby prawidłowo dodawać kontakty;
3. synchronizować kontakty – czyli aktualizować istniejące i dodawać nowe.
Pomocne
Pojedynczy kontakt w systemie, to zbiór danych dotyczących osoby lub przedsiębiorstwa, takich jak nazwisko lub nazwa, kontaktowy numer telefonu czy adres email.
1. Dodanie kontaktu
Jedną z podstawowych możliwości wykorzystania API integracyjnego jest dodawanie kontaktów do systemu Systell Contact Center.
Pomocne
Aby dodać kontakt do systemu, poza tokenem, będziesz potrzebować:
- definicji pól danych kontaktu. Możesz pobrać je z systemu za pośrednictwem API (instrukcja w punkcie 2.).
Gdy masz już gotową listę informacji o kontaktach, które chcesz wprowadzić do systemu, wykorzystaj je do skonstruowania wywołania dodania kontaktu tak, że:
- key z wyniku pobierania listy pól kontaktu – użyj jako nazwy pola;
- przypisz jej odpowiednią wartość dla wybranego kontaktu.
Na przykład:
jeśli na pobranej liście pól kontaktu znajduje się:
"key": "FirstName", "value": "Imię"
to przy tworzeniu wpisu dla kontaktu o imieniu Jan, będzie to:
"firstName": "Jan"
Aby dodać kontakt wywołaj (dane przykładowe):
POST IntegrationApi/Record
{
"name": "Nazwa",
"firstName": "Jan",
"lastName": "Testowski",
"city": "Poznań",
"region": "TEST6",
"postCode": "60-600",
"phoneNumber1": "123456789",
"phoneNumber2": "987654321",
"email": "jan.testowski@systell.eu",
"recordItems": [
{
"name": "PoleTest",
"value": "Dodatkowe pole na dane kontaktu"
}
]
}
}
W rezultacie otrzymasz status 201 created oraz identyfikator nowo dodanego kontaktu.
Dobre praktyki
Uzyskany identyfikator dobrze jest zapisać w swoim systemie. Ułatwi to późniejsze aktualizacje kontaktu i na przykład dodanie go do kampanii.
2. Pobieranie listy pól danych kontaktu
Jeśli chcesz dodawać do SCC kontakty, będzie Ci potrzebna lista pól danych kontaktu. Najpewniejszą metodą jej uzyskania jest pobranie również przez API.
Tą metodą uzyskasz listę wszystkich parametrów kontaktu, także tych dodatkowych, które zostały skonfigurowanie w czasie wdrażania systemu (na przykład Testowe Pole).
Aby pobrać definicje pól kontaktu wywołaj (dane przykładowe):
GET IntegrationApi/Record/GetDefinitions
{
"record":[
{
"key": "Name",
"value": "Firma"
},
{
"key": "FirstName",
"value": "Imię"
},
{
"key": "LastName",
"value": "Nazwisko"
},
{
"key": "Adress",
"value": "Adres"
},
{
"key": "PhoneNumber1",
"value": "Telefon 1"
},
{
"key": "RecordEmail",
"value": "Email"
},
{
"key": "PESEL",
"value": "PESEL"
},
{
"key": "REGON",
"value": "REGON"
},
{
"key": "KRS",
"value": "KRS"
},
{
"key": "NIP",
"value": "NIP"
},
{
"key": "Position",
"value": "Stanowisko"
}
]
"recordItems":[
{
"key": "Testowe_Pole",
"value": "Testowe_Pole"
}
]
}
Gdzie, w otrzymanym rezultacie:
- key – to nazwa parametru w bazie danych;
- value – jest nazwą tego parametru widoczną w systemie Systell Contact Center.
3. Synchronizacja kontaktów
Synchronizacja jest akcją uzupełniającą do scenariusza dodawania kontaktów.
Pomocne
Synchronizacja składa się z:
- Aktualizacji listy kontaktów, bez powielania wpisów, mimo że wprowadzana lista może zawierać mieszaninę kontaktów już dodanych do SCC wcześniej i nowych.
- Aktualizacji danych w istniejących kontaktach.
Do synchronizacji danych kontaktu będą potrzebne:
- nazwa pola, według którego ma zostać określone czy jest to nowy kontakt do dodania, czy istniejący do aktualizacji danych – żeby synchronizacja zadziałała prawidłowo powinno być to pole zawierające wartości unikatowe dla każdego wpisu;
- dane kontaktów do dodania lub aktualizacji.
Żeby zsynchronizować dane kontaktowe w SCC wywołaj (dane przykładowe):
POST IntegrationApi/Record/Upsert
Przykład synchronizacji danych po polu Email, w którym przechowywane są informacje o adresie poczty elektronicznej kontaktu:
{
"record": {
"name": "Nazwa",
"firstName": "Jan",
"lastName": "Testowski",
"phoneNumber1": "123456789",
"email": "jan.testowski@systell.eu",
"region": "jan.testowski@systell.pl"
},
"syncFields": [
"record.region"
]
}
Jeśli w systemie istnieje już kontakt o danym adresie email – jego pozostałe dane zostaną zaktualizowane. Jeżeli podany adres nie znajduje się w polu Email przypisanego do żadnego z istniejących kontaktów – zostanie utworzony nowy kontakt.
Przykład dodania nowego kontaktu:
{
"operationName": "INSERT",
"records": [
{
"id": "aeca92df-6aa9-4eab-a844-7811a9989d72",
"recordNumber": "R9LCH9T1W1",
"lastUse": "1899-12-31T23:00:00Z",
"lastActiveUse": "1899-12-31T23:00:00Z",
"timeOfCreation": "2023-08-21T11:38:17Z",
"timeOfModification": "2023-08-21T11:38:17Z",
"recordItems": [],
"recordType": {
"key": "efd810b0-f462-4e01-9160-b69621b78c58",
"name": "RECORD_TYPE_RECORD",
"description": "Jestem ciekaw ile się tekstu tu zmieści (Kontakt)"
}
"parent": null,
"children": null,
"guardian": null,
"name": "Nazwa",
"firstName": "Jan",
"lastName": "Testowski",
"address": "",
"addressNumber": "",
"city": "",
"region": "jan.testowski.systell.pl",
"postCode": "",
"phoneNumber1": "123456789",
"phoneNumber2": "",
"customKey": "",
"blocked": 0,
"lifeSpan": null,
"nextId": "R9LCH9T1W1",
"email": "jan.testowski@systell.eu",
"nip": null,
"pesel": null,
"regon": null,
"krs": null,
"position": null
}
]
"succeeded": true
}
Przykład zaktualizowania istniejącego kontaktu:
{
"operationName": "UPDATE",
"records": [
{
"id": "aeca92df-6aa9-4eab-a844-7811a9989d72",
"recordNumber": "R9LCH9T1W1",
"lastUse": "1899-12-31T23:00:00Z",
"lastActiveUse": "1899-12-31T23:00:00Z",
"timeOfCreation": "2023-08-21T11:38:17Z",
"timeOfModification": "2023-08-21T11:41:37Z",
"recordItems": [],
"recordType": {
"key": "efd810b0-f462-4e01-9160-b69621b78c58",
"name": "RECORD_TYPE_RECORD",
"description": "Jestem ciekaw ile się tekstu tu zmieści (Kontakt)"
}
"parent": null,
"children": null,
"guardian": null,
"name": "Nazwa",
"firstName": "Jan",
"lastName": "Testowski",
"address": "",
"addressNumber": "",
"city": "",
"region": "jan.testowski.systell.pl",
"postCode": "",
"phoneNumber1": "123456789",
"phoneNumber2": "",
"customKey": "",
"blocked": 0,
"lifeSpan": null,
"nextId": "R9LCH9T1W1",
"email": "jan.testowski@systell.eu",
"nip": null,
"pesel": null,
"regon": null,
"krs": null,
"position": null
}
]
"succeeded": true
}
Mając token i dane kontaktów możesz wykonywać przez API inne operacje na danych, np. dodawać sprawy.
Pomocne
Pamiętaj, że jeśli masz pytania lub potrzebujesz rozwiązania problemu z samodzielną integracją, zawsze możesz liczyć na nasz zespół specjalistów i skontaktować się z nami