Informacje ogólne
Do czego możesz wykorzystać API SALESmanago?
API SALESmanago jest jednym z wielu sposobów na zintegrowanie strony eCommerce lub innego oprogramowania z SALESmanago. Jak każde inne połączenie API, korzystanie z API SALESmanago wymaga przynajmniej podstawowej wiedzy technicznej, a do bardziej zaawansowanych integracji potrzebne jest głębsze zrozumienie zagadnień programistycznych.
Dane autoryzacyjne
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c"
}
Autentykacja
API SALESmanago jest otwarte dla naszych klientów, co oznacza, że każdy klient może się z nim zintegrować bez dodatkowych opłat. Aby zacząć korzystać z naszego API, musisz najpierw uzyskać dane autentykacyjne:
- clientId – Twój identyfikator klienta, który można znaleźć w SALESmanago ➔ Centrum Integracji ➔ API (zakładka API v2).
- apiKey – dowolny losowy ciąg znaków.
- sha – wartość wygenerowana na podstawie sha1(apiKey+clientId+apiSecret), gdzie znak plusa służy do konkatenacji. Wartość apiSecret jest unikalna dla każdego klienta, znajdziesz ją we wspomnianej wcześniej zakładce API v2.
Wszystkie żądania muszą także zawierać requestTime – UNIX-owy znacznik czasu (timestamp) w milisekundach.
Szczegóły techniczne
Wszystkie endpointy mają następującą strukturę adresu:
https://xxx.salesmanago.pl/api
gdzie xxx to identyfikator twojego serwera SALESmanago (w większości przypadków będzie to www, app2 albo app3).
Wszystkie żądania są wysyłane przy użyciu metody HTTP POST i są enkapsulowane w formacie JSON. W związku z tym wymagane są następujące nagłówki:
Accept: application/json, application/json
Content-Type: application/json;charset=UTF-8
Większość bibliotek HTTP samodzielnie dołącza te nagłówki, gdy w treści żądania wysyłany jest obiekt JSON.
Integracja kodu monitorującego
Kod Monitorujący jest odpowiedzialny za monitorowanie Kontaktów na twojej stronie internetowej, dlatego jego wdrożenie jest szczególnie zalecane. Aby Kod Monitorujący nie wpływał na wydajność twojej strony internetowej, wszystkie skrypty JavaScript są ładowane asynchronicznie już po załadowaniu strony.
Kod Monitorujący możesz znaleźć w SALESmanago ➔ Centrum Integracji ➔ Kod Monitorujący. Skrypt ten powinien zostać dodany do witryny tuż przed znacznikiem zamykającym </body>. Jeśli twoja strona została stworzona na zamówienie, dodanie kodu do szablonu strony powinno być łatwe. Jeśli strona jest oparta na oprogramowaniu innych firm, spróbuj wyszukać hasło “[nazwa platformy] add custom javascript”. Kod Monitorujący możesz też dodać, używając Google Tag Manager (GTM). Aby to zrobić, zaloguj się do SALESmanago, a następnie przejdź to Centrum Integracji ➔ Kod Monitorujący i kliknij przycisk w sekcji Użyj Google Tag Manager (GTM).
Sprawdzanie poprawności pola e-mail
Adres e-mail może mieć maksymalnie 254 znaki. Według standardu RFC882 system weryfikuje, czy adres zawiera maksymalnie 64 znaki przed symbolem @ oraz poprawną domenę internetową po nim.
Przesyłanie dodatkowych informacji monitorujących
Przykładowy kod wraz z wartością contactId:
<script type="text/javascript">
var _smid = "your-client-id-123";
var _smclientid = "contactIdFromResponse-123";
</script>
<script src="https://www.salesmanago.pl/static/sm.js" type="text/javascript"/>
Alternatywnie, przesyłając formularz przez AJAX można zapisać samo ciasteczko:
$.ajax({
type:'POST',
url:'/account/registerDemoVideo.htm',
data:$("#registerForm").serialize(),
cache:false,
timeout:240000,
success:function (data) {
if (data == 'Wrong_Email') {
alert('Podany email nie jest prawidłowy.');
$("#email").focus();
} else {
createCookie('smclient', data, 365 * 10);
$(".registeredInfo").show();
}
},
error:function (data) {
alert("Błąd – nie udało się zarejestrować");
}});
W odpowiedzi na zapytanie /contact/upsert otrzymujemy unikatowy identyfikator. Aby usprawnić monitoring zachowania użytkowników na stronie WWW należy ten parametr przekazać przynajmniej na jednej podstronie odwiedzanej przez użytkownika – np. po zalogowaniu – w momencie logowania wykonujemy zapytanie /contact/upsert a otrzymaną wartość contactId drukujemy wraz z kodem JavaScript systemu monitorowania SALESmanago.
API - Zarządzanie kontaktami
Dodawanie nowego lub modyfikacja istniejącego kontaktu
Przykładowe żądanie z podstawowymi danymi:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"contact": {
"email": "name@example.com",
"phone": "+15554443322",
"name": "John Doe",
"externalId": "U12345",
"address": {
"streetAddress": "Main Street 21",
"zipCode": "90210",
"city": "San José",
"country": "US"
}
},
"province": "California",
"birthday": "19870605",
"forceOptIn": true,
"forceOptOut": false,
"forcePhoneOptIn": false,
"forcePhoneOptOut": true,
"tags": [
"T_SHIRTS",
"SWEATERS",
"UPSELL"
],
"removeTags": [
"FIRST_PURCHASE"
]
}
Przykładowe zaawansowane żądanie:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"contact": {
"email": "name@example.com",
"phone": "+15554443322",
"fax" : "+15551112233",
"name": "John Doe",
"externalId": "U12345",
"state" : "PROSPECT",
"address": {
"streetAddress": "Main Street 21",
"zipCode": "90210",
"city": "San José",
"country": "US"
}
},
"province": "California",
"birthday": "19870605",
"forceOptIn": true,
"forceOptOut": false,
"forcePhoneOptIn": false,
"forcePhoneOptOut": true,
"useApiDoubleOptIn": true,
"doubleOptInLanguage": "ES",
"newEmail": "new.email@example.com",
"tags": [
"T_SHIRTS",
"SWEATERS",
"UPSELL"
],
"removeTags": [
"FIRST_PURCHASE"
],
"properties": {
"t_shirt_size": "XL",
"gender": "Male"
},
"dictionaryProperties": [
{
"name": "member_since",
"type": "DATE",
"value": 1459938888000
},
{
"name": "shoe_size",
"type": "NUMBER",
"value": 10
}
],
"consentDetails": [
{
"consentName": "TERMS_OF_SERVICE",
"consentAccept": true,
"agreementDate": 1659938888000,
"ip": "192.168.0.1",
"optOut": false,
"consentDescriptionId": 1234
},
{
"consentName": "PHYSICAL_MAIL",
"consentAccept": false,
"agreementDate": 1659938888000,
"ip": "192.168.0.1",
"optOut": true,
"consentDescriptionId": 5678
}
]
}
Przykładowa odpowiedź
{
"contactId" : "1a2b-...-3c4d",
"message" : [],
"success" : true,
"externalId": "U12345"
}
Możesz dodać lub zmodyfikować kontakt używając metody API:
https://www.salesmanago.pl/api/contact/upsert
Podstawowe pola:
Jedynymi obowiązkowymi polami są pola autentykacyjne, pole owner oraz adres e-mail Kontaktu. Jednak, aby w pełni wykorzystać potencjał SALESmanago, możesz przesłać więcej danych o Kontakcie. Wykorzystasz je potem w Procesach Automatyzacji, personalizacji, segmentacji i innych funkcjonalnościach.
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | Właściciel kontaktu (e-mail konta użytkownika SALESmanago) |
| contact | obiekt | Obiekt zawierający podstawowe dane o Kontakcie |
| name | 255 | Nazwa Kontaktu |
| email* | 254[?] | E-mail Kontaktu |
| contactId | UUID | Identyfikator Kontaktu z SALESmanago, który otrzymasz w odpowiedzi na każde żądanie z dodaniem lub aktualizacją Kontaktu. Jeśli identyfikujesz Kontakt używając contactId, pole email nie jest obowiązkowe. |
| phone | 255 | Numer telefonu Kontaktu |
| fax | 255 | Numer faksu Kontaktu |
| company | 255 | Firma Kontaktu |
| externalId | 255 | Zewnętrzne ID Kontaktu, na przykład ID użytkownika z platformy eCommerce |
| birthday | 8 | Data urodzenia Kontaktu, przekazywana jako łańcuch znaków w postaci:yyyyMMdd lub MMdd gdzie yyyy – czterocyfrowy rok, MM – dwucyfrowy miesiąc, dd – dwucyfrowy dzień |
| address | obiekt | Obiekt zawierający adres Kontaktu |
| streetAddress | 255 | Ulica i numer domu |
| zipCode | 255 | Kod pocztowy |
| city | 255 | Miasto |
| country | 255 | Kraj, rekomendowany format zapisu to kod alfa-2 standardu ISO 3166-1 |
| province | 255 | Jednostka podziału terytorialnego w kraju, np. Małopolskie |
Zgody wyrażone przez Kontakt:
Nowe Kontakty są domyślnie dodawane do SALESmanago z wyrażoną zgodą na E-mail Marketing, ale bez zgody na Mobile Marketing. Jest to przydatne, kiedy integrujesz formularz zapisu na newsletter. Jeśli przesyłasz kontakty z innego formularza, gdzie wyrażenie zgód nie jest obowiązkowe pamiętaj o konieczności zmiany statusów zgód.
| Pole | Max. długość | Opis |
|---|---|---|
| forceOptIn | true/false | Flaga oznaczająca wyrażenie zgody na E-mail Marketing |
| forceOptOut | true/false | Flaga oznaczająca wycofanie zgody na E-mail Marketing |
| useApiDoubleOptIn | true/false | Flaga wskazująca, czy status opt-in powinien być potwierdzony przy użyciu double opt-in. Dotyczy to tylko kontaktów zmieniających swój status na opt-in. |
| doubleOptInLanguage | 255 | Język kontaktu, który ma być użyty podczas wysyłania wiadomości double opt-in |
| forcePhoneOptIn | true/false | Flaga oznaczająca wycofanie zgody na Mobile Marketing |
| forcePhoneOptOut | true/false | Flaga oznaczająca wycofanie zgody na Mobile Marketing |
Do SALESmanago możesz przesłać również inne typy zgód, np. Zgodę na warunki użytkowania systemu czy zgodę na tradycyjną korespondencję marketingową. Do tego celu wykorzystaj zgody, które zdefiniujesz w SALESmanago Ustawienia ➔ Inne ➔ Lista zgód. Tekst zgody możesz aktualizować, co utworzy jej nowszą wersję, która nadpisze tę istniejącą. SALESmanago zapisuje informację która wersja zgody została wyrażona/odrzucona przez Kontakt.
Za pomocą pól consentAccept i optOut możesz ustawić jeden z trzech statusów zgody na karcie kontaktu. W tym celu prześlij odpowiednie flagi consentAccept oraz optOut:
- consentAccept=false, optOut=false – zgoda niepotwierdzona,
- consentAccept=true, optOut=false – zgoda potwierdzona,
- consentAccept=false, optOut=true – zgoda wycofana,
- consentAccept=true, optOut=true – zgoda wycofana.
Jeżeli kontakt posiada już status zgody „potwierdzona” lub „wycofana” – nie można go zmienić na status zgody „niepotwierdzona”.
| Pole | Max. długość | Opis |
|---|---|---|
| consentDetails | tablica obiektów | Tablica obiektów pozwalająca przesłać dodatkowe zgody wyrażone przez Kontakt. Każdy typ zgody musi zostać wcześniej zdefiniowany w SALESmanago Ustawienia ➔ Inne ➔ Lista zgód. |
| consentName | 255 | Nazwa zgody |
| consentAccept | true/false | Wartość logiczna zgody (true lub false) |
| agreementDate | UNIX timestamp [ms] | Data wyrażenia zgody. Jeśli jej nie prześlesz, jako data zgody zostanie przypisana domyślnie data bieżąca. |
| ip | 255 | Adres IP Kontaktu. |
| optOut | true/false | Wartość logiczna wycofania zgody (true lub false). |
| consentDescriptionId | true/false | Identyfikator opisu zgody. Znajdziesz go w SALESmanago Ustawienia ➔ Inne ➔ Lista zgód. |
Dodatkowe szczegóły Kontaktu
Są 3 sposoby na przesłanie dodatkowych danych kontaktowych, które możesz wykorzystać w Procesach Automatyzacji, personalizacji, segmentacji i innych funkcjach. Wzbogać swoje dane poprzez:
1. Tagi – najbardziej podstawowe dodatkowe informacje. Mają tylko wartości, więc możesz przypisać wiele tagów w obrębie tego samego obszaru, np. DOG_FOOD, CAT_FOOD.
2. Szczegóły standardowe – bardziej rozbudowany rodzaj informacji dodatkowych. Szczegóły standardowe to pary danych tekstowych składające się z kluczy i wartości, np. nazwa szczegółu: kierunek_podrozy, wartość: Bułgaria, lub nazwa detalu: marka_samochodu, wartość: TESLA. Zarówno klucz, jak i wartość mogą mieć długość do 255 znaków. Nie muszą być one predefiniowane w SALESmanago.
3. Szczegóły słownikowe – podobne do szczegółów standardowych. Są to pary złożone z kluczy i wartości, z obsługą wartości liczbowych i dat, np. nazwa detalu: data_slubu, wartość 1653861600000, (czyli 30.05.2022), lub nazwa detalu: rozmiar_koszuli, wartość: 42. Szczegóły słownikowe są definiowane systemowo, co oznacza, że jeśli zdefiniujesz szczegół słownikowy dla jednego kontaktu, to pole szczegółu zostanie utworzone dla wszystkich kontaktów. Listę szczegółów słownikowych można zobaczyć w SALESmanago Ustawienia ➔ Inne ➔ Szczegóły słownikowe.
| Pole | Max. długość | Opis |
|---|---|---|
| tags | 255/tag | Tablica tagów dla Kontaktu Tagi mogą zawierać standardowe znaki alfabetu łacińskiego oraz znaki podkreślenia. Jeśli przesyłane tagi zawierają nieobsługiwane znaki, zostaną one automatycznie dostosowane do formatu obsługiwanego przez system. Znaki specjalne zostaną zastąpione znakiem podkreślenia (_), a znaki diakrytyczne zostaną zastąpione ich odpowiednikiem w alfabecie łacińskim. |
| removeTags | 255/tag | Tablica tagów do usunięcia. Podanie tego samego tagu w obu tablicach spowoduje jego całkowite usunięcie. |
| properties | 255/szczegół | Tablica szczegółów standardowych podanych jako pary klucz-wartość. Nie zaleca się używania znaków specjalnych, znaków diakrytycznych i spacji w nazwach szczegółów. |
| dictionaryProperties | tablica obiektów | Tablica obiektów zawierająca definicje szczegółów słownikowych. Szczegóły słownikowe mogą zawierać wartości liczbowe lub daty. Jeśli określisz szczegół słownikowy dla jednego kontaktu, szczegół zostanie zdefiniowany dla wszystkich kontaktów. |
| name | 3-255 | Nazwa szczegółu. Nie zaleca się używania znaków specjalnych, znaków diakrytycznych i spacji w nazwach szczegółów. |
| type | enum NUMBER, DATE |
Typ szczegółu słownikowego: NUMBER lub DATE |
| value | 255 | Wartość szczegółu słownikowego. Dla typu NUMBER: Liczba całkowita większa od 0. Dla typu DATE: Wartość UNIX timestamp [ms]. |
Zaawansowane pola:
Pól zaawansowanych możesz użyć, aby zmienić adres e-mail lub stan Kontaktu, wysłać konkretny e-mail z potwierdzeniem subskrypcji lub zmienić sposób przetwarzania żądania.
| Pole | Max. długość | Opis |
|---|---|---|
| newEmail | 254[?] | Nowy adres e-mail (jeżeli ma zostać zmodyfikowany). Zmiana adresu e-mail kontaktu jest możliwa wyłącznie, jeśli kontakt zostanie zidentyfikowany za pomocą obecnego adresu e-mail. |
| async | true/false | Parametr określający sposób dodania Kontaktu do SALESmanago. Domyślną i zalecaną wartością jest „true”, której wybór zainicjuje wykonanie procesu asynchronicznie. Oznacza to, że wartość contactId otrzymasz natychmiast, podczas gdy dane Kontaktu będą aktualizowane z niewielkim opóźnieniem. Jeśli zdecydujesz się przetwarzać Kontakt synchronicznie, twoje żądanie może zająć więcej niż 1000 ms. |
| state | enum CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN |
Status Kontaktu (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN) |
| doubleOptInEmailId** | 255 | Opcjonalny identyfikator maila dla double opt-in |
W rezultacie zapytania otrzymasz:
| success - wartość logiczna informująca o rezultacie zapytania (udane/nieudane) | |
| contactId - unikatowy identyfikator Kontaktu. W większości przypadków ten identyfikator powinien zostać ustawiony w przeglądarce Kontaktu jako wartość ciasteczka smclient. | |
| message - tablica dodatkowych informacji zawierająca komunikaty błędów | |
| externalId - zewnętrzne ID Kontaktu | |
| Flaga useApiDoubleOptIn jest nadrzędna nad flagą forceOptIn. Użycie useApiDoubleOptIn wraz z forceOptIn spowoduje, że forceOptIn zostanie zignorowane. |
Asynchroniczne dodawanie lub modyfikacja wielu kontaktów na raz
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-",
"apiKey": "your-api-key-",
"requestTime": 1348046897664,
"sha": "shacode",
"owner": "admin@vendor.pl",
"upsertDetails": [
{
"newEmail": null,
"contact": {
"email": "batchtest2@benhauer.pl",
"name": "Konrad Test1",
"phone": "+48123321123",
"fax": "+48345543345",
"company": "Benhauer Sp. z o.o. Sp. K.",
"externalId": null,
"state": "PROSPECT",
"address": {
"streetAddress": "Brzyczyńska 123",
"zipCode": "43-305",
"city": "Bielsko-Biała",
"country": "PL"
}
},
"relation" : {
"type": "PARENT",
"email": "child@test.pl"
},
"tags": [
"API",
"ADmanago"
],
"removeTags": [
"Test_tag",
"New"
],
"properties": {
"custom.nickname": "Konri1",
"custom.sex": "M"
},
"dictionaryProperties": [
{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday": "19801017",
"province": "Małopolska",
"forceOptIn" : true,
"forceOptOut" : false,
"forcePhoneOptIn" : true,
"forcePhoneOptOut" : false
},
{
"contact": {
"email": "batchtest1@benhauer.pl",
"name": "Konrad Test2",
"phone": "+48123321123",
"fax": "+48345543345",
"company": "Benhauer Sp. z o.o. Sp. K.",
"externalId": null
},
"newEmail": "batchtestNew@benhauer.pl",
"forceOptIn": true,
"forceOptOut": false,
"forcePhoneOptIn": true,
"forcePhoneOptOut": false,
"tags": [
"API",
"ADmanago"
],
"properties": {
"custom.nickname": "Konri2",
"custom.sex": "M"
},
"consentDetails": [
{
"consentName": "ZGODA",
"consentAccept": true,
"agreementDate": 1391167515515,
"ip":"192.168.7.139",
"optOut": false,
"consentDescriptionId": 1
}
],
"birthday": "19801017"
}
],
"useApiDoubleOptIn": true,
"lang": "PL",
"fireEvents": false
}
Rezultat zapytania:
{
"success":true,
"message":["Batch upsert added to execute."],
"requestId":37
}
Przykładowy json ze statusem batchupserta:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 37
}
Przykładowa odpowiedź:
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Wiele kontaktów naraz dodajemy lub modyfikujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/batchupsertv2
W zapytaniu podajemy tablicę kontaktów w polu upsertDetails. Podstawowe elementy jakie można podać w elemencie tablicy contact można znaleźć powyżej w opisie metody upsert (patrz Dodawanie nowego lub modyfikacja istniejącego kontaktu).
Pola dostępne w zapytaniu metody batchupsertv2:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| upsertDetails* | 1000 | Tablica obiektów typu Kontakt |
| email* | 254[?] | email kontaktu, nowy gdy tworzymy kontakt, istniejący gdy modyfikujemy |
| name | 255 | nazwa kontaktu |
| phone | 255 | numer telefonu |
| fax | 255 | numer fax |
| company | 255 | firma kontaktu |
| state | CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN | status kontaktu |
| externalId | 255 | identyfikator zewnętrzny kontaktu |
| newEmail | 254[?] | nowy email kontaktu |
| birthday | yyyyMMdd/Mmdd | data urodzenia, przekazywana jako łańcuch znaków w postaci: yyyyMMdd lub Mmdd (yyyy – 4 cyfrowy rok, MM – dwucyfrowy miesiąc, dd – dwucyfrowy dzień) |
| province | 255 | województwo |
| streetAddress | 255 | ulica i numer domu |
| zipCode | 255 | kod pocztowy |
| city | 255 | miasto |
| country | 255 | kraj |
| forceOptOut | true/false | wymuszenie opt-out po dodaniu/modyfikacji |
| forceOptIn | true/false | wymuszenie opt-in po dodaniu/modyfikacji (o ile nie wybrano wcześniejszej opcji) |
| forcePhoneOptOut | true/false | wymuszenie opt-out z telefonu po dodaniu/modyfikacji |
| forcePhoneOptIn | true/false | wymuszenie opt-in na telefon po dodaniu/modyfikacji (o ile nie wybrano wcześniejszej opcji) |
| tags | 255/tag | tablica tagów kontaktu |
| removeTags | 255/tag | tablica tagów do usunięcia |
| properties | 255/detal | definiowane przez użytkownika atrybuty kontaktu. Zaleca się nie stosować polskich znaków oraz spacji w nazwie, ale jest to dozwolone. |
| dictionaryProperties | - | definiowane przez użytkownika atrybuty słownikowe, po pierwszym dodaniu danego atrybutu można go wykorzystać dla pozostałych kontaktów poprzez ponowne podanie takiej samej nazwy i typu z przypisaną inną wartością. |
| name | 255 | nazwa |
| type | NUMBER lub DATE | typ |
| value | - | liczba całkowita większa od 0, dla typu DATE timestamp, z godziną ustawioną na 00:00:00 czasu UTC |
| useApiDoubleOptIn | true/false | użycie opcji double opt in, domyślnie true |
| lang | 255 | język kontaktu |
| fireEvents | true/false | Jeśli metoda jest ustawiona jako „false” zapobiega uruchamianiu reguł i Workflow wywołanych zdarzeniami utworzonymi w czasie upsertu kontaktów (import z nadpisywaniem i modyfikacją istniejących kontaktów). |
Dla użytkowników z uprawnieniami do Contact relationship dodatkowo mamy dostępne pola:
| Pole | Max. długość | Opis |
|---|---|---|
| relation | - | tworzy relację z podanym kontaktem |
| type | CHILD lub PARENT | rodzaj relacji |
| 254[?] | email kontaktu z którym ma zostać stworzona relacja, podany kontakt musi już istnieć w systemie |
W odpowiedzi, w polu requestId, otrzymujemy identyfikator zadania po którym możemy monitorować jego postęp.
Aby sprawdzić status operacji należy wysłać żądanie na adres:
https://www.salesmanago.pl/api/job/status
W requeście przekazujemy identyfikator jak w przykładzie.
W odpowiedzi dostaniemy komunikat mówiący o postępie upserta lub link do pobrania pliku z informacjami o zaktualizowanych kontaktach.
Link jest ważny tylko przez kilka minut.
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane),
contactIds – tablica unikatowych identyfikatorów uaktualnionego lub nowo dodanego kontaktu,
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd,
invalidContacts – tablica niepoprawnych kontaktów
W przypadku nowych kontaktów pole „newEmail” zostanie zignorowane. Nowym kontaktom zostanie przypisany adres zgodny z danymi w polu: „email”.
Usuwanie wielu kontaktów na raz
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1348046897664,
"sha": "8d893f41dd479bb0489686f04b0a169005d22559",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "stage",
"value": "funnel1",
"optValue": "stage1,stage2"
},
{
"addresseeType": "email",
"value": "email1@test.pl, email2@test.pl"
}
]
}
Wiele kontaktów naraz usuwamy wywołując metodę:
https://www.salesmanago.pl/api/contact/batchDelete
Akcja wykonuje się synchronicznie, więc przy dużej liczbie kontaktów do usunięcia może zająć kilka sekund.
Pola dostępne w zapytaniu metody batchDelete:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contacts* | - | tablica kontaktów do usunięcia |
| addresseeType* | EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE, ID | typ adresowania |
| value* | 255 | adres e-mail kontaktu, jego identyfikator, tag, lejek |
| optValue | 255 | opcjonalnie dla typu STAGE podajemy po przecinku nazwy etapów w podanym wyżej lejku |
Rezultat zapytania:
{
"success":true,
"message":[],
"result": "Contacts deleted"
}
W odpowiedzi otrzymujemy status zapytania oraz w przypadku sukcesu listę identyfikatorów dla kontaktów dodanych:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane),
contactIds – tablica unikatowych identyfikatorów uaktualnionego lub nowo dodanego kontaktu,
result – rezultat zapytania
Usuwanie kontaktu
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"email" : "test@salesmanago.pl",
"owner" : "admin@vendor.pl"
}
Kontakt usuwamy wywołując metodę:
https://www.salesmanago.pl/api/contact/delete
Pola dostępne w zapytaniu metody delete:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| email* | 254[?] | e-mail kontaktu |
Rezultat zapytania:
{
"success": true,
"message": [],
"result": "Contact deleted"
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result – dodatkowe informacje mówiące o usunięciu kontaktu lub pozwalające zidentyfikować błąd
Sprawdzanie czy kontakt jest już zarejestrowany
Przykładowa struktura danych zapytania:
{
"clientId": "client-id",
"apiKey": "api-key-123",
"requestTime": 1481532212995,
"sha": "abcd509ac6867955a5333d6eb0c460455c74ccc6",
"email": "***@gmail.com",
"owner": "admin@vendor.pl"
}
Istnienie kontaktu w bazie sprawdzamy metodą:
https://www.salesmanago.pl/api/contact/hasContact
Pola dostępne w zapytaniu metody hasContact:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| email* | 254[?] | email szukanego kontaktu |
Rezultat zapytania:
{
"success": true,
"message": [],
"result": true,
"contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6"
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result - rezultat zapytania
contactId - id wyszukanego kontaktu
Eksport podstawowych danych kontaktów po adresie email
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481533177752,
"sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
"owner": "admin@vendor.pl",
"email": [
"piotr***@gmail.com"
]
}
Listę podstawowych danych kontaktów eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/basic
Pola dostępne w zapytaniu metody basic:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| email* | 254/email[?] | tablica adresów email eksportowanych kontaktów |
Rezultat zapytania:
{
"success": true,
"message": [],
"contacts": [
{
"name": "Piotr",
"email": "piotr****@gmail.com",
"phone": "500100100",
"fax": "",
"score": 1920,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Benhauer",
"externalId": null,
"address": {
"streetAddress": "Grzegórzecka 21",
"zipCode": "30-555",
"city": "Kraków",
"country": "Polska"
},
"contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
"birthdayYear": null,
"birthdayMonth": null,
"birthdayDay": null,
"modifiedOn": 1479215570000,
"createdOn": 1432887727000,
"lastVisit": 1481528930000
}
]
}
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
contacts – eksportowane kontakty
name – nazwa kontaktu
email – e-mail kontaktu
phone – numer telefonu
fax – numer fax kontaktu
score – liczba punktów
state – status kontaktu (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
optedOut – czy kontakt wycofał zgodę na otrzymywanie maili,
optedOutPhone - czy kontakt wycofał zgodę na kontakt telefoniczny
deleted – czy kontakt został usunięty
invalid – czy kontakt jest niepoprawny
company – nazwa firmy kontaktu
externalId – identyfikator zewnętrzny kontaktu
address – adres kontaktu
streetAddress – ulica i numer domu
zipCode – kod pocztowy
city – miasto
country – kraj
contactId - identyfikator kontaktu
birthdayYear – rok urodzenia kontaktu
birthdayMonth – miesiąc urodzenia kontaktu
birthdayDay – dzień urodzin
modifiedOn – data ostatniej modyfikacji kontaktu
createdOn – data stworzenia kontaktu,
lastVisit – data ostatniej wizyty kontaktu,
Eksport podstawowych danych kontaktów po ID kontaktu
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481535098734,
"sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
"owner": "admin@vendor.pl",
"id": [
"99cdc5fe-7376-436e-acb5-7180c97dadb6"
]
}
Listę podstawowych danych kontaktów eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/basicById
Pola dostępne w zapytaniu metody basicById:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| id* | 255/id | tablica identyfikatorów eksportowanych kontaktów |
Rezultat zapytania:
{
"success": true,
"message": [],
"contacts": [
{
"name": "Piotr",
"email": "piotr****@gmail.com",
"phone": "500100100",
"fax": "",
"score": 1920,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Benhauer",
"externalId": null,
"address": {
"streetAddress": "Grzegórzecka 21",
"zipCode": "30-555",
"city": "Kraków",
"country": "Polska"
},
"contactId": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
"birthdayYear": null,
"birthdayMonth": null,
"birthdayDay": null,
"modifiedOn": 1479215570000,
"createdOn": 1432887727000,
"lastVisit": 1481528930000
}
]
}
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
contacts – eksportowane kontakty
name – nazwa kontaktu
email – e-mail kontaktu
phone – numer telefonu
fax – numer fax kontaktu
score – liczba punktów
state – status kontaktu (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
optedOut – czy kontakt wycofał zgodę na otrzymywanie maili,
optedOutPhone - czy kontakt wycofał zgodę na kontakt telefoniczny
deleted – czy kontakt został usunięty
invalid – czy kontakt jest niepoprawny
company – nazwa firmy kontaktu
externalId – identyfikator zewnętrzny kontaktu
address – adres kontaktu
streetAddress – ulica i numer domu
zipCode – kod pocztowy
city – miasto
country – kraj
contactId - identyfikator kontaktu
birthdayYear – rok urodzenia kontaktu
birthdayMonth – miesiąc urodzenia kontaktu
birthdayDay – dzień urodzin
modifiedOn – data ostatniej modyfikacji kontaktu
createdOn – data stworzenia kontaktu,
lastVisit – data ostatniej wizyty kontaktu,
Eksport kontaktów po adresie e-mail dla danego właściciela
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"email" : [ "****@gmail.com" ],
"owner" : "admin@vendor.pl",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
Kontakty eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/list
Pola dostępne w zapytaniu metody list:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| email* | 254/email[?] | tablica adresów email eksportowanych kontaktów ( max 50 kontaktów na raz ) |
Rezultat zapytania:
{
"success": true,
"message": [],
"contacts": [
{
"id": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
"name": "Konrad",
"email": "your-contact-email@mail.com",
"phone": "123456789",
"fax": "987654321",
"score": 775,
"state": "PROSPECT",
"optedOut": true,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Benhauer",
"externalId": "externalId",
"address": {
"streetAddress": "Grzegórzecka 21",
"zipCode": "",
"city": "Kraków",
"country": "Polska"
},
"birthdayYear": 2000,
"birthdayMonth": 1,
"birthdayDay": 1,
"province": "Małopolska",
"mainContactOwner": "admin@vendor.pl",
"modifiedOn": 1479209074000,
"createdOn": 1432887727000,
"purchaseProbability": 0.3541016524943863,
"contactVisits": [
{
"conversationIntId": null,
"host": "10.10.10.10",
"time": 1328050810504,
"duration": null,
"visitSource": "NEXT",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": null,
"visitScore": 1,
"url": "/test.htm",
"location": null
}
],
"contactTags": [
{
"tag": "ADMANAGO",
"tagName": "ADMANAGO",
"score": 12,
"createdOn": 1432887757000,
"tagWithScore": "ADMANAGO (1)"
}
],
"contactEvents": [
{
"date": 1432887757000,
"description": "Note",
"detail1": null,
"detail2": null,
"detail3": null,
"detail4": null,
"detail5": null
}
],
"emailMessages": [
{
"name": "Email",
"subject": "Temat",
"date": 1479209121000,
"sent": false,
"dateSent": null,
"opened": false,
"dateOpened": null,
"clicked": false,
"dateClicked": null,
"emailConversation": 25584162,
"intId": null,
"deliveryStatus": null
}
],
"properties": [
{
"name": "detail",
"value": "detail-value"
}
],
"contactFunnels": [
{
"salesFunnel": "SalesFunnel 1",
"salesFunnelId": "5561397c-9792-4b60-aed1-a045b86c6b13",
"salesStage": "Stage",
"salesStageId": "de0cf594-b999-438a-b1f0-8578c36a8da5"
}
],
"contactNotes": [
{
"note": "Note",
"date": 1479208770000,
"priv": false
}
],
"contactTasks": [
{
"id": "395c5276-a40f-417c-bee8-1d6e80373adb",
"note": "Task",
"date": 1479250800000,
"cc": "",
"reminder": 1479249900000
}
],
"contactExtEvents": [
{
"eventId": "bd2fd558-29da-49b7-be31-6ee551cd5e13",
"date": 1433449419000,
"description": "Cart",
"products": "7,6",
"location": null,
"value": 57.69,
"contactExtEventType": "CART",
"shopDomain":"shop.salesmanago.pl",
"detail1": null,
"detail2": null,
"detail3": null,
"detail4": null,
"detail5": null,
"detail6": null,
"detail7": null,
"detail8": null,
"detail9": null,
"detail10": null,
"detail11": null,
"detail12": null,
"detail13": null,
"detail14": null,
"detail15": null,
"detail16": null,
"detail17": null,
"detail18": null,
"detail19": null,
"detail20": null,
"externalId": null
}
],
"coupons": [
{
"name": "Kupon",
"coupon": "SB173",
"validTo": 1480245622000,
"used": false
}
],
"smsMessages": [
{
"createdDate": 1479209040000,
"dateSent": 1479209971000,
"dateDelivered": null,
"deliveryStatus": null,
"dateReplied": null,
"replayMsg": null,
"content": "Test",
"sentBy": "admin@vendor.pl"
}
],
"consents": [
{
"name": "ZGODA_1",
"description": "Description1",
"ip": "0:0:0:0:0:0:0:1",
"action": "A",
"createdOn": 1546730871000,
"source": "F",
"dateOn": 1546730873000
},
{
"name": "ZGODA_2",
"description": "Description2",
"ip": "0:0:0:0:0:0:0:1",
"action": "D",
"createdOn": 1546730871000,
"source": "C",
"dateOn": 1546730873000
},
{
"name": "ZGODA_3",
"description": "Description3",
"ip": "0:0:0:0:0:0:0:1",
"action": "R",
"createdOn": 1546730871000,
"source": "CC",
"dateOn": 1546730873000
}
]
}
]
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
contacts – eksportowane kontakty
id – identyfikator kontaktu
name – imię kontaktu
email – e-mail kontaktu
phone – numer telefonu
fax – numer fax kontaktu
score – liczba punktów
state – status kontaktu (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
optedOut – czy kontakt wycofał zgodę na otrzymywanie maili,
optedOutPhone - czy kontakt wycofał zgodę na kontakt telefoniczny
deleted – czy kontakt został usunięty
invalid – czy kontakt jest niepoprawny
company – nazwa firmy kontaktu
externalId – identyfikator zewnętrzny kontaktu
address – adres kontaktu
streetAddress – ulica i numer domu
zipCode – kod pocztowy
city – miasto
country – kraj
birthdayYear – rok urodzenia kontaktu
birthdayMonth – miesiąc urodzenia kontaktu
birthdayDay – dzień urodzin
province - województwo
mainContactOwner – identyfikator głównego właściciela kontaktu
modifiedOn – data ostatniej modyfikacji kontaktu
createdOn – data stworzenia kontaktu,
purchaseProbability – wartość predykcji wystąpienia zakupu
contactVisits – lista wizyt kontaktu
conversationIntId – identyfikator mailingu z którego pochodzi wizyta
host - strona którą odwiedzał kontakt
time - data wizyty
duration - czas trwania
visitSource – źródło wizyty, możliwe wartości tego pola to:
EMAIL_CONVERSATION - wejście z maila (kliknięcie w link)
SEARCH_ENGINE - wejście z wyszukiwarki
ADVERTISEMENT - wejście z boksu reklamowego (AdWords)
REFERRER - wejście z witryny odsyłającej
DIRECT - wejście bezpośrednie, lub przejście na kolejną stronę
visitSourceHost - host odsyłający (refferer)
visitSourceKeywords - słowa kluczowe
visitScore – liczba punktów wizyty
url – adres odwiedzonej strony
location - lokalizacja
contactTags – tagi kontaktu
tag – tekst tagu
tagName – nazwa tagu
score – liczba punktów tagu
createdOn – data nadania tagu
tagWithScore – nazwa tagu wraz z liczbą punktów
contactEvents – wydarzenia
date – data wystąpienia wydarzenia
description – opis wydarzenia
detail1-5 – detale wydarzenia
emailMessages – e-maile z ostatnich 3 miesięcy
name – Nazwa wiadomości
subject – Temat wiadomości
date – data stworzenia
sent – czy wiadomość została wysłana
dateSent – data wysłania
opened – czy wiadomość została otwarta
dateOpened – data otwarcia wiadomości
clicked – czy wiadomość została kliknięta
dateClicked – data kliknięcia wiadomości
emailConversation – identyfikator konwersacji
deliveryStatus – status doręczenia
properties – szczegóły kontaktu
name – nazwa szczegółu
value – wartość szczegółu
contactFunnels – lejki sprzedażowe
salesFunnel – nazwa lejka
salesFunnelId – identyfikator lejka
salesStage – nazwa etapu lejka
salesStageId – identyfikator lejka
contactNotes - notatki
note – treść notatki
date – data utworzenia notatki
priv – czy wiadomość jest prywatna
contactTasks – zadania
id – identyfikator zadania
note – treść zadania
date – data utworzenia zadania
cc – mail na który ma zostać wysłana kopia przypomnienia
reminder – data przypomnienia o zadaniu
contactExtEvents – zdarzenia zewnętrzne
eventId – identyfikator zdarzenia,
date – data zdarzenia
description – opis zdarzenia
products – wartość kolumny produkty (np. identyfikatory)
location – lokalizacja
value – wartość zdarzenia
contactExtEventType – typ zdarzenia
shopDomain – domena sklepu
detail1-20 – detale zdarzenia (max 20)
externalId – zewnętrzny identyfikator zdarzenia.
coupons - kupony
name – nazwa kuponu
coupon – ciąg znaków kuponu
validTo – data ważności kuponu
used – czy kupon został użyty
smsMessages – wiadomości sms
createdDate – data stworzenia wiadomości
dateSent – data wysłania wiadomości
dateDelivered – data dostarczenia wiadomości
deliveryStatus – status dostarczenia
dateReplied – data otrzymania odpowiedzi
replayMsg – treść odpowiedzi
content – zawartość wiadomości
sentBy – e-mail osoby wysyłającej wiadomości
consents - zgody
name - nazwa zgody
description - opis zgody
ip - ip źródłowe, z którego została wykonana akcja na zgodzie
action - A - zaakceptowane zgody, D - usunięte zgody, R - odrzucone zgody
createdOn - data utworzenia
dateOn - data aktywowania zgody
source - źródło pochodzenia zgody - API - api, C - chat, F - formularz, CC - karta kontaktu
Eksport Kontaktów po ID Kontaktu
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"contactId" : ["ab12-...-cd34", "ef56-...-ab78"]
}
Aby wyeksportować Kontakty po ID Kontaktu, użyj następującej metody:
https://xxx.salesmanago.com/api/contact/listById
Pola dostępne w metodzie listById:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | Właściciel Kontaktów (e-mail konta użytkownika SALESmanago) |
| contactId* | 50*36 | Tablica identyfikatorów Kontaktów (UUID), które mają zostać wyeksportowane ( maksymalnie 50 identyfikatorów w jednym żądaniu ) |
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
contacts – tablica obiektów z danymi o Kontaktach
unavailableContacts – tablica ID Kontaktów, do których dany właściciel nie ma dostępu
Przykładowe żądanie:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"contactId" : ["ab12-...-cd34", "ef56-...-ab78"]
}
Przykładowa odpowiedź:
{
"success": true,
"message": [],
"contacts": [
{
"id": "ab12-...-cd34",
"name": "John Doe",
"email": "name@example.com",
"phone": "+15554443322",
"fax" : "+15551112233",
"score": 777,
"state": "PROSPECT",
"optedOut": true,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Acme Corporation",
"externalId": "U12345",
"address": {
"streetAddress": "Main Street",
"zipCode": "AB 00000",
"city": "Anytown",
"country": "United States"
},
"birthdayYear": 1987,
"birthdayMonth": 6,
"birthdayDay": 5,
"province": "California",
"mainContactOwner": "salesmanago.user@yourcompany.com",
"modifiedOn": 1659938888000,
"createdOn": 1459938888000,
"purchaseProbability": 0.314159265359,
"contactVisits": [
{
"conversationIntId": null,
"host": "192.168.1.1",
"time": 1659938888000,
"duration": null,
"visitSource": "NEXT",
"visitSourceHost": "example.com",
"visitSourceKeywords": null,
"visitScore": 1,
"url": "/example.html",
"location": null
}
],
"contactTags": [
{
"tag": "SWEATERS",
"tagName": "SWEATERS",
"score": 3,
"createdOn": 1459938888000,
"tagWithScore": "SWEATERS (3)"
}
],
"emailMessages": [
{
"name": "Special discount code",
"subject": "Special prize for you 🎁 Redeem before it's gone 😍",
"date": 1659938888000,
"sent": true,
"dateSent": 1659938888000,
"opened": true,
"dateOpened": 16599399999000,
"clicked": false,
"dateClicked": null,
"emailConversation": 123456,
"intId": null,
"deliveryStatus": null
}
],
"properties": [
{
"name": "sweater_size",
"value": "XL"
}
],
"contactFunnels": [
{
"salesFunnel": "Example funnel",
"salesFunnelId": "1234-...-5678",
"salesStage": "Example stage",
"salesStageId": "abcd-...-efab"
}
],
"contactNotes": [
{
"note": "Example note",
"date": 1659938888000,
"priv": false
}
],
"contactTasks": [
{
"id": "1234-...-5678",
"note": "Example task",
"date": 1659938888000,
"cc": "",
"reminder": 16599399999000
}
],
"contactExtEvents": [
{
"eventId": "ab12-...-cd34",
"date": 1659938888000,
"description": "https://example.com/cartRecovery/controller/cartId=1234-5678-9098",
"products": "p0123, p4567",
"location": "examplecom",
"value": 189.99,
"contactExtEventType": "PURCHASE",
"shopDomain":"example.com",
"detail1": "1,4,1",
"detail2": "189.99",
"detail3": "dresses",
"detail4": "black,black,white",
"detail5": null,
"detail6": null,
"detail7": null,
"detail8": null,
"detail9": null,
"detail10": null,
"detail11": null,
"detail12": null,
"detail13": null,
"detail14": null,
"detail15": null,
"detail16": null,
"detail17": null,
"detail18": null,
"detail19": null,
"detail20": null,
"externalId": "ID-123456"
}
],
"coupons": [
{
"name": "10% Voucher",
"coupon": "A1B2C3D4",
"validTo": 16599399999000,
"used": false
}
],
"smsMessages": [
{
"createdDate": 1659938888000,
"dateSent": 1659938888000,
"dateDelivered": 16599399999000,
"deliveryStatus": true,
"dateReplied": null,
"replayMsg": null,
"content": "Welcome to Example.com",
"sentBy": "salesmanago.user@yourcompany.com"
}
],
"consents": [
{
"name": "TERMS_OF_SERVICE",
"description": "I hereby accept TOS",
"ip": "192.168.0.1",
"action": "A",
"createdOn": 1659938888000,
"source": "F",
"dateOn": 1546730873000
},
{
"name": "PHYSICAL_MAIL",
"description": "I hereby consent to receive marketing materials by postal service",
"ip": "192.168.0.1",
"action": "D",
"createdOn": 1459938888000,
"source": "C",
"dateOn": 1659938888000
} ]
}
],
"unavailableContacts": ["ef56-...-ab78"]
}
Eksport danych o kontaktach
Przykładowy json:
{
"clientId": "yourcliendID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"dateRange": {
"startDate": 1652359692,
"endDate": 1652359694
},
"contacts" : [
{"addresseeType" : "tag", "value" : "TEST, TEST3"},
{"addresseeType" : "email", "value" : "test1@test.pl, test2@test.pl"},
{"addresseeType" : "stage", "value" : "funnel1", "optValue": "stage1"},
{"addresseeType" : "contact_id", "value" : "test123"}
],
"data": [
{"dataType" : "CONTACT"},
{"dataType" : "TAG"},
{"dataType" : "EXT_EVENT"},
{"dataType" : "VISITS"},
{"dataType" : "EMAILS"},
{"dataType" : "FUNNELS"},
{"dataType" : "NOTES"},
{"dataType" : "TASKS"},
{"dataType" : "COUPONS"},
{"dataType" : "SMS"},
{"dataType" : "CONSENTS"},
{"dataType" : "PROPERTIES"},
{"dataType" : "DICTIONARY_PROPERTIES"}
]
}
Przykładowa odpowiedź:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 37
}
Przykładowy json ze statusem eksportu:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 37
}
Przykładowa odpowiedź:
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/ye4vodnswfo6zp75/36m0iryqk4wlt6wu/1bau18werv4ixk0d.json?AWSAccessKeyId=AKIAJS5TR7Z2ERLL5DIQ&Expires=1510133411&Signature=YUm1NsYMenpTdl4MC9cxDk%2Ba2nA%3D"
}
Przykład struktury wyeksportowanych danych:
[
{
"5bb84002-08ae-11e7-a63d-28d24400c116": {
"contactData": {
"email": "test.test@onet.pl",
"id": "5bb84002-08ae-11e7-a63d-28d24400c116",
"createdOn": 1489493057000,
"modifiedOn": 1489493303000,
"name": null,
"score": null,
"fax": null,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"streetAddress": null,
"zipCode": null,
"city": null,
"country": null,
"birthday": null,
"province": null,
"mainOwner": null,
"lastOptInOn": 1634671777000,
"lastOptOutOn": 1634671197000
},
"tagData": [
{
"tagName": "TEST1",
"score": 1,
"createdOn": 1489493073000
},
{
"tagName": "LESZNO",
"score": 1,
"createdOn": 1489493317000
},
{
"tagName": "TEST3",
"score": 1,
"createdOn": 1489493316000
}
],
"extEventData": [
{
"eventId:": "dsakjl-fsdfsd-fsdfds-fsdf-awrew",
"date": 1523658987421,
"description": "description",
"products": "product1, product2, product3",
"location": "www.salesmanago.pl",
"value": "100.56",
"contactExtEventType": "CART",
"detail1": "online",
"detail2": null,
"detail3": null,
"externalId": "externalId"
}
],
"visitsData": [
{
"host": "salesmanago.pl",
"time": 1245874523658,
"duration": 200,
"visitSource": "www.salesmanago.pl",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": "salesmanago",
"visitScore": 10,
"url": "/cennik",
"location": "https://www.salesmanago.pl"
},
{
"host": "salesmanago.pl",
"time": 1245874523658,
"duration": 200,
"visitSource": "www.salesmanago.pl",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": "salesmanago",
"visitScore": 10,
"url": "/cennik",
"location": "https://www.salesmanago.pl"
}
],
"emailsData": [
{
"name": "#API: dyn",
"subject": "Sample API subject",
"date": 1497445747000,
"sent": false,
"dateSent": null,
"opened": false,
"dateOpened": null,
"clicked": false,
"dateClicked": null,
"emailConversation": null,
"deliveryStatus": null
}
],
"funnelsData": [
{
"salesFunnel": "lejek1",
"salesFunnelId": "fdshs-fdsfds-fdsfds-fdsfds",
"salesStage": "stage1",
"salesStageId": "iuyiuy-iuyiuy-iuyhvh-bvgbg"
}
],
"notesData": [
{
"note": "notatka dla kontatu",
"date": 1245854525698,
"priv": true
},
{
"note": "kupil produkt",
"date": 1245854525698,
"priv": false
}
],
"tasksData": [
{
"id": "ygfrg-fdfdf-fdfds-fsdfsd",
"note": "task dla kontaktu",
"date": 1452565898745,
"cc": "admin@vendor.pl",
"reminder": 1421524587456
}
],
"couponsData": [
{
"name": "coupon1",
"coupon": "couponCode",
"validTo": 1212452325658,
"used": false
}
],
"smsData": [
{
"createdDate": 1245214587452,
"dateSent": 1245214587452,
"dateDelivered": 1245214587452,
"deliveryStatus": "DELIVRD:00",
"dateReplied": null,
"replayMsg": null,
"content": "content",
"sentBy": null
}
],
"contactPropertiesData": [
{
"name": "t_shirt_size",
"value": "XL"
}
],
"contactDictionaryPropertiesData": [
{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "shoe_size",
"type": "NUMBER",
"value": 9
}
]
}
},
{
"5e428789-08ae-11e7-a63d-28d24400c116": {
"contactData": {
"email": "test2@o2.pl",
"id": "5e428789-08ae-11e7-a63d-28d24400c116",
"createdOn": 1489493057000,
"modifiedOn": 1489493303000,
"name": null,
"score": null,
"fax": null,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"streetAddress": null,
"zipCode": null,
"city": null,
"country": null,
"birthday": null,
"province": null,
"mainOwner": null,
"lastOptInOn": 1634671777000,
"lastOptOutOn": 1634671197000
},
"tagData": [
{
"tag": null,
"tagName": "TEST1",
"score": 1,
"createdOn": 1489493073000
},
{
"tag": null,
"tagName": "LESZNO",
"score": 1,
"createdOn": 1489493317000
},
{
"tag": null,
"tagName": "TEST2",
"score": 1,
"createdOn": 1489493316000
}
],
"extEventData": null,
"visitsData": null,
"emailsData": [
{
"name": "#API: dyn",
"subject": "Sample API subject",
"date": 1497445763000,
"sent": false,
"dateSent": null,
"opened": false,
"dateOpened": null,
"clicked": false,
"dateClicked": null,
"emailConversation": null,
"deliveryStatus": null
}
],
"funnelsData": null,
"notesData": null,
"tasksData": null,
"couponsData": null,
"smsData": null,
"consentsData": [
{
"name": "ZGODA_1",
"description": "Description1",
"ip": "0:0:0:0:0:0:0:1",
"action": "A",
"createdOn": "2018-10-22",
"source": "API",
"dateOn": "2018-10-22"
},
{
"name": "ZGODA_2",
"description": "Description2",
"ip": "0:0:0:0:0:0:0:1",
"action": "D",
"createdOn": "2018-10-22",
"source": "API",
"dateOn": "2018-10-22"
},
{
"name": "ZGODA_3",
"description": "Description3",
"ip": "0:0:0:0:0:0:0:1",
"action": "R",
"createdOn": "2018-10-22",
"source": "API",
"dateOn": "2018-10-22"
}
]
}
}
]
Metoda API ogranicza zakres eksportowanych danych do tych, które są określone w żądaniu. Do eksportu danych udostępniane są selectory, dzięki którym można sprecyzować grupę kontaktów dla której ma zostać wykonany eksport. Selectory działają na takiej samej zasadzie, jak w przypadku wysyłki e-mail. Dostępne selectory:
email - adres e-mail kontaktu,
tag - nazwa tagu w systemie przypisana do kontaktu lub do grupy kontaktów,
contact_id - zewnętrzny identyfikator kontaktu,
funnel - nazwa lejka sprzedażowego,
stage - nazwa etapu w lejku sprzedażowym (w tym przypadku należy określić nazwę lejka oraz nazwę etapu w którym
znajdują się kontakty),
externalId - zewnętrzne ID kontaktu.
Zakres danych jakie można eksportować:
CONTACT - obejmuje podstawowe dane o kontakcie takie jak nazwa kontaktu, adres e-mail, numer telefonu itp.),
TAG - lista przypisanych tagów dla kontaktu,
EXT_EVENT - lista zdarzeń zewnętrznych kontaktu (np. koszyk, zakup),
VISITS - lista stron odwiedzanych przez kontakt w ciągu ostatnich 7 dni,
EMAILS - lista wysłanych e-maili do kontaktu wraz z informacjami, czy kontakt je otworzył, kiedy to nastąpiło itp.
FUNNELS - lista lejków sprzedażowych, w których znajduje się kontakt,
NOTES - lista przypisanych notatek do kontaktu,
TASKS - lista zadań przypisanych do kontaktu,
COUPONS - lista kuponów,
SMS - lista wiadomości SMS do kontaktu wraz z informacjami.
CONSENTS - lista zgód (A - zaakceptowana, D - usunięta, R - odrzucona)
PROPERTIES - definiowane przez użytkownika atrybuty kontaktu. Zaleca się nie stosować polskich znaków oraz spacji w nazwie, ale jest to dozwolone.
DICTIONARY_PROPERTIES - definiowane przez użytkownika atrybuty słownikowe, po pierwszym dodaniu danego atrybutu można go wykorzystać dla pozostałych kontaktów poprzez ponowne podanie takiej samej nazwy i typu z przypisaną inną wartością.
Należy wybrać minimum jeden typ danych do eksportu (np. tag, contact, funnel). Typy nie są współzależne od siebie, a to
znaczy, że każdy typ można wyeksportować samodzielnie.
Eksport wykonywany jest do pliku w formacie json, do którego później udostępniany jest link.
Adres na który należy wysłać żądanie o wykonanie eksportu:
https://www.salesmanago.pl/api/contact/export/data
W parametrze “contacts” należy podać listę kontaktów, których dane chcemy wyeksportować.
W parametrze “data” należy podać listę typów danych, jakie chcemy wyeksportować.
W odpowiedzi otrzymujemy numer, po którym można monitorować status eksportu.
Parametr “requestId” jest naszym identyfikatorem eksportu.
Aby sprawdzić status eksportu należy wysłać żądanie na adres:
https://www.salesmanago.pl/api/job/status
Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.
W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.
Link jest ważny tylko przez kilka minut.
Eksport listy ostatnio stworzonych kontaktów
Przykładowa struktura danych zapytania:
{
"clientId": "h4jsu6pc5txybj04",
"apiKey": "qwetreryuii",
"requestTime": 1481531514145,
"sha": "abcd509ac6eb0c460455c74ccc66867955a5333d",
"owner": "admin@vendor.pl",
"from": 1478939514146,
"to": 1481531514132
}
Kontakty eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/createdContacts
Pola dostępne w zapytaniu metody createdContacts:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| from* | timestamp(ms) | początkowy zakres dat stworzenia |
| to* | timestamp(ms) | końcowy zakres dat stworzenia |
Rezultat zapytania:
{
"success": true,
"message": [],
"createdContacts": [
{
"id": "c3477890-3da7-4010-96d0-45aab0586b7f",
"email": "***@gmail.com"
}
]
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
createdContacts – kontakty zmodyfikowane w podanym przedziale czasu,
id – id kontaktu
email – email kontaktu
Eksport listy ostatnio zmodyfikowanych kontaktów
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime":1362056589362,
"sha":"64656d78b80d5df677700dabd363e1ffe51b59a7",
"owner":"admin@vendor.pl",
"from":1359673200361,
"to":1363042800362
}
Kontakty eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/modifiedContacts
Pola dostępne w zapytaniu metody modifiedContacts:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| from* | timestamp(ms) | początkowy zakres dat modyfikacji |
| to* | timestamp(ms) | końcowy zakres dat modyfikacji |
Rezultat zapytania:
{
"success":true,
"message":[],
"modifiedContacts":[
{
"id":"f66ca32b-c117-4b52-b3b8-863be077e710",
"email":"aleksander.***@benhauer.pl"
},
{
"id":"426e0ef8-675f-47fc-8ea8-745ac1706904",
"email":"konrad.***@salesmanago.pl"
},
{
"id":"1775d70e-cd61-4dd6-983a-64f067486adf",
"email":"marek.***@salesmanago.pl"
}
]
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
modifiedContacts – kontakty zmodyfikowane w podanym przedziale czasu,
id – id kontaktu
email – email kontaktu
Ostatnio zmodyfikowane Kontakty (lista stronicowana)
Ta metoda pozwala uzyskać listę Kontaktów, które po raz ostatni zostały zmodyfikowane we wskazanym okresie. Maksymalny przedział czasowy pomiędzy polami from i to wynosi 30 dni.
Przykładowe żądanie:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"from" : 1657267688000,
"to": 1659938888000,
"page" : 1,
"size" : 1000
}
Endpoint:
https://www.salesmanago.pl/api/contact/paginatedModifiedContacts
Pola dostępne w metodzie paginatedModifiedContacts:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | Właściciel Kontaktów (e-mail konta użytkownika SALESmanago) |
| from* | UNIX timestamp (ms) |
Zakres dat ostatniej modyfikacji, z którego mają zostać wylistowane Kontakty. Maksymalny zakres filtrowania wynosi 30 dni. |
| to* | UNIX timestamp (ms) | |
| page* | 1+ | Numer strony, zaczynając od 1, z której zostaną pobrane wyniki |
| size* | 1000 | Liczba wyników na stronie |
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
modifiedContacts – tablica z wynikami
contactId – unikatowy identyfikator Kontaktu
email – adres e-mail kontaktu.
Przykładowa odpowiedź:
{
"success": true,
"message": [],
"modifiedContacts": [
{
"id": "c100-...-298c",
"email": "name@example.com"
},
{
"id": "d256-...-4fe8",
"email": "name2@example.com"
}
],
"hasMore": true
}
Aktywność kontaktów
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"from":1328050800504,
"to":1333231200504,
"allVisits":true,
"ipDetails":true
}
Z SALESmanago możemy pobrać informacje o aktywności kontaktów w danym okresie. W tym celu wykonujemy metodę:
https://www.salesmanago.pl/api/contact/recentActivity
Pola dostępne w zapytaniu metody recentActivity:
| Pole | Max. długość | Opis |
|---|---|---|
| from* | timestamp(ms) | data początkowa (timestamp, czyli czas jaki upłynął w milisekundach od północy 1 stycznia 1970 UTC) |
| to* | timestamp(ms) | data końcowa (timestamp, czyli czas jaki upłynął w milisekundach od północy 1 stycznia 1970 UTC) |
| allVisits | true/false | w przypadku ustawienia na true SALESmanago zwróci w detalach odwiedzin informacje o wszystkich stronach otwartych przez klienta w wybranym okresie |
| ipDetails | true/false | w przypadku ustawienia na true SALESmanago zwróci w detalach odwiedzin informacje dodatkowe wyszukane dla IP klienta |
Rezultat zapytania:
{
"success":true,
"message":[],
"recentActivities": {
"from":1328050800504,
"to":1333231200504,
"monitoredContacts": 12300,
"totalContacts":234000,
"customers":[{
"uuid": 191615173,
"time":1330239675000,
"duration":22000,
"visitSource":"REFERRER",
"visitSourceHost":null,
"visitSourceKeywords":"localhost",
"visitSourceDetails":null,
"visitScore":120,
"client":"Benhauer Sp. z o.o. Sp. K. - Konrad Pawlus",
"email":"konradpawlus@gmail.com",
"contactId":"1d8cba47-f4b2-4efe-8250-5bdab5346628",
"url": "/test.htm",
"ipOrganization": "TP SA",
"vid": 7,
"cid": null,
"ipDetails": {
"ip" : "123.123.123.123",
"countryCode" : "PL",
"countryName" : "Poland",
"regionCode" : "77",
"regionName" : "Malopolskie",
"city" : "Cracow",
"postalCode" : "",
"latitude" : "50.083300",
"longitude" : "19.916700",
"isp" : "Neostrada Plus",
"organization" : "Neostrada Plus"
},
"contactVisits": [{
"conversationIntId": null,
"host": "10.10.10.10",
"time": 1328050810504,
"duration": null,
"visitSource": "NEXT",
"visitSourceHost": "salesmanago.pl",
"visitSourceKeywords": null,
"visitScore": 1,
"url": "/test.htm",
"location": null
}]}],
"partners":["... jw. ..."],
"prospects":["... jw. ..."],
"anonymous":["... jw. ..."],
"allVisits":["... jw. ..."],
"visitStats": [
{
"date": 1330239675000,
"partnersVisits": 123,
"prospectsVisits": 234,
"customersVisits": 456,
"otherVisits": 4321
}
]
}
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
recentActivity – struktura składająca się z trzech tablic wizyt: klientów (customers), partnerów (partners), potencjalnych klientów (prospects).
from – data początkowa
to – data końcowa
monitoredContacts – liczba monitorowanych kontaktów
totalContacts – liczba wszystkich kontaktów
customers – lista wizyt klientów
partners – lista wizyt partnerów
prospects – lista wizyt potencjalnych klientów
anonymous – lista wizyt anonimowych
allVisits – lista wszystkich wizyt
element wizyty klienta w listach:
time – czas wizyty
duration – czas trwania
visitSource – zasoby wizyty
visitSourceKeywords – słowa kluczowe
visitSourceHost – host
visitSourceDetails – detale wizyt
visitScore – liczba punktów
url – URL odwiedzonej strony
client – nazwa klienta
email – email klienta
contactId – unikatowy identyfikator klienta,
vid - ID sprzedawcy
cid - ID kontaktu
ipDetails – detale zdekodowane z IP klienta
ip – numer IP
countryCode – kod ISO kraju (2-znaki)
countryName – nazwa kraju
regionCode – kod regionu
regionName – nazwa regionu
city – miasto
postalCode – kod pocztowy
latitude – szerokość geograficzna
longitude – długość geograficzna
isp – nazwa ISP
organization – nazwa organizacji
contactVisits – wizyty kontaktu
conversationIntId – ID konwersji
host – strona która była odwiedzana
time – czas wizyty
duration – czas trwania
visitSource – zasoby wizyty
visitSourceKeywords – słowa kluczowe
visitSourceHost – host
visitScore – liczba punktów
url – URL odwiedzonej strony
location – lokalizacja wizyty
visitStats – statystyki wizyt z ostatniego tygodnia:
date – czas wizyty
partnersVisits – liczba wizyt partnerów
prospectsVisits – liczba wizyt potencjalnych klientów
customersVisits – liczba wizyt klientów
otherVisits – liczba innych wizyt
Eksport stronicowanej listy kontaktów
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "api-key-123",
"requestTime": 1481206581347,
"sha": "5333dabcd509455c74ccc6ac6eb0c4606867955a",
"owner": "admin@vendor.pl",
"page": 1,
"size": 100
}
Kontakty podzielone na części eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/paginatedContactList/export
Pola dostępne w zapytaniu metody paginatedContactListExport:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| page* | - | numer strony kontaków |
| size* | - | liczba kontaktów na jednej stronie (max 1000) |
Rezultat zapytania:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 37
}
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
requestId – identyfikator eksportu
Parametr “requestId” jest naszym identyfikatorem eksportu.
Aby sprawdzić status eksportu należy wysłać żądanie na adres: https://www.salesmanago.pl/api/job/status
Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.
W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.
Link jest ważny tylko przez kilka minut.
Przykładowa struktura danych zapytania /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Rezultat zapytania
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Kontakty przypisane do wskazanego właściciela
Przykładowe żądanie:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"page": 1,
"size": 1000
}
Ta metoda pozwala uzyskać listę Kontaktów, które są przypisane do właściciela określonego w polu owner.
Endpoint:
https://www.salesmanago.pl/api/contact/paginatedListById
Pola dostępne w metodzie paginatedListById:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | Właściciel Kontaktów (e-mail konta użytkownika SALESmanago) |
| page* | 1+ | Numer strony, zaczynając od 1, z której zostaną pobrane wyniki |
| size* | 1000 | Liczba wyników na stronie |
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
hasMore – wartość logiczna informująca, że dostępne są kolejne strony z wynikami zapytania
WAŻNE: Pozostałe pola zostały opisane w metodzie contact/list
Przykładowa odpowiedź:
{
"success": true,
"message": [],
"contacts": [
{
"id": "1a2b-...-3c4d",
"name": "John Doe",
"email": "name@example.com",
"phone": "+15554443322",
"fax": null,
"score": 123,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": "Big Company LLC",
"externalId": "U12345",
"address": {
"streetAddress": "Main Street 21",
"zipCode": "90210",
"city": "San José",
"country": "US"
},
"birthdayYear": 1987,
"birthdayMonth": 06,
"birthdayDay": 05,
"province": "California",
"mainContactOwner": "salesmanago.user@yourcompany.com",
"contactVisits": [],
"contactTags": [
{
"tag": "T_SHIRTS",
"tagName": "T_SHIRTS",
"score": 12,
"createdOn": 1659938888000,
"tagWithScore": "T_SHIRTS (12)"
}
],
"contactEvents": [],
"emailMessages": [],
"properties": [],
"contactFunnels": [],
"contactNotes": [],
"contactTasks": [],
"contactExtEvents": [],
"coupons": [],
"smsMessages": [],
"modifiedOn": 1559938888000,
"createdOn": 1459938888000
},
{
"id": "d256-...-4fe8",
"name": "Victoria Doe",
"email": "name2@example.com",
"phone": null,
"fax": null,
"score": 0,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"externalId": null,
"address": null,
"birthdayYear": "1985",
"birthdayMonth": "5",
"birthdayDay": "30",
"province": "",
"mainContactOwner": "salesmanago.user@yourcompany.com",
"contactVisits": [],
"contactTags": [],
"contactEvents": [],
"emailMessages": [],
"properties": [],
"contactFunnels": [],
"contactNotes": [],
"contactTasks": [],
"contactExtEvents": [],
"coupons": [],
"smsMessages": [],
"modifiedOn": 1549938888000,
"createdOn": 1449938888000
}
],
"hasMore": true
}
Zmiana głównego właściciela kontaktu
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": "1327056031488",
"sha": "2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
"contact": "contact@email.com",
"owner": "Owner@email.com",
"newOwner": "newOwner@email.com"
}
Nowego właściciela ustawiamy wywołując metodę:
https://www.salesmanago.pl/api/contact/setMainOwner
Pola dostępne w zapytaniu metody setMainOwner:
| Pole | Max. długość | Opis |
|---|---|---|
| contact* | 255 | adres e-mail kontaktu |
| owner* | 255 | właściciel kontaktu |
| newOwner* | 255 | nowy główny właściciel kontaktu (email konta użytkownika SALESmanago) |
Rezultat zapytania:
{
"success": true,
"message": []
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Zatrzymanie monitorowania kontaktów
Przykładowa struktura danych zapytania:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "12345trewq",
"async": false,
"requestTime": 1512720868000,
"sha": "36ec9c925975fa077aa39660386e41de3e25349a",
"owner": "admin@vendor.pl",
"contacts" : [
{"addresseeType" : "email", "value" : "test2@test.pl"}
]
}
W celu zatrzymania monitorowania kontaktów poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/contact/stopMonitoring
Pola dostępne w zapytaniu metody stopMonitoring:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contacts* | - | tablica kontaktów |
Rezultat zapytania
{
"success": true,
"message": [
"Contacts have stopped being monitored."
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Przywrócenie monitorowania kontaktów
Przykładowa struktura danych zapytania:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "12345trewq",
"async": false,
"requestTime": 1512720868000,
"sha": "36ec9c925975fa077aa39660386e41de3e25349a",
"owner": "admin@vendor.pl",
"contacts" : [
{"addresseeType" : "email", "value" : "test2@test.pl"}
]
}
W celu przywrócenia monitorowania kontaktów poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/contact/restoreMonitoring
Pola dostępne w zapytaniu metody restoreMonitoring:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contacts* | - | tablica kontaktów |
Rezultat zapytania
{
"success": true,
"message": [
"Contacts have restored being monitored."
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
API - Zdarzenia zewnętrzne
Dodawanie Zdarzenia Zewnętrznego
Przykładowe żądanie z podstawowymi danymi:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"email": "name@example.com",
"contactEvent": {
"date": 1659938888000,
"contactExtEventType": "PURCHASE",
"products": "p0123, p4567",
"value": 189.99,
"location": "examplecom"
}
}
Przykładowe żądanie z zaawansowanymi danymi:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"email": "name@example.com",
"contactEvent": {
"date": 1659938888000,
"contactExtEventType": "PURCHASE",
"products": "p0123, p4567",
"value": 189.99,
"location": "examplecom",
"externalId": "ID-123456",
"detail1": "1,4,1",
"detail2": "189.99",
"detail3": "dresses",
"detail4": "black,black,white",
"description": "https://example.com/cartRecovery/controller/cartId=1234-5678-9098"
}
}
Możesz dodać nowe Zdarzenie Zewnętrzne używając metody API:
https://www.salesmanago.pl/api/v2/contact/addContactExtEvent
Czym są Zdarzenia Zewnętrzne?
Zdarzenia Zewnętrzne (ang. External Events) reprezentują najważniejsze akcje wykonane przez Kontakt, takie jak zakup (PURCHASE) czy dodanie produktów do koszyka (CART). Zdarzenia Zewnętrzne możesz wykorzystać w celu tworzenia Procesów Automatyzacji oraz budowania statystyk transakcji i rekomendacji produktów.
Ważne: Zdarzenie Zewnętrzne może zostać przypisane wyłącznie do istniejącego Kontaktu. Jeżeli w momencie przesłania Zdarzenia Zewnętrznego metodą v2/contact/addContactExtEvent Kontakt nie istnieje w SALESmanago, system odczeka 5 minut i spróbuje dodać Zdarzenie Zewnętrzne ponownie. System będzie podejmować próby dodania Zdarzenia przez 1 godzinę. Jeśli po tym czasie Kontakt nadal nie będzie istniał w SALESmanago, Zdarzenie Zewnętrzne nie zostanie dodane.
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | Właściciel kontaktu (e-mail konta użytkownika SALESmanago) |
| email* | 254[?] | E-mail Kontaktu, dla którego dodawane jest Zdarzenie Zewnętrzne |
| contactId | UUID | Identyfikator Kontaktu z SALESmanago otrzymywany w odpowiedzi na każde żądanie z dodaniem lub aktualizacją Kontaktu. Jeśli identyfikujesz Kontakt używając contactId, pole email nie jest obowiązkowe. |
| date* | timestamp | Wartość UNIX timestamp [ms] |
| contactExtEventType* | enum | Typ Zdarzenia Zewnętrznego, np. PURCHASE, CART |
| products | 512 | Lista ID produktów oddzielonych przecinkami. Ważne: Identyfikatory produktów przesyłanych w Zdarzeniu powinny być zgodne z identyfikatorami produktów z Katalogu Produktowego / Feedu Produktowego XML |
| value | float (19.2) | Wartość Zdarzenia (np. kwota zakupu) |
| E-shop ID (location) | 36 | Identyfikator sklepu zgodny z polem location podanym podczas tworzenia Katalogu Produktowego / Feedu Produktowego XML. Pozwala na połączenie Zdarzenia Zewnętrznego i produktów z konkretnego sklepu (lub z konkretnej wersji językowej sklepu).
Pole location może zawierać maksymalnie 36 znaków (wyłącznie litery a-z, A-Z, cyfry 0-9, znak _). Wartość nie może zaczynać się od cyfry. Tip: Możesz użyć nazwy domeny bez kropki, np. examplecom (lub examplecom_ES dla konkretnej wersji językowej sklepu). |
| externalId | 255 | Dodatkowy identyfikator Zdarzenia Zewnętrznego, na przykład ID zamówienia z platformy eCommerce |
| detail1 | 20x255 | Szczegóły Zdarzenia Zewnętrznego, które możesz wykorzystać w Procesach Automatyzacji, w treści e-maili lub podczas eksportu danych przez API.
Przykłady wykorzystania: liczba zakupionych produktów, wartość lub kategoria najdroższego produktu, metoda płatności, metoda wysyłki, sposób pakowania |
| detail2 | ||
| detail… | ||
| description | 2048 | Pole przeznaczone do dowolnego wykorzystania, np. na uwagi do zamówienia, link z podsumowaniem zamówienia, link odzyskiwania koszyka |
Typy Zdarzeń Zewnętrznych
SALESmanago oferuje wiele typów Zdarzeń Zewnętrznych. Zdarzenia PURCHASE (zakup) oraz CART (dodanie do koszyka) są automatycznie brane pod uwagę w panelach analitycznych. Pozostałe typy Zdarzeń Zewnętrznych nie mają specjalnego zastosowania – możesz ich używać w celu przesłania dowolnej akcji wykonanej przez Kontakt.
Lista dostępnych Zdarzeń Zewnętrznych:
- PURCHASE
- CART
- TRANSACTION
- CANCELLATION
- RETURN
- VISIT
- PHONE_CALL
- OTHER
- RESERVATION
- CANCELLED
- ACTIVATION
- MEETING
- OFFER
- DOWNLOAD
- LOGIN
- SURVEY
Rezultat zapytania:
{
"success": true,
"message": [],
"eventId": "0e8c-...-9ba2c",
"contact": {
"email": "name@example.com",
"contactId": null,
"emailOrContactId": "name@example.com"
}
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
eventId – unikatowy identyfikator Zdarzenia Zewnętrznego. Możesz go wykorzystać do aktualizacji
Zdarzenia Zewnętrznego przy użyciu metody updateContactExtEvent (np. podczas dodania kolejnego produktu do koszyka)
contact – obiekt z podstawowymi informacjami o Kontakcie (adres e-mail lub contactId)
Dodawanie wielu zdarzeń zewnętrznych na raz
Przykładowa struktura zapytania dodająca zdarzenia:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"sha": "09b42a100849de3e4f7fad4f445eb47e833dba87",
"owner":"user@vendor.pl",
"events": [
{
"contactId":"001e720f-b2ab-4203-a25f-b089557cf0da",
"contactEvent":{
"date":356180568153,
"description":"Bought with \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Paid with card",
"detail3":null,
"externalId":"B-99999999",
"shopDomain":"shop.salesmanago.pl"
}
},
{
"email":"best.user@best.pl",
"contactEvent":{
"date":356180568153,
"description":"Bought with \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Paid with card",
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
},
{
"email":"best.user@best.pl",
"contactEvent":{
"date":356180568153,
"description":"Bought with \"Super Bonus\"",
"products":"p02, p03",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Paid with card",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}
]
}
W celu dodania wielu zdarzeń wykonujemy metodę:
https://www.salesmanago.pl/api/contact/batchAddContactExtEvent
Pola dostępne w zapytaniu metody batchAddContactExtEvent:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| events* | - | lista zdarzeń zewnętrznych (nie może być pusta oraz większa od 1000) |
Pojedynczy element listy zdarzeń zewnętrznych zawiera:
| Pole | Max. długość | Opis |
|---|---|---|
| email* | 254[?] | email kontaktu dla którego dodawane jest zdarzenie |
| contactId | 255 | identyfikator kontaktu dla którego dodawane jest zdarzenie (może być używane zamiennie z adresem email) |
| contactEvent* | - | obiekt zdarzenia zewnętrznego ( czytaj więcej - Dodawanie zdarzeń ) |
Rezultat zapytania:
{
"success": true,
"message": [],
"failedContacts": [],
"createdAmount": 10,
"failedAmount": 0
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
failedContacts – tablica kontaktów dla których dodanie zdarzenia nie powiodło się
createdAmount – liczba stworzonych zdarzeń
failedAmount – liczba zdarzeń których dodawanie zakończyło się błędem
Modyfikacja zdarzenia zewnętrznego (zalecana)
Przykładowa struktura zapytania modyfikująca zdarzenie:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"contactEvent":{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"date":1356180568153,
"description":"Zakup z kartą \"Super Bonus\"",
"products":"p01, p02",
"location":"Shop_ID",
"value":1234.43,
"contactExtEventType":"PURCHASE",
"detail1":"C.ID: *** *** 234",
"detail2":"Płatość kartą",
"detail3":null,
"externalId":"A-123123123",
"shopDomain":"shop.salesmanago.pl"
}
}
W celu zmodyfikowania zdarzenia wykonujemy metodę:
https://www.salesmanago.pl/api/v2/contact/updateContactExtEvent
Pola dostępne w zapytaniu metody updateContactExtEvent:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| eventId* | 255 | ID zdarzenia (zwrócone przez metodę dodającą) |
| date* | timestamp(ms) | data zdarzenia (timestamp, czyli czas jaki upłynął w milisekundach od północy 1 stycznia 1970 UTC), |
| description | 2048 | opis zdarzenia |
| products | 512 | opcjonalna lista ID produktów oddzielona przecinkami, pole ID powinno być spójne z polem externalId w feedzie produktowym |
| ID sklepu (location)* | 36 | unikalny identyfikator sklepu – identyfikator ten służy do połączenia informacji o produkcie przesyłanych w zdarzeniu zewnętrznym z konkretnym feedem produktowym. Może zawierać maksymalnie 36 znaków bez spacji (wartość może zawierać litery a-z, cyfry 1-9, /_-.). Unikalny identyfikator ma być dokładnie taki sam jak wartość pola location w przesyłanych zdarzeniach zewnętrznych z danego sklepu. WAŻNE: Jeżeli posiadasz wgrany tylko jeden feed produktowy, system automatycznie połączy przesyłane zdarzenia z feedem produktowym wgranym do systemu. Natomiast, gdy korzystasz z opcji multistore ważne jest zachowanie spójności w przesyłaniu zdarzeń zewnętrznych z unikalnym identyfikatorem. |
| value | (19 2) | opcjonalna wartość zdarzenia np. wydana kwota (max 19 cyfr + 2 po przecinku) |
| contactExtEventType* | 255 | typ zdarzenie, dopuszczalne wartości: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION |
| detail1-20 | 255/detal | opcjonalne detale zdarzenia, |
| externalId | 255 | opcjonalne ID zdarzenia np. ID z systemu kasowego itp., |
| shopDomain | - | domena sklepu |
Rezultat zapytania:
{
"eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
"message" : [ ],
"success" : true
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
eventId – ID zmodyfikowanego zdarzenia
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Usuwanie zdarzenia zewnętrznego
Możesz usunąć zdarzenia zewnętrzne używając metody API:
https://www.salesmanago.pl/api/v2/contact/deleteContactExtEvent
Przykładowa struktura danych zapytania:
Z wykorzystaniem eventId:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1645453269000,
"sha": "3e4ec39722326150aae60f41e038d1def4450f46",
"owner": "owner@example.com",
"eventId": "7284e317-3bb6-4505-afbe-55b9a101339a"
}
Z wykorzystaniem externalId:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1645453269000,
"sha": "3e4ec39722326150aae60f41e038d1def4450f46",
"owner": "owner@example.com",
"externalId": "A-123123123"
}
Rezultat zapytania:
{
"success": true,
"message": [],
"result": "Ext event has been scheduled to delete."
}
{
"success": false,
"message": ["No eventId/externalId specified"],
"result": null
}
Pola dostępne w zapytaniu metody deleteContactExtEvent:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | Właściciel kontaktu (e-mail konta użytkownika SALESmanago) |
| eventId** | 255 | ID zdarzenia (zwrócone przez metodę addContactExtEvent) |
| externalId** | 255 | Zewnętrzne ID zdarzenia |
** Musisz określić przynajmniej jedno z nich. Jeśli podasz oba, eventId będzie miał pierwszeństwo.
W wyniku zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result – informacja dodatkowa przy rezultacie success = true: (“Ext event has been scheduled to delete.”)
API - Zarządzanie kuponami
Użycie kuponu dla kontaktu
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"email" : "test@salesmanago.pl",
"coupon" : "SAMPLE-COUPON-123"
}
Kupon zniżkowy dla kontaktu można oznaczyć jako użyty wywołując metodę:
https://www.salesmanago.pl/api/contact/useContactCoupon
Pola dostępne w zapytaniu metody useContactCoupon:
| Pole | Max. długość | Opis |
|---|---|---|
| email* | 254[?] | email kontaktu |
| coupon* | 255 | nazwa kuponu |
Rezultat zapytania:
{
"success": true,
"message": [],
"result": null
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result - rezultat used/error informujący o rezultacie zapytania
Dodanie kuponu dla kontaktu
Przykładowa struktura danych zapytania:
{
"clientId": "client-id",
"apiKey": "api-key-123",
"requestTime": 1481528920123,
"sha": "abcd5460455c09ac6eb0c74cc333dc66867955a5",
"name": "Coupon123",
"email": "***@gmail.com",
"length": 7,
"valid": 1484207320124,
"coupon": "couponVal"
}
Kupon zniżkowy dla kontaktu można dodać wywołując metodę:
https://www.salesmanago.pl/api/contact/addContactCoupon
Pola dostępne w zapytaniu metody addContactCoupon:
| Pole | Max. długość | Opis |
|---|---|---|
| email* | 254[?] | email kontaktu |
| name* | 64 | nazwa kuponu |
| length** | - | długość kuponu w przypadku automatycznego generowania (wartość z zakresu 5-64) |
| valid | - | data ważności kuponu (timestamp w milisekundach), domyślnie jest to rok |
| coupon** | 32 | wartość kuponu w przypadku ręcznego wprowadzania (minimun 5 znaków) |
**Tylko jedno z tych pól jest wymagane.
Rezultat zapytania:
{
"success": true,
"message": [],
"result": null,
"coupon": "couponVal"
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result - rezultat zapytania
coupon - wartość stworzonego kuponu
API - Lejki
Dodawanie lejka
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"group": "funnel group",
"potValue": 4,
"stages" : [
{"name": "stage name", "order": 1},
{"name": "second stage name", "order": 2}
]
}
Dodajemy lejek wywołując metodę:
https://www.salesmanago.pl/api/funnel/add
Pola dostępne w zapytaniu metody add:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | - | mail użytkownika |
| funnel* | - | nazwa lejka |
| group | - | grupa lejka |
| potValue | - | domyślna wartość kontaktów |
| stages* | - | lista etapów lejka |
| name* | 255 | nazwa etapu lejka (min 3 znaki) |
| order* | - | kolejność etapu (min wartość 1, wartości kolejności powinny tworzyć ciąg 1,2,3…liczba etapów) |
Rezultat zapytania:
{
"success": true,
"message": [
"Funnel funnel_name was added."
]
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia importu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Dodawanie kontaktów do lejka
Przykładowa struktura danych zapytania:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "qwertgfdsa1234",
"requestTime": 1496399754907,
"sha": "07f7333f11745f30e1bd5adec2092d89ab2f00a7",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"stage": "stage name",
"potValue": 4,
"modify": true,
"contacts": [
{"addresseeType": "EMAIL",
"value": "test1@test.pl, test2@test.pl, test3@test.pl"
}
]
}
Dodajemy kontakt do lejka wywołując metodę:
https://www.salesmanago.pl/api/funnel/addContact
Pola dostępne w zapytaniu metody addContact:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | - | mail użytkownika |
| funnel* | - | nazwa lejka |
| stage* | - | nazwa etapu |
| potValue | - | wartosć kontaktów dodawanych |
| modify | - | (wartość logiczna) kontakt ma zostać oznaczony jako zmodyfikowany przy dodaniu do lejka domyślnie false |
| contacts* | - | adres e-mail kontaktu, jego identyfikator, tag lub lejek |
Rezultat zapytania:
{
"success":true,
"message":[],
"addedContacts": {
"07381ccd-8d0f-4458-89d9-58ed23634209": true,
"bd7bd136-3702-401c-8b4a-3a40dd7546d8": true,
"e4743be9-24ed-4d23-b032-b7c68f0a660b": true,
"e99d6439-2191-4c55-9116-12b9bc63fa93": true,
"5b45e6bc-72ea-45bc-8d61-985e9066bd3a": true
}
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia importu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Usuwanie lejka/etapu
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"stage": "stage name"
}
Lejek/etap usuwamy wywołując metodę:
https://www.salesmanago.pl/api/funnel/delete
Pola dostępne w zapytaniu metody delete:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | - | mail użytkownika |
| funnel* | - | nazwa lejka |
| stage | - | nazwa etapu |
stage - parametr opcjonalny - gdy pusty, metoda usuwa cały lejek, gdy uzupełniony usuwa wybrany etap w lejku
Rezultat zapytania:
{
"success": true,
"message": [
"Specified funnel stage will be deleted in a few seconds"
]
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia importu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Pobieranie liczby kontaktów w lejku/etapie
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42",
"owner": "owner@mail.com",
"funnel": "funnel_name",
"stage": "stage name"
}
Pobieramy liczbę kontaktów wywołując metodę:
https://www.salesmanago.pl/api/funnel/count
Pola dostępne w zapytaniu metody count:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | - | mail użytkownika |
| funnel* | - | nazwa lejka |
| stage | - | nazwa etapu |
stage - parametr opcjonalny - gdy pusty, metoda zwraca liczbę kontaktów w całym lejku, gdy uzupełniony zwraca liczbę w wybranym etapie
Rezultat zapytania:
{
"success": true,
"message": [],
"count": 123
}
W rezultacie zapytania otrzymujemy:
success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
count – liczba kontaktów w lejku/etapie
API - Zarządzanie tagami
Eksport listy tagów
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"showSystemTags" : true,
"owner" : "admin@vendor.pl",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
Tagi eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/tags
Pola dostępne w zapytaniu metody tags:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| showSystemTags* | true/false | przy ustawieniach na true SALESmanago zwróci również tagi systemowe |
Rezultat zapytania
{
"tags" : [ { "tag" : "ADmanago",
"numberOfTagged" : 12
} ],
"message" : [ ],
"success" : true
}
W rezultacie zapytania otrzymujemy:
tags – eksportowane tagi
tag – nazwa tagu
numberOfTagged – liczba otagowanych kontaktów
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
API - Wiadomości email
Eksport globalnych statystyk wysłanych e-maili
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-123",
"apiKey": "your-api-key-123",
"requestTime": 1645453269000,
"sha": "3e4ec39722326150aae60f41e038d1def4450f46",
"user": "owner@example.com",
"from": 1631271157000,
"to": 1645453270000,
"conversationType": "MAILING"
}
Możesz eksportować globalne statystyki e-mail metodą API:
https://www.salesmanago.pl/api/email/globalConversationStatistics
Pola dostępne w zapytaniu metody apiGlobalConversationStatistics:
| Pole | Max. długość | Opis |
|---|---|---|
| from* | 255 | data początkowa zakresu eksportu – data w formacie UNIX timestamp [ms] |
| to* | 255 | data końcowa zakresu eksportu – data w formacie UNIX timestamp [ms] |
| conversationType | enum: SMTP, AD_HOC, MAILING, RULE, W, API, TEST_AB, FINAL_TEST_AB, BIRTHDAY, CYCLIC, SCHEDULED, BRITHDAY_YT, TEST | Typ e-maili, którego statystyki mają zostać wyeksportowane. Jeśli typ nie zostanie podany, wyeksportowane zostaną statystyki wszystkich typów. |
Dostępne typy e-maili masowych:
- MAILING
- TEST_AB
- FINAL_TEST_AB
- BIRTHDAY
- BIRTHDAY_YR
- CYCLIC
- SCHEDULED
Rezultat zapytania:
{
"success": true,
"message": [],
"from": 1631271157000,
"to": 1645453270000,
"sent": 32997135,
"opened": 4115080,
"clicked": 874927,
"openedUnique": 2683298,
"clickedUnique": 471739,
"softBounce": 647244,
"hardBounce": 30128,
"resigned": 6868
}
W wyniku zapytania otrzymasz:
success – status zakończenia eksportu
message – tablica dodatkowych informacji, która pozwala zidentyfikować błąd
from – data początkowa
to – data końcowa
oraz dane statystyczne ze wskazanego zakresu i typu:
sent – liczba wysłanych e-maili
opened – liczba otwartych e-maili
clicked – liczba klikniętych e-maili
openedUnique – liczba unikalnych otwarć
clickedUnique – liczba unikalnych kliknięć
softBounce – liczba miękkich zwrotek
hardBounce – liczba twardych zwrotek
Dowiedz się czym są miękkie i twarde zwrotki >>
resigned – liczba kontaktów, które wypisały się z newslettera, korzystając z linku w stopce
Dodawanie lub aktualizacja e-maila
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"requestTime": 1481535098734,
"sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
"emailId": "1234-...-abcd",
"emailOwner": "user@example.com",
"name": "Special discount code",
"utmCampaign": "Spring/summer campaign",
"subject": "Special prize for you 🎁 Redeem before it's gone 😍",
"senderAccountId": "6789-...-efgh",
"content": "<html><body>...$opt-out$...</body></html>",
"shared": false
}
W celu dodania lub aktualizacji e-maila należy skorzystać z metody:
https://xxx.salesmanago.com/api/email/upsert
Pola dostępne w zapytaniu metody email/upsert::
| Pole | Max. długość | Opis |
|---|---|---|
| emailId | UUID | Identyfikator e-maila używany podczas aktualizacji już istniejącego e-maila |
| emailOwner* | 255 | Użytkownik SALESmanago, do którego ma zostać przypisany tworzony e-mail. Nie możesz zmienić właściciel e-maila podczas aktualizacji. |
| name* | 255 | Nazwa e-maila widoczna w SALESmanago |
| group | 255 | Nazwa grupy do której zostanie przypisany e-mail. Jeśli zostawisz to pole puste, email zostanie przypisany do domyślnej grupy. |
| subject* | 998 | Temat e-maila. Możesz użyć znaków UTF-8. |
| senderAccountId* | UUID | Identyfikator konta wysyłkowego SALESmanago. Tę wartość znajdziesz w SALESmanago ➔ Ustawienia ➔ Konta E-mail. |
| content* | 2 MB | Treść HTML wiadomości e-mail. |
| shared | bool | Flaga, która pozwala ci udostępnić e-maila innym użytkownikom przypisanym do tego samego konta SALESmanago. Domyślną wartością jest false. |
| utmCampaign | 255 | Parametr utm_campaign do śledzenia kampanii np. przy użyciu Google Analytics |
Rezultat zapytania:
{
"message": [],
"success": true,
"emailId": "1234-...-abcd"
}
W rezultacie zapytania otrzymasz:
emailId – Identyfikator e-maila przy pomocy którego możesz aktualizować jego zawartość.
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
Wysyłanie wiadomości email (zalecana)
Przykładowa struktura danych zapytania:
{
"clientId": "ye4vodnswfo6zp75",
"apiKey": "qwertgfdsa1234",
"requestTime": 1496399754907,
"sha": "02d89ab2f7333f11745f30e100a7fbd5adec2097",
"user": "admin@vendor.pl",
"emailId": "emailid",
"date": 1234562541250,
"html": "<html> <body> text $opt-out$ </body> </html>",
"campaign": "nazwa kampani",
"subject": "temat mojej wiaodmości",
"contacts": [
{
"addresseeType": "EMAIL",
"value": "test1@test.pl, test2@test.pl, test3@test.pl",
"properties": [
{
"name": "name",
"value": "value"
},
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "CONTACT_ID",
"value": "contact-id-1, contact-id-2, contact-id-3, contact-id-3"
},
{
"addresseeType": "TAG",
"value": "tag1, tag2",
"properties": [
{
"name": "name",
"value": "value"
},
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "FUNNEL",
"value": "funnel-name-1, funnel-nam-2",
"properties": [
{
"name": "name",
"value": "value"
},
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "STAGE",
"value": "funnel-name",
"optValue": "stage-name-1, stage-name-2"
}
],
"excludeContacts": [
{
"addresseeType": "EMAIL",
"value": "test5@test.pl, test6@test.pl, test8@test.pl",
"properties": [
{
"name": "name",
"value": "value"
}
]
},
{
"addresseeType": "TAG",
"value": "exclude-tag-1",
"properties": []
}
]
}
W celu wysłania maila poprzez API należy skorzystać z nowej metody:
https://www.salesmanago.pl/api/email/sendEmail
Pola dostępne w zapytaniu metody sendEmail:
| Pole | Max. długość | Opis |
|---|---|---|
| user* | 255 | adres email użytkownika Salesmanago |
| emailId* | 255 | identyfikator wiadomości z systemu SALESmanago |
| date* | timestamp(ms) | data wysyłki |
| html | - | zawartość maila w formacie HTML (jeżeli nie podana – zostanie użyta domyślna). Wymagane jest użycie linku opt-out ($opt-out$) |
| campaign | 255 | kampania dla śledzenia Google UTM (jeżeli nie podana – zostanie użyta domyślna) |
| subject | 2048 | temat wysyłki (jeżeli nie podany – zostanie użyty domyślny) |
| contacts* | - | tablica kontaktów, do których zostanie wysłany email |
| addresseeType* | 255 | typ adresowania ( EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE) |
| value* | 255 | opcjonalnie – adres e-mail kontaktu, jego identyfikator, tag lub lejek |
| optValue | 255 | opcjonalnie dla typu STAGE podajemy po przecinku nazwy etapów w podanym wyżej lejku do których adresujemy wysyłke |
| properties | 255 | definiowane przez użytkownika atrybuty dodatkowe wiadomości e-mail. Zaleca się nie stosować znaków diakrytycznych oraz spacji w nazwie, ale jest to dozwolone. W wiadomości e-mail należy użyć konstrukcji $cst.nazwaParametru$ w celu podstawienia odpowiedniej wartości |
| excludeContacts | - | tablica kontaktów, które będą wykluczone z wysyłki |
Rezultat zapytania
{
"success": true,
"message": [
"Emails are scheduling to send."
],
"conversationId": "conversation-id"
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationId - identyfikator mailingu
Wysyłanie potwierdzenia subskrypcji
Przykładowe żądanie z użyciem języka e-maila:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"email": "name@example.com",
"tag": "CSV_IMPORT",
"doubleOptInLanguage": "ES"
}
Przykładowe żądanie z użyciem ID e-maila:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"email": "name@example.com",
"tag": "CSV_IMPORT",
"doubleOptInEmailId": "6d5c-...-0102"
}
Przykładowa odpowiedź:
{
"success": true,
"message": ["Contact exists - confirmation email sent"],
"contactExists": true,
"contactId": "1a2b-...-3c4d"
}
Ta metoda umożliwia wysłanie e-maila z potwierdzeniem subskrypcji, czyli double opt-in, do istniejących Kontaktów o statusie opt-out. Możesz również określić dodatkowy parametr tag, aby wysłać potwierdzenie tylko do Kontaktów oznaczonych tym tagiem.
Endpoint:
https://www.salesmanago.pl/api/email/sendConfirmation
Pola dostępne w zapytaniu metody sendConfirmation:
| Pole | Max. długość | Opis |
|---|---|---|
| email* | 254[?] | Adres e-mail Kontaktu |
| owner* | 255 | Właściciel Kontaktu (e-mail konta użytkownika SALESmanago) |
| tag | 255 | Opcjonalny parametr definiujący tag, który musi posiadać Kontakt, aby został do niego wysłany e-mail z potwierdzeniem subskrypcji |
| doubleOptInLanguage | 255 | E-mail z potwierdzeniem subskrypcji, wskazany poprzez jedną z poniższych opcji: - język, zgodnie z mapowaniem w SALESmanago ➔ Ustawienia ➔ Inne ➔ Aplikacja ➔ API, - ID e-maila, które znajdziesz w adresie URL podczas edycji e-maila z potwierdzeniem subskrypcji |
| doubleOptInEmailId | 255 |
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
contactExists – wartość logiczna informująca, czy dany Kontakt istnieje w SALESmanago
contactId – ID Kontaktu, które możesz wykorzystać, aby móc później zidentyfikować Kontakt
Wysyłanie wiadomości email z załącznikiem
Przykładowa struktura danych zapytania:
POST /api/email/sendWithAttachment HTTP/1.1
HOST: dev.salesmanago.pl
content-type: multipart/form-data; boundary=----WebKitFormBoundary1aTYxdL1yD9GkrBw
accept: application/json, application/*+json
cookie: JSESSIONID=B79601649C8C221E3024EF909FD27A51; SERVERID=A
content-length: 81854
------WebKitFormBoundary1aTYxdL1yD9GkrBw
Content-Disposition: form-data; name="attachment"; filename="poster.gif"
Content-Type: image/gif
<-- zawartość pliku -->
------WebKitFormBoundary1aTYxdL1yD9GkrBw
Content-Disposition: form-data; name="emailSendRequest"
{
"clientId": "r60ta7pkk1cqh1iy",
"apiKey": "sdfsfsfsdf",
"requestTime": 1391167514795,
"sha": "229c9b4e06d6742330d7fe7c6882469bcac90686",
"user": "test@test.com",
"emailId": "1ece2b0d-9061-4295-9ad4-34ab82fa852e",
"html" : "<html><body>email-html-content</body></html>",
"contacts": [
{
"addresseeType" : "EMAIL",
"email": "test@test.com",
"contactId": null,
"tag" : null,
"properties": [
{ "name": "ext_detal_01", "value": "value_01" }
,
{ "name": "ext_detal_02", "value": "value_02" }
]
},
{
"addresseeType" : "EMAIL",
"email": "test.stepniak+1@gmail.com",
"contactId": null,
"tag" : null,
"properties": [
{ "name": "ext_detal_03", "value": "value_03" }
,
{ "name": "ext_detal_04", "value": "value_04" }
]
}
],
"excludeContacts": [
{
"addresseeType" : "EMAIL",
"email": "user3@example.com",
"contactId": null,
"tag" : null,
"properties": []
}
],
"date": 1391167515515,
"subject": "Sample API subject",
"campaign": "monitor_me_in_ga",
"immediate" : false,
"rule" : false
}
W celu wysłania maila z załącznikiem poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/email/sendWithAttachment
Pola dostępne w zapytaniu metody sendWithAttachment:
| Pole | Max. długość | Opis |
|---|---|---|
| user* | 255 | adres email użytkownika Salesmanago |
| emailId* | 255 | identyfikator wiadomości z systemu SALESmanago |
| date* | timestamp(ms) | data wysyłki |
| subject | 2048 | temat wysyłki (jeżeli nie podany – zostanie użyty domyślny) |
| campaign | 255 | kampania dla śledzenia Google UTM (jeżeli nie podana – zostanie użyta domyślna) |
| html | - | zawartość maila w formacie HTML (jeżeli nie podana – zostanie użyta domyślna) |
| contacts* | - | tablica kontaktów, do których zostanie wysłany email |
| addresseeType* | 255 | typ adresowania ( EMAIL, CONTACT_ID, TAGS) |
| email/contactId/tag* | 254[?] | opcjonalnie – adres e-mail kontaktu, jego identyfikator lub tag |
| properties | 255 | definiowane przez użytkownika atrybuty dodatkowe wiadomości e-mail. Zaleca się nie stosować znaków diakrytycznych oraz spacji w nazwie, ale jest to dozwolone. W wiadomości e-mail należy użyć konstrukcji $cst.nazwaParametru$ w celu podstawienia odpowiedniej wartości |
| excludeContacts | - | tablica kontaktów, które będą wykluczone z wysyłki |
| immediate | true/false | przypisanie wartości true spowoduje natychmiastowe wysłanie wiadomości e-mail |
| rule | true/false | przypisanie wartości true spowoduje oznaczenie wiadomości jako e-mail z reguły |
| attachment* | - | załączony plik |
Rezultat zapytania
{
"success": true,
"message": ["Emails are scheduled to send."],
"conversationId":"6bd61df3-44f3-825c-8c18-3d7813fea03b"
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationId – identyfikator mailingu
Pobieranie masowych konwersacji email
Przykładowa struktura danych zapytania:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1485520055,
"sha":"11fbaf0ad77f1491979594f58ba10565b30926",
"from":1491965421341,
"to":1491979590565
}
W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/email/massConversationList
Pola dostępne w zapytaniu metody massConversationList:
| Pole | Max. długość | Opis |
|---|---|---|
| from* | timestamp(ms) | początek zakresu dat stworzenia konwersacji email |
| to* | timestamp(ms) | koniec zakresu dat stworzenia konwersacji email |
Rezultat zapytania
{
"success": true,
"message": [],
"conversationList": [
"86dfe8bd-f21d-4f5e-9f53-19c929877d3c",
"5c27d476-282d-4235-9393-300d359b2d51"
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationList - lista identyfikatorów masowych konwersacji email
Statystyki wysłanych e-maili
Przykładowe żądanie z conversationId:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"user": "salesmanago.user@yourcompany.com",
"conversationId": "a254-...-5ed9"
}
Przykładowe żądanie z zakresem czasu:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"user": "salesmanago.user@yourcompany.com",
"from": "1649938888000",
"to": "1659938888000",
"requestType": "MAILING",
"exportType": "FULL"
}
Możesz pobrać statystyki wysłanych e-maili używając metody API:
https://www.salesmanago.com/api/email/conversationStatistics
Pola dostępne w metodzie conversationStatistics:
| Pole | Max. długość | Opis |
|---|---|---|
| user* | 255 | Adres e-mail użytkownika SALESmanago. Statystyki zostaną pobrane tylko dla e-maili, których autorem jest wskazany użytkownik. |
| conversationId | 255 | Identyfikator konwersacji, widoczny w URL analityki e-maila. Ważne: jeśli to pole jest obecne, pola from, to i conversationType są ignorowane. |
| from | timestamp(ms) | Data rozpoczęcia zakresu eksportu – data w formacie UNIX timestamp [ms]. Ważne: to pole jest wymagane, jeśli pole conversationId nie zostało podane. |
| to | timestamp(ms) | Data zakończenia zakresu eksportu – data w formacie UNIX timestamp [ms]. Ważne: to pole jest wymagane, jeśli pole conversationId nie zostało podane. |
| conversationType | 255 | Typ e-maili:
|
| exportType | 255 | Zakres eksportu:
|
Rezultat zapytania:
{
"success": true,
"message": [],
"requestId": 123456
}
Metoda do pobrania URL pliku:
/api/job/status
Zobacz dokumentację >>Przykładowa struktura pliku dla exportType BASIC i podanym conversationId:
{
"conversationId": "a254-...-5ed9",
"name": "Sample conversation name",
"subject": "Sample conversation subject",
"dateSent": 1609938888000,
"sentBy": "salesmanago.user@yourcompany.com",
"sentMessage": 1000,
"openedMessage": 800,
"uniqueOpens": 500,
"clickedMessage": 300,
"uniqueClicks": 200,
"errorMessage": 0,
"softBounce": 10,
"hardBounce": 20,
"resigned": 0,
"testAB": false,
"message": []
}
Przykładowa struktura pliku dla exportType SHORT i podanym conversationId:
{
"conversationId": "a254b80b-fac2-4401-b0a1-6eda1bf45ed9",
"name": "Your conversation name",
"subject": "Your conversation subject",
"dateSent": 1668755462468,
"sentBy": "name@example.com",
"sentMessage": 100,
"openedMessage": 120,
"uniqueOpens": 50,
"clickedMessage": 30,
"uniqueClicks": 20,
"errorMessage": 0,
"softBounce": 10,
"hardBounce": 10,
"resigned": 0,
"testAB": false,
"contacts": [
"contact1@example.com",
"contact2@example.com"
]
}
Przykładowa struktura pliku dla exportType FULL i podanym conversationId:
{
"conversationId": "a254-...-5ed9",
"name": "Sample conversation name",
"subject": "Sample conversation subject",
"dateSent": 1609938888000,
"sentBy": "salesmanago.user@yourcompany.com",
"sentMessage": 1000,
"openedMessage": 800,
"uniqueOpens": 500,
"clickedMessage": 300,
"uniqueClicks": 200,
"errorMessage": 0,
"softBounce": 10,
"hardBounce": 20,
"resigned": 0,
"testAB": false,
"openedBy": [
{
"email": "name1@example.com",
"contactId": "f35c-...-684e",
"dateOpened": 1659938888000,
"dateClicked": 1659938899000,
"optedOut": false
}
],
"clickedBy": [
{
"email": "name1@example.com",
"contactId": "f35c-...-684e",
"dateOpened": 1659938888000,
"dateClicked": 1659938899000,
"optedOut": false
}
],
"softBouncedBy": [
"nam2@example.com"
],
"hardBouncedBy": [
"nam3@example.com"
],
"resignedBy": [
{
"email": "name4@example.com",
"contactId": "a123-...-54bc",
"dateOpened": 1659937777000,
"dateClicked": 1659937788000,
"optedOut": true
}
]
}
Przykładowa struktura pliku dla exportType BASIC i podanym zakresem czasowym:
[
{
"conversationId": "a254-...-5ed9",
"name": "Sample conversation name",
"subject": "Sample conversation subject",
"dateSent": 1609938888000,
"sentBy": "salesmanago.user@yourcompany.com",
"sentMessage": 1000,
"openedMessage": 800,
"uniqueOpens": 500,
"clickedMessage": 300,
"uniqueClicks": 200,
"errorMessage": 0,
"softBounce": 10,
"hardBounce": 20,
"resigned": 0,
"testAB": false
},
{
"conversationId": "a254-...-5ed9",
"name": "Another conversation name",
"subject": "Another conversation subject",
"dateSent": 1619938888000,
"sentBy": "salesmanago.user@yourcompany.com",
"sentMessage": 2000,
"openedMessage": 1600,
"uniqueOpens": 1000,
"clickedMessage": 600,
"uniqueClicks": 400,
"errorMessage": 0,
"softBounce": 20,
"hardBounce": 40,
"resigned": 0,
"testAB": false
}
]
Plik wynikowy eksportu zawiera:
message—tablica dodatkowych informacji zawierająca komunikaty błędów
Pola obecne dla typu eksportu BASIC:
conversationId—identyfikator konwersacji
name—nazwa e-maila
subject—temat e-maila
dateSent—UNIX timestamp [ms]
sentBy—konto wysyłkowe
sentMessage—liczba wysłanych wiadomości e-mail
openedMessage—liczba wiadomości, które zostały otwarte.
uniqueOpens—liczba Kontaktów, które otworzyły wiadomość
clickedMessage—liczba kliknięć wiadomości e-mail
uniqueClicks—liczba Kontaktów, które kliknęły wiadomość e-mail
errorMessage—liczba błędnych wiadomości e-mail
softBounce—liczba miękkich zwrotek
hardBounce—liczba twardych zwrotek
resigned—liczba Kontaktów, które zrezygnowały z subskrypcji poprzez kliknięcie w link w danym e-mailu
testAB—wartość boolean; true dla e-maili, które były częścią testu A/B
Dodatkowe pola dla eksportu typu SHORT:
contacts—tablica adresów e-mail odbiorców
Dodatkowe pola dla typu eksportu FULL:
openedBy—tablica kontaktów, które otwarły wiadomość e-mail
clickedBy—tablica kontaktów, które kliknęły wiadomość e-mail
softBouncedBy—tablica kontaktów, które zostały oznaczone jako miękka zwrotka
hardBouncedBy—tablica kontaktów, które zostały oznaczone jako twarda zwrotka
resignedBy—tablica kontaktów, które zrezygnowały z subskrypcji poprzez kliknięcie w link w danym e-mailu
Struktura danych dla powyższych tablic (typ eksportu FULL):
email—adres e-mail Kontaktu
contactId—Identyfikator Kontaktu
externalId—Zewnętrzny identyfikator Kontaktu
dateOpened—UNIX timestamp [ms]
dateClicked—UNIX timestamp [ms]
optedOut—wartość boolean; true dla Kontaktów, które zrezygnowały z subskrypcji poprzez kliknięcie w link w danym e-mailu
WAŻNE: Tablica contacts nie jest dostępna dla typu eksportu FULL
Pobieranie kontaktów, do których została wysłana wiadomość email
Przykładowa struktura danych zapytania:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"user": "user@user.com",
"conversationId": "5f0baebd-96bc-4a55-9ffe-709b04992327"
}
W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/email/messageStatistics
Pola dostępne w zapytaniu metody messageStatistics:
| Pole | Max. długość | Opis |
|---|---|---|
| conversationId* | 255 | identyfikator konwersacji |
| user* | 255 | email użytkownika |
Rezultat zapytania
{
"success": true,
"message": [],
"requestId": 123
}
W odpowiedzi otrzymujemy “requestId”, który jest naszym identyfikatorem eksportu.
Aby sprawdzić status eksportu należy wysłać żądanie metodą POST na adres:
https://www.salesmanago.pl/api/job/status
W którym podajemy requestId (z odpowiedzi metody użytej wcześniej), w którym zawarty był numer do monitorowania statusu eksportu.
W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.
Link jest ważny tylko przez kilka minut.
Przykładowa struktura danych zapytania /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Rezultat zapytania
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json?AWSAccessKeyId="
}
Przykład struktury wyeksportowanych danych dla /api/email/messageStatistics:
{
"conversationId": "5f0baebd-96bc-4a55-9ffe-709b04992327",
"name": "Test email",
"subject": "Lorem ipsum",
"sentMessage": 317,
"sentTo": [
{
"email": "test1@gmail.com",
"contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
"dateOpened": 1533170052000
},
{
"email": "test2@gmail.com",
"contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
"dateOpened": 1533170052000
},
{
"email": "test3@gmail.com",
"contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
"dateOpened": 1533256452000
}
]
}
API - Wiadomości tekstowe
Wysyłanie wiadomości
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"templateName": "abcd-...-1234",
"user": "salesmanago.user@example.com",
"contacts": [
{
"addresseeType": "EMAIL",
"value": "name1@example.com, name2@example.com"
}
],
"name": "Sample conversation name",
"sender": "Example sender",
"textContent": "Visit example.com and get up to 50% off",
"shortenLinks": false,
"messagingChannelIntegration": [
{
"channel": "SMS",
"provider": "APIFONICA"
},
{
"channel": "VIBER",
"provider": "OCTAPUSH"
}
],
"allowDiacritics": true
}
W celu wysłania wiadomości, należy skorzystać z metody:
https://xxx.salesmanago.com/api/messaging/send
Pola dostępne w metodzie send:
| Pole | Max. długość | Opis |
|---|---|---|
| sender | 255 | Nazwa/ID nadawcy |
| name* | 255 | Nazwa wiadomości, która będzie będzie wyświetlać się w SALESmanago |
| templateName | 255 | Możesz podać tylko jedno z tych pól: Albo nazwę szablonu albo treść wiadomości do wysłania. |
| textContent | ||
| messagingChannelIntegration | 255 | Lista zintegrowanych kanałów wysyłania wiadomości. Składa się z par typu klucz-wartość, gdzie:
|
| contacts* | Zbiór obiektów typu Contact z polami określonymi poniżej:
|
|
| user* | 254 | Email użytkownika |
| shortenLinks | Wartość logiczna określająca czy linki mają być skrócone. Domyślnie fałsz. | |
| time | Czas wysyłki w milisekundach. Najwcześniejszą dozwoloną wartością jest jeden dzień wcześniej, co skutkuje ustawieniem czasu na teraz. Najpóźniejsza dozwolona wartość to 1 rok od teraz. Domyślną wartością jest teraz. | |
| allowDiacritics | Wartość logiczna określająca czy dozwolone są znaki diakrytyczne. Domyślnie fałsz. |
Rezultat zapytania:
{
"success": true,
"message": ["Scheduled sending"],
"conversationId": 1
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
conversationId – identyfikator konwersacji
Lista masowych konwersacji
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"from": "1649938888000",
"to": "1649938889000",
"source": "MASS"
}
W celu pobrania listy masowych wiadomości Mobile Marketing w wybranym przedziale czasowym, należy skorzystać z metody:
https://xxx.salesmanago.com/api/messaging/conversationList
Pola dostępne w metodzie conversationList:
| Pole | Max. długość | Opis |
|---|---|---|
| from* | 255 | Daty w formacie UNIX timestamp. Maksymalny zakres czasu dla źródeł RULE i WORKFLOW wynosi 7 dni. Maksymalny zakres czasu dla innych źródeł wynosi 30 dni. |
| to* | 255 | |
| source | ENUM | Wartość enum; pozwala na filtrowanie listy po typie źródła wiadomości.
Dozwolone wartości:
|
Rezultat zapytania:
{
"success": true,
"message": [],
"conversationIds": [123456,234567,3456789]
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
conversationIds – lista identyfikatorów konwersacji
Pobranie danych konwersacji.
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"conversationId": 12345
}
W celu pobrania danych należy skorzystać z metody:
https://xxx.salesmanago.com/api/messaging/mass/conversation/data
Pola dostępne w metodzie conversation/data:
| Pole | Max. długość | Opis |
|---|---|---|
| conversationId* | int | Identyfikator Konwersacji |
Rezultat zapytania:
{
"success": true,
"message": [],
"messagingContentList": [
{
"name": "Spring Campaign",
"date": 1649938888000,
"textContent": "Visit example.com and get up to 50% off",
"phone": "+15554443322",
"contactId" : "1a2b-...-3c4d",
"externalId": null,
"channel" : "SMS"
},
{
"name": "Spring Campaign",
"date": 1659938888000,
"textContent": "Visit example.com and get up to 50% off",
"phone": "+15554443333",
"contactId" : "1a2b-...-3c4d",
"externalId": null,
"channel" : "SMS"
},
{
"name": "Spring Campaign",
"date": 1669938888000,
"textContent": "Example Visit example.com and get up to 50% off",
"phone": "+15554443344",
"contactId" : "1a2b-...-3c4d",
"externalId": null,
"channel" : "SMS"
}
]
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
messagingContentList – lista obiektów z danymi konwersacji
Statystyki wysyłek wiadomości
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"conversationId": 123456,
"channel": "SMS",
"source": "MASS"
}
W celu pobrania statystyk wysyłek wiadomości z modułu Mobile Marketing należy skorzystać z metody:
https://xxx.salesmanago.com/api/messaging/conversationStats
Pola dostępne w metodzie conversationStats:
| Pole | Max. długość | Opis |
|---|---|---|
| conversationId* | 36 | Identyfikator konwersacji wiadomości zwrócony przez metodę wysyłania. Identyfikator konwersacji można również znaleźć w adresie URL w analizie wysłanych wiadomości. |
| channel | 100 | Wartość enumerowana umożliwiająca filtrowanie statystyk według typu kanału. Dozwolone wartości:
|
| source | 255 | Wartość enumerowana umożliwiająca filtrowanie statystyk według typu źródła wiadomości. Dozwolone wartości:
|
Rezultat zapytania:
{
"success": true,
"message": [],
"conversationTemplateId": 9876543,
"sentDate": 1659938888000,
"user": "salesmanago.user@example.com",
"name": "Spring Campaign",
"statistics": {
"SMS": {
"cancelled": false,
"sent": 1200,
"delivered": 1150,
"undelivered": 50,
"clicked": 800
},
"VIBER": {
"cancelled": false,
"sent": 1200,
"delivered": 1150,
"undelivered": 50,
"clicked": 800
}
}
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationTemplateId – ID użytego szablonu wiadomości
sentDate – Data wysłania wiadomości w formacie UNIX timestamp [ms]
user – Użytkownik SALESmanago do którego przypisana jest konwersacja
name – nazwa wiadomości widoczna w SALESmanago
SMS/WHATS_APP/VIBER – obiekt zawierający statystyki z danego kanału
cancelled – wartość logiczna informująca czy wysyłka została anulowana w danym kanale
sent – liczba wysłanych wiadomości w danym kanale
delivered – liczba dostarczonych wiadomości w danym kanale
undelivered – liczba niedostarczonych wiadomości w danym kanale
clicked – liczba klikniętych wiadomości w danym kanale
Wysyłanie wiadomości SMS
Przykładowa struktura danych zapytania:
{
"clientId": "xxyyzz",
"apiKey": "yourApiKey",
"sha": "4288423ba34736e50f852228ea1d0c79628d3e16",
"requestTime":1327056031488,
"user": "user@vendor.pl",
"contacts": [
{
"email": "contact@gmail.com"
},
{
"email": "test@gmail.com"
},
{
"contactId": "c4c52fea-47b1-1b1e-8680-40a230eb49bc"
},
{
"tag": "SM_TEST"
}
],
"text": "Hello world!",
"date": 1403187522125,
"gateway": "SMSAPI",
"name": "api-test"
}
W celu wysłania wiadomości sms poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/send
Pola dostępne w zapytaniu metody send:
| Pole | Max. długość | Opis |
|---|---|---|
| user* | 255 | mail użytkownika |
| date* | timestamp(ms) | aktualny znacznik czasu |
| text* | - | treść wiadomości |
| templateIntId* | 255 | id szablonu wiadomości sms, który będzie użyty jako treść wysyłanego SMS (alternatywa dla pola “text”) |
| contacts* | - | lista obiektów kontaktów |
| gateway | 255 | nazwa bramki |
| name | 255 | nazwa kampanii |
Lista obiektów kontaktów (pole “contacts”) to tablica obiektów, które mogą zawierać pola:
| Pole | Max. długość | Opis |
|---|---|---|
| email** | 254[?] | e-mail kontaktu |
| contactId** | 255 | id kontaktu z systemu SALESmanago |
| tag** | 255 | tag przypisany do grupy kontaktów SALESmanago (w polu “contacts” można użyć maksymalnie 10 obiektów “tag”) |
**Wymagane jest użycie przynajmniej jednego z wymienionych pól.
Rezultat zapytania
{
"success": true,
"message": [
"API Smses are scheduled to send."
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Pobieranie masowych konwersacji SMS
Przykładowa struktura danych zapytania:
{
"clientId":"h4jsu6pc5txybj04",
"apiKey":"your-api-key-123",
"requestTime":1485520055,
"sha":"11fbaf0ad77f1491979594f58ba10565b30926",
"from":1491965421341,
"to":1491979590565
}
W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/massConversationList
Pola dostępne w zapytaniu metody massConversationList:
| Pole | Max. długość | Opis |
|---|---|---|
| from* | timestamp(ms) | początek zakresu dat stworzenia konwersacji sms |
| to* | timestamp(ms) | koniec zakresu dat stworzenia konwersacji sms |
Rezultat zapytania
{
"success": true,
"message": [],
"conversationList": [
"86dfe8bd-f21d-4f5e-9f53-19c929877d3c",
"5c27d476-282d-4235-9393-300d359b2d51"
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationList - lista identyfikatorów masowych konwersacji sms
Pobieranie statystyk SMS po ID konwersacji
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd"
}
W celu pobrania statystyk kampanii SMS należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/conversationStatistics
Pola dostępne w zapytaniu metody conversationStatistics:
| Pole | Max. długość | Opis |
|---|---|---|
| conversationId* | 255 | identyfikator konwersacji |
Rezultat zapytania
{
"success": true,
"message": [],
"conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd",
"name": "test",
"messages": 2,
"sentMessages": 2,
"deliveredCount": 1,
"delivered": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"repliedCount": 1,
"replied": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"notDeliveredCount": 1,
"notDelivered": [
{
"email": "example_mail_2@test.pl",
"id": "9ca03a61-04a2-4d89-ae9c-1b3394814f52",
"contactExternalId": "extId_2"
}
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationId - identyfikator wysyłki SMS
name - nazwa konwersacji
messages - liczba wiadomości do wysłania
sentMessages - liczba wysłanych wiadomości
deliveryCount - liczba dostarczonych wiadomości
delivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
repliedCount - liczba wiadomości, na które zostały wysłane odpowiedzi
replied - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
notDeliveredCount - liczba wiadomości, które nie zostały dostarczone
notDelivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
Pobieranie statystyk SMS po nazwie konwersacji
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"name": "test"
}
W celu pobrania statystyk kampanii SMS należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/conversationStatisticsByName
Pola dostępne w zapytaniu metody conversationStatisticsByName:
| Pole | Max. długość | Opis |
|---|---|---|
| name* | 255 | nazwa konwersacji |
Rezultat zapytania
{
"success": true,
"message": [],
"count": 59,
"conversationStatistics": [
{
"success": true,
"message": [],
"conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd",
"messages": 2,
"sentMessages": 2,
"deliveredCount": 1,
"delivered": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"repliedCount": 1,
"replied": [
{
"email": "example_mail_1@test.pl",
"id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
"dateTimestamp": 1513853328000,
"contactExternalId": "extId"
}
],
"notDeliveredCount": 1,
"notDelivered": [
{
"email": "example_mail_2@test.pl",
"id": "9ca03a61-04a2-4d89-ae9c-1b3394814f52",
"contactExternalId": "extId_2"
}
]
}
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
count – liczba konwersacji
conversationStatistics - statystyki kampanii SMS
conversationId - identyfikator mailingu
messages - liczba wiadomości do wysłania
sentMessages - liczba wysłanych wiadomości
deliveryCount - liczba dostarczonych wiadomości
delivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
repliedCount - liczba wiadomości, na które zostały wysłane odpowiedzi
replied - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
notDeliveredCount - liczba wiadomości, które nie zostały dostarczone
notDelivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
Pobieranie statystyk konwersacji SMS
Przykładowa struktura danych zapytania:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"conversationId": "ace8beeb-a0dc-4234-afc8-e6274de9e0ae"
}
W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/smsConversationStatistics
Pola dostępne w zapytaniu metody smsConversationStatistics:
| Pole | Max. długość | Opis |
|---|---|---|
| conversationId* | 255 | identyfikator konwersacji |
Rezultat zapytania
{
"success": true,
"message": [],
"conversationId": "ace8beeb-a0dc-4234-afc8-e6274de9e0ae",
"messages": 3,
"sentCount": 3,
"sent": [
{
"email": "test1@testowy.pl",
"id": "09d20ef2-1a4e-11e7-baad-0cc47a6bceb8",
"dateTimestamp": 1564408685000,
"contactExternalId": null
},
{
"email": "test2@testowy.pl",
"id": "0ae3be46-ca11-11e7-adbf-0cc47a6bceb8",
"dateTimestamp": 1564408684000,
"contactExternalId": null
},
{
"email": "test3@testowy.pl",
"id": "0afd8128-ca11-11e7-adbf-0cc47a6bceb8",
"dateTimestamp": 1564408868000,
"contactExternalId": null
}
],
"deliveredCount": 2,
"delivered": [
{
"email": "test1@testowy.pl",
"id": "09d20ef2-1a4e-11e7-baad-0cc47a6bceb8",
"dateTimestamp": 1564408691000,
"contactExternalId": null
},
{
"email": "test2@testowy.pl",
"id": "0ae3be46-ca11-11e7-adbf-0cc47a6bceb8",
"dateTimestamp": 1564408691000,
"contactExternalId": null
}
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationId - identyfikator konwersacji
messages - liczba wiadomości
sentCount - liczba wysłanych wiadomości
sent - lista kontaktów, dla których została zrealizowana wysyłka wiadomości
deliveredCount - liczba dostarczonych wiadomości
delivered - lista kontaktów, do których została dostarczona wiadomość
API - Zadania
Zadania kontaktów
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
"finished" : false,
"smContactTaskReq" : {
"contactEmail" : "konrad-123@konri.com",
"id" : "task-id-123",
"note" : "Zadzwonić do klienta",
"date" : 1359673200361,
"cc" : "konrad-test-123@konri.com",
"reminder" : "30_MIN",
"realized" : false
}
}
Dodawania, aktualizację oraz usuwanie zadania kontaktu wykonujemy za pomocą jednej metody:
https://www.salesmanago.pl/api/contact/updateTask
Pola dostępne w zapytaniu metody updateTask:
| Pole | Max. długość | Opis |
|---|---|---|
| finished | true/false | przypisanie wartości true spowoduje skasowanie zadania i wtedy wymagany jest jedynie dodatkowy parametr id. Przy dodawaniu i aktualizacji zadania należy przypisać wartość false |
| contactEmail** | 255 | e-mail kontaktu do którego zostanie przypisane zadanie |
| id | 255 | id zadania |
| note | 2048 | notatka zadania |
| date** | timestamp(ms) | data wykonania zadania |
| cc | 255 | lista emaili do których zostanie wysłane przypomnienie (emaile powinny być oddzielone przecinkami) |
| reminder** | 255 | przypomnienie o wykonaniu zadania. Określa kiedy przypomnienie ma zostać wysłane*. Dopuszczalne wartości: 15_MIN – 15 minut przed, 30_MIN – 30 minut przed, 1_HOUR – godzinę przed, 12_HOUR – 12 godzin przed, 1_DAY – 1 dzień przed, 1_WEEK – 1 tydzień przed, |
| realized | true/false | przypisanie wartości true spowoduje oznaczenie taska jako zrealizowanego |
** pola obowiązkowe podczas dodawania zadania
Rezultat zapytania
{
"taskId" : "task-Id-123",
"message" : [ ],
"success" : true
}
W rezultacie zapytania otrzymujemy:
taskId – id zadania którego dotyczy akcja
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
API - Notatki
Dodawanie Notatki
Przykładowa struktura danych zapytania:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
"owner": "owner@test.pl",
"contactId": "",
"email": "test1@test.pl",
"priv": false,
"note": "Notatka ktora bedzie dodana do kontaktu"
}
Dodawanie notatki do kontaktu wykonujemy za pomocą metody:
https://www.salesmanago.pl/api/contact/addNote
Pola dostępne w zapytaniu metody addNote:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | konto właściciela kontaktu do którego dodawana jest notatka |
| email* | 254[?] | email kontaktu do którego dodajemy notatkę (opcjonalnie z contactId) |
| contactId* | 255 | id kontaktu do którego dodajemy notatkę (opcjonalnie z email) |
| priv | true/false | definiuje czy notatka ma być prywatna, czyli widoczna tylko przez dodającego (domyślnie false) |
| note* | 1024 | treść notatki |
Rezultat zapytania
{
"success": true,
"message": [
"Note was added to contact"
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
API - Inne
Autoryzacja tymczasowa
Przykładowa struktura danych zapytania:
{
"userName" : "admin@vendor.pl",
"password" : "****"
}
System SALESmanago umożliwia uzyskanie tymczasowego tokenu wykorzystując nazwę użytkownika i hasło. W tym celu należy wykonać metodę:
https://www.salesmanago.pl/api/system/authorise
Pola dostępne w zapytaniu metody authorise:
| Pole | Max. długość | Opis |
|---|---|---|
| userName* | 255 | nazwa użytkownika |
| password* | 255 | hasło |
Rezultat zapytania
{
"token" : "b426c6663d844305b2539e9bc27b75dc",
"clientId" : "your-client-id-123",
"validTo" : 1359673200361,
"message" : [ ],
"success" : true
}
W rezultacie zapytania otrzymujemy:
token – to tymczasowy token, który można użyć w celu autoryzacji w zamian za apiSecret,
clientId – identyfikator klienta, wymagany do kolejnych operacji,
validTo – data ważności
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd,
success – wartość logicznaznajduje się ma wspomnianej zakładce „Integracja” informująca o rezultacie zapytania (udane / nieudane)
Pobieranie listy kont użytkowników danego klienta
Przykładowa struktura danych zapytania:
{
"clientId": "your-api-key-123",
"apiKey": "your-client-id-123",
"requestTime": 1234567896541,
"sha": "4f69782e826841f794080cae87648e42"
}
W celu otrzymania listy kont użytkowników danego klienta należy skorzystać z metody:
https://www.salesmanago.pl/api/user/listByClient
Pola dostępne w zapytaniu metody listByClient:
Ta metoda nie wymaga żadnych dodatkowych pól.
Rezultat zapytania:
{
"success": true,
"message": [],
"users": [
"admin@vendor.pl",
"test@test.pl"
]
}
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
users – lista emaili użytkowników
Pobierz URL pliku z danymi eksportu
Przykładowe żądanie:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"owner": "salesmanago.user@yourcompany.com",
"requestId": 1234567
}
Możesz uzyskać adres URL pliku zawierającego wyeksportowane dane za pomocą metody API:
https://www.salesmanago.pl/api/job/status
Asynchroniczne eksporty
Wiele metod API pozwala na asynchroniczne eksportowanie danych do pliku JSON. Dzięki temu połączenie HTTP może zostać zamknięte, podczas gdy eksport jest przetwarzany w tle. W zależności od zakresu eksportu, może to trwać nawet kilkanaście minut, co znacznie przekracza maksymalny czas połączenia i nie byłoby możliwe w przypadku żądań synchronicznych. Typowy eksport składa się z:
1. Żądania eksportu, które zwraca requestId
2. Cyklicznego żądania job/status, które po podaniu requestId zwraca URL pliku JSON
3. Żądania GET w celu pobrania pliku JSON
Zalecany czas odpytywania o plik JSON przy użyciu job/status to 60 sekund.
Odpowiedź przed przetworzeniem eksportu:
{
"success": true,
"message": [
"Job not start yet"
]
}
Pola dostępne w metodzie job/status:
| Pole | Max. długość | Opis |
|---|---|---|
| owner | 255 | Właściciel Kontaktów (e-mail konta użytkownika SALESmanago) |
| requestId | int | Unikalny identyfikator żądania otrzymany z metody eksportu |
Przykładowa odpowiedź po przetworzeniu eksportu:
{
"success": true,
"message": [],
"fileUrl": "https://storage.googleapis.com/sm-file/a1b2-...-c3d4/1234-...-5678/abcd-...-efgh.json?GoogleAccessId=..."
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
fileUrl – adres URL pliku z eksportem, ważny przez kilka minut od wygenerowania linku. Ważne: To pole zwracane jest tylko po ukończeniu eksportu.
API - Workflow
Pobieranie listy workflow 2.0
Przykładowa struktura danych zapytania:
{
"clientId" : "your-client-id-123",
"apiKey" : "your-api-key-123",
"requestTime" : 1234567896541,
"sha" : "4f69782e826841f794080cae87648e42"
}
W celu pobrania listy workflow 2.0 należy skorzystać z metody:
https://www.salesmanago.pl/api/workflow/list
Pola dostępne w zapytaniu metody api/workflow/list: Ta metoda nie wymaga żadnych dodatkowych pól.
Rezultat zapytania:
{
"success": true,
"message": [],
"workflows": [
{
"id": 1000001,
"name": "workflow 1"
},
{
"id": 1000002,
"name": "workflow 2"
}
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
workflows - lista nieusuniętych workflow 2.0
id - id workflow
name - nazwa workflow
Workflow Statisctics
Przykładowa struktura danych zapytania:
{
"clientId": "axf46o35hgrf015q",
"apiKey": "test123test",
"requestTime": 1348046897664,
"sha": "3436a3efd8c63f72c8ba827d53d1297482e6d85d",
"workflowId": 10032430,
"period": "PREVIOUS_YEAR"
}
W celu pobrania workflow statisctics należy skorzystać z metody:
https://www.salesmanago.pl/api/workflow/statistics
Pola dostępne w zapytaniu metody /api/workflow/statistics: Ta metoda nie wymaga żadnych dodatkowych pól.
Rezultat zapytania:
{
"success": true,
"message": [],
"name": "New Workflow 2022-02-23 12:53",
"creationDate": 1645617296,
"launchesNumber": 0,
"revenueStats": {
"totalSales": 0.0,
"totalLastClickSales": 0.0,
"totalTransactionNumber": 0,
"totalLastClickTransactionNumber": 0,
"emailSales": 0.0,
"emailLastClickSales": 0.0,
"emailTransactionNumber": 0,
"emailLastClickTransactionNumber": 0,
"webPushSales": 0.0,
"webPushClickSales": 0.0,
"webPushTransactionNumber": 0,
"webPushLastClickTransactionNumber": 0,
"smsSales": 0.0,
"smsClickSales": 0.0,
"smsTransactionNumber": 0,
"smsLastClickTransactionNumber": 0
},
"emailStats": {
"averageOr": "-",
"uniqueOpens": 0,
"allOpens": 0,
"averageCtr": "-",
"uniqueClicks": 0,
"allCliks": 0,
"averageCtor": "-",
"optOut": "-",
"contactsOptOut": 0,
"sentMessages": 0,
"messageToSend": 0,
"failedMessages": 0,
"spam": 0,
"softBounces": 0,
"hardBounces": 0
}
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
name - nazwa workflow
creationDate - lista nieusuniętych workflow 2.0
launchesNumber - id workflow
revenueStats - id workflow
totalSales -
totalLastClickSales -
totalTransactionNumber -
totalLastClickTransactionNumber -
emailSales -
emailLastClickSales -
emailTransactionNumber -
emailLastClickTransactionNumber -
webPushSales -
webPushClickSales -
webPushTransactionNumber -
webPushLastClickTransactionNumber -
smsSales -
smsClickSales -
smsTransactionNumber -
smsLastClickTransactionNumber -
emailStats -
averageOr -
uniqueOpens -
allOpens -
averageCtr -
uniqueClicks -
allClicks -
averageCtor -
optOut -
contactsOptOut -
sentMessages -
messageToSend -
failedMessages -
spam -
softBounces -
hardBounces -
API - Web Push
Pobieranie statystyk wysłanego powiadomienia Web Push
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"wizardId": 123456
}
Możesz pobrać statystyki wysłanego powiadomienia Web Push używając metody API:
https://www.salesmanago.pl/api/web/push/stats
Pola dostępne w metodzie web/push/stats:
| Pole | Max. długość | Opis |
|---|---|---|
| wizardId* | Long (19) | Identyfikator przydzielony do wysłanego powiadomienia Web Push. Możesz go znaleźć, przechodząc do Web Push ➔ Wysłane Web Pushe, a następnie klikając Analityka w wybranym wierszu. Identyfikator znajduje się w adresie URL. |
Rezultat zapytania:
{
"success": true,
"message": [],
"name": "Example Web Push",
"date": 1630150200000,
"totalSent": 500,
"anonymousSent": 200,
"totalOpened": 150,
"totalClicked": 100,
"richWebPushOpened": 100,
"richWebPushClicked": 50,
"sent": [
"name01@example.com",
"name02@example.com",
"name03@example.com",
"name04@example.com",
"..."
],
"opened": [
"name01@example.com",
"name02@example.com",
"name03@example.com",
"name04@example.com",
"..."
],
"clicked": [
"name01@example.com",
"name02@example.com",
"..."
]
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
name - nazwa powiadomienia Web Push
date - data wysłania powiadomienia Web Push
totalSent - liczba wysłanych powiadomień Web Push
anonymousSent - liczba wysłanych Web Pushy do Kontaktów anonimowych
totalOpened - liczba dostarczonych powiadomień Web Push
totalClicked - liczba klikniętych powiadomień Web Push
richWebPushOpened - liczba dostarczonych powiadomień Rich Web Push
richWebPushClicked - liczba klikniętych powiadomień Rich Web Push
sent - lista adresów e-mail Kontaktów, do których wysłano Web Push
opened - lista adresów e-mail Kontaktów, do których dostarczono Web Push
clicked - lista adresów e-mail Kontaktów, które kliknęły powiadomienie Web Push
Pobieranie listy identyfikatorów powiadomień web push
Przykładowa struktura danych zapytania:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"from":1572605631000,
"to":1573558527000
}
W celu pobrania ID powiadomień web push należy skorzystać z metody:
https://www.salesmanago.pl/api/web/push/ids
Pola dostępne w zapytaniu metody web/push/ids:
| Pole | Max. długość | Opis |
|---|---|---|
| from* | Timestamp | początek zakresu dat wysłanych web push |
| to* | Timestamp | koniec zakresu dat wysłanych web push |
Rezultat zapytania:
{
"success": true,
"message": [],
"webPushIds": [
1,2,3
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
webPushIds - lista id wysłanych powiadomień web push
Lista identyfikatorów powiadomień Web Push
Przykładowa struktura danych zapytania:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "dsadsadasdsadsadsadsadsadsadb",
"requestTime" :1626774053,
"from":1595238047,
"to":1626774053
}
Użyj następującej metody, aby uzyskać listę identyfikatorów powiadomień Web Push:
https://www.salesmanago.pl/api/notification/conversation/ids
Wypełnij dostępne pola, aby autoryzować metodę:
| Pole | Max. długość | Opis |
|---|---|---|
| apiKey* | - | klucz do API |
| clientId* | - | id użytkownika |
| sha* | - | wygenerowany sha |
| requestTime* | - | czas wykonania żądania (ms) |
| from* | 255 | początkowy zakres dat stworzenia |
| to* | 255 | końcowy zakres dat stworzenia |
Rezultat zapytania:
{
"success": true,
"message": [
"Conversation list "
],
"pushConversationIds": [
16,
17,
18,
19
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
pushConversationIds – tablica z id webpushy
Eksportowanie statystyk formularzy zgody do pliku dostępnego z repozytorium
Przykładowa struktura danych zapytania:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "1a3225a77b341043e17672f369e9150afed488eb",
"requestTime" :1626774053,
"user":"superuser@gmail.com",
"intId":101044
}
Użyj następującej metody, aby wyeksportować statystyki formularzy zgody do pliku, który będzie dostępny z repozytorium:
https://www.salesmanago.pl/api/notification/consent/form/stats
Wypełnij dostępne pola, aby autoryzować metodę:
| Pole | Max. długość | Opis |
|---|---|---|
| apiKey* | - | klucz do API |
| clientId* | - | id użytkownika |
| sha* | - | wygenerowany sha |
| requestTime* | - | czas wykonania żądania (ms) |
| user* | 255 | email użytkownika |
| intId* | - | id formularza |
Rezultat zapytania:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 2660
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
requestId – identyfikator eksportu
Parametr “requestId” jest naszym identyfikatorem eksportu.
Aby sprawdzić status eksportu należy wysłać żądanie na adres: https://www.salesmanago.pl/api/job/status
Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.
W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.
Link jest ważny tylko przez kilka minut.
Przykładowa struktura danych zapytania /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Rezultat zapytania
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Eksportuj statystyki powiadomień Web Push do pliku dostępnego z Repozytorium
Przykładowa struktura danych zapytania:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "1a3225a77b341043e17672f369e9150afed488eb",
"user": "superuser@gmail.com",
"itemId": "1",
"webPushSourceType": "MASS"
}
Użyj poniższej metody, aby wyeksportować statystyki powiadomień Web Push do pliku, który będzie dostępny z repozytorium:
https://www.salesmanago.pl/api/notification/push/stats
Wypełnij dostępne pola, aby autoryzować metodę:
| Pole | Max. długość | Opis |
|---|---|---|
| apiKey* | - | klucz do API |
| clientId* | - | id użytkownika |
| sha* | - | wygenerowany sha |
| user* | 255 | email użytkownika |
| itemId* | id | |
| webPushSourceType* | typ webpusha |
Rezultat zapytania:
{
"success": true,
"message": [
"Export added to execute."
],
"requestId": 2659
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
requestId – identyfikator eksportu
Parametr “requestId” jest naszym identyfikatorem eksportu.
Aby sprawdzić status eksportu należy wysłać żądanie na adres: https://www.salesmanago.pl/api/job/status
Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.
W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.
Link jest ważny tylko przez kilka minut.
Przykładowa struktura danych zapytania /api/job/status:
{
"clientId": "yourclientID",
"apiKey": "yourAPIkey",
"requestTime": 1500556989,
"sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
"owner": "admin@vendor.pl",
"requestId": 123
}
Rezultat zapytania
{
"success": true,
"message": [],
"fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}
Nazwa i identyfikator formularza zgody
Przykładowa struktura danych zapytania:
{
"apiKey": "test123test",
"clientId" : "ye4vodnswfo6zp75",
"sha" : "1a3225a77b341043e17672f369e9150afed488eb",
"requestTime" :1626774053
}
Użyj następującej metody, aby uzyskać nazwę i identyfikator formularza zgody:
https://www.salesmanago.pl/api/notification/consent/form/data
Użyj tej metody, jeśli chcesz sprawdzić konkretny ID klienta, otrzymasz informację o ID oraz formularzu, na który zapisany jest kontakt
Wypełnij dostępne pola, aby autoryzować metodę:
| Pole | Max. długość | Opis |
|---|---|---|
| apiKey* | - | klucz do API |
| clientId* | - | id użytkownika |
| sha* | - | wygenerowany sha |
| requestTime* | - | czas wykonania żądania (ms) |
Rezultat zapytania:
{
"success": true,
"message": [],
"consentFormList": [
{
"intId": 101045,
"name": "Nowy formularz zgody 2021-06-22 14:49"
},
{
"intId": 101044,
"name": "Nowy formularz zgody 2021-06-02 12:05"
}
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
consentFormList – tablica zawierajaca obiekty z nazwą oraz id formularza
intId – id formularza
name – nazwa formularza
API - Program Lojalnościowy
Dodawanie kontaktu do Loyalty Program
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "email",
"value": "email@addresseeType.pl"
}
],
"loyaltyProgram": "Loyalty Program Name"
}
Dodawanie kontaktu do Loyalty Program wykonujemy wywołując metodę:
https://www.salesmanago.pl/api/loyalty/program/v1/addContact
Pola dostępne w zapytaniu metody addContact:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contacts* | 255 | lista kontaktów do dodania, zgodna z innymi metodami api które zawierają addresseeType oraz ich wartości. |
| loyaltyProgram* | 255 | nazwa programu lojalnościowego do którego ma zostać dodany kontakt |
Rezultat zapytania:
{
"message": [],
"success": true,
"points": 123
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
points – liczba punktów
Usuwanie kontaktu z Loyalty Program
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "email",
"value": "email@addresseeType.pl"
}
],
"loyaltyProgram": "Loyalty Program Name"
}
Usuwanie kontaktu z Loyalty Program wykonujemy wywołując metodę:
https://www.salesmanago.pl/api/loyalty/program/v1/removeContact
Pola dostępne w zapytaniu metody removeContact:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contacts* | 255 | lista kontaktów do dodania, zgodna z innymi metodami api które zawierają addresseeType oraz ich wartości. |
| loyaltyProgram* | 255 | nazwa programu lojalnościowego z którego ma zostać usunięty kontakt |
Rezultat zapytania:
{
"message": [],
"success": true
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Dodawanie/usuwanie punktów kontaktu dla Loyalty Program
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"contacts": [
{
"addresseeType": "email",
"value": "email@addresseeType.pl"
}
],
"loyaltyProgram": "Loyalty Program Name",
"points": 12,
"modificationType": "SUBTRACT",
"comment": "Comment text"
}
Dodawanie/usuwanie punktów kontaktu dla Loyalty Program wykonujemy wywołując metodę:
https://www.salesmanago.pl/api/loyalty/program/v1/modifyPoints
Pola dostępne w zapytaniu metody modifyPoints:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contacts* | 255 | lista kontaktów, dla której liczba punktów ma zostać zmieniona (zgodna z innymi metodami API, które zawierają addresseeType oraz ich wartości) |
| loyaltyProgram* | 255 | nazwa programu lojalnościowego |
| points* | 255 | liczba punktów |
| modificationType* | SUBTRACT - odjęcie punktów, ADD - dodanie punktów | typ modyfikacji |
| comment | 255 | komentarz do danej modyfikacji |
Rezultat zapytania:
{
"message": [],
"success": true
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
Zwracanie liczby punktów w Programie Lojalnościowym
Przykładowa struktura danych zapytania:
{
"clientId": "clientId",
"apiKey": "apiKey",
"requestTime": 1481543324302,
"sha": "sha1",
"owner": "admin@vendor.pl",
"email": "email@addresseeType.pl",
"loyaltyProgram": "Loyalty Program Name"
}
Możesz sprawdzić liczbę punktów konkretnego kontaktu w wybranym Programie Lojalnościowym używając metody API:
https://www.salesmanago.pl/api/loyalty/program/v1/getPoints
Pola dostępne w zapytaniu metody getPoints:
| Pole | Max. długość | Opis |
|---|---|---|
| clientId* | - | id użytkownika |
| apiKey* | - | klucz do API |
| sha* | - | wygenerowany sha |
| owner* | - | właściciel kontaktu (email konta użytkownika SALESmanago) |
| requestTime* | - | czas wykonania żądania (ms) |
| email* | 254[?] | adres e-mail kontaktu |
| loyaltyProgram* | 255 | nazwa programu lojalnościowego |
Rezultat zapytania:
{
"message": [],
"success": true,
"points": 123
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
points – liczba punktów zebranych przez kontakt w wybranym programie lojalnościowym
API - Mechanizmy rekomendacji
Ostatnio wyświetlane produkty
Przykładowe żądanie:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"contactUuid": "1a2b-...-3c4d",
"shopName": "Example Store"
}
W celu pobrania listy ostatnio oglądanych produktów użyj poniższej metody:
https://www.salesmanago.pl/api/recommendation/lastViewed
Pola dostępne w metodzie lastViewed:
| Pole | Max. długość | Opis |
|---|---|---|
| contactUuid* | UUID | Identyfikator Kontaktu z SALESmanago, który otrzymasz w odpowiedzi na każde żądanie z dodaniem lub aktualizacją Kontaktu. |
| shopName* | 64 | Nazwa Katalogu Produktowego / Feedu Produktowego XML. Uwaga: nie mylić z polem location. |
Rezultat żądania:
{
"message": [],
"success": true,
"productIds": [
"5678",
"9876"
]
}
W rezultacie zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
productIds – lista ID produktów
Najczęściej kupowane produkty
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"shopName": "dataSource"
}
Najczęściej kupowane produkty pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/mostPurchased
Pola dostępne w zapytaniu metody mostPurchased:
| Pole | Max. długość | Opis |
|---|---|---|
| shopName* | 255 | nazwa źródła danych |
Rezultat zapytania:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
productIds – tablica zawierająca id produktów
Produkty kupione przez kontakt (tylko dla kontaktów monitorowanych)
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"smClient": "fecfca38-1f97-437d-91c4-2f30a67e31fa",
"shopName": "dataSource"
}
Produkty kupione przez kontakt pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/purchasedByContact
Pola dostępne w zapytaniu metody purchasedByContact:
| Pole | Max. długość | Opis |
|---|---|---|
| shopName* | 255 | nazwa źródła danych |
| smClient* | 255 | wartość ciasteczka smclient |
Rezultat zapytania:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
productIds – tablica zawierająca id produktów
Produkty zakupione wraz z oglądanym produktem
Przykładowa struktura danych zapytania:
{
"clientId": "axf46o35hgrf015q",
"apiKey": "Hh39uCkBdxTAXAvQE9Ng",
"requestTime": 1481543324302,
"sha": "480f4dc004753394507ec94cf8c84fa26f413623",
"productId": "5",
"shopName": "name"
}
Produkty zakupione wraz z oglądanym produktem pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/purchasedTogether
Pola dostępne w zapytaniu metody purchasedTogether:
| Pole | Max. długość | Opis |
|---|---|---|
| shopName* | 64 | nazwa źródła danych |
| productId* | 32 | id produktu |
Rezultat zapytania:
{
"message" : [ ],
"success" : true,
"productIds" : [
6754,
6755
]
}
Rezultat zapytania (error):
{
"success": false,
"message": [
"Product Id is invalid"
],
"productIds": null
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
productIds – tablica zawierająca id produktów
API - Cinderella AI
Pobieranie rekomendacji produktowych na podstawie rozpoznawania obrazów
Przykładowa struktura danych zapytania:
{
"clientId": "a1b2-...-c3d4",
"apiKey": "e5f6-...-g7h8",
"requestTime": 1659938888000,
"sha": "2aa3-...-e00c",
"imageUrl": "https://example.com/temp/uploads/a1b2c3d4e5.jpg",
"location": "examplecom"
}
Description:
Możesz pobrać listę ID produktów zbliżonych wizualnie do zdjęcia przesłanego przez kontakt korzystając z metody API:
Endpoint
https://www.salesmanago.pl/api/vision
Pola dostępne w metodzie vision:
| Pole | Max. długość | Opis |
|---|---|---|
| imageUrl* | 2048 | Adres URL przesłanego przez kontakt zdjęcia, które może zostać pobrane przez serwery SALESmanago |
| location* | 64 | Pole location zdefiniowane podczas tworzenia Feedu Produktowego XML / Katalogu Produktowego. Wartość pola możesz sprawdzić w SALESmanago → Centrum Integracji → Katalogi Produktowe. |
Rezultat zapytania:
{
"success": true,
"message": [],
"vision": {
"status": "ok",
"photo": "https://example.com/temp/uploads/a1b2c3d4e5.jpg",
"result": [
{
"id": "p0123",
"score": 0.9589041829109192
},
{
"id": "p3456",
"score": 0.94405747056007385
},
{
"id": "p5678",
"score": 0.9198060393333435
}
],
"bq_errors": 0
}
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
status – status wyszukiwania przy pomocy zdjęcia
photo – adres URL przesłanego zdjęcia
result – tablica obiektów zawierająca wyniki wyszukiwania
id – ID produktu
score – wartość dziesiętna pomiędzy 0 i 1 określająca podobieństwo wizualne produktu do zdjęcia przesłanego przez kontakt
bq_errors – liczba błędnych dopasowań
API - Centrum Preferencji Klienta
Centrum Preferencji Klienta
Aby otrzymać wstępnie autoryzowany widok Centrum Preferencji Klienta wywołaj:
https://www.salesmanago.pl/api/customerPreferenceCenter/generateEndpoint
Przykładowa struktura danych zapytania:
{
"clientId": "5vvtmri5ocom6n8g",
"apiKey": "-8773203084919279780-2743038323156910252",
"requestTime": 1391167514795,
"sha": "184db1df6ec4893a1f50809bf8d1a4fe88cde4dc",
"preferenceCenterId" : "7bd071c1-cb96-45a7-8e95-c512c76189a2",
"contactId": "47d82f5a-87d3-11eb-a567-f8a2d6e832bf"
}
Rezultat zapytania:
{
"success": true,
"message": [],
"endpoint": "https://www.salesmanago.pl/customerPreferenceCenter/#/7bd071c1-cb96-45a7-8e95-c512c76189a2/47d82f5a-87d3-11eb-a567-f8a2d6e832bf/?key=240491"
}
Pola dostępne w zapytaniu metody generateEndpoint:
| Field | Max. length | Description |
|---|---|---|
| preferenceCenterId* | 255 | Identyfikator Centrum Preferencji Klienta (może być skopiowany z zakładki Dostęp w ostatnim kroku kreatora Centrum Preferencji Klienta lub z pop-upu pojawiającego się po zapisaniu Centrum) |
| contactId* | 255 | Identyfikator kontaktu SALESmanago (możesz użyć wartości ciasteczka „smclient”) |
W wyniku zapytania otrzymasz:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
endpoint – adres URL zawierający widok dashboardu użytkownika Centrum Preferencji Klienta. Widok jest autoryzowany za pomocą parametru key, co oznacza, że kontakt nie będzie musiał potwierdzać dostępu za pomocą wiadomości e-mail.