Informacje ogólne
Dane autoryzacyjne
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c"
}
Każde zdalne wywołanie API, z wyjątkiem autoryzacji musi zawierać dane autoryzacyjne.
Wartość clientId znajduje się na zakładce „Integracja” menu „Ustawienia”.
Wartość apiKey to losowy ciąg znaków służący do autoryzacji.
Wartość sha generowana jest algorytmem SHA-1 z łańcucha powstałego z połączenia:
apiKey + clientId + apiSecret. ApiSecret znajduje się na wspomnianej zakładce „Integracja”.
requestTime (timestamp - ms) to czas w którym wykonywane jest zapytanie.
Często wykorzystywanymi polami są owner i user (podane w opisach metod). Służą one do tego, aby dana akcja była autoryzowana przez konkretnego użytkownika lub żeby można było przypisać ownera do konkretnego kontaktu.
Wszystkie zapytania wykonywane muszą być na adresie:
https://www.salesmanago.pl/api
Na przykład
https://xyz.salesmanago.pl/api/contact/upsert
Gdzie xyz to identyfikator Twojego serwera (www lub app2, app3…)
Accept: application/json, application/json
Content-Type: application/json;charset=UTF-8
Zapytanie wysyłane jest metodą HTTP POST, w przypadku, gdy użyta ma być metoda HTTP GET jest to wyraźnie zaznaczone w instrukcji użycia danej metody.
W dokumentacji znakiem * oznaczone zostały pola wymagane.
Integracja kodu monitorującego
Po aktywacji naszego konta otrzymujemy dostęp do kodu monitorującego na naszą witrynę.
Kod znajdziemy na stronie głównej, widocznej zaraz po zalogowaniu (do czasu wykrycia przez SALESmanago kodu na naszej stronie), lub w menu „Ustawienia” > „Integracja”.
Skrypt[1] należy wgrać na każdą stronę naszego serwisu, zaraz przed zakończeniem sekcji „body”.
Najlepiej, gdy istnieje możliwość skrypt ten wgrać w szablon naszego serwisu, tak by sam kod znajdował się w jednym miejscu, a był drukowany identycznie na wszystkich stronach.
Przykładowo, skrypt w CMS Wordpress można wgrać do pliku „footer.php”. Oto przykład:
Po kilkunastu minutach od wdrożenia, o ile na naszej stronie pojawiają się wizyty, informacja o potrzebie wdrożenia kodu zniknie ze strony głównej SALESmanago.
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ładowa struktura danych zapytania:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1327056031488,
"sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
"async": true,
"contact" : {
"email" : "konrad-test-1@konri.com",
"fax" : "+48345543345",
"name" : "Konrad Test",
"phone" : "+48123321123",
"company" : "Benhauer",
"externalId" : null,
"state" : "PROSPECT",
"address":{
"streetAddress":"Brzyczyńska 123",
"zipCode":"43-305",
"city":"Bielsko-Biała",
"country":"PL"
}
},
"owner" : "admin@vendor.pl",
"newEmail" : "",
"forceOptIn" : true,
"forceOptOut" : false,
"forcePhoneOptIn" : true,
"forcePhoneOptOut" : false,
"tags" : [ "API","ADmanago"],
"removeTags" : [ "Test_tag","New"],
"properties" : {
"custom.nickname":"Konri",
"custom.sex":"M"
},
"dictionaryProperties": [{
"name": "birthday",
"type": "DATE",
"value": 1488927600000
},
{
"name": "visits",
"type": "NUMBER",
"value": 42
}
],
"birthday" : "19801017",
"province" : "Małopolska",
"useApiDoubleOptIn":true,
"apiDoubleOptInEmailTemplateId":null,
"apiDoubleOptInEmailAccountId":null,
"apiDoubleOptInEmailSubject":null,
"lang":"PL",
"consentDetails": [
{
"consentName": "ZGODA",
"consentAccept": true,
"agreementDate": 1391167515515,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 123456
},
{
"consentName": "ZGODA2",
"consentAccept": false,
"agreementDate": 1391167515789,
"ip":"192.168.7.139",
"optOut": true,
"consentDescriptionId": 345678
}
]
}
Kontakt dodajemy wywołując metodę:
https://www.salesmanago.pl/api/contact/upsert
Podstawowe elementy jakie można podać dodając nowy kontakt w strukturze to:
| Pole | Max. długość | Opis |
|---|---|---|
| async | true/false | parametr określający sposób dodawania kontaktów do systemu Salesmanago, rekomendowaną i domyślną opcją jest wartość “true”, która wykonuje proces z opóźnieniem zależnym od obciążenia systemu, jeżeli natomiast wymagane jest dodawanie kontaktów natychmiast po wysłaniu żądania należy wybrać opcję “false”. |
| name | 255 | nazwa kontaktu |
| email* | 254[?] | email kontaktu |
| phone | 255 | numer telefonu |
| fax | 255 | numer fax |
| company | 255 | firma kontaktu |
| externalId | 255 | zewnętrzne ID kontaktu |
| state | CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN | status 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ń) |
| useApiDoubleOptIn** | true/false | opcjonalny identyfikator szablonu dla double-opt-in, domyślnie false |
| lang** | 255 | język kontaktu |
| apiDoubleOptInEmailTemplateId** | 255 | opcjonalny identyfikator szablonu dla double-opt-in, |
| apiDoubleOptInEmailAccountId** | 255 | opcjonalny identyfikator konta e-mail dla double-opt-in, |
| apiDoubleOptInEmailSubject** | 255 | opcjonalny temat wiadomości dla double-opt-in, |
| address | 255 | adres kontaktu |
| streetAddress | 255 | ulica i numer domu |
| zipCode | 255 | kod pocztowy |
| city | 255 | miasto |
| country | 255 | kraj |
**W przypadku użycia flagi useApiDoubleOptIn, należy wybrać jedną z dwóch możliwości:
- uzupełniony parametr lang
- wszystkie trzy parametry apiDoubleOptInEmailTemplateId, apiDoubleOptInEmailAccountId i apiDoubleOptInEmailSubject.
Dodatkowo do zapytania należy dołączyć informację o właścicielu kontaktu (koncie do którego kontakt zostanie przypisany):
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
Opcjonalnie możemy zmienić adres e-mail kontaktu. Należy wtedy wypełnić pole newEmail:
| Pole | Max. długość | Opis |
|---|---|---|
| newEmail | 254[?] | nowy adres email (jeżeli chcemy go zmodyfikować) |
W przypadku nowych kontaktów pole „newEmail” zostanie zignorowane. Nowym kontaktom zostanie przypisany adres zgodny z danymi w polu: „email”.
Możemy również wymusić tzw. opt-in/opt-out kontaktu. Należy wtedy wypełnić pole forceOptIn lub forceOptOut.
W przypadku braku tych pól kontakt zostanie stworzony w systemie ze statusem opt-in.
| Pole | Max. długość | Opis |
|---|---|---|
| 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) |
W zapytaniu istnieje możliwość oznaczenia kontaktu tagami i usunięcia obecnych tagów.
Tagi przesyłamy jako tablica łańcuchów tekstowych w polu tags.
| Pole | Max. długość | Opis |
|---|---|---|
| tags | 255/tag | tablica tagów kontaktu |
| removeTags | 255/tag | tablica tagów do usunięcia |
Budując zapytanie „Upsert” nie zaleca się umieszczania w jego strukturze polecenia dodawania i usuwania tego samego tagu w tym samym requeście (zapytaniu), gdyż spowoduje to całkowite usunięcie tagu. Aby zaktualizować tag, należy w pierwszym requeście usunąć wybrany tag, a w drugim, osobnym zapytaniu dodać ten tag celem jego aktualizacji.
Istnieje również możliwość przypisać do kontaktu dowolną liczbę pól definiowanych przez użytkownika. Przesyłamy ją za pomocą mapy:
| Pole | Max. długość | Opis |
|---|---|---|
| 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, DATE | typ |
| value | 255 | liczba całkowita większa od 0, dla typu DATE timestamp, z godziną ustawioną na 00:00:00 czasu UTC |
| consentName | 255 | nazwa zgody (UWAGA - zgoda musi istnieć w systemie), |
| consentAccept | true/false | wartość logiczna zgody (true lub false), |
| agreementDate | timestamp | data wyrażenia zgody (jako wartość w ms - w razie braku pola użyta zostanie aktualna data), |
| ip | 255 | adres IP kontaktu, |
| optOut | true/false | wartość logiczna wypowiedzenia zgody (true lub false) |
| consentDescriptionId | true/false | identyfikator opisu zgody |
Rezultat zapytania:
{
"contactId" : "21c252a6-6de0-436b-bae8-9d0142363266",
"message" : [],
"success" : true,
"externalId": null
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
contactId – to unikatowy identyfikator uaktualnionego lub nowo dodanego kontaktu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
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) |
| 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
}
],
"incomingEmailMessages": [
{
"subject": "Temat",
"date": 1479209971000
}
],
"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
incomingEmailMessages – nadchodzące wiadomości email
subject – temat wiadomości
date – planowana data wysłania
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 dla danego właściciela
Przykładowa struktura danych zapytania:
{
"apiKey" : "your-api-key-123",
"clientId" : "your-client-id-123",
"contactId" : [ "123-XYZ" ],
"owner" : "admin@vendor.pl",
"requestTime" : 1329128188409,
"sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}
Kontakty po ID eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/listById
Pola dostępne w zapytaniu metody listById:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| contactId* | 255 | tablica identyfikatorów eksportowanych kontaktów ( max 50 kontaktów na raz ) |
Rezultat zapytania przesyłany jest w odpowiedzi jako struktura JSON identyczna z wcześniejszym zapytaniem.
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
}
]
}
},
{
"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.
Zapominanie kontaktu
Przykładowa struktura danych zapytania:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"email" : "test@salesmanago.pl",
"owner" : "admin@vendor.pl"
}
Kontakt zapominamy wywołując metodę:
https://www.salesmanago.pl/api/contact/forget
Kontakt można oznaczyć jako zapomniany.
Pola dostępne w zapytaniu metody forget:
| Pole | Max. długość | Opis |
|---|---|---|
| email* | 254[?] | email kontaktu, który zostanie zapomniany |
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
Rezultat zapytania:
{
"success": true,
"message": [],
"result": "Contact forgotten"
}
W rezultacie zapytania otrzymujemy:
success - wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message - tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result - resultat procesu
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
Stronicowana lista ostatnio modyfikowanych kontaktów
Przykładowa struktura danych zapytania:
{
"clientId": "jaco",
"apiKey": "jaco",
"requestTime": 1481206581347,
"sha": "627e5189c02a73bb37dd660caefb8a75c5b128b3",
"owner": "admin@admin.pl",
"from" : 0,
"to": 100000000000000,
"page" : 1,
"size" : 2
}
Kontakty podzielone na części eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/paginatedModifiedContacts
Pola dostępne w zapytaniu metody paginatedModifiedContacts:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | mail użytkownika |
| from* | timestamp(ms) | data modyfikacji (ms), od której nastąpi wyszukanie kontaktów |
| to* | timestamp(ms) | data modyfikacji (ms), do której będą wyszukiwane kontakty |
| page* | - | aktualnie zwracana strona wyników |
| size* | 1000 | rozmiar tablicy zwracanych wyników |
Rezultat zapytania:
{
"success": true,
"message": [],
"modifiedContacts": [
{
"id": "c10019fd-58f2-4a3b-8461-524dc9e8298c",
"email": "jaco@jaco.pl"
},
{
"id": "d256329b-736b-11e7-b8f0-f07959164fe8",
"email": "test.mokrysz+2073importdataurodzin@gmail.com"
}
],
"hasMore": true
}
W rezultacie zapytania otrzymujemy:
hasMore – (wartość logiczna) informuje czy czy są dostępne kolejne strony z wynikami
modifiedContacts – tablica obiektów kontaktów zawierająca pola ‘id’ i 'email’
id – identyfikator kontaktu
email – E-mail kontaktu
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"
}
Stronicowana lista kontaktów dla danego właściciela
Przykładowa struktura danych zapytania:
{
"clientId": "jaco",
"apiKey": "jaco",
"requestTime": 1481206581347,
"sha": "627e5189c02a73bb37dd660caefb8a75c5b128b3",
"owner": "admin@admin.pl",
"page": 1,
"size": 2
}
Kontakty podzielone na części eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/paginatedListById
Pola dostępne w zapytaniu metody paginatedListById:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | - | mail użytkownika |
| page* | - | aktualnie zwracana strona wyników |
| size* | 1000 | rozmiar tablicy zwracanych wyników |
Rezultat zapytania:
{
"success": true,
"message": [],
"contacts": [
{
"id": "c10019fd-58f2-4a3b-8461-524dc9e8298c",
"name": "jac jacek",
"email": "jaco@jaco.pl",
"phone": null,
"fax": null,
"score": 0,
"state": "PROSPECT",
"optedOut": false,
"optedOutPhone": false,
"deleted": false,
"invalid": false,
"company": null,
"externalId": null,
"address": null,
"birthdayYear": null,
"birthdayMonth": null,
"birthdayDay": null,
"province": "",
"mainContactOwner": "admin@admin.pl",
"contactVisits": [],
"contactTags": [
{
"tag": "TAG",
"tagName": "TAG",
"score": 1,
"createdOn": 1500625819000,
"tagWithScore": "TAG (1)"
}
],
"contactEvents": [],
"emailMessages": [],
"properties": [],
"contactFunnels": [],
"contactNotes": [],
"contactTasks": [
{
"id": "f5ada145-ebc8-4be0-bad5-3df34f3cfecd",
"note": "",
"date": 1499378400000,
"cc": "",
"reminder": 1499377500000
},
{
"id": "708aa28a-fd6a-44ea-9652-b88cf73496d4",
"note": "",
"date": 1499378400000,
"cc": "xyz@xyz.xyz",
"reminder": 1499376600000
}
],
"incomingEmailMessages": [],
"contactExtEvents": [],
"coupons": [],
"smsMessages": [],
"modifiedOn": 1500626587000,
"createdOn": 1500559084000
},
{
"id": "d256329b-736b-11e7-b8f0-f07959164fe8",
"name": "test.mokrysz+2073importdataurodzin@gmail.com",
"email": "test.mokrysz+2073importdataurodzin@gmail.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": "admin@admin.pl",
"contactVisits": [],
"contactTags": [],
"contactEvents": [],
"emailMessages": [],
"properties": [],
"contactFunnels": [],
"contactNotes": [],
"contactTasks": [],
"incomingEmailMessages": [],
"contactExtEvents": [],
"coupons": [],
"smsMessages": [],
"modifiedOn": 1501229258000,
"createdOn": 1501229258000
}
],
"hasMore": true
}
W rezultacie zapytania otrzymujemy:
hasMore – (wartość logiczna) informuje czy są dostępne kolejne strony rezultatów
Rezultat zapytania przesyłany jest w odpowiedzi jako struktura JSON identyczna z wcześniejszym zapytaniem.
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 (zalecana)
Przykładowa struktura zapytania rejestrującego nowe zdarzenie:
{
"clientId":"your-client-id-123",
"apiKey":"your-api-key-123",
"requestTime":1356180568127,
"sha":"3e4ec39722326150aae60f41e038d1def4450f46",
"owner":"admin@vendor.pl",
"email":"konrad@benhauer.com",
"contactEvent":{
"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 dodania zdarzenia wykonujemy metodę:
https://www.salesmanago.pl/api/v2/contact/addContactExtEvent
Pola dostępne w zapytaniu metody addContactExtEvent:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| email*/contactId* | 254[?] | adres e-mail kontaktu lub identyfikator kontaktu |
| 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, CANCELLATION, RETURN, SURVEY, APP_STATUS, APP_TYPE_WEB, APP_TYPE_MANUAL, APP_TYPE_RETENTION, APP_TYPE_UPSALE, LOAN_STATUS, LOAN_ORDER, FIRST_LOAN, REPEATED_LOAN |
| 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 dodanego zdarzenia
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
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 i jeden dzień |
| 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ładowa struktura danych zapytania:
{
"clientId":"vgqgnhyxnk46va7s",
"apiKey":"api_key_code",
"requestTime":1488803352992,
"sha":"0fd94b6bcf9d97dc79df6951575ebdeaf4617c96",
"email":"test@test.com",
"owner":"test@owner.pl",
"tag":"Tag",
"lang":"PL",
"apiDoubleOptInEmailTemplateId":"",
"apiDoubleOptInEmailAccountId":"",
"apiDoubleOptInEmailSubject":""
}
W celu wysłania maila potwierdzającego subskrypcję poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/email/sendConfirmation
Metoda sendConfirmation ma na celu wysłanie wiadomości potwierdzającej subskrypcję (znane w systemie jako doubleOptIn) dla podanego w zapytaniu kontaktu (email). Wiadomość zostanie wysłana do kontaktów które istnieją oraz nie posiadają już statusu OptIn. Opcjonalnym kryterium jest dodanie tagu (pole “tag”), który musi posiadać kontakt by zostało wysłane potwierdzenie.
Pola dostępne w zapytaniu metody sendConfirmation:
| Pole | Max. długość | Opis |
|---|---|---|
| email* | 254[?] | email kontaktu |
| owner* | 255 | email właściciela kontaktu |
| tag | 255 | opcjonalny parametr definiujący tag który musi posiadać kontakt by został do niego wysłany e-mail potwierdzający |
| lang** | 255 | język wysyłanej wiadomości email |
| apiDoubleOptInEmailTemplateId** | 255 | opcjonalny identyfikator szablonu dla double-opt-in, |
| apiDoubleOptInEmailAccountId** | 255 | opcjonalny identyfikator konta e-mail dla double-opt-in, |
| apiDoubleOptInEmailSubject** | 255 | opcjonalny temat wiadomości dla double-opt-in |
**Należy wybrać jedną z dwóch możliwości:
- uzupełniony parametr lang
- wszystkie trzy parametry apiDoubleOptInEmailTemplateId, apiDoubleOptInEmailAccountId i apiDoubleOptInEmailSubject.
Rezultat zapytania
{
"success":true,
"message":["Contact exists - confirmation email sent"],
"contactExists":true,
"contactId":"4850e968-45fa-4910-bf8c-0d2cfdbaa42b"
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd/rezultat zapytania
contactExists – wartość logiczna informująca czy dany kontakt istnieje w bazie
contactId – identyfikator kontaktu
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 stworzonych wiadomości
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"owner": "admin@vendor.pl"
}
W celu pobrania stworzonych wiadomości należy skorzystać z metody:
https://www.salesmanago.pl/api/email/messages
Pola dostępne w zapytaniu metody /api/email/messages:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | email użytkownika |
Rezultat zapytania
{
"success": true,
"message": [],
"standardMessages": [
{
"id": "f98243e0-fe89-4a71-88c3-2b966505cde8",
"name": "Message1",
"subject": "Subject 1",
"createdOn": 1515594292000,
"shared": false,
"emailAccountId": "11f2a086-1bcb-47eb-943c-4de682b39536",
"templateId": "402b6894-3cce-4117-9a36-8bb7f3344de1",
"userAccountId": "3373ad25-d13a-484c-a24d-d37ba3d5cce0",
"modifiedOn": 1515594292000,
"campaign": "default",
"notVisibleOnList": false,
"dynamic": false,
"ignoreLimits": false,
"emailCreator": false
},
{
"id": "639e5c7c-1589-4fb3-92d9-e126434c7603",
"name": "Message 2",
"subject": "Subject 2",
"createdOn": 1515595800000,
"shared": false,
"emailAccountId": "11f2a086-1bcb-47eb-943c-4de682b39536",
"templateId": "32d60879-5049-4f97-97d5-1a7a8843355c",
"userAccountId": "3373ad25-d13a-484c-a24d-d37ba3d5cce0",
"modifiedOn": 1515595800000,
"campaign": "",
"notVisibleOnList": false,
"dynamic": false,
"ignoreLimits": false,
"emailCreator": true
}
]
}
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
standardMessages - lista stworzonych wiadomości z następującymi parametrami:
id - identyfikator wiadomości
name - nazwa wiadomości
subject - temat wiadomości
createdOn - data stworzenia wiadomości ( Timestamp )
shared - wartość logiczna informująca o współdzieleniu wiadomości (współdzielona / niewspółdzielona)
emailAccountId - identyfikator konta wysyłkowego, do którego jest przypisana wiadomość
templateId - identyfikator szablonu wiadomości
userAccountId - identyfikator konta użytkownika, ktory stworzył wiadomość
modifiedOn - data ostatniej modyfikacji wiadomości ( Timestamp )
campaign - nazwa kampanii
notVisibleOnList - wartość logiczna informująca o widoczności wiadomości na standardowej liście (widoczna / niewidoczna)
dynamic - wartość logiczna informująca o tym, czy wiadomość jest dynamiczna (dynamiczna / niedynamiczna)
ignoreLimits - wartość logiczna informująca, czy wiadomość ignoruje filtry wysyłek (ignoruje / nie ignoruje)
emailCreator - wartość logiczna informująca, czy wiadomość została stworzona z kreatora
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
Pobieranie masowych konwersacji emaili bezpośrednich
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/massDirectConversationList
Pola dostępne w zapytaniu metody massDirectConversationList:
| 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
Pobieranie statystyk konwersacji
Przykładowa struktura danych zapytania:
{
"clientId": "client-id-123",
"apiKey": "api-key-123",
"sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
"requestTime":1327056031488,
"user": "user@user.com",
"conversationId": "dc4ef436-3d1b-4a85-b061-77236b1766e1"
}
W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/email/conversationStatistics
Pola dostępne w zapytaniu metody conversationStatistics:
| 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"
}
Przykład struktury wyeksportowanych danych dla /api/email/conversationStatistics:
{
"conversationId": "example_id_123",
"name": "Name",
"subject": "Subject",
"sentMessage": 2,
"openedMessage": 2,
"uniqueOpens": 2,
"clickedMessage": 1,
"uniqueClicks": 1,
"errorMessage": 0,
"softBounce": 0,
"hardBounce": 0,
"resigned": 0,
"dateSent": 1536748629000,
"openedBy": [
{
"email": "example_email_1@test.pl",
"contactId": "78376c41-b78a-4c68-a4ac-dcc638c90ede",
"externalId": "externalId_1",
"dateOpened": 1536752109000,
"dateClicked": 1536752229000,
"bounce": null,
"optedOut": false
},
{
"email": "example_email_2@test.pl",
"contactId": "f761f4d7-d833-4ff4-80c8-b104fc662f9c",
"externalId": null,
"dateOpened": 1536752109000,
"dateClicked": null,
"bounce": null,
"optedOut": false
}
],
"clickedBy": [
{
"email": "example_email_1@test.pl",
"contactId": "78376c41-b78a-4c68-a4ac-dcc638c90ede",
"externalId": "externalId_1",
"dateOpened": 1536752109000,
"dateClicked": 1536752229000,
"bounce": null,
"optedOut": false
}
],
"softBouncedBy": null,
"hardBouncedBy": null,
"resignedBy": null
}
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 SMS
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
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 wysyłki web push
Przykładowa struktura danych zapytania:
{
"apiKey": "our-api-key-123",
"clientId" : "your-client-id-123",
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"requestTime" : 1327059355361,
"wizardId": 23657
}
W celu pobrania statystyk wysyłki web push należy skorzystać z metody:
https://www.salesmanago.pl/api/web/push/stats
Pola dostępne w zapytaniu metody web/push/stats:
| Pole | Max. długość | Opis |
|---|---|---|
| wizardId* | 255 | identyfikator wysyłki |
Rezultat zapytania:
{
"success": true,
"message": [],
"name": "webpush name",
"date": 1590582123218,
"totalSent": 44,
"anonymousSent": 35,
"totalOpened": 12,
"totalClicked": 5,
"richWebPushOpened": 2,
"richWebPushClicked": 2,
"sent": [
"test1@gmail.com",
"test2@gmail.com",
"test3@gmail.com",
"test4@gmail.com",
"test5@gmail.com",
"test6@gmail.com",
"test7@gmail.com",
"test8@gmail.com",
"test9@gmail.com"
],
"opened": [
"test1@gmail.com",
"test2@gmail.com",
"test3@gmail.com",
"test4@gmail.com",
"test5@gmail.com"
],
"clicked": [
"test1@gmail.com",
"test2@gmail.com"
]
}
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 powiadomienia web push
date - data wysłania powiadomienia web push
totalSent - liczba wysłanych web pushy
anonymousSent - liczba wysłanych web pushy do kontaktów anonimowych
totalOpened - liczba otwarć
totalClicked - liczba kliknięć
richWebPushOpened - liczba otwarć powiadomień rich web push
richWebPushClicked - liczba kliknięć w powiadomienia rich web push
sent - lista adresów email, kontaktów, do których wysłano web push
opened - lista adresów email, kontaktów, które otworzyły web push
clicked - lista adresów email, kontaktów, które kliknęły w 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 oglądane produkty
Przykładowa struktura danych zapytania:
{
"clientId": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"contactUuid": "170675fb1b0-56e5eec9cf80-7a8a851e-b0d145fc-b61bb5fc-bcced77f3c28",
"shopName": "dataSource"
}
Ostatnio oglądane produkty pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/lastViewed
Pola dostępne w zapytaniu metody lastViewed:
| Pole | Max. długość | Opis |
|---|---|---|
| contactUuid* | 255 | wartość ciasteczka smuuid |
| 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
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": "your-client-id-123",
"apiKey": "salesmanago",
"requestTime": 1481543324302,
"sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
"productId": 207,
"shopName": "dataSource"
}
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* | 255 | nazwa źródła danych |
| productId* | 255 | id produktu |
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
API - Vision
Rekomendacje produktów oparte o SALESmanago Cinderella AI
Przykładowa struktura danych zapytania:
{
"clientId" : "your-client-id-123",
"apiKey" : "your-api-key-123",
"requestTime":1611512104000,
"sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
"urlImg":"https://urlimg.com/name.jpg",
"vendorDataSourceIntId":123
}
Rezultat zapytania:
{
"success": true,
"message": [],
"vision": {
"status": "ok",
"photo": "https://urlimg.com/name.jpg",
"result": [
{
"id": "123",
"score": 0.3589041829109192
},
{
"id": "456",
"score": 0.34405747056007385
},
{
"id": "789",
"score": 0.3198060393333435
}
],
"bq_errors": 0
}
}
Rekomendacje produktów oparte na SALESmanago Cinderella AI pobieramy korzystając z metody:
https://www.salesmanago.pl/api/vision
Pola dostępne w zapytaniu metody vision:
| Pole | Max. długość | Opis |
|---|---|---|
| urlImg* | 255 | url wyszukiwanego zdjęcia |
| vendorDataSourceIntId* | 255 | id feeda produktowego - jest dostępne w ustawienia > integracja > feedy produktowe |
W rezultacie zapytania otrzymujemy:
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
status - status wyszukiwania
photo - url wyszukiwanego zdjęcia
result - wyniki wyszukiwania
id - id produktu
score - procent dopasowania
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.
Integracja Frontend
Przy użyciu zdarzeń zewnętrznych (external events) możemy przesyłać do systemu SALESmanago dodatkowe informacje na temat kontaktów z zewnętrznych systemów. Najpopularniejszym sposobem wykorzystania zdarzeń zewnętrznych w branży eCommerce jest przesyłanie informacji o dokonanym zakupie (PURCHASE) lub porzuconym koszyku (CART) przez kontakt. Dzięki tym informacjom możemy np.:
- gromadzić dane transakcyjne, wykorzystywane w panelu analitycznym Analityka eCommerce,
- rozpocząć działania mające na celu ratowanie porzuconego koszyka,
- wysłać wiadomość z podziękowaniem za dokonanie zakupu,
- ustawić zaawansowaną segmentację kontaktów ze względu na wartość dokonywanych zakupów.
Oczywiście istnieją inne rodzaje zdarzeń zewnętrznych, które można wykorzystać i dostosować do własnych potrzeb. Są to:
- WIZYTA (VISIT)
- ROZMOWA TELEFONICZNA (PHONE_CALL);
- REZERWACJA (RESERVATION),
- ODWOŁANIE (CANCELED)
- AKTYWACJA (ACTIVATION)
- SPOTKANIE (MEETING)
- OFERTA (OFFER)
- POBRANIE (DOWNLOAD)
- LOGOWANIE (LOGIN)
- TRANSAKCJA (TRANSACTION)
- INNE (OTHER).
Zdarzenia zewnętrzne można przesyłać poprzez API. Informacje o tym znajdują się w naszej specyfikacji.
Drugim sposobem przesyłania zdarzeń zewnętrznych jest możliwość przesyłania ich poprzez JavaScript.
Wówczas nie musimy przekazywać tych danych przez API.
Metoda nie jest rekomendowana. Zalecamy stosowanie metody addContactExtEvent.
Przesyłanie zdarzeń zewnętrzynch przez JavaScript
[Krok 1] Podmiana kodu monitorującego na swojej stronie – obecny kod należy podmienić na ten znajdujący się poniżej uzupełniając odpowiednio pole ” var _smid = ” swoim indywidualnym ID klienta.
Skrypt monitorujący:
<script type="text/javascript">
var _smid="SHORT_ID_TO_REPLACE";
(function(w, r, a, sm, s){
w['SalesmanagoObject']=r; w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)};
sm=document.createElement('script'); sm.type='text/javascript'; sm.async=true; sm.src=a;
s=document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(sm,s);
})(window,'sm',('https:'==document.location.protocol?'https://':'http://')+'endpoint/static/sm.js');
</script>
Endpoint oraz indywidualne ID klienta znajduje się w zakładce USTAWIENIA -> INTEGRACJE-> Dostęp przez API.
[Krok 2] Raportowanie konkretnego zdarzenia – każde zewnętrzne zdarzenie możemy raportować w następujący sposób.
Skrypt raportujący zdarzenie:
<script type="text/javascript">
var d = new Date();
sm('extEvent',
{ owner: '******@******.pl',//TU PROSZĘ UZUPEŁNIĆ KONTO UŻYTKOWNIKA W SYSTEMIE
email: 'nowyevent1@test.pl',//EMAIL KONTAKTU
contactExtEventType:"PURCHASE",//TYP ZDARZENIA
date: d.getTime(),//DATA ZDARZENIA
description: 'description about transaction',//OPIS ZDARZENIA
products: 'p01, p02, p03',//PRODUKTY
location: 'location',//LOKALIZACJA
value: 213.32,//WARTOŚĆ (TYLKO CYFRY)
details: ['details', 'detail2'], //DETALE JAKO TABLICA(maks 20)
externalId: 'zam' + d.getTime()}//ZEWNĘTRZNE ID
);
</script>
Pola dostępne w skrypcie raportującym:
| Pole | Max. długość | Opis |
|---|---|---|
| owner* | 255 | właściciel kontaktu (email konta użytkownika SALESmanago) |
| email*/contactId* | 254[?] | adres e-mail kontaktu lub identyfikator kontaktu |
| contactExtEventType* | 255 | typ zdarzenie, dopuszczalne wartości: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION, CANCELLATION, RETURN, SURVEY, APP_STATUS, APP_TYPE_WEB, APP_TYPE_MANUAL, APP_TYPE_RETENTION, APP_TYPE_UPSALE, LOAN_STATUS, LOAN_ORDER, FIRST_LOAN, REPEATED_LOAN |
| 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) |
| detail1-20 | 255/detal | opcjonalne detale zdarzenia, |
| externalId | 255 | opcjonalne ID zdarzenia np. ID z systemu kasowego itp. |
Integracja zdarzeń zewnętrznych typu koszyk
Do przekazania tego typu danych używamy metod addContactExtEvent oraz updateContactExtEvents. Identyfikatory produktów dodawanych do koszyka należy przechowywać w polu products. Najbardziej optymalną metodą jest przekazanie całej zawartości koszyka przy pomocy jednego zapytania – produkty oddzielając przecinkami lub średnikami. Można również raz wykonać metodę addContactExtEvent zapisując zwrócony rezultat (eventId) – przy kolejnym dodaniu tylko aktualizować listę produktów (przy użyciu metody updateContactExtEvent oraz wspomnianego eventId).
Zapytanie addContactExtEvent można wykonywać na dwa sposoby:
- przy użyciu adresu email,
- przy użyciu contactId (wartości z ciasteczka smclient, którą można wyciągnąć np: przy użyciu javascript).
Tych dwóch sposobów nie można używać łącznie - nie można też dodawać zdarzeń zewnętrznych dla kontaktów niezidentyfikowanych.
Dodatkowo scenariusz, gdy niemonitorowany (brak smclient oraz maila) - dodaje produkty do koszyka:
Należy wtedy takie produkty trzymać po stronie sklepu (np. w sesji) - i od razu w momencie zidentyfikowania kontaktu przekazać produkty do salesmanago z użyciem metody addContactExtEvent.
Monitorowanie zdarzeń AJAX/JavaScript
SALESmanago pozwala obok samych wizyt rejestrować zdarzenia JavaScript – np. otwarcia tzw. zakładek czy pobrania plików.
Aby zarejestrować zdarzenie zewnętrzne należy w skrypcie JavaScript na naszej stronie wywołać metodę SALESmanago:
smEvent(eventName)
gdzie:
eventName to nazwa zdarzenia np. „detale-lokata”, „detale-kredyt”.
należy takie zdarzenie podpiąć pod konkretne elementy, które chce się monitorować, np.:
<a href="download.pdf" onclick="smEvent('PDF-download');return true;">download</a>