Informacje ogólne

Do czego możesz wykorzystać API SALESmanago?

API SALESmanago jest jednym z wielu sposobów na zintegrowanie strony eCommerce lub innego oprogramowania z SALESmanago. Jak każde inne połączenie API, korzystanie z API SALESmanago wymaga przynajmniej podstawowej wiedzy technicznej, a do bardziej zaawansowanych integracji potrzebne jest głębsze zrozumienie zagadnień programistycznych.

Dane autoryzacyjne

{
  "clientId":"your-client-id-123",
  "apiKey":"your-api-key-123",
  "requestTime":1327056031488,
  "sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c"
}

Autentykacja

API SALESmanago jest otwarte dla naszych klientów, co oznacza, że każdy klient może się z nim zintegrować bez dodatkowych opłat. Aby zacząć korzystać z naszego API, musisz najpierw uzyskać dane autentykacyjne:

clientId – Twój identyfikator klienta, który można znaleźć w SALESmanago ➔ Centrum Integracji ➔ API (zakładka API v2).
apiKey – dowolny losowy ciąg znaków.
sha – wartość wygenerowana na podstawie sha1(apiKey+clientId+apiSecret), gdzie znak plusa służy do konkatenacji. Wartość apiSecret jest unikalna dla każdego klienta, znajdziesz ją we wspomnianej wcześniej zakładce API v2.

Wszystkie żądania muszą także zawierać requestTime – UNIX-owy znacznik czasu (timestamp) w milisekundach.

Szczegóły techniczne

Wszystkie endpointy mają następującą strukturę adresu:
https://xxx.salesmanago.pl/api
gdzie xxx to identyfikator twojego serwera SALESmanago (w większości przypadków będzie to www, app2 albo app3).

Wszystkie żądania są wysyłane przy użyciu metody HTTP POST i są enkapsulowane w formacie JSON. W związku z tym wymagane są następujące nagłówki:
Accept: application/json, application/json
Content-Type: application/json;charset=UTF-8
Większość bibliotek HTTP samodzielnie dołącza te nagłówki, gdy w treści żądania wysyłany jest obiekt JSON.

Integracja kodu monitorującego

Kod Monitorujący jest odpowiedzialny za monitorowanie Kontaktów na twojej stronie internetowej, dlatego jego wdrożenie jest szczególnie zalecane. Aby Kod Monitorujący nie wpływał na wydajność twojej strony internetowej, wszystkie skrypty JavaScript są ładowane asynchronicznie już po załadowaniu strony.

alt text

Kod Monitorujący możesz znaleźć w SALESmanago ➔ Centrum Integracji ➔ Kod Monitorujący. Skrypt ten powinien zostać dodany do witryny tuż przed znacznikiem zamykającym </body>. Jeśli twoja strona została stworzona na zamówienie, dodanie kodu do szablonu strony powinno być łatwe. Jeśli strona jest oparta na oprogramowaniu innych firm, spróbuj wyszukać hasło “[nazwa platformy] add custom javascript”. Kod Monitorujący możesz też dodać, używając Google Tag Manager (GTM). Aby to zrobić, zaloguj się do SALESmanago, a następnie przejdź to Centrum Integracji ➔ Kod Monitorujący i kliknij przycisk w sekcji Użyj Google Tag Manager (GTM).

Sprawdzanie poprawności pola e-mail

Adres e-mail może mieć maksymalnie 254 znaki. Według standardu RFC882 system weryfikuje, czy adres zawiera maksymalnie 64 znaki przed symbolem @ oraz poprawną domenę internetową po nim.

Przesyłanie dodatkowych informacji monitorujących

Przykładowy kod wraz z wartością contactId:

<script type="text/javascript">  
    var _smid = "your-client-id-123";
    var _smclientid = "contactIdFromResponse-123";
</script>
<script src="https://www.salesmanago.pl/static/sm.js" type="text/javascript"/>

Alternatywnie, przesyłając formularz przez AJAX można zapisać samo ciasteczko:

    $.ajax({
        type:'POST',
        url:'/account/registerDemoVideo.htm',
        data:$("#registerForm").serialize(),
        cache:false,
        timeout:240000,
        success:function (data) {
            if (data == 'Wrong_Email') {
                alert('Podany email nie jest prawidłowy.');
                $("#email").focus();
            } else {
                createCookie('smclient', data, 365 * 10);
                $(".registeredInfo").show();
            }
        },
        error:function (data) {
            alert("Błąd – nie udało się zarejestrować");
        }});

W odpowiedzi na zapytanie /contact/upsert otrzymujemy unikatowy identyfikator. Aby usprawnić monitoring zachowania użytkowników na stronie WWW należy ten parametr przekazać przynajmniej na jednej podstronie odwiedzanej przez użytkownika – np. po zalogowaniu – w momencie logowania wykonujemy zapytanie /contact/upsert a otrzymaną wartość contactId drukujemy wraz z kodem JavaScript systemu monitorowania SALESmanago.

API - Zarządzanie kontaktami

Dodawanie nowego lub modyfikacja istniejącego kontaktu

Przykładowe żądanie z podstawowymi danymi:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "contact": {
    "email": "name@example.com",
    "phone": "+15554443322",
    "name": "John Doe",
    "externalId": "U12345",
    "address": {
      "streetAddress": "Main Street 21",
      "zipCode": "90210",
      "city": "San José",
      "country": "US"
    }
  },
  "province": "California",
  "birthday": "19870605",

  "forceOptIn": true,
  "forceOptOut": false,
  "forcePhoneOptIn": false,
  "forcePhoneOptOut": true,

  "tags": [
    "T_SHIRTS",
    "SWEATERS",
    "UPSELL"
  ],
  "removeTags": [
    "FIRST_PURCHASE"
  ]
 }

Przykładowe zaawansowane żądanie:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "contact": {
    "email": "name@example.com",
    "phone": "+15554443322",
    "fax" : "+15551112233",
    "name": "John Doe",
    "externalId": "U12345",
    "state" : "PROSPECT",
    "address": {
      "streetAddress": "Main Street 21",
      "zipCode": "90210",
      "city": "San José",
      "country": "US"
    }
  },
  "province": "California",
  "birthday": "19870605",

  "forceOptIn": true,
  "forceOptOut": false,
  "forcePhoneOptIn": false,
  "forcePhoneOptOut": true,
  "useApiDoubleOptIn": true,
  "doubleOptInLanguage": "ES",

  "newEmail": "new.email@example.com",

  "tags": [
    "T_SHIRTS",
    "SWEATERS",
    "UPSELL"
  ],
  "removeTags": [
    "FIRST_PURCHASE"
  ],

  "properties": {
    "t_shirt_size": "XL",
    "gender": "Male"
  },
  "dictionaryProperties": [
    {
      "name": "member_since",
      "type": "DATE",
      "value": 1459938888000
    },
    {
      "name": "shoe_size",
      "type": "NUMBER",
      "value": 10
    }
  ],

  "consentDetails": [
    {
      "consentName": "TERMS_OF_SERVICE",
      "consentAccept": true,
      "agreementDate": 1659938888000,
      "ip": "192.168.0.1",
      "optOut": false,
      "consentDescriptionId": 1234
    },
    {
      "consentName": "PHYSICAL_MAIL",
      "consentAccept": false,
      "agreementDate": 1659938888000,
      "ip": "192.168.0.1",
      "optOut": true,
      "consentDescriptionId": 5678
    }
  ]
}

Przykładowa odpowiedź


{
  "contactId" : "1a2b-...-3c4d",
  "message" : [],
  "success" : true,
  "externalId": "U12345"
}

Możesz dodać lub zmodyfikować kontakt używając metody API:
https://www.salesmanago.pl/api/contact/upsert

Podstawowe pola:

Jedynymi obowiązkowymi polami są pola autentykacyjne, pole owner oraz adres e-mail Kontaktu. Jednak, aby w pełni wykorzystać potencjał SALESmanago, możesz przesłać więcej danych o Kontakcie. Wykorzystasz je potem w Procesach Automatyzacji, personalizacji, segmentacji i innych funkcjonalnościach.

Pole	Max. długość	Opis
owner*	255	Właściciel kontaktu (e-mail konta użytkownika SALESmanago)
contact	obiekt	Obiekt zawierający podstawowe dane o Kontakcie
name	255	Nazwa Kontaktu
email*	254^[?]	E-mail Kontaktu
contactId	UUID	Identyfikator Kontaktu z SALESmanago, który otrzymasz w odpowiedzi na każde żądanie z dodaniem lub aktualizacją Kontaktu. Jeśli identyfikujesz Kontakt używając `contactId`, pole `email` nie jest obowiązkowe.
phone	255	Numer telefonu Kontaktu
fax	255	Numer faksu Kontaktu
company	255	Firma Kontaktu
externalId	255	Zewnętrzne ID Kontaktu, na przykład ID użytkownika z platformy eCommerce
birthday	8	Data urodzenia Kontaktu, przekazywana jako łańcuch znaków w postaci:yyyyMMdd lub MMdd gdzie yyyy – czterocyfrowy rok, MM – dwucyfrowy miesiąc, dd – dwucyfrowy dzień
address	obiekt	Obiekt zawierający adres Kontaktu
streetAddress	255	Ulica i numer domu
zipCode	255	Kod pocztowy
city	255	Miasto
country	255	Kraj, rekomendowany format zapisu to kod alfa-2 standardu ISO 3166-1
province	255	Jednostka podziału terytorialnego w kraju, np. Małopolskie

Zgody wyrażone przez Kontakt:

Nowe Kontakty są domyślnie dodawane do SALESmanago z wyrażoną zgodą na E-mail Marketing, ale bez zgody na Mobile Marketing. Jest to przydatne, kiedy integrujesz formularz zapisu na newsletter. Jeśli przesyłasz kontakty z innego formularza, gdzie wyrażenie zgód nie jest obowiązkowe pamiętaj o konieczności zmiany statusów zgód.

Pole	Max. długość	Opis
forceOptIn	true/false	Flaga oznaczająca wyrażenie zgody na E-mail Marketing
forceOptOut	true/false	Flaga oznaczająca wycofanie zgody na E-mail Marketing
useApiDoubleOptIn	true/false	Flaga wskazująca, czy status opt-in powinien być potwierdzony przy użyciu double opt-in. Dotyczy to tylko kontaktów zmieniających swój status na opt-in.
doubleOptInLanguage	255	Język kontaktu, który ma być użyty podczas wysyłania wiadomości double opt-in
forcePhoneOptIn	true/false	Flaga oznaczająca wycofanie zgody na Mobile Marketing
forcePhoneOptOut	true/false	Flaga oznaczająca wycofanie zgody na Mobile Marketing

Do SALESmanago możesz przesłać również inne typy zgód, np. Zgodę na warunki użytkowania systemu czy zgodę na tradycyjną korespondencję marketingową. Do tego celu wykorzystaj zgody, które zdefiniujesz w SALESmanago Ustawienia ➔ Inne ➔ Lista zgód. Tekst zgody możesz aktualizować, co utworzy jej nowszą wersję, która nadpisze tę istniejącą. SALESmanago zapisuje informację która wersja zgody została wyrażona/odrzucona przez Kontakt.
Za pomocą pól consentAccept i optOut możesz ustawić jeden z trzech statusów zgody na karcie kontaktu. W tym celu prześlij odpowiednie flagi consentAccept oraz optOut:

consentAccept=false, optOut=false – zgoda niepotwierdzona,
consentAccept=true, optOut=false – zgoda potwierdzona,
consentAccept=false, optOut=true – zgoda wycofana,
consentAccept=true, optOut=true – zgoda wycofana.

Jeżeli kontakt posiada już status zgody „potwierdzona” lub „wycofana” – nie można go zmienić na status zgody „niepotwierdzona”.

Pole	Max. długość	Opis
consentDetails	tablica obiektów	Tablica obiektów pozwalająca przesłać dodatkowe zgody wyrażone przez Kontakt. Każdy typ zgody musi zostać wcześniej zdefiniowany w SALESmanago Ustawienia ➔ Inne ➔ Lista zgód.
consentName	255	Nazwa zgody
consentAccept	true/false	Wartość logiczna zgody (true lub false)
agreementDate	UNIX timestamp [ms]	Data wyrażenia zgody. Jeśli jej nie prześlesz, jako data zgody zostanie przypisana domyślnie data bieżąca.
ip	255	Adres IP Kontaktu.
optOut	true/false	Wartość logiczna wycofania zgody (true lub false).
consentDescriptionId	true/false	Identyfikator opisu zgody. Znajdziesz go w SALESmanago Ustawienia ➔ Inne ➔ Lista zgód.

Dodatkowe szczegóły Kontaktu

Są 3 sposoby na przesłanie dodatkowych danych kontaktowych, które możesz wykorzystać w Procesach Automatyzacji, personalizacji, segmentacji i innych funkcjach. Wzbogać swoje dane poprzez:

1. Tagi – najbardziej podstawowe dodatkowe informacje. Mają tylko wartości, więc możesz przypisać wiele tagów w obrębie tego samego obszaru, np. DOG_FOOD, CAT_FOOD.
2. Szczegóły standardowe – bardziej rozbudowany rodzaj informacji dodatkowych. Szczegóły standardowe to pary danych tekstowych składające się z kluczy i wartości, np. nazwa szczegółu: kierunek_podrozy, wartość: Bułgaria, lub nazwa detalu: marka_samochodu, wartość: TESLA. Zarówno klucz, jak i wartość mogą mieć długość do 255 znaków. Nie muszą być one predefiniowane w SALESmanago.
3. Szczegóły słownikowe – podobne do szczegółów standardowych. Są to pary złożone z kluczy i wartości, z obsługą wartości liczbowych i dat, np. nazwa detalu: data_slubu, wartość 1653861600000, (czyli 30.05.2022), lub nazwa detalu: rozmiar_koszuli, wartość: 42. Szczegóły słownikowe są definiowane systemowo, co oznacza, że jeśli zdefiniujesz szczegół słownikowy dla jednego kontaktu, to pole szczegółu zostanie utworzone dla wszystkich kontaktów. Listę szczegółów słownikowych można zobaczyć w SALESmanago Ustawienia ➔ Inne ➔ Szczegóły słownikowe.

Pole	Max. długość	Opis
tags	255/tag	Tablica tagów dla Kontaktu Tagi mogą zawierać standardowe znaki alfabetu łacińskiego oraz znaki podkreślenia. Jeśli przesyłane tagi zawierają nieobsługiwane znaki, zostaną one automatycznie dostosowane do formatu obsługiwanego przez system. Znaki specjalne zostaną zastąpione znakiem podkreślenia (_), a znaki diakrytyczne zostaną zastąpione ich odpowiednikiem w alfabecie łacińskim.
removeTags	255/tag	Tablica tagów do usunięcia. Podanie tego samego tagu w obu tablicach spowoduje jego całkowite usunięcie.
properties	255/szczegół	Tablica szczegółów standardowych podanych jako pary klucz-wartość. Nie zaleca się używania znaków specjalnych, znaków diakrytycznych i spacji w nazwach szczegółów.
dictionaryProperties	tablica obiektów	Tablica obiektów zawierająca definicje szczegółów słownikowych. Szczegóły słownikowe mogą zawierać wartości liczbowe lub daty. Jeśli określisz szczegół słownikowy dla jednego kontaktu, szczegół zostanie zdefiniowany dla wszystkich kontaktów.
name	3-255	Nazwa szczegółu. Nie zaleca się używania znaków specjalnych, znaków diakrytycznych i spacji w nazwach szczegółów.
type	enum NUMBER, DATE	Typ szczegółu słownikowego: NUMBER lub DATE
value	255	Wartość szczegółu słownikowego. Dla typu NUMBER: Liczba całkowita większa od 0. Dla typu DATE: Wartość UNIX timestamp [ms].

Zaawansowane pola:

Pól zaawansowanych możesz użyć, aby zmienić adres e-mail lub stan Kontaktu, wysłać konkretny e-mail z potwierdzeniem subskrypcji lub zmienić sposób przetwarzania żądania.

Pole	Max. długość	Opis
newEmail	254^[?]	Nowy adres e-mail (jeżeli ma zostać zmodyfikowany). Zmiana adresu e-mail kontaktu jest możliwa wyłącznie, jeśli kontakt zostanie zidentyfikowany za pomocą obecnego adresu e-mail.
async	true/false	Parametr określający sposób dodania Kontaktu do SALESmanago. Domyślną i zalecaną wartością jest „true”, której wybór zainicjuje wykonanie procesu asynchronicznie. Oznacza to, że wartość contactId otrzymasz natychmiast, podczas gdy dane Kontaktu będą aktualizowane z niewielkim opóźnieniem. Jeśli zdecydujesz się przetwarzać Kontakt synchronicznie, twoje żądanie może zająć więcej niż 1000 ms.
state	enum CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN	Status Kontaktu (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
doubleOptInEmailId**	255	Opcjonalny identyfikator maila dla double opt-in

W rezultacie zapytania otrzymasz:


success - wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
contactId - unikatowy identyfikator Kontaktu. W większości przypadków ten identyfikator powinien zostać ustawiony w przeglądarce Kontaktu jako wartość ciasteczka smclient.
message - tablica dodatkowych informacji zawierająca komunikaty błędów
externalId - zewnętrzne ID Kontaktu
Flaga useApiDoubleOptIn jest nadrzędna nad flagą forceOptIn. Użycie useApiDoubleOptIn wraz z forceOptIn spowoduje, że forceOptIn zostanie zignorowane.

Asynchroniczne dodawanie lub modyfikacja wielu kontaktów na raz

Przykładowa struktura danych zapytania:

{
  "clientId": "your-client-id-",
  "apiKey": "your-api-key-",
  "requestTime": 1348046897664,
  "sha": "shacode",
  "owner": "admin@vendor.pl",
  "upsertDetails": [
    {
      "newEmail": null,
      "contact": {
        "email": "batchtest2@benhauer.pl",
        "name": "Konrad Test1",
        "phone": "+48123321123",
        "fax": "+48345543345",
        "company": "Benhauer Sp. z o.o. Sp. K.",
        "externalId": null,
        "state": "PROSPECT",
        "address": {
          "streetAddress": "Brzyczyńska 123",
          "zipCode": "43-305",
          "city": "Bielsko-Biała",
          "country": "PL"
        }
      },
      "relation" : {
        "type": "PARENT",
        "email": "child@test.pl"
      },
      "tags": [
        "API",
        "ADmanago"
      ],
      "removeTags": [
        "Test_tag",
        "New"
      ],
      "properties": {
        "custom.nickname": "Konri1",
        "custom.sex": "M"
      },
      "dictionaryProperties": [
        {
          "name": "birthday",
          "type": "DATE",
          "value": 1488927600000
        },
        {
          "name": "visits",
          "type": "NUMBER",
          "value": 42
        }
      ],
      "birthday": "19801017",
      "province": "Małopolska",
      "forceOptIn" : true,
      "forceOptOut" : false,
      "forcePhoneOptIn" : true,
      "forcePhoneOptOut" : false
    },
    {
      "contact": {
        "email": "batchtest1@benhauer.pl",
        "name": "Konrad Test2",
        "phone": "+48123321123",
        "fax": "+48345543345",
        "company": "Benhauer Sp. z o.o. Sp. K.",
        "externalId": null
      },
      "newEmail": "batchtestNew@benhauer.pl",
      "forceOptIn": true,
      "forceOptOut": false,
      "forcePhoneOptIn": true,
      "forcePhoneOptOut": false,
      "tags": [
        "API",
        "ADmanago"
      ],
      "properties": {
        "custom.nickname": "Konri2",
        "custom.sex": "M"
      },
      "consentDetails": [
        {
          "consentName": "ZGODA",
          "consentAccept": true,
          "agreementDate": 1391167515515,
          "ip":"192.168.7.139",
          "optOut": false,
          "consentDescriptionId": 1
        }
      ],
      "birthday": "19801017"
    }
  ],
  "useApiDoubleOptIn": true,
  "lang": "PL",
  "fireEvents": false

}

Rezultat zapytania:

{
  "success":true,
  "message":["Batch upsert added to execute."],
  "requestId":37
}

Przykładowy json ze statusem batchupserta:

{
  "clientId": "yourclientID",
  "apiKey": "yourAPIkey",
  "requestTime": 1500556989,
  "sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
  "owner": "admin@vendor.pl",
  "requestId": 37
}

Przykładowa odpowiedź:

{
  "success": true,
  "message": [],
  "fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}

Wiele kontaktów naraz dodajemy lub modyfikujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/batchupsertv2

W zapytaniu podajemy tablicę kontaktów w polu upsertDetails. Podstawowe elementy jakie można podać w elemencie tablicy contact można znaleźć powyżej w opisie metody upsert (patrz Dodawanie nowego lub modyfikacja istniejącego kontaktu).

Pola dostępne w zapytaniu metody batchupsertv2:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
upsertDetails*	1000	Tablica obiektów typu Kontakt
email*	254^[?]	email kontaktu, nowy gdy tworzymy kontakt, istniejący gdy modyfikujemy
name	255	nazwa kontaktu
phone	255	numer telefonu
fax	255	numer fax
company	255	firma kontaktu
state	CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN	status kontaktu
externalId	255	identyfikator zewnętrzny kontaktu
newEmail	254^[?]	nowy email kontaktu
birthday	yyyyMMdd/Mmdd	data urodzenia, przekazywana jako łańcuch znaków w postaci: yyyyMMdd lub Mmdd (yyyy – 4 cyfrowy rok, MM – dwucyfrowy miesiąc, dd – dwucyfrowy dzień)
province	255	województwo
streetAddress	255	ulica i numer domu
zipCode	255	kod pocztowy
city	255	miasto
country	255	kraj
forceOptOut	true/false	wymuszenie opt-out po dodaniu/modyfikacji
forceOptIn	true/false	wymuszenie opt-in po dodaniu/modyfikacji (o ile nie wybrano wcześniejszej opcji)
forcePhoneOptOut	true/false	wymuszenie opt-out z telefonu po dodaniu/modyfikacji
forcePhoneOptIn	true/false	wymuszenie opt-in na telefon po dodaniu/modyfikacji (o ile nie wybrano wcześniejszej opcji)
tags	255/tag	tablica tagów kontaktu
removeTags	255/tag	tablica tagów do usunięcia
properties	255/detal	definiowane przez użytkownika atrybuty kontaktu. Zaleca się nie stosować polskich znaków oraz spacji w nazwie, ale jest to dozwolone.
dictionaryProperties	-	definiowane przez użytkownika atrybuty słownikowe, po pierwszym dodaniu danego atrybutu można go wykorzystać dla pozostałych kontaktów poprzez ponowne podanie takiej samej nazwy i typu z przypisaną inną wartością.
name	255	nazwa
type	NUMBER lub DATE	typ
value	-	liczba całkowita większa od 0, dla typu DATE timestamp, z godziną ustawioną na 00:00:00 czasu UTC
useApiDoubleOptIn	true/false	użycie opcji double opt in, domyślnie true
lang	255	język kontaktu
fireEvents	true/false	Jeśli metoda jest ustawiona jako „false” zapobiega uruchamianiu reguł i Workflow wywołanych zdarzeniami utworzonymi w czasie upsertu kontaktów (import z nadpisywaniem i modyfikacją istniejących kontaktów).

Dla użytkowników z uprawnieniami do Contact relationship dodatkowo mamy dostępne pola:

Pole	Max. długość	Opis
relation	-	tworzy relację z podanym kontaktem
type	CHILD lub PARENT	rodzaj relacji
email	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:

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
    }
  ]
}

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
    }
  ]
}

Eksport kontaktów po adresie e-mail dla danego właściciela

Przykładowa struktura danych zapytania:

{ 
  "apiKey" : "your-api-key-123",
  "clientId" : "your-client-id-123",
  "email" : [ "****@gmail.com" ],
  "owner" : "admin@vendor.pl",
  "requestTime" : 1329128188409,
  "sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}

Kontakty eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/list

Pola dostępne w zapytaniu metody list:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
email*	254/email^[?]	tablica adresów email eksportowanych kontaktów ( max 50 kontaktów na raz )

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "contacts": [
    {
      "id": "99cdc5fe-7376-436e-acb5-7180c97dadb6",
      "name": "Konrad",
      "email": "your-contact-email@mail.com",
      "phone": "123456789",
      "fax": "987654321",
      "score": 775,
      "state": "PROSPECT",
      "optedOut": true,
      "optedOutPhone": false,
      "deleted": false,
      "invalid": false,
      "company": "Benhauer",
      "externalId": "externalId",
      "address": {
        "streetAddress": "Grzegórzecka 21",
        "zipCode": "",
        "city": "Kraków",
        "country": "Polska"
      },
      "birthdayYear": 2000,
      "birthdayMonth": 1,
      "birthdayDay": 1,
      "province": "Małopolska",
      "mainContactOwner": "admin@vendor.pl",
      "modifiedOn": 1479209074000,
      "createdOn": 1432887727000,
      "purchaseProbability": 0.3541016524943863,
      "contactVisits": [
        {
          "conversationIntId": null,
          "host": "10.10.10.10",
          "time": 1328050810504,
          "duration": null,
          "visitSource": "NEXT",
          "visitSourceHost": "salesmanago.pl",
          "visitSourceKeywords": null,
          "visitScore": 1,
          "url": "/test.htm",
          "location": null
        }
      ],
      "contactTags": [
        {
          "tag": "ADMANAGO",
          "tagName": "ADMANAGO",
          "score": 12,
          "createdOn": 1432887757000,
          "tagWithScore": "ADMANAGO (1)"
        }
      ],
      "contactEvents": [
        {
          "date": 1432887757000,
          "description": "Note",
          "detail1": null,
          "detail2": null,
          "detail3": null,
          "detail4": null,
          "detail5": null
        }
      ],
      "emailMessages": [
        {
          "name": "Email",
          "subject": "Temat",
          "date": 1479209121000,
          "sent": false,
          "dateSent": null,
          "opened": false,
          "dateOpened": null,
          "clicked": false,
          "dateClicked": null,
          "emailConversation": 25584162,
          "intId": null,
          "deliveryStatus": null
        }
      ],
      "properties": [
        {
          "name": "detail",
          "value": "detail-value"
        }
      ],
      "contactFunnels": [
        {
          "salesFunnel": "SalesFunnel 1",
          "salesFunnelId": "5561397c-9792-4b60-aed1-a045b86c6b13",
          "salesStage": "Stage",
          "salesStageId": "de0cf594-b999-438a-b1f0-8578c36a8da5"
        }
      ],
      "contactNotes": [
        {
          "note": "Note",
          "date": 1479208770000,
          "priv": false
        }
      ],
      "contactTasks": [
        {
          "id": "395c5276-a40f-417c-bee8-1d6e80373adb",
          "note": "Task",
          "date": 1479250800000,
          "cc": "",
          "reminder": 1479249900000
        }
      ],
      "contactExtEvents": [
        {
          "eventId": "bd2fd558-29da-49b7-be31-6ee551cd5e13",
          "date": 1433449419000,
          "description": "Cart",
          "products": "7,6",
          "location": null,
          "value": 57.69,
          "contactExtEventType": "CART",
          "shopDomain":"shop.salesmanago.pl",
          "detail1": null,
          "detail2": null,
          "detail3": null,
          "detail4": null,
          "detail5": null,
          "detail6": null,
          "detail7": null,
          "detail8": null,
          "detail9": null,
          "detail10": null,
          "detail11": null,
          "detail12": null,
          "detail13": null,
          "detail14": null,
          "detail15": null,
          "detail16": null,
          "detail17": null,
          "detail18": null,
          "detail19": null,
          "detail20": null,
          "externalId": null
        }
      ],
      "coupons": [
        {
          "name": "Kupon",
          "coupon": "SB173",
          "validTo": 1480245622000,
          "used": false
        }
      ],
      "smsMessages": [
        {
          "createdDate": 1479209040000,
          "dateSent": 1479209971000,
          "dateDelivered": null,
          "deliveryStatus": null,
          "dateReplied": null,
          "replayMsg": null,
          "content": "Test",
          "sentBy": "admin@vendor.pl"
        }
      ],
      "consents": [
        {
          "name": "ZGODA_1",
          "description": "Description1",
          "ip": "0:0:0:0:0:0:0:1",
          "action": "A",
          "createdOn": 1546730871000,
          "source": "F",
          "dateOn": 1546730873000
        },
        {
          "name": "ZGODA_2",
          "description": "Description2",
          "ip": "0:0:0:0:0:0:0:1",
          "action": "D",
          "createdOn": 1546730871000,
          "source": "C",
          "dateOn": 1546730873000
        },
        {
          "name": "ZGODA_3",
          "description": "Description3",
          "ip": "0:0:0:0:0:0:0:1",
          "action": "R",
          "createdOn": 1546730871000,
          "source": "CC",
          "dateOn": 1546730873000
        }
      ]
    }
  ]
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
contacts – eksportowane kontakty
id – identyfikator kontaktu
name – imię kontaktu
email – e-mail kontaktu
phone – numer telefonu
fax – numer fax kontaktu
score – liczba punktów
state – status kontaktu (CUSTOMER, PROSPECT, PARTNER, OTHER, UNKNOWN)
optedOut – czy kontakt wycofał zgodę na otrzymywanie maili,
optedOutPhone - czy kontakt wycofał zgodę na kontakt telefoniczny
deleted – czy kontakt został usunięty
invalid – czy kontakt jest niepoprawny
company – nazwa firmy kontaktu
externalId – identyfikator zewnętrzny kontaktu
address – adres kontaktu
streetAddress – ulica i numer domu
zipCode – kod pocztowy
city – miasto
country – kraj
birthdayYear – rok urodzenia kontaktu
birthdayMonth – miesiąc urodzenia kontaktu
birthdayDay – dzień urodzin
province - województwo
mainContactOwner – identyfikator głównego właściciela kontaktu
modifiedOn – data ostatniej modyfikacji kontaktu
createdOn – data stworzenia kontaktu,
purchaseProbability – wartość predykcji wystąpienia zakupu
contactVisits – lista wizyt kontaktu
conversationIntId – identyfikator mailingu z którego pochodzi wizyta
host - strona którą odwiedzał kontakt
time - data wizyty
duration - czas trwania
visitSource – źródło wizyty, możliwe wartości tego pola to:
EMAIL_CONVERSATION - wejście z maila (kliknięcie w link)
SEARCH_ENGINE - wejście z wyszukiwarki
ADVERTISEMENT - wejście z boksu reklamowego (AdWords)
REFERRER - wejście z witryny odsyłającej
DIRECT - wejście bezpośrednie, lub przejście na kolejną stronę
visitSourceHost - host odsyłający (refferer)
visitSourceKeywords - słowa kluczowe
visitScore – liczba punktów wizyty
url – adres odwiedzonej strony
location - lokalizacja
contactTags – tagi kontaktu
tag – tekst tagu
tagName – nazwa tagu
score – liczba punktów tagu
createdOn – data nadania tagu
tagWithScore – nazwa tagu wraz z liczbą punktów
contactEvents – wydarzenia
date – data wystąpienia wydarzenia
description – opis wydarzenia
detail1-5 – detale wydarzenia
emailMessages – e-maile z ostatnich 3 miesięcy
name – Nazwa wiadomości
subject – Temat wiadomości
date – data stworzenia
sent – czy wiadomość została wysłana
dateSent – data wysłania
opened – czy wiadomość została otwarta
dateOpened – data otwarcia wiadomości
clicked – czy wiadomość została kliknięta
dateClicked – data kliknięcia wiadomości
emailConversation – identyfikator konwersacji
deliveryStatus – status doręczenia
properties – szczegóły kontaktu
name – nazwa szczegółu
value – wartość szczegółu
contactFunnels – lejki sprzedażowe
salesFunnel – nazwa lejka
salesFunnelId – identyfikator lejka
salesStage – nazwa etapu lejka
salesStageId – identyfikator lejka
contactNotes - notatki
note – treść notatki
date – data utworzenia notatki
priv – czy wiadomość jest prywatna
contactTasks – zadania
id – identyfikator zadania
note – treść zadania
date – data utworzenia zadania
cc – mail na który ma zostać wysłana kopia przypomnienia
reminder – data przypomnienia o zadaniu
contactExtEvents – zdarzenia zewnętrzne
eventId – identyfikator zdarzenia,
date – data zdarzenia
description – opis zdarzenia
products – wartość kolumny produkty (np. identyfikatory)
location – lokalizacja
value – wartość zdarzenia
contactExtEventType – typ zdarzenia
shopDomain – domena sklepu detail1-20 – detale zdarzenia (max 20)
externalId – zewnętrzny identyfikator zdarzenia.
coupons - kupony
name – nazwa kuponu
coupon – ciąg znaków kuponu
validTo – data ważności kuponu
used – czy kupon został użyty
smsMessages – wiadomości sms
createdDate – data stworzenia wiadomości
dateSent – data wysłania wiadomości
dateDelivered – data dostarczenia wiadomości
deliveryStatus – status dostarczenia
dateReplied – data otrzymania odpowiedzi
replayMsg – treść odpowiedzi
content – zawartość wiadomości
sentBy – e-mail osoby wysyłającej wiadomości
consents - zgody
name - nazwa zgody
description - opis zgody
ip - ip źródłowe, z którego została wykonana akcja na zgodzie
action - A - zaakceptowane zgody, D - usunięte zgody, R - odrzucone zgody
createdOn - data utworzenia
dateOn - data aktywowania zgody
source - źródło pochodzenia zgody - API - api, C - chat, F - formularz, CC - karta kontaktu

Eksport kontaktów po ID kontaktu 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
        }
      ],
      "contactPropertiesData": [
        {
          "name": "t_shirt_size",
          "value": "XL"
        }
      ],
      "contactDictionaryPropertiesData": [
        {
          "name": "birthday",
          "type": "DATE",
          "value": 1488927600000
        },
        {
          "name": "shoe_size",
          "type": "NUMBER",
          "value": 9
        }
      ]
    }
  },
  {
    "5e428789-08ae-11e7-a63d-28d24400c116": {
      "contactData": {
        "email": "test2@o2.pl",
        "id": "5e428789-08ae-11e7-a63d-28d24400c116",
        "createdOn": 1489493057000,
        "modifiedOn": 1489493303000,
        "name": null,
        "score": null,
        "fax": null,
        "state": "PROSPECT",
        "optedOut": false,
        "optedOutPhone": false,
        "deleted": false,
        "invalid": false,
        "company": null,
        "streetAddress": null,
        "zipCode": null,
        "city": null,
        "country": null,
        "birthday": null,
        "province": null,
        "mainOwner": null,
        "lastOptInOn": 1634671777000,
        "lastOptOutOn": 1634671197000
      },
      "tagData": [
        {
          "tag": null,
          "tagName": "TEST1",
          "score": 1,
          "createdOn": 1489493073000
        },
        {
          "tag": null,
          "tagName": "LESZNO",
          "score": 1,
          "createdOn": 1489493317000
        },
        {
          "tag": null,
          "tagName": "TEST2",
          "score": 1,
          "createdOn": 1489493316000
        }
      ],
      "extEventData": null,
      "visitsData": null,
      "emailsData": [
        {
          "name": "#API: dyn",
          "subject": "Sample API subject",
          "date": 1497445763000,
          "sent": false,
          "dateSent": null,
          "opened": false,
          "dateOpened": null,
          "clicked": false,
          "dateClicked": null,
          "emailConversation": null,
          "deliveryStatus": null
        }
      ],
      "funnelsData": null,
      "notesData": null,
      "tasksData": null,
      "couponsData": null,
      "smsData": null,
      "consentsData": [
        {
          "name": "ZGODA_1",
          "description": "Description1",
          "ip": "0:0:0:0:0:0:0:1",
          "action": "A",
          "createdOn": "2018-10-22",
          "source": "API",
          "dateOn": "2018-10-22"
        },
        {
          "name": "ZGODA_2",
          "description": "Description2",
          "ip": "0:0:0:0:0:0:0:1",
          "action": "D",
          "createdOn": "2018-10-22",
          "source": "API",
          "dateOn": "2018-10-22"
        },
        {
          "name": "ZGODA_3",
          "description": "Description3",
          "ip": "0:0:0:0:0:0:0:1",
          "action": "R",
          "createdOn": "2018-10-22",
          "source": "API",
          "dateOn": "2018-10-22"
        }
      ]
    }
  }
]

Metoda API ogranicza zakres eksportowanych danych do tych, które są określone w żądaniu. Do eksportu danych udostępniane są selectory, dzięki którym można sprecyzować grupę kontaktów dla której ma zostać wykonany eksport. Selectory działają na takiej samej zasadzie, jak w przypadku wysyłki e-mail. Dostępne selectory:

email - adres e-mail kontaktu,
tag - nazwa tagu w systemie przypisana do kontaktu lub do grupy kontaktów,
contact_id - zewnętrzny identyfikator kontaktu,
funnel - nazwa lejka sprzedażowego,
stage - nazwa etapu w lejku sprzedażowym (w tym przypadku należy określić nazwę lejka oraz nazwę etapu w którym znajdują się kontakty),
externalId - zewnętrzne ID kontaktu.

Zakres danych jakie można eksportować:

CONTACT - obejmuje podstawowe dane o kontakcie takie jak nazwa kontaktu, adres e-mail, numer telefonu itp.),
TAG - lista przypisanych tagów dla kontaktu,
EXT_EVENT - lista zdarzeń zewnętrznych kontaktu (np. koszyk, zakup),
VISITS - lista stron odwiedzanych przez kontakt w ciągu ostatnich 7 dni,
EMAILS - lista wysłanych e-maili do kontaktu wraz z informacjami, czy kontakt je otworzył, kiedy to nastąpiło itp.
FUNNELS - lista lejków sprzedażowych, w których znajduje się kontakt,
NOTES - lista przypisanych notatek do kontaktu,
TASKS - lista zadań przypisanych do kontaktu,
COUPONS - lista kuponów,
SMS - lista wiadomości SMS do kontaktu wraz z informacjami.
CONSENTS - lista zgód (A - zaakceptowana, D - usunięta, R - odrzucona)
PROPERTIES - definiowane przez użytkownika atrybuty kontaktu. Zaleca się nie stosować polskich znaków oraz spacji w nazwie, ale jest to dozwolone.
DICTIONARY_PROPERTIES - definiowane przez użytkownika atrybuty słownikowe, po pierwszym dodaniu danego atrybutu można go wykorzystać dla pozostałych kontaktów poprzez ponowne podanie takiej samej nazwy i typu z przypisaną inną wartością.

Należy wybrać minimum jeden typ danych do eksportu (np. tag, contact, funnel). Typy nie są współzależne od siebie, a to znaczy, że każdy typ można wyeksportować samodzielnie.
Eksport wykonywany jest do pliku w formacie json, do którego później udostępniany jest link.

Adres na który należy wysłać żądanie o wykonanie eksportu:
https://www.salesmanago.pl/api/contact/export/data

W parametrze “contacts” należy podać listę kontaktów, których dane chcemy wyeksportować.
W parametrze “data” należy podać listę typów danych, jakie chcemy wyeksportować.

W odpowiedzi otrzymujemy numer, po którym można monitorować status eksportu.

Parametr “requestId” jest naszym identyfikatorem eksportu.

Aby sprawdzić status eksportu należy wysłać żądanie na adres:
https://www.salesmanago.pl/api/job/status

Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.

W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.

Link jest ważny tylko przez kilka minut.

Eksport listy ostatnio stworzonych kontaktów

Przykładowa struktura danych zapytania:

{
  "clientId": "h4jsu6pc5txybj04",
  "apiKey": "qwetreryuii",
  "requestTime": 1481531514145,
  "sha": "abcd509ac6eb0c460455c74ccc66867955a5333d",
  "owner": "admin@vendor.pl",
  "from": 1478939514146,
  "to": 1481531514132
}

Kontakty eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/createdContacts

Pola dostępne w zapytaniu metody createdContacts:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
from*	timestamp(ms)	początkowy zakres dat stworzenia
to*	timestamp(ms)	końcowy zakres dat stworzenia

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "createdContacts": [
    {
      "id": "c3477890-3da7-4010-96d0-45aab0586b7f",
      "email": "***@gmail.com"
    }
  ]
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
createdContacts – kontakty zmodyfikowane w podanym przedziale czasu,
id – id kontaktu
email – email kontaktu

Eksport listy ostatnio zmodyfikowanych kontaktów

Przykładowa struktura danych zapytania:

{ 
    "apiKey" : "your-api-key-123",
    "clientId" : "your-client-id-123",
    "requestTime":1362056589362,
    "sha":"64656d78b80d5df677700dabd363e1ffe51b59a7",
    "owner":"admin@vendor.pl",
    "from":1359673200361,
    "to":1363042800362
}

Kontakty eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/modifiedContacts

Pola dostępne w zapytaniu metody modifiedContacts:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
from*	timestamp(ms)	początkowy zakres dat modyfikacji
to*	timestamp(ms)	końcowy zakres dat modyfikacji

Rezultat zapytania:

{
    "success":true,
    "message":[],
    "modifiedContacts":[
        {
            "id":"f66ca32b-c117-4b52-b3b8-863be077e710",
            "email":"aleksander.***@benhauer.pl"
        },
        {
            "id":"426e0ef8-675f-47fc-8ea8-745ac1706904",
            "email":"konrad.***@salesmanago.pl"
        },
        {
            "id":"1775d70e-cd61-4dd6-983a-64f067486adf",
            "email":"marek.***@salesmanago.pl"
        }
    ]
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
modifiedContacts – kontakty zmodyfikowane w podanym przedziale czasu,
id – id kontaktu
email – email kontaktu

Ostatnio zmodyfikowane Kontakty (lista stronicowana)

Ta metoda pozwala uzyskać listę Kontaktów, które po raz ostatni zostały zmodyfikowane we wskazanym okresie. Maksymalny przedział czasowy pomiędzy polami from i to wynosi 30 dni.

Przykładowe żądanie:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "from" : 1657267688000,
  "to": 1659938888000,
  "page" : 1,
  "size" : 1000
}

Endpoint:
https://www.salesmanago.pl/api/contact/paginatedModifiedContacts

Pola dostępne w metodzie paginatedModifiedContacts:

Pole	Max. długość	Opis
owner*	255	Właściciel Kontaktów (e-mail konta użytkownika SALESmanago)
from*	UNIX timestamp (ms)	Zakres dat ostatniej modyfikacji, z którego mają zostać wylistowane Kontakty. Maksymalny zakres filtrowania wynosi 30 dni.
to*	UNIX timestamp (ms)
page*	1+	Numer strony, zaczynając od 1, z której zostaną pobrane wyniki
size*	1000	Liczba wyników na stronie

W rezultacie zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów

modifiedContacts – tablica z wynikami
contactId – unikatowy identyfikator Kontaktu
email – adres e-mail kontaktu.

Przykładowa odpowiedź:

{
  "success": true,
  "message": [],

  "modifiedContacts": [
    {
      "id": "c100-...-298c",
      "email": "name@example.com"
    },
    {
      "id": "d256-...-4fe8",
      "email": "name2@example.com"
    }
  ],
  "hasMore": true
}

Aktywność kontaktów

Przykładowa struktura danych zapytania:

{ 
  "apiKey" : "your-api-key-123",
  "clientId" : "your-client-id-123",
  "requestTime" : 1329128188409,
  "sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
  "from":1328050800504,
  "to":1333231200504,
  "allVisits":true,
  "ipDetails":true
}

Z SALESmanago możemy pobrać informacje o aktywności kontaktów w danym okresie. W tym celu wykonujemy metodę:
https://www.salesmanago.pl/api/contact/recentActivity

Pola dostępne w zapytaniu metody recentActivity:

Pole	Max. długość	Opis
from*	timestamp(ms)	data początkowa (timestamp, czyli czas jaki upłynął w milisekundach od północy 1 stycznia 1970 UTC)
to*	timestamp(ms)	data końcowa (timestamp, czyli czas jaki upłynął w milisekundach od północy 1 stycznia 1970 UTC)
allVisits	true/false	w przypadku ustawienia na true SALESmanago zwróci w detalach odwiedzin informacje o wszystkich stronach otwartych przez klienta w wybranym okresie
ipDetails	true/false	w przypadku ustawienia na true SALESmanago zwróci w detalach odwiedzin informacje dodatkowe wyszukane dla IP klienta

Rezultat zapytania:

{
    "success":true,
    "message":[],
    "recentActivities": {
        "from":1328050800504,
        "to":1333231200504,
        "monitoredContacts": 12300,
        "totalContacts":234000,
        "customers":[{
            "uuid": 191615173,
            "time":1330239675000,
            "duration":22000,
            "visitSource":"REFERRER",
            "visitSourceHost":null,
            "visitSourceKeywords":"localhost",
            "visitSourceDetails":null,
            "visitScore":120,
            "client":"Benhauer Sp. z o.o. Sp. K. - Konrad Pawlus",
            "email":"konradpawlus@gmail.com",
            "contactId":"1d8cba47-f4b2-4efe-8250-5bdab5346628",
            "url": "/test.htm",
            "ipOrganization": "TP SA",
            "vid": 7,
            "cid": null,
            "ipDetails": {
                "ip" : "123.123.123.123",
                "countryCode" : "PL",
                "countryName" : "Poland",
                "regionCode" : "77",
                "regionName" : "Malopolskie",
                "city" : "Cracow",
                "postalCode" : "",
                "latitude" : "50.083300",
                "longitude" : "19.916700",
                "isp" : "Neostrada Plus",
                "organization" : "Neostrada Plus"
             },
            "contactVisits": [{ 
                "conversationIntId": null,
                "host": "10.10.10.10",
                "time": 1328050810504,
                "duration": null,
                "visitSource": "NEXT",
                "visitSourceHost": "salesmanago.pl",
                "visitSourceKeywords": null,
                "visitScore": 1,
                "url": "/test.htm",
                "location": null         
            }]}],
        "partners":["... jw. ..."],
        "prospects":["... jw. ..."],
        "anonymous":["... jw. ..."],       
        "allVisits":["... jw. ..."],       
        "visitStats": [
            {
                "date": 1330239675000, 
                "partnersVisits": 123,
                "prospectsVisits": 234,
                "customersVisits": 456,
                "otherVisits": 4321
            }
        ]
    }
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
recentActivity – struktura składająca się z trzech tablic wizyt: klientów (customers), partnerów (partners), potencjalnych klientów (prospects).
from – data początkowa
to – data końcowa
monitoredContacts – liczba monitorowanych kontaktów
totalContacts – liczba wszystkich kontaktów customers – lista wizyt klientów
partners – lista wizyt partnerów
prospects – lista wizyt potencjalnych klientów
anonymous – lista wizyt anonimowych
allVisits – lista wszystkich wizyt element wizyty klienta w listach:
time – czas wizyty
duration – czas trwania
visitSource – zasoby wizyty
visitSourceKeywords – słowa kluczowe
visitSourceHost – host
visitSourceDetails – detale wizyt
visitScore – liczba punktów
url – URL odwiedzonej strony
client – nazwa klienta
email – email klienta
contactId – unikatowy identyfikator klienta,
vid - ID sprzedawcy
cid - ID kontaktu
ipDetails – detale zdekodowane z IP klienta
ip – numer IP
countryCode – kod ISO kraju (2-znaki)
countryName – nazwa kraju
regionCode – kod regionu
regionName – nazwa regionu
city – miasto
postalCode – kod pocztowy
latitude – szerokość geograficzna
longitude – długość geograficzna
isp – nazwa ISP
organization – nazwa organizacji
contactVisits – wizyty kontaktu
conversationIntId – ID konwersji
host – strona która była odwiedzana
time – czas wizyty
duration – czas trwania
visitSource – zasoby wizyty
visitSourceKeywords – słowa kluczowe
visitSourceHost – host
visitScore – liczba punktów
url – URL odwiedzonej strony
location – lokalizacja wizyty
visitStats – statystyki wizyt z ostatniego tygodnia:
date – czas wizyty
partnersVisits – liczba wizyt partnerów
prospectsVisits – liczba wizyt potencjalnych klientów
customersVisits – liczba wizyt klientów
otherVisits – liczba innych wizyt

Eksport stronicowanej listy kontaktów

Przykładowa struktura danych zapytania:

{
  "clientId": "clientId",
  "apiKey": "api-key-123",
  "requestTime": 1481206581347,
  "sha": "5333dabcd509455c74ccc6ac6eb0c4606867955a",
  "owner": "admin@vendor.pl",
  "page": 1,
  "size": 100
}

Kontakty podzielone na części eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/paginatedContactList/export

Pola dostępne w zapytaniu metody paginatedContactListExport:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
page*	-	numer strony kontaków
size*	-	liczba kontaktów na jednej stronie (max 1000)

Rezultat zapytania:

{
   "success": true,
   "message": [
      "Export added to execute."
   ],
   "requestId": 37
}

success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
requestId – identyfikator eksportu

Parametr “requestId” jest naszym identyfikatorem eksportu.

Aby sprawdzić status eksportu należy wysłać żądanie na adres: https://www.salesmanago.pl/api/job/status

Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.

W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.

Link jest ważny tylko przez kilka minut.

Przykładowa struktura danych zapytania /api/job/status:


{
  "clientId": "yourclientID",
  "apiKey": "yourAPIkey",
  "requestTime": 1500556989,
  "sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
  "owner": "admin@vendor.pl",
  "requestId": 123
}

Rezultat zapytania


{
  "success": true,
  "message": [],
  "fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}

Kontakty przypisane do wskazanego właściciela

Przykładowe żądanie:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "page": 1,
  "size": 1000
}

Ta metoda pozwala uzyskać listę Kontaktów, które są przypisane do właściciela określonego w polu owner.

Endpoint:
https://www.salesmanago.pl/api/contact/paginatedListById

Pola dostępne w metodzie paginatedListById:

Pole	Max. długość	Opis
owner*	255	Właściciel Kontaktów (e-mail konta użytkownika SALESmanago)
page*	1+	Numer strony, zaczynając od 1, z której zostaną pobrane wyniki
size*	1000	Liczba wyników na stronie

W rezultacie zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów

hasMore – wartość logiczna informująca, że dostępne są kolejne strony z wynikami zapytania

WAŻNE: Pozostałe pola zostały opisane w metodzie contact/list

Przykładowa odpowiedź:

{
  "success": true,
  "message": [],
  "contacts": [
    {
      "id": "1a2b-...-3c4d",
      "name": "John Doe",
      "email": "name@example.com",
      "phone": "+15554443322",
      "fax": null,
      "score": 123,
      "state": "PROSPECT",
      "optedOut": false,
      "optedOutPhone": false,
      "deleted": false,
      "invalid": false,
      "company": "Big Company LLC",
      "externalId": "U12345",
      "address": {
        "streetAddress": "Main Street 21",
        "zipCode": "90210",
        "city": "San José",
        "country": "US"
      },
      "birthdayYear": 1987,
      "birthdayMonth": 06,
      "birthdayDay": 05,
      "province": "California",
      "mainContactOwner": "salesmanago.user@yourcompany.com",
      "contactVisits": [],
      "contactTags": [
        {
          "tag": "T_SHIRTS",
          "tagName": "T_SHIRTS",
          "score": 12,
          "createdOn": 1659938888000,
          "tagWithScore": "T_SHIRTS (12)"
        }
      ],
      "contactEvents": [],
      "emailMessages": [],
      "properties": [],
      "contactFunnels": [],
      "contactNotes": [],
      "contactTasks": [],
      "contactExtEvents": [],
      "coupons": [],
      "smsMessages": [],
      "modifiedOn": 1559938888000,
      "createdOn": 1459938888000
    },
    {
      "id": "d256-...-4fe8",
      "name": "Victoria Doe",
      "email": "name2@example.com",
      "phone": null,
      "fax": null,
      "score": 0,
      "state": "PROSPECT",
      "optedOut": false,
      "optedOutPhone": false,
      "deleted": false,
      "invalid": false,
      "company": null,
      "externalId": null,
      "address": null,
      "birthdayYear": "1985",
      "birthdayMonth": "5",
      "birthdayDay": "30",
      "province": "",
      "mainContactOwner": "salesmanago.user@yourcompany.com",
      "contactVisits": [],
      "contactTags": [],
      "contactEvents": [],
      "emailMessages": [],
      "properties": [],
      "contactFunnels": [],
      "contactNotes": [],
      "contactTasks": [],
      "contactExtEvents": [],
      "coupons": [],
      "smsMessages": [],
      "modifiedOn": 1549938888000,
      "createdOn": 1449938888000
    }
  ],
  "hasMore": true
}

Zmiana głównego właściciela kontaktu

Przykładowa struktura danych zapytania:

{
   "clientId": "your-client-id-123",
   "apiKey": "your-api-key-123",
   "requestTime": "1327056031488",
   "sha": "2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
   "contact": "contact@email.com",
   "owner": "Owner@email.com",
   "newOwner": "newOwner@email.com"
}

Nowego właściciela ustawiamy wywołując metodę:
https://www.salesmanago.pl/api/contact/setMainOwner

Pola dostępne w zapytaniu metody setMainOwner:

Pole	Max. długość	Opis
contact*	255	adres e-mail kontaktu
owner*	255	właściciel kontaktu
newOwner*	255	nowy główny właściciel kontaktu (email konta użytkownika SALESmanago)

Rezultat zapytania:

{
   "success": true,
   "message": []
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

Zatrzymanie monitorowania kontaktów

Przykładowa struktura danych zapytania:

{
  "clientId": "ye4vodnswfo6zp75",
  "apiKey": "12345trewq",
  "async": false,
  "requestTime": 1512720868000,
  "sha": "36ec9c925975fa077aa39660386e41de3e25349a",
  "owner": "admin@vendor.pl",
  "contacts" : [
    {"addresseeType" : "email", "value" : "test2@test.pl"} 
  ]
}

W celu zatrzymania monitorowania kontaktów poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/contact/stopMonitoring

Pola dostępne w zapytaniu metody stopMonitoring:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
contacts*	-	tablica kontaktów

Rezultat zapytania

{
  "success": true,
  "message": [
    "Contacts have stopped being monitored."
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

Przywrócenie monitorowania kontaktów

Przykładowa struktura danych zapytania:

{
  "clientId": "ye4vodnswfo6zp75",
  "apiKey": "12345trewq",
  "async": false,
  "requestTime": 1512720868000,
  "sha": "36ec9c925975fa077aa39660386e41de3e25349a",
  "owner": "admin@vendor.pl",
  "contacts" : [
    {"addresseeType" : "email", "value" : "test2@test.pl"} 
  ]
}

W celu przywrócenia monitorowania kontaktów poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/contact/restoreMonitoring

Pola dostępne w zapytaniu metody restoreMonitoring:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
contacts*	-	tablica kontaktów

Rezultat zapytania

{
  "success": true,
  "message": [
    "Contacts have restored being monitored."
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

API - Zdarzenia zewnętrzne

Dodawanie Zdarzenia Zewnętrznego

Przykładowe żądanie z podstawowymi danymi:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "contactEvent": {
    "date": 1659938888000,
    "contactExtEventType": "PURCHASE",
    "products": "p0123, p4567",
    "value": 189.99,
    "location": "examplecom"
  }
}

Przykładowe żądanie z zaawansowanymi danymi:

{
    "clientId": "a1b2-...-c3d4",
    "apiKey": "e5f6-...-g7h8",
    "requestTime": 1659938888000,
    "sha": "2aa3-...-e00c",

    "owner": "salesmanago.user@yourcompany.com",
    "email": "name@example.com",
    "contactEvent": {
        "date": 1659938888000,
        "contactExtEventType": "PURCHASE",
        "products": "p0123, p4567",
        "value": 189.99,
        "location": "examplecom",
        "externalId": "ID-123456",
        "detail1": "1,4,1",
        "detail2": "189.99",
        "detail3": "dresses",
        "detail4": "black,black,white",
        "description": "https://example.com/cartRecovery/controller/cartId=1234-5678-9098"
    }
}

Możesz dodać nowe Zdarzenie Zewnętrzne używając metody API:
https://www.salesmanago.pl/api/v2/contact/addContactExtEvent

Czym są Zdarzenia Zewnętrzne?

Zdarzenia Zewnętrzne (ang. External Events) reprezentują najważniejsze akcje wykonane przez Kontakt, takie jak zakup (PURCHASE) czy dodanie produktów do koszyka (CART). Zdarzenia Zewnętrzne możesz wykorzystać w celu tworzenia Procesów Automatyzacji oraz budowania statystyk transakcji i rekomendacji produktów.

Ważne: Zdarzenie Zewnętrzne może zostać przypisane wyłącznie do istniejącego Kontaktu. Jeżeli w momencie przesłania Zdarzenia Zewnętrznego metodą v2/contact/addContactExtEvent Kontakt nie istnieje w SALESmanago, system odczeka 5 minut i spróbuje dodać Zdarzenie Zewnętrzne ponownie. System będzie podejmować próby dodania Zdarzenia przez 1 godzinę. Jeśli po tym czasie Kontakt nadal nie będzie istniał w SALESmanago, Zdarzenie Zewnętrzne nie zostanie dodane.

Pole	Max. długość	Opis
owner*	255	Właściciel kontaktu (e-mail konta użytkownika SALESmanago)
email*	254^[?]	E-mail Kontaktu, dla którego dodawane jest Zdarzenie Zewnętrzne
contactId	UUID	Identyfikator Kontaktu z SALESmanago otrzymywany w odpowiedzi na każde żądanie z dodaniem lub aktualizacją Kontaktu. Jeśli identyfikujesz Kontakt używając contactId, pole email nie jest obowiązkowe.
date*	timestamp	Wartość UNIX timestamp [ms]
contactExtEventType*	enum	Typ Zdarzenia Zewnętrznego, np. PURCHASE, CART
products	512	Lista ID produktów oddzielonych przecinkami. Ważne: Identyfikatory produktów przesyłanych w Zdarzeniu powinny być zgodne z identyfikatorami produktów z Katalogu Produktowego / Feedu Produktowego XML
value	float (19.2)	Wartość Zdarzenia (np. kwota zakupu)
E-shop ID (location)	36	Identyfikator sklepu zgodny z polem location podanym podczas tworzenia Katalogu Produktowego / Feedu Produktowego XML. Pozwala na połączenie Zdarzenia Zewnętrznego i produktów z konkretnego sklepu (lub z konkretnej wersji językowej sklepu). Pole location może zawierać maksymalnie 36 znaków (wyłącznie litery a-z, A-Z, cyfry 0-9, znak _). Wartość nie może zaczynać się od cyfry. Tip: Możesz użyć nazwy domeny bez kropki, np. examplecom (lub examplecom_ES dla konkretnej wersji językowej sklepu).
externalId	255	Dodatkowy identyfikator Zdarzenia Zewnętrznego, na przykład ID zamówienia z platformy eCommerce
detail1	20x255	Szczegóły Zdarzenia Zewnętrznego, które możesz wykorzystać w Procesach Automatyzacji, w treści e-maili lub podczas eksportu danych przez API. Przykłady wykorzystania: liczba zakupionych produktów, wartość lub kategoria najdroższego produktu, metoda płatności, metoda wysyłki, sposób pakowania
detail2
detail…
description	2048	Pole przeznaczone do dowolnego wykorzystania, np. na uwagi do zamówienia, link z podsumowaniem zamówienia, link odzyskiwania koszyka

Typy Zdarzeń Zewnętrznych

SALESmanago oferuje wiele typów Zdarzeń Zewnętrznych. Zdarzenia PURCHASE (zakup) oraz CART (dodanie do koszyka) są automatycznie brane pod uwagę w panelach analitycznych. Pozostałe typy Zdarzeń Zewnętrznych nie mają specjalnego zastosowania – możesz ich używać w celu przesłania dowolnej akcji wykonanej przez Kontakt.

Lista dostępnych Zdarzeń Zewnętrznych:

PURCHASE
CART
TRANSACTION
CANCELLATION
RETURN
VISIT
PHONE_CALL
OTHER
RESERVATION
CANCELLED
ACTIVATION
MEETING
OFFER
DOWNLOAD
LOGIN
SURVEY

Rezultat zapytania:

{
  "success": true,
  "message": [],

  "eventId": "0e8c-...-9ba2c",
  "contact": {
    "email": "name@example.com",
    "contactId": null,
    "emailOrContactId": "name@example.com"
  }
}

W rezultacie zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów

eventId – unikatowy identyfikator Zdarzenia Zewnętrznego. Możesz go wykorzystać do aktualizacji Zdarzenia Zewnętrznego przy użyciu metody updateContactExtEvent (np. podczas dodania kolejnego produktu do koszyka)
contact – obiekt z podstawowymi informacjami o Kontakcie (adres e-mail lub contactId)

Dodawanie wielu zdarzeń zewnętrznych na raz

Przykładowa struktura zapytania dodająca zdarzenia:

{
 "clientId": "your-client-id-123",
 "apiKey": "your-api-key-123",
 "sha": "09b42a100849de3e4f7fad4f445eb47e833dba87",
 "owner":"user@vendor.pl",
 "events": [
        {
            "contactId":"001e720f-b2ab-4203-a25f-b089557cf0da",
            "contactEvent":{
                "date":356180568153,
                "description":"Bought with \"Super Bonus\"",
                "products":"p01, p02",
                "location":"Shop_ID",
                "value":1234.43,
                "contactExtEventType":"PURCHASE",
                "detail1":"C.ID: *** *** 234",
                "detail2":"Paid with card",
                "detail3":null,
                "externalId":"B-99999999",
                "shopDomain":"shop.salesmanago.pl"
            }   
        },
        {
            "email":"best.user@best.pl",
            "contactEvent":{
                "date":356180568153,
                "description":"Bought with \"Super Bonus\"",
                "products":"p01, p02",
                "location":"Shop_ID",
                "value":1234.43,
                "contactExtEventType":"PURCHASE",
                "detail1":"C.ID: *** *** 234",
                "detail2":"Paid with card",
                "externalId":"A-123123123",
                "shopDomain":"shop.salesmanago.pl"
            }   
        },
        {
            "email":"best.user@best.pl",
            "contactEvent":{
                "date":356180568153,
                "description":"Bought with \"Super Bonus\"",
                "products":"p02, p03",
                "location":"Shop_ID",
                "value":1234.43,
                "contactExtEventType":"PURCHASE",
                "detail1":"C.ID: *** *** 234",
                "detail2":"Paid with card",
                "detail3":null,
                "externalId":"A-123123123",
                "shopDomain":"shop.salesmanago.pl"
            }   
        }
    ]
}

W celu dodania wielu zdarzeń wykonujemy metodę:
https://www.salesmanago.pl/api/contact/batchAddContactExtEvent

Pola dostępne w zapytaniu metody batchAddContactExtEvent:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
events*	-	lista zdarzeń zewnętrznych (nie może być pusta oraz większa od 1000)

Pojedynczy element listy zdarzeń zewnętrznych zawiera:

Pole	Max. długość	Opis
email*	254^[?]	email kontaktu dla którego dodawane jest zdarzenie
contactId	255	identyfikator kontaktu dla którego dodawane jest zdarzenie (może być używane zamiennie z adresem email)
contactEvent*	-	obiekt zdarzenia zewnętrznego ( czytaj więcej - Dodawanie zdarzeń )

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "failedContacts": [],
  "createdAmount": 10,
  "failedAmount": 0
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
failedContacts – tablica kontaktów dla których dodanie zdarzenia nie powiodło się
createdAmount – liczba stworzonych zdarzeń
failedAmount – liczba zdarzeń których dodawanie zakończyło się błędem

Modyfikacja zdarzenia zewnętrznego (zalecana)

Przykładowa struktura zapytania modyfikująca zdarzenie:

{
    "clientId":"your-client-id-123",
    "apiKey":"your-api-key-123",
    "requestTime":1356180568127,
    "sha":"3e4ec39722326150aae60f41e038d1def4450f46",
    "owner":"admin@vendor.pl",
    "contactEvent":{
        "eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
        "date":1356180568153,
        "description":"Zakup z kartą \"Super Bonus\"",
        "products":"p01, p02",
        "location":"Shop_ID",
        "value":1234.43,
        "contactExtEventType":"PURCHASE",
        "detail1":"C.ID: *** *** 234",
        "detail2":"Płatość kartą",
        "detail3":null,
        "externalId":"A-123123123",
        "shopDomain":"shop.salesmanago.pl"
    }
}

W celu zmodyfikowania zdarzenia wykonujemy metodę:
https://www.salesmanago.pl/api/v2/contact/updateContactExtEvent

Pola dostępne w zapytaniu metody updateContactExtEvent:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
eventId*	255	ID zdarzenia (zwrócone przez metodę dodającą)
date*	timestamp(ms)	data zdarzenia (timestamp, czyli czas jaki upłynął w milisekundach od północy 1 stycznia 1970 UTC),
description	2048	opis zdarzenia
products	512	opcjonalna lista ID produktów oddzielona przecinkami, pole ID powinno być spójne z polem externalId w feedzie produktowym
ID sklepu (location)*	36	unikalny identyfikator sklepu – identyfikator ten służy do połączenia informacji o produkcie przesyłanych w zdarzeniu zewnętrznym z konkretnym feedem produktowym. Może zawierać maksymalnie 36 znaków bez spacji (wartość może zawierać litery a-z, cyfry 1-9, /_-.). Unikalny identyfikator ma być dokładnie taki sam jak wartość pola location w przesyłanych zdarzeniach zewnętrznych z danego sklepu. WAŻNE: Jeżeli posiadasz wgrany tylko jeden feed produktowy, system automatycznie połączy przesyłane zdarzenia z feedem produktowym wgranym do systemu. Natomiast, gdy korzystasz z opcji multistore ważne jest zachowanie spójności w przesyłaniu zdarzeń zewnętrznych z unikalnym identyfikatorem.
value	(19 2)	opcjonalna wartość zdarzenia np. wydana kwota (max 19 cyfr + 2 po przecinku)
contactExtEventType*	255	typ zdarzenie, dopuszczalne wartości: PURCHASE, CART, VISIT, PHONE_CALL, OTHER, RESERVATION, CANCELLED, ACTIVATION, MEETING, OFFER, DOWNLOAD, LOGIN, TRANSACTION
detail1-20	255/detal	opcjonalne detale zdarzenia,
externalId	255	opcjonalne ID zdarzenia np. ID z systemu kasowego itp.,
shopDomain	-	domena sklepu

Rezultat zapytania:

{ 
  "eventId":"7284e317-3bb6-4505-afbe-55b9a101339a",
  "message" : [  ],
  "success" : true 
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
eventId – ID zmodyfikowanego zdarzenia
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

Usuwanie zdarzenia zewnętrznego

Możesz usunąć zdarzenia zewnętrzne używając metody API:
https://www.salesmanago.pl/api/v2/contact/deleteContactExtEvent

Przykładowa struktura danych zapytania:

Z wykorzystaniem eventId:

{
    "clientId": "your-client-id-123",
    "apiKey": "your-api-key-123",
    "requestTime": 1645453269000,
    "sha": "3e4ec39722326150aae60f41e038d1def4450f46",
    "owner": "owner@example.com",
    "eventId": "7284e317-3bb6-4505-afbe-55b9a101339a"
}

Z wykorzystaniem externalId:

{
    "clientId": "your-client-id-123",
    "apiKey": "your-api-key-123",
    "requestTime": 1645453269000,
    "sha": "3e4ec39722326150aae60f41e038d1def4450f46",
    "owner": "owner@example.com",
    "externalId": "A-123123123"
}

Rezultat zapytania:

{
    "success": true,
    "message": [],
    "result": "Ext event has been scheduled to delete."
}

{
    "success": false,
    "message": ["No eventId/externalId specified"],
    "result": null
}

Pola dostępne w zapytaniu metody deleteContactExtEvent:

Pole	Max. długość	Opis
owner*	255	Właściciel kontaktu (e-mail konta użytkownika SALESmanago)
eventId**	255	ID zdarzenia (zwrócone przez metodę addContactExtEvent)
externalId**	255	Zewnętrzne ID zdarzenia

** Musisz określić przynajmniej jedno z nich. Jeśli podasz oba, eventId będzie miał pierwszeństwo.

W wyniku zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result – informacja dodatkowa przy rezultacie success = true: (“Ext event has been scheduled to delete.”)

API - Zarządzanie kuponami

Użycie kuponu dla kontaktu

Przykładowa struktura danych zapytania:

{ 
 "apiKey" : "your-api-key-123",
 "clientId" : "your-client-id-123",
 "sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
 "requestTime" : 1327059355361,
 "email" : "test@salesmanago.pl",
 "coupon" : "SAMPLE-COUPON-123"
}

Kupon zniżkowy dla kontaktu można oznaczyć jako użyty wywołując metodę:
https://www.salesmanago.pl/api/contact/useContactCoupon

Pola dostępne w zapytaniu metody useContactCoupon:

Pole	Max. długość	Opis
email*	254^[?]	email kontaktu
coupon*	255	nazwa kuponu

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "result": null
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result - rezultat used/error informujący o rezultacie zapytania

Dodanie kuponu dla kontaktu

Przykładowa struktura danych zapytania:

{
  "clientId": "client-id",
  "apiKey": "api-key-123",
  "requestTime": 1481528920123,
  "sha": "abcd5460455c09ac6eb0c74cc333dc66867955a5",
  "name": "Coupon123",
  "email": "***@gmail.com",
  "length": 7,
  "valid": 1484207320124,
  "coupon": "couponVal"
}

Kupon zniżkowy dla kontaktu można dodać wywołując metodę:
https://www.salesmanago.pl/api/contact/addContactCoupon

Pola dostępne w zapytaniu metody addContactCoupon:

Pole	Max. długość	Opis
email*	254^[?]	email kontaktu
name*	64	nazwa kuponu
length**	-	długość kuponu w przypadku automatycznego generowania (wartość z zakresu 5-64)
valid	-	data ważności kuponu (timestamp w milisekundach), domyślnie jest to rok
coupon**	32	wartość kuponu w przypadku ręcznego wprowadzania (minimun 5 znaków)

**Tylko jedno z tych pól jest wymagane.

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "result": null,
  "coupon": "couponVal"
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
result - rezultat zapytania
coupon - wartość stworzonego kuponu

API - Lejki

Dodawanie lejka

Przykładowa struktura danych zapytania:

{
  "clientId": "clientId",
  "apiKey": "apiKey",
  "requestTime": 1234567896541,
  "sha": "4f69782e826841f794080cae87648e42",
  "owner": "owner@mail.com",
  "funnel": "funnel_name",
  "group": "funnel group",
  "potValue": 4,
  "stages" : [
    {"name": "stage name", "order": 1},
    {"name": "second stage name", "order": 2}
  ]
}

Dodajemy lejek wywołując metodę:
https://www.salesmanago.pl/api/funnel/add

Pola dostępne w zapytaniu metody add:

Pole	Max. długość	Opis
owner*	-	mail użytkownika
funnel*	-	nazwa lejka
group	-	grupa lejka
potValue	-	domyślna wartość kontaktów
stages*	-	lista etapów lejka
name*	255	nazwa etapu lejka (min 3 znaki)
order*	-	kolejność etapu (min wartość 1, wartości kolejności powinny tworzyć ciąg 1,2,3…liczba etapów)

Rezultat zapytania:

{
  "success": true,
  "message": [
    "Funnel funnel_name was added."
  ]
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia importu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

Dodawanie kontaktów do lejka

Przykładowa struktura danych zapytania:

{
  "clientId": "ye4vodnswfo6zp75",
  "apiKey": "qwertgfdsa1234",
  "requestTime": 1496399754907,
  "sha": "07f7333f11745f30e1bd5adec2092d89ab2f00a7",
  "owner": "owner@mail.com",
  "funnel": "funnel_name",
  "stage": "stage name",
  "potValue": 4,
  "modify": true,
  "contacts": [
    {"addresseeType": "EMAIL",
      "value": "test1@test.pl, test2@test.pl, test3@test.pl"
    }
  ]
}

Dodajemy kontakt do lejka wywołując metodę:
https://www.salesmanago.pl/api/funnel/addContact

Pola dostępne w zapytaniu metody addContact:

Pole	Max. długość	Opis
owner*	-	mail użytkownika
funnel*	-	nazwa lejka
stage*	-	nazwa etapu
potValue	-	wartosć kontaktów dodawanych
modify	-	(wartość logiczna) kontakt ma zostać oznaczony jako zmodyfikowany przy dodaniu do lejka domyślnie false
contacts*	-	adres e-mail kontaktu, jego identyfikator, tag lub lejek

Rezultat zapytania:

{
  "success":true,
  "message":[],
  "addedContacts": {
    "07381ccd-8d0f-4458-89d9-58ed23634209": true,
    "bd7bd136-3702-401c-8b4a-3a40dd7546d8": true,
    "e4743be9-24ed-4d23-b032-b7c68f0a660b": true,
    "e99d6439-2191-4c55-9116-12b9bc63fa93": true,
    "5b45e6bc-72ea-45bc-8d61-985e9066bd3a": true
  }
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia importu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

Usuwanie lejka/etapu

Przykładowa struktura danych zapytania:

{
  "clientId": "clientId",
  "apiKey": "apiKey",
  "requestTime": 1234567896541,
  "sha": "4f69782e826841f794080cae87648e42",
  "owner": "owner@mail.com",
  "funnel": "funnel_name",
  "stage": "stage name"
}

Lejek/etap usuwamy wywołując metodę:
https://www.salesmanago.pl/api/funnel/delete

Pola dostępne w zapytaniu metody delete:

Pole	Max. długość	Opis
owner*	-	mail użytkownika
funnel*	-	nazwa lejka
stage	-	nazwa etapu

stage - parametr opcjonalny - gdy pusty, metoda usuwa cały lejek, gdy uzupełniony usuwa wybrany etap w lejku

Rezultat zapytania:

{
  "success": true,
  "message": [
    "Specified funnel stage will be deleted in a few seconds"
  ]
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia importu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

Pobieranie liczby kontaktów w lejku/etapie

Przykładowa struktura danych zapytania:

{
  "clientId": "clientId",
  "apiKey": "apiKey",
  "requestTime": 1234567896541,
  "sha": "4f69782e826841f794080cae87648e42",
  "owner": "owner@mail.com",
  "funnel": "funnel_name",
  "stage": "stage name"
}

Pobieramy liczbę kontaktów wywołując metodę:
https://www.salesmanago.pl/api/funnel/count

Pola dostępne w zapytaniu metody count:

Pole	Max. długość	Opis
owner*	-	mail użytkownika
funnel*	-	nazwa lejka
stage	-	nazwa etapu

stage - parametr opcjonalny - gdy pusty, metoda zwraca liczbę kontaktów w całym lejku, gdy uzupełniony zwraca liczbę w wybranym etapie

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "count": 123
}

W rezultacie zapytania otrzymujemy:

success – informacja o poprawności zakończenia eksportu
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
count – liczba kontaktów w lejku/etapie

API - Zarządzanie tagami

Eksport listy tagów

Przykładowa struktura danych zapytania:

{ 
  "apiKey" : "your-api-key-123",
  "clientId" : "your-client-id-123",
  "showSystemTags" : true,
  "owner" : "admin@vendor.pl",
  "requestTime" : 1329128188409,
  "sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7"
}

Tagi eksportujemy wywołując metodę:
https://www.salesmanago.pl/api/contact/tags

Pola dostępne w zapytaniu metody tags:

Pole	Max. długość	Opis
owner*	255	właściciel kontaktu (email konta użytkownika SALESmanago)
showSystemTags*	true/false	przy ustawieniach na true SALESmanago zwróci również tagi systemowe

Rezultat zapytania

{ 
  "tags" : [ { "tag" : "ADmanago",
              "numberOfTagged" : 12
       } ],
  "message" : [  ],
  "success" : true
}

W rezultacie zapytania otrzymujemy:

tags – eksportowane tagi
tag – nazwa tagu
numberOfTagged – liczba otagowanych kontaktów
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

API - Wiadomości email

Eksport globalnych statystyk wysłanych e-maili

Przykładowa struktura danych zapytania:

{
  "clientId": "your-client-id-123",
  "apiKey": "your-api-key-123",
  "requestTime": 1645453269000,
  "sha": "3e4ec39722326150aae60f41e038d1def4450f46",
  "user": "owner@example.com",
  "from": 1631271157000,
  "to": 1645453270000,
  "conversationType": "MAILING"
}

Możesz eksportować globalne statystyki e-mail metodą API:
https://www.salesmanago.pl/api/email/globalConversationStatistics

Pola dostępne w zapytaniu metody apiGlobalConversationStatistics:

Pole	Max. długość	Opis
from*	255	data początkowa zakresu eksportu – data w formacie UNIX timestamp [ms]
to*	255	data końcowa zakresu eksportu – data w formacie UNIX timestamp [ms]
conversationType	enum: SMTP, AD_HOC, MAILING, RULE, W, API, TEST_AB, FINAL_TEST_AB, BIRTHDAY, CYCLIC, SCHEDULED, BRITHDAY_YT, TEST	Typ e-maili, którego statystyki mają zostać wyeksportowane. Jeśli typ nie zostanie podany, wyeksportowane zostaną statystyki wszystkich typów.

Dostępne typy e-maili masowych:

MAILING
TEST_AB
FINAL_TEST_AB
BIRTHDAY
BIRTHDAY_YR
CYCLIC
SCHEDULED

Rezultat zapytania:

{
    "success": true,
    "message": [],
    "from": 1631271157000,
    "to": 1645453270000,
    "sent": 32997135,
    "opened": 4115080,
    "clicked": 874927,
    "openedUnique": 2683298,
    "clickedUnique": 471739,
    "softBounce": 647244,
    "hardBounce": 30128,
    "resigned": 6868
}

W wyniku zapytania otrzymasz:

success – status zakończenia eksportu
message – tablica dodatkowych informacji, która pozwala zidentyfikować błąd
from – data początkowa
to – data końcowa

oraz dane statystyczne ze wskazanego zakresu i typu:

sent – liczba wysłanych e-maili
opened – liczba otwartych e-maili
clicked – liczba klikniętych e-maili
openedUnique – liczba unikalnych otwarć
clickedUnique – liczba unikalnych kliknięć
softBounce – liczba miękkich zwrotek
hardBounce – liczba twardych zwrotek
Dowiedz się czym są miękkie i twarde zwrotki >>
resigned – liczba kontaktów, które wypisały się z newslettera, korzystając z linku w stopce

Dodawanie lub aktualizacja e-maila

Przykładowa struktura danych zapytania:

{
  "clientId": "client-id-123",
  "apiKey": "api-key-123",
  "requestTime": 1481535098734,
  "sha": "abcd56045567955a533c74ccc6683d09ac6eb0c4",
  "emailId": "1234-...-abcd",
  "emailOwner": "user@example.com",
  "name": "Special discount code",
  "utmCampaign": "Spring/summer campaign",
  "subject": "Special prize for you 🎁 Redeem before it's gone 😍",
  "senderAccountId": "6789-...-efgh",
  "content": "<html><body>...$opt-out$...</body></html>",
  "shared": false
}

W celu dodania lub aktualizacji e-maila należy skorzystać z metody:
https://xxx.salesmanago.com/api/email/upsert

Pola dostępne w zapytaniu metody email/upsert::

Pole	Max. długość	Opis
*emailId*	UUID	Identyfikator e-maila używany podczas aktualizacji już istniejącego e-maila
*emailOwner**	255	Użytkownik SALESmanago, do którego ma zostać przypisany tworzony e-mail. Nie możesz zmienić właściciel e-maila podczas aktualizacji.
*name**	255	Nazwa e-maila widoczna w SALESmanago
*group*	255	Nazwa grupy do której zostanie przypisany e-mail. Jeśli zostawisz to pole puste, email zostanie przypisany do domyślnej grupy.
*subject**	998	Temat e-maila. Możesz użyć znaków UTF-8.
*senderAccountId**	UUID	Identyfikator konta wysyłkowego SALESmanago. Tę wartość znajdziesz w SALESmanago ➔ Ustawienia ➔ Konta E-mail.
*content**	2 MB	Treść HTML wiadomości e-mail.
*shared*	bool	Flaga, która pozwala ci udostępnić e-maila innym użytkownikom przypisanym do tego samego konta SALESmanago. Domyślną wartością jest false.
*utmCampaign*	255	Parametr utm_campaign do śledzenia kampanii np. przy użyciu Google Analytics

Rezultat zapytania:

{
  "message": [],
  "success": true,
  "emailId": "1234-...-abcd"
}

W rezultacie zapytania otrzymasz:

emailId – Identyfikator e-maila przy pomocy którego możesz aktualizować jego zawartość.

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)

message – tablica dodatkowych informacji

Wysyłanie wiadomości email (zalecana)

Przykładowa struktura danych zapytania:

{
  "clientId": "ye4vodnswfo6zp75",
  "apiKey": "qwertgfdsa1234",
  "requestTime": 1496399754907,
  "sha": "02d89ab2f7333f11745f30e100a7fbd5adec2097",
  "user": "admin@vendor.pl",
  "emailId": "emailid",
  "date": 1234562541250,
  "html": "<html> <body> text $opt-out$ </body> </html>",
  "campaign": "nazwa kampani",
  "subject": "temat mojej wiaodmości",
  "contacts": [
    {
      "addresseeType": "EMAIL",
      "value": "test1@test.pl, test2@test.pl, test3@test.pl",
      "properties": [
        {
          "name": "name",
          "value": "value"
        },
        {
          "name": "name",
          "value": "value"
        }
      ]
    },
    {
      "addresseeType": "CONTACT_ID",
      "value": "contact-id-1, contact-id-2, contact-id-3, contact-id-3"
    },
    {
      "addresseeType": "TAG",
      "value": "tag1, tag2",
      "properties": [
        {
          "name": "name",
          "value": "value"
        },
        {
          "name": "name",
          "value": "value"
        }
      ]
    },
    {
      "addresseeType": "FUNNEL",
      "value": "funnel-name-1, funnel-nam-2",
      "properties": [
        {
          "name": "name",
          "value": "value"
        },
        {
          "name": "name",
          "value": "value"
        }
      ]
    },
    {
      "addresseeType": "STAGE",
      "value": "funnel-name",
      "optValue": "stage-name-1, stage-name-2"
    }
  ],
  "excludeContacts": [
    {
      "addresseeType": "EMAIL",
      "value": "test5@test.pl, test6@test.pl, test8@test.pl",
      "properties": [
        {
           "name": "name",
           "value": "value"
        }             
      ]
    },
    {
      "addresseeType": "TAG",
      "value": "exclude-tag-1",
      "properties": []
    }
  ]
}

W celu wysłania maila poprzez API należy skorzystać z nowej metody:
https://www.salesmanago.pl/api/email/sendEmail

Pola dostępne w zapytaniu metody sendEmail:

Pole	Max. długość	Opis
user*	255	adres email użytkownika Salesmanago
emailId*	255	identyfikator wiadomości z systemu SALESmanago
date*	timestamp(ms)	data wysyłki
html	-	zawartość maila w formacie HTML (jeżeli nie podana – zostanie użyta domyślna). Wymagane jest użycie linku opt-out ($opt-out$)
campaign	255	kampania dla śledzenia Google UTM (jeżeli nie podana – zostanie użyta domyślna)
subject	2048	temat wysyłki (jeżeli nie podany – zostanie użyty domyślny)
contacts*	-	tablica kontaktów, do których zostanie wysłany email
addresseeType*	255	typ adresowania ( EMAIL, CONTACT_ID, TAG, FUNNEL, STAGE)
value*	255	opcjonalnie – adres e-mail kontaktu, jego identyfikator, tag lub lejek
optValue	255	opcjonalnie dla typu STAGE podajemy po przecinku nazwy etapów w podanym wyżej lejku do których adresujemy wysyłke
properties	255	definiowane przez użytkownika atrybuty dodatkowe wiadomości e-mail. Zaleca się nie stosować znaków diakrytycznych oraz spacji w nazwie, ale jest to dozwolone. W wiadomości e-mail należy użyć konstrukcji $cst.nazwaParametru$ w celu podstawienia odpowiedniej wartości
excludeContacts	-	tablica kontaktów, które będą wykluczone z wysyłki

Rezultat zapytania

{
  "success": true,
  "message": [
    "Emails are scheduling to send."
  ],
  "conversationId": "conversation-id"
}

W rezultacie zapytania otrzymujemy:

Wysyłanie potwierdzenia subskrypcji

Przykładowe żądanie z użyciem języka e-maila:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "tag": "CSV_IMPORT",
  "doubleOptInLanguage": "ES"
}

Przykładowe żądanie z użyciem ID e-maila:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "email": "name@example.com",
  "tag": "CSV_IMPORT",
  "doubleOptInEmailId": "6d5c-...-0102"
}

Przykładowa odpowiedź:

{
  "success": true,
  "message": ["Contact exists - confirmation email sent"],

  "contactExists": true,
  "contactId": "1a2b-...-3c4d"
}

Ta metoda umożliwia wysłanie e-maila z potwierdzeniem subskrypcji, czyli double opt-in, do istniejących Kontaktów o statusie opt-out. Możesz również określić dodatkowy parametr tag, aby wysłać potwierdzenie tylko do Kontaktów oznaczonych tym tagiem.

Endpoint:
https://www.salesmanago.pl/api/email/sendConfirmation

Pola dostępne w zapytaniu metody sendConfirmation:

Pole	Max. długość	Opis
email*	254^[?]	Adres e-mail Kontaktu
owner*	255	Właściciel Kontaktu (e-mail konta użytkownika SALESmanago)
tag	255	Opcjonalny parametr definiujący tag, który musi posiadać Kontakt, aby został do niego wysłany e-mail z potwierdzeniem subskrypcji
doubleOptInLanguage	255	E-mail z potwierdzeniem subskrypcji, wskazany poprzez jedną z poniższych opcji: - język, zgodnie z mapowaniem w SALESmanago ➔ Ustawienia ➔ Inne ➔ Aplikacja ➔ API, - ID e-maila, które znajdziesz w adresie URL podczas edycji e-maila z potwierdzeniem subskrypcji
doubleOptInEmailId	255

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
contactExists – wartość logiczna informująca, czy dany Kontakt istnieje w SALESmanago
contactId – ID Kontaktu, które możesz wykorzystać, aby móc później zidentyfikować Kontakt

Wysyłanie wiadomości email z załącznikiem

Przykładowa struktura danych zapytania:

    POST /api/email/sendWithAttachment HTTP/1.1
    HOST: dev.salesmanago.pl
    content-type: multipart/form-data; boundary=----WebKitFormBoundary1aTYxdL1yD9GkrBw
    accept: application/json, application/*+json
    cookie: JSESSIONID=B79601649C8C221E3024EF909FD27A51; SERVERID=A
    content-length: 81854

    ------WebKitFormBoundary1aTYxdL1yD9GkrBw
    Content-Disposition: form-data; name="attachment"; filename="poster.gif"
    Content-Type: image/gif

    <-- zawartość pliku -->

    ------WebKitFormBoundary1aTYxdL1yD9GkrBw
    Content-Disposition: form-data; name="emailSendRequest"

    {
      "clientId": "r60ta7pkk1cqh1iy",
      "apiKey": "sdfsfsfsdf",
      "requestTime": 1391167514795,
      "sha": "229c9b4e06d6742330d7fe7c6882469bcac90686",
      "user": "test@test.com",
      "emailId": "1ece2b0d-9061-4295-9ad4-34ab82fa852e",
      "html" : "<html><body>email-html-content</body></html>",
      "contacts": [
        {
          "addresseeType" : "EMAIL",
          "email": "test@test.com",
          "contactId": null,
          "tag" : null,
          "properties": [
            { "name": "ext_detal_01", "value": "value_01" }
          ,
            { "name": "ext_detal_02", "value": "value_02" }
          ]
        },
        {
          "addresseeType" : "EMAIL",
          "email": "test.stepniak+1@gmail.com",
          "contactId": null,
          "tag" : null,
          "properties": [
            { "name": "ext_detal_03", "value": "value_03" }
          ,
            { "name": "ext_detal_04", "value": "value_04" }
          ]
        }
      ],
      "excludeContacts": [
              {
            "addresseeType" : "EMAIL",
                  "email": "user3@example.com",
                  "contactId": null,
            "tag" : null,
            "properties": []
              }
          ],
      "date": 1391167515515,
      "subject": "Sample API subject",
      "campaign": "monitor_me_in_ga",
      "immediate" : false,
      "rule" : false
    }

W celu wysłania maila z załącznikiem poprzez API należy skorzystać z metody:
https://www.salesmanago.pl/api/email/sendWithAttachment

Pola dostępne w zapytaniu metody sendWithAttachment:

Pole	Max. długość	Opis
user*	255	adres email użytkownika Salesmanago
emailId*	255	identyfikator wiadomości z systemu SALESmanago
date*	timestamp(ms)	data wysyłki
subject	2048	temat wysyłki (jeżeli nie podany – zostanie użyty domyślny)
campaign	255	kampania dla śledzenia Google UTM (jeżeli nie podana – zostanie użyta domyślna)
html	-	zawartość maila w formacie HTML (jeżeli nie podana – zostanie użyta domyślna)
contacts*	-	tablica kontaktów, do których zostanie wysłany email
addresseeType*	255	typ adresowania ( EMAIL, CONTACT_ID, TAGS)
email/contactId/tag*	254^[?]	opcjonalnie – adres e-mail kontaktu, jego identyfikator lub tag
properties	255	definiowane przez użytkownika atrybuty dodatkowe wiadomości e-mail. Zaleca się nie stosować znaków diakrytycznych oraz spacji w nazwie, ale jest to dozwolone. W wiadomości e-mail należy użyć konstrukcji $cst.nazwaParametru$ w celu podstawienia odpowiedniej wartości
excludeContacts	-	tablica kontaktów, które będą wykluczone z wysyłki
immediate	true/false	przypisanie wartości true spowoduje natychmiastowe wysłanie wiadomości e-mail
rule	true/false	przypisanie wartości true spowoduje oznaczenie wiadomości jako e-mail z reguły
attachment*	-	załączony plik

Rezultat zapytania

{
    "success": true,
    "message": ["Emails are scheduled to send."],
    "conversationId":"6bd61df3-44f3-825c-8c18-3d7813fea03b"
}

W rezultacie zapytania otrzymujemy:

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:

Statystyki wysłanych e-maili

Przykładowe żądanie z conversationId:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",


  "user": "salesmanago.user@yourcompany.com",
  "conversationId": "a254-...-5ed9"
}

Przykładowe żądanie z zakresem czasu:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",


  "user": "salesmanago.user@yourcompany.com",
  "from": "1649938888000",
  "to": "1659938888000",
  "requestType": "MAILING",
  "exportType": "FULL"
}

Możesz pobrać statystyki wysłanych e-maili używając metody API:
https://www.salesmanago.com/api/email/conversationStatistics

Pola dostępne w metodzie conversationStatistics:

Pole	Max. długość	Opis
user*	255	Adres e-mail użytkownika SALESmanago. Statystyki zostaną pobrane tylko dla e-maili, których autorem jest wskazany użytkownik.
conversationId	255	Identyfikator konwersacji, widoczny w URL analityki e-maila. Ważne: jeśli to pole jest obecne, pola `from`, `to` i `conversationType` są ignorowane.
from	timestamp(ms)	Data rozpoczęcia zakresu eksportu – data w formacie UNIX timestamp [ms]. Ważne: to pole jest wymagane, jeśli pole `conversationId` nie zostało podane.
to	timestamp(ms)	Data zakończenia zakresu eksportu – data w formacie UNIX timestamp [ms]. Ważne: to pole jest wymagane, jeśli pole `conversationId` nie zostało podane.
conversationType	255	Typ e-maili: MAILING CYCLIC TEST_AB FINAL_TEST_AB BIRTHDAY Jeśli to pole nie jest obecne, zostaną zwrócone e-maile wszystkich typów.
exportType	255	Zakres eksportu: BASIC SHORT FULL Domyślną wartością jest FULL.

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "requestId": 123456
}

Metoda do pobrania URL pliku:
/api/job/status
Zobacz dokumentację >>

Przykładowa struktura pliku dla exportType BASIC i podanym conversationId:

{
  "conversationId": "a254-...-5ed9",
  "name": "Sample conversation name",
  "subject": "Sample conversation subject",
  "dateSent": 1609938888000,
  "sentBy": "salesmanago.user@yourcompany.com",
  "sentMessage": 1000,
  "openedMessage": 800,
  "uniqueOpens": 500,
  "clickedMessage": 300,
  "uniqueClicks": 200,
  "errorMessage": 0,
  "softBounce": 10,
  "hardBounce": 20,
  "resigned": 0,
  "testAB": false,
  "message": []
}

Przykładowa struktura pliku dla exportType SHORT i podanym conversationId:

{
  "conversationId": "a254b80b-fac2-4401-b0a1-6eda1bf45ed9",
  "name": "Your conversation name",
  "subject": "Your conversation subject",
  "dateSent": 1668755462468,
  "sentBy": "name@example.com",
  "sentMessage": 100,
  "openedMessage": 120,
  "uniqueOpens": 50,
  "clickedMessage": 30,
  "uniqueClicks": 20,
  "errorMessage": 0,
  "softBounce": 10,
  "hardBounce": 10,
  "resigned": 0,
  "testAB": false,
  "contacts": [
    "contact1@example.com",
    "contact2@example.com"
  ]
}

Przykładowa struktura pliku dla exportType FULL i podanym conversationId:

{
  "conversationId": "a254-...-5ed9",
  "name": "Sample conversation name",
  "subject": "Sample conversation subject",
  "dateSent": 1609938888000,
  "sentBy": "salesmanago.user@yourcompany.com",
  "sentMessage": 1000,
  "openedMessage": 800,
  "uniqueOpens": 500,
  "clickedMessage": 300,
  "uniqueClicks": 200,
  "errorMessage": 0,
  "softBounce": 10,
  "hardBounce": 20,
  "resigned": 0,
  "testAB": false,
  "openedBy": [
    {
      "email": "name1@example.com",
      "contactId": "f35c-...-684e",
      "dateOpened": 1659938888000,
      "dateClicked": 1659938899000,
      "optedOut": false
    }
  ],
  "clickedBy": [
    {
      "email": "name1@example.com",
      "contactId": "f35c-...-684e",
      "dateOpened": 1659938888000,
      "dateClicked": 1659938899000,
      "optedOut": false
    }
  ],
  "softBouncedBy": [
    "nam2@example.com"
  ],
  "hardBouncedBy": [
    "nam3@example.com"
  ],
  "resignedBy": [
    {
      "email": "name4@example.com",
      "contactId": "a123-...-54bc",
      "dateOpened": 1659937777000,
      "dateClicked": 1659937788000,
      "optedOut": true
    }
  ]
}

Przykładowa struktura pliku dla exportType BASIC i podanym zakresem czasowym:

[
  {
    "conversationId": "a254-...-5ed9",
    "name": "Sample conversation name",
    "subject": "Sample conversation subject",
    "dateSent": 1609938888000,
    "sentBy": "salesmanago.user@yourcompany.com",
    "sentMessage": 1000,
    "openedMessage": 800,
    "uniqueOpens": 500,
    "clickedMessage": 300,
    "uniqueClicks": 200,
    "errorMessage": 0,
    "softBounce": 10,
    "hardBounce": 20,
    "resigned": 0,
    "testAB": false
  },
  {
    "conversationId": "a254-...-5ed9",
    "name": "Another conversation name",
    "subject": "Another conversation subject",
    "dateSent": 1619938888000,
    "sentBy": "salesmanago.user@yourcompany.com",
    "sentMessage": 2000,
    "openedMessage": 1600,
    "uniqueOpens": 1000,
    "clickedMessage": 600,
    "uniqueClicks": 400,
    "errorMessage": 0,
    "softBounce": 20,
    "hardBounce": 40,
    "resigned": 0,
    "testAB": false
  }
]

Plik wynikowy eksportu zawiera:

message—tablica dodatkowych informacji zawierająca komunikaty błędów

Pola obecne dla typu eksportu BASIC:
conversationId—identyfikator konwersacji
name—nazwa e-maila
subject—temat e-maila
dateSent—UNIX timestamp [ms]
sentBy—konto wysyłkowe
sentMessage—liczba wysłanych wiadomości e-mail
openedMessage—liczba wiadomości, które zostały otwarte.
uniqueOpens—liczba Kontaktów, które otworzyły wiadomość
clickedMessage—liczba kliknięć wiadomości e-mail
uniqueClicks—liczba Kontaktów, które kliknęły wiadomość e-mail
errorMessage—liczba błędnych wiadomości e-mail
softBounce—liczba miękkich zwrotek
hardBounce—liczba twardych zwrotek
resigned—liczba Kontaktów, które zrezygnowały z subskrypcji poprzez kliknięcie w link w danym e-mailu
testAB—wartość boolean; true dla e-maili, które były częścią testu A/B

Dodatkowe pola dla eksportu typu SHORT:
contacts—tablica adresów e-mail odbiorców

Dodatkowe pola dla typu eksportu FULL:
openedBy—tablica kontaktów, które otwarły wiadomość e-mail
clickedBy—tablica kontaktów, które kliknęły wiadomość e-mail
softBouncedBy—tablica kontaktów, które zostały oznaczone jako miękka zwrotka
hardBouncedBy—tablica kontaktów, które zostały oznaczone jako twarda zwrotka
resignedBy—tablica kontaktów, które zrezygnowały z subskrypcji poprzez kliknięcie w link w danym e-mailu

Struktura danych dla powyższych tablic (typ eksportu FULL):
email—adres e-mail Kontaktu
contactId—Identyfikator Kontaktu
externalId—Zewnętrzny identyfikator Kontaktu
dateOpened—UNIX timestamp [ms]
dateClicked—UNIX timestamp [ms]
optedOut—wartość boolean; true dla Kontaktów, które zrezygnowały z subskrypcji poprzez kliknięcie w link w danym e-mailu

WAŻNE: Tablica contacts nie jest dostępna dla typu eksportu FULL

Pobieranie kontaktów, do których została wysłana wiadomość email

Przykładowa struktura danych zapytania:

{
  "apiKey": "our-api-key-123",
  "clientId" : "your-client-id-123",
  "sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
  "requestTime" : 1327059355361,
  "user": "user@user.com",
  "conversationId": "5f0baebd-96bc-4a55-9ffe-709b04992327"
}

W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/email/messageStatistics

Pola dostępne w zapytaniu metody messageStatistics:

Pole	Max. długość	Opis
conversationId*	255	identyfikator konwersacji
user*	255	email użytkownika

Rezultat zapytania


{
  "success": true,
  "message": [],
  "requestId": 123
}

W odpowiedzi otrzymujemy “requestId”, który jest naszym identyfikatorem eksportu.

Aby sprawdzić status eksportu należy wysłać żądanie metodą POST na adres: https://www.salesmanago.pl/api/job/status

W którym podajemy requestId (z odpowiedzi metody użytej wcześniej), w którym zawarty był numer do monitorowania statusu eksportu.

W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.

Link jest ważny tylko przez kilka minut.

Przykładowa struktura danych zapytania /api/job/status:


{
  "clientId": "yourclientID",
  "apiKey": "yourAPIkey",
  "requestTime": 1500556989,
  "sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
  "owner": "admin@vendor.pl",
  "requestId": 123
}

Rezultat zapytania


{
  "success": true,
  "message": [],
  "fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json?AWSAccessKeyId="
}

Przykład struktury wyeksportowanych danych dla /api/email/messageStatistics:


{
  "conversationId": "5f0baebd-96bc-4a55-9ffe-709b04992327",
  "name": "Test email",
  "subject": "Lorem ipsum",
  "sentMessage": 317,
  "sentTo": [
    {
    "email": "test1@gmail.com",
    "contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
    "dateOpened": 1533170052000
    },
    {
    "email": "test2@gmail.com",
    "contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
    "dateOpened": 1533170052000
    },
    {
    "email": "test3@gmail.com",
    "contactId": "7bc9092c-0221-483b-92d3-d97ddcda1fa3",
    "dateOpened": 1533256452000
        }
  ]
}

API - Wiadomości 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:

Pobieranie statystyk SMS po ID konwersacji

Przykładowa struktura danych zapytania:

{
  "clientId": "client-id-123",
  "apiKey": "api-key-123",
  "sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
  "requestTime":1327056031488,
  "conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd"
}

W celu pobrania statystyk kampanii SMS należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/conversationStatistics

Pola dostępne w zapytaniu metody conversationStatistics:

Pole	Max. długość	Opis
conversationId*	255	identyfikator konwersacji

Rezultat zapytania

{
  "success": true,
  "message": [],
  "conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd",
  "name": "test",
  "messages": 2,
  "sentMessages": 2,
  "deliveredCount": 1,
  "delivered": [
      {
          "email": "example_mail_1@test.pl",
          "id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
          "dateTimestamp": 1513853328000,
          "contactExternalId": "extId"
      }
  ],
  "repliedCount": 1,
  "replied": [
      {
          "email": "example_mail_1@test.pl",
          "id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
          "dateTimestamp": 1513853328000,
          "contactExternalId": "extId"
      }
  ],
  "notDeliveredCount": 1,
  "notDelivered": [
      {
          "email": "example_mail_2@test.pl",
          "id": "9ca03a61-04a2-4d89-ae9c-1b3394814f52",
          "contactExternalId": "extId_2"
      }   
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationId - identyfikator wysyłki SMS
name - nazwa konwersacji
messages - liczba wiadomości do wysłania
sentMessages - liczba wysłanych wiadomości
deliveryCount - liczba dostarczonych wiadomości
delivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
repliedCount - liczba wiadomości, na które zostały wysłane odpowiedzi
replied - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
notDeliveredCount - liczba wiadomości, które nie zostały dostarczone
notDelivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości

Pobieranie statystyk SMS po nazwie konwersacji

Przykładowa struktura danych zapytania:

{
  "clientId": "client-id-123",
  "apiKey": "api-key-123",
  "sha": "abcd50460455c79ac6eb0c4ccc66867955a5333d",
  "requestTime":1327056031488,
  "name": "test"
}

W celu pobrania statystyk kampanii SMS należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/conversationStatisticsByName

Pola dostępne w zapytaniu metody conversationStatisticsByName:

Pole	Max. długość	Opis
name*	255	nazwa konwersacji

Rezultat zapytania

{
  "success": true,
  "message": [],
  "count": 59,
  "conversationStatistics": [
    {
      "success": true,
      "message": [],
      "conversationId": "2924d07f-dc0e-495b-b375-14ef95a485cd",
      "messages": 2,
      "sentMessages": 2,
      "deliveredCount": 1,
      "delivered": [
          {
              "email": "example_mail_1@test.pl",
              "id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
              "dateTimestamp": 1513853328000,
              "contactExternalId": "extId"
          }
      ],
      "repliedCount": 1,
      "replied": [
          {
              "email": "example_mail_1@test.pl",
              "id": "ca7126a8-9eb4-480a-900a-daca3d47780f",
              "dateTimestamp": 1513853328000,
              "contactExternalId": "extId"
          }
      ],
      "notDeliveredCount": 1,
      "notDelivered": [
          {
              "email": "example_mail_2@test.pl",
              "id": "9ca03a61-04a2-4d89-ae9c-1b3394814f52",
              "contactExternalId": "extId_2"
          }   
      ]
    }
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
count – liczba konwersacji
conversationStatistics - statystyki kampanii SMS
conversationId - identyfikator mailingu
messages - liczba wiadomości do wysłania
sentMessages - liczba wysłanych wiadomości
deliveryCount - liczba dostarczonych wiadomości
delivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
repliedCount - liczba wiadomości, na które zostały wysłane odpowiedzi
replied - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości
contactExternalId - zewnętrzne ID kontaktu
notDeliveredCount - liczba wiadomości, które nie zostały dostarczone
notDelivered - lista kontaktów, do których została dostarczona wiadomość. Składa się z pól:
email - adres email kontaktu
id - identyfikator kontaktu
dateTimestamp - data odpowiedzi na wiadomości

Pobieranie statystyk konwersacji SMS

Przykładowa struktura danych zapytania:

{
    "apiKey": "our-api-key-123",
    "clientId" : "your-client-id-123",
    "sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
    "requestTime" : 1327059355361,
    "conversationId": "ace8beeb-a0dc-4234-afc8-e6274de9e0ae"
}

W celu pobrania statystyk konwersacji należy skorzystać z metody:
https://www.salesmanago.pl/api/sms/smsConversationStatistics

Pola dostępne w zapytaniu metody smsConversationStatistics:

Pole	Max. długość	Opis
conversationId*	255	identyfikator konwersacji

Rezultat zapytania


{
    "success": true,
    "message": [],
    "conversationId": "ace8beeb-a0dc-4234-afc8-e6274de9e0ae",
    "messages": 3,
    "sentCount": 3,
    "sent": [
        {
        "email": "test1@testowy.pl",
        "id": "09d20ef2-1a4e-11e7-baad-0cc47a6bceb8",
        "dateTimestamp": 1564408685000,
        "contactExternalId": null
        },
        {
        "email": "test2@testowy.pl",
        "id": "0ae3be46-ca11-11e7-adbf-0cc47a6bceb8",
        "dateTimestamp": 1564408684000,
        "contactExternalId": null
        },
        {
        "email": "test3@testowy.pl",
        "id": "0afd8128-ca11-11e7-adbf-0cc47a6bceb8",
        "dateTimestamp": 1564408868000,
        "contactExternalId": null
        }
    ],
    "deliveredCount": 2,
    "delivered": [
        {
        "email": "test1@testowy.pl",
        "id": "09d20ef2-1a4e-11e7-baad-0cc47a6bceb8",
        "dateTimestamp": 1564408691000,
        "contactExternalId": null
        },
        {
        "email": "test2@testowy.pl",
        "id": "0ae3be46-ca11-11e7-adbf-0cc47a6bceb8",
        "dateTimestamp": 1564408691000,
        "contactExternalId": null
        }
    ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
conversationId - identyfikator konwersacji
messages - liczba wiadomości
sentCount - liczba wysłanych wiadomości
sent - lista kontaktów, dla których została zrealizowana wysyłka wiadomości
deliveredCount - liczba dostarczonych wiadomości
delivered - lista kontaktów, do których została dostarczona wiadomość

API - Zadania

Zadania kontaktów

Przykładowa struktura danych zapytania:

{ 
  "apiKey" : "your-api-key-123",
  "clientId" : "your-client-id-123",
  "requestTime" : 1329128188409,
  "sha" : "02bfe70541d3907cf487f26dc2665b184b1221a7",
  "finished" : false,
  "smContactTaskReq" : { 
      "contactEmail" : "konrad-123@konri.com",
      "id" : "task-id-123",
      "note" : "Zadzwonić do klienta",
      "date" : 1359673200361,
      "cc" : "konrad-test-123@konri.com",
      "reminder" : "30_MIN",
      "realized" : false 
    }
}

Dodawania, aktualizację oraz usuwanie zadania kontaktu wykonujemy za pomocą jednej metody:
https://www.salesmanago.pl/api/contact/updateTask

Pola dostępne w zapytaniu metody updateTask:

Pole	Max. długość	Opis
finished	true/false	przypisanie wartości true spowoduje skasowanie zadania i wtedy wymagany jest jedynie dodatkowy parametr id. Przy dodawaniu i aktualizacji zadania należy przypisać wartość false
contactEmail**	255	e-mail kontaktu do którego zostanie przypisane zadanie
id	255	id zadania
note	2048	notatka zadania
date**	timestamp(ms)	data wykonania zadania
cc	255	lista emaili do których zostanie wysłane przypomnienie (emaile powinny być oddzielone przecinkami)
reminder**	255	przypomnienie o wykonaniu zadania. Określa kiedy przypomnienie ma zostać wysłane*. Dopuszczalne wartości: 15_MIN – 15 minut przed, 30_MIN – 30 minut przed, 1_HOUR – godzinę przed, 12_HOUR – 12 godzin przed, 1_DAY – 1 dzień przed, 1_WEEK – 1 tydzień przed,
realized	true/false	przypisanie wartości true spowoduje oznaczenie taska jako zrealizowanego

** pola obowiązkowe podczas dodawania zadania

Rezultat zapytania

{ 
  "taskId" : "task-Id-123",
  "message" : [  ],
  "success" : true
}

W rezultacie zapytania otrzymujemy:

taskId – id zadania którego dotyczy akcja
success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd

API - Notatki

Dodawanie Notatki

Przykładowa struktura danych zapytania:

{
  "clientId":"your-client-id-123",
  "apiKey":"your-api-key-123",
  "requestTime":1327056031488,
  "sha":"2aa3927a7dee8c2a712adb5375f5fa36dd8fe00c",
  "owner": "owner@test.pl",
  "contactId": "",
  "email": "test1@test.pl",
  "priv": false,
  "note": "Notatka ktora bedzie dodana do kontaktu"
}

Dodawanie notatki do kontaktu wykonujemy za pomocą metody:
https://www.salesmanago.pl/api/contact/addNote

Pola dostępne w zapytaniu metody addNote:

Pole	Max. długość	Opis
owner*	255	konto właściciela kontaktu do którego dodawana jest notatka
email*	254^[?]	email kontaktu do którego dodajemy notatkę (opcjonalnie z contactId)
contactId*	255	id kontaktu do którego dodajemy notatkę (opcjonalnie z email)
priv	true/false	definiuje czy notatka ma być prywatna, czyli widoczna tylko przez dodającego (domyślnie false)
note*	1024	treść notatki

Rezultat zapytania

{
  "success": true,
  "message": [
    "Note was added to contact"
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji

API - Inne

Autoryzacja tymczasowa

Przykładowa struktura danych zapytania:

{ 
  "userName" : "admin@vendor.pl",
  "password" : "****"
}

System SALESmanago umożliwia uzyskanie tymczasowego tokenu wykorzystując nazwę użytkownika i hasło. W tym celu należy wykonać metodę:
https://www.salesmanago.pl/api/system/authorise

Pola dostępne w zapytaniu metody authorise:

Pole	Max. długość	Opis
userName*	255	nazwa użytkownika
password*	255	hasło

Rezultat zapytania

{ 
  "token" : "b426c6663d844305b2539e9bc27b75dc",
  "clientId" : "your-client-id-123",
  "validTo" : 1359673200361,
  "message" : [  ],
  "success" : true 
}

W rezultacie zapytania otrzymujemy:

token – to tymczasowy token, który można użyć w celu autoryzacji w zamian za apiSecret,
clientId – identyfikator klienta, wymagany do kolejnych operacji,
validTo – data ważności
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd,
success – wartość logicznaznajduje się ma wspomnianej zakładce „Integracja” informująca o rezultacie zapytania (udane / nieudane)

Pobieranie listy kont użytkowników danego klienta

Przykładowa struktura danych zapytania:

{
  "clientId": "your-api-key-123",
  "apiKey": "your-client-id-123",
  "requestTime": 1234567896541,
  "sha": "4f69782e826841f794080cae87648e42"
}

W celu otrzymania listy kont użytkowników danego klienta należy skorzystać z metody:
https://www.salesmanago.pl/api/user/listByClient

Pola dostępne w zapytaniu metody listByClient:
Ta metoda nie wymaga żadnych dodatkowych pól.

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "users": [
    "admin@vendor.pl",
    "test@test.pl"
  ]
}

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
users – lista emaili użytkowników

Pobierz URL pliku z danymi eksportu

Przykładowe żądanie:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "owner": "salesmanago.user@yourcompany.com",
  "requestId": 1234567
}

Możesz uzyskać adres URL pliku zawierającego wyeksportowane dane za pomocą metody API:
https://www.salesmanago.pl/api/job/status

Asynchroniczne eksporty

Wiele metod API pozwala na asynchroniczne eksportowanie danych do pliku JSON. Dzięki temu połączenie HTTP może zostać zamknięte, podczas gdy eksport jest przetwarzany w tle. W zależności od zakresu eksportu, może to trwać nawet kilkanaście minut, co znacznie przekracza maksymalny czas połączenia i nie byłoby możliwe w przypadku żądań synchronicznych. Typowy eksport składa się z:
1. Żądania eksportu, które zwraca requestId
2. Cyklicznego żądania job/status, które po podaniu requestId zwraca URL pliku JSON
3. Żądania GET w celu pobrania pliku JSON
Zalecany czas odpytywania o plik JSON przy użyciu job/status to 60 sekund.

Odpowiedź przed przetworzeniem eksportu:

{
  "success": true,
  "message": [
    "Job not start yet"
  ]
}

Pola dostępne w metodzie job/status:

Pole	Max. długość	Opis
owner	255	Właściciel Kontaktów (e-mail konta użytkownika SALESmanago)
requestId	int	Unikalny identyfikator żądania otrzymany z metody eksportu

Przykładowa odpowiedź po przetworzeniu eksportu:

{
  "success": true,
  "message": [],
  "fileUrl": "https://storage.googleapis.com/sm-file/a1b2-...-c3d4/1234-...-5678/abcd-...-efgh.json?GoogleAccessId=..."
}

W rezultacie zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
fileUrl – adres URL pliku z eksportem, ważny przez kilka minut od wygenerowania linku. Ważne: To pole zwracane jest tylko po ukończeniu eksportu.

API - Workflow

Pobieranie listy workflow 2.0

Przykładowa struktura danych zapytania:

{ 
 "clientId" : "your-client-id-123",
 "apiKey" : "your-api-key-123",
 "requestTime" : 1234567896541,
 "sha" : "4f69782e826841f794080cae87648e42"
}

W celu pobrania listy workflow 2.0 należy skorzystać z metody:
https://www.salesmanago.pl/api/workflow/list

Pola dostępne w zapytaniu metody api/workflow/list: Ta metoda nie wymaga żadnych dodatkowych pól.

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "workflows": [
    {
        "id": 1000001,
        "name": "workflow 1"
    },
    {
        "id": 1000002,
        "name": "workflow 2"
    }
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
workflows - lista nieusuniętych workflow 2.0
id - id workflow
name - nazwa workflow

Workflow Statisctics

Przykładowa struktura danych zapytania:

{
    "clientId": "axf46o35hgrf015q",
    "apiKey": "test123test",
    "requestTime": 1348046897664,
    "sha": "3436a3efd8c63f72c8ba827d53d1297482e6d85d",
    "workflowId": 10032430,
    "period": "PREVIOUS_YEAR"
}

W celu pobrania workflow statisctics należy skorzystać z metody:
https://www.salesmanago.pl/api/workflow/statistics

Pola dostępne w zapytaniu metody /api/workflow/statistics: Ta metoda nie wymaga żadnych dodatkowych pól.

Rezultat zapytania:

{
    "success": true,
    "message": [],
    "name": "New Workflow 2022-02-23 12:53",
    "creationDate": 1645617296,
    "launchesNumber": 0,
    "revenueStats": {
        "totalSales": 0.0,
        "totalLastClickSales": 0.0,
        "totalTransactionNumber": 0,
        "totalLastClickTransactionNumber": 0,
        "emailSales": 0.0,
        "emailLastClickSales": 0.0,
        "emailTransactionNumber": 0,
        "emailLastClickTransactionNumber": 0,
        "webPushSales": 0.0,
        "webPushClickSales": 0.0,
        "webPushTransactionNumber": 0,
        "webPushLastClickTransactionNumber": 0,
        "smsSales": 0.0,
        "smsClickSales": 0.0,
        "smsTransactionNumber": 0,
        "smsLastClickTransactionNumber": 0
    },
    "emailStats": {
        "averageOr": "-",
        "uniqueOpens": 0,
        "allOpens": 0,
        "averageCtr": "-",
        "uniqueClicks": 0,
        "allCliks": 0,
        "averageCtor": "-",
        "optOut": "-",
        "contactsOptOut": 0,
        "sentMessages": 0,
        "messageToSend": 0,
        "failedMessages": 0,
        "spam": 0,
        "softBounces": 0,
        "hardBounces": 0
    }
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
name - nazwa workflow
creationDate - lista nieusuniętych workflow 2.0
launchesNumber - id workflow
revenueStats - id workflow
totalSales -
totalLastClickSales -
totalTransactionNumber -
totalLastClickTransactionNumber -
emailSales -
emailLastClickSales -
emailTransactionNumber -
emailLastClickTransactionNumber -
webPushSales -
webPushClickSales -
webPushTransactionNumber -
webPushLastClickTransactionNumber -
smsSales -
smsClickSales -
smsTransactionNumber -
smsLastClickTransactionNumber -
emailStats -
averageOr -
uniqueOpens -
allOpens -
averageCtr -
uniqueClicks -
allClicks -
averageCtor -
optOut -
contactsOptOut -
sentMessages -
messageToSend -
failedMessages -
spam -
softBounces -
hardBounces -

API - Web Push

Pobieranie statystyk wysłanego powiadomienia Web Push

Przykładowa struktura danych zapytania:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "wizardId": 123456
}

Możesz pobrać statystyki wysłanego powiadomienia Web Push używając metody API:
https://www.salesmanago.pl/api/web/push/stats

Pola dostępne w metodzie web/push/stats:

Pole	Max. długość	Opis
wizardId*	Long (19)	Identyfikator przydzielony do wysłanego powiadomienia Web Push. Możesz go znaleźć, przechodząc do Web Push ➔ Wysłane Web Pushe, a następnie klikając Analityka w wybranym wierszu. Identyfikator znajduje się w adresie URL.

Rezultat zapytania:

{
  "success": true,
  "message": [],

  "name": "Example Web Push",
  "date": 1630150200000,
  "totalSent": 500,
  "anonymousSent": 200,
  "totalOpened": 150,
  "totalClicked": 100,
  "richWebPushOpened": 100,
  "richWebPushClicked": 50,
  "sent": [
    "name01@example.com",
    "name02@example.com",
    "name03@example.com",
    "name04@example.com",
    "..."
  ],
  "opened": [
    "name01@example.com",
    "name02@example.com",
    "name03@example.com",
    "name04@example.com",
    "..."
  ],
  "clicked": [
    "name01@example.com",
    "name02@example.com",
    "..."
  ]
}

W rezultacie zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów

name - nazwa powiadomienia Web Push
date - data wysłania powiadomienia Web Push
totalSent - liczba wysłanych powiadomień Web Push
anonymousSent - liczba wysłanych Web Pushy do Kontaktów anonimowych
totalOpened - liczba dostarczonych powiadomień Web Push
totalClicked - liczba klikniętych powiadomień Web Push
richWebPushOpened - liczba dostarczonych powiadomień Rich Web Push
richWebPushClicked - liczba klikniętych powiadomień Rich Web Push
sent - lista adresów e-mail Kontaktów, do których wysłano Web Push
opened - lista adresów e-mail Kontaktów, do których dostarczono Web Push
clicked - lista adresów e-mail Kontaktów, które kliknęły powiadomienie Web Push

Pobieranie listy identyfikatorów powiadomień web push

Przykładowa struktura danych zapytania:

{
    "apiKey": "our-api-key-123",
    "clientId" : "your-client-id-123",
    "sha" : "08924f45afc2e4fb8b652c53cdb493c7ddb846a1",
    "requestTime" : 1327059355361,
    "from":1572605631000,
    "to":1573558527000
}

W celu pobrania ID powiadomień web push należy skorzystać z metody:
https://www.salesmanago.pl/api/web/push/ids

Pola dostępne w zapytaniu metody web/push/ids:

Pole	Max. długość	Opis
from*	Timestamp	początek zakresu dat wysłanych web push
to*	Timestamp	koniec zakresu dat wysłanych web push

Rezultat zapytania:

{
    "success": true,
    "message": [],
    "webPushIds": [
        1,2,3
    ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
webPushIds - lista id wysłanych powiadomień web push

Lista identyfikatorów powiadomień Web Push

Przykładowa struktura danych zapytania:

{
  "apiKey": "test123test",
  "clientId" : "ye4vodnswfo6zp75",
  "sha" : "dsadsadasdsadsadsadsadsadsadb",
  "requestTime" :1626774053,
  "from":1595238047,
  "to":1626774053
}

Użyj następującej metody, aby uzyskać listę identyfikatorów powiadomień Web Push:
https://www.salesmanago.pl/api/notification/conversation/ids

Wypełnij dostępne pola, aby autoryzować metodę:

Pole	Max. długość	Opis
apiKey*	-	klucz do API
clientId*	-	id użytkownika
sha*	-	wygenerowany sha
requestTime*	-	czas wykonania żądania (ms)
from*	255	początkowy zakres dat stworzenia
to*	255	końcowy zakres dat stworzenia

Rezultat zapytania:

{
  "success": true,
  "message": [
    "Conversation list "
  ],
  "pushConversationIds": [
    16,
    17,
    18,
    19
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji
pushConversationIds – tablica z id webpushy

Eksportowanie statystyk formularzy zgody do pliku dostępnego z repozytorium

Przykładowa struktura danych zapytania:

{
  "apiKey": "test123test",
  "clientId" : "ye4vodnswfo6zp75",
  "sha" : "1a3225a77b341043e17672f369e9150afed488eb",
  "requestTime" :1626774053,
  "user":"superuser@gmail.com",
  "intId":101044
}

Użyj następującej metody, aby wyeksportować statystyki formularzy zgody do pliku, który będzie dostępny z repozytorium:
https://www.salesmanago.pl/api/notification/consent/form/stats

Wypełnij dostępne pola, aby autoryzować metodę:

Pole	Max. długość	Opis
apiKey*	-	klucz do API
clientId*	-	id użytkownika
sha*	-	wygenerowany sha
requestTime*	-	czas wykonania żądania (ms)
user*	255	email użytkownika
intId*	-	id formularza

Rezultat zapytania:

{
  "success": true,
  "message": [
    "Export added to execute."
  ],
  "requestId": 2660
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
requestId – identyfikator eksportu

Parametr “requestId” jest naszym identyfikatorem eksportu.

Aby sprawdzić status eksportu należy wysłać żądanie na adres: https://www.salesmanago.pl/api/job/status

Tu podajemy requestId z odpowiedzi, w której zawarty był numer do monitorowania statusu eksportu.

W odpowiedzi dostaniemy komunikat mówiący o postępie eksportu lub link do pobrania pliku z wyeksportowanymi danymi kontaktów.

Link jest ważny tylko przez kilka minut.

Przykładowa struktura danych zapytania /api/job/status:


{
  "clientId": "yourclientID",
  "apiKey": "yourAPIkey",
  "requestTime": 1500556989,
  "sha": "4afd12754c746fa9f71648f2e2276ae40eccfe41",
  "owner": "admin@vendor.pl",
  "requestId": 123
}

Rezultat zapytania


{
  "success": true,
  "message": [],
  "fileUrl": "https://salesmanago.s3.amazonaws.com/notrealdata/notrealdata/notrealdata.json"
}

Eksportuj statystyki powiadomień Web Push do pliku dostępnego z Repozytorium

Przykładowa struktura danych zapytania:

{
  "apiKey": "test123test",
  "clientId" : "ye4vodnswfo6zp75",
  "sha" : "1a3225a77b341043e17672f369e9150afed488eb",
  "user": "superuser@gmail.com",
  "itemId": "1",
  "webPushSourceType": "MASS"
}

Użyj poniższej metody, aby wyeksportować statystyki powiadomień Web Push do pliku, który będzie dostępny z repozytorium:
https://www.salesmanago.pl/api/notification/push/stats

Wypełnij dostępne pola, aby autoryzować metodę:

Pole	Max. długość	Opis
apiKey*	-	klucz do API
clientId*	-	id użytkownika
sha*	-	wygenerowany sha
user*	255	email użytkownika
itemId*		id
webPushSourceType*		typ webpusha

Rezultat zapytania:

{
  "success": true,
  "message": [
    "Export added to execute."
  ],
  "requestId": 2659
}

W rezultacie zapytania otrzymujemy:

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:

API - Mechanizmy rekomendacji

Ostatnio wyświetlane produkty

Przykładowe żądanie:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "contactUuid": "1a2b-...-3c4d",
  "shopName": "Example Store"
}

W celu pobrania listy ostatnio oglądanych produktów użyj poniższej metody:
https://www.salesmanago.pl/api/recommendation/lastViewed

Pola dostępne w metodzie lastViewed:

Pole	Max. długość	Opis
contactUuid*	UUID	Identyfikator Kontaktu z SALESmanago, który otrzymasz w odpowiedzi na każde żądanie z dodaniem lub aktualizacją Kontaktu.
shopName*	64	Nazwa Katalogu Produktowego / Feedu Produktowego XML. Uwaga: nie mylić z polem `location`.

Rezultat żądania:

{
  "message": [],
  "success": true,
  "productIds": [
    "5678",
    "9876"
  ]
}

W rezultacie zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
productIds – lista ID produktów

Najczęściej kupowane produkty

Przykładowa struktura danych zapytania:

{
  "clientId": "your-client-id-123",
  "apiKey": "salesmanago",
  "requestTime": 1481543324302,
  "sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
  "shopName": "dataSource"
}

Najczęściej kupowane produkty pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/mostPurchased

Pola dostępne w zapytaniu metody mostPurchased:

Pole	Max. długość	Opis
shopName*	255	nazwa źródła danych

Rezultat zapytania:

{
  "message" : [  ],
  "success" : true,
  "productIds" : [
    6754,
    6755
  ]
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
productIds – tablica zawierająca id produktów

Produkty kupione przez kontakt (tylko dla kontaktów monitorowanych)

Przykładowa struktura danych zapytania:

{
  "clientId": "your-client-id-123",
  "apiKey": "salesmanago",
  "requestTime": 1481543324302,
  "sha": "02bfe70541d3907cf487f26dc2665b184b1221a7",
  "smClient": "fecfca38-1f97-437d-91c4-2f30a67e31fa",
  "shopName": "dataSource"
}

Produkty kupione przez kontakt pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/purchasedByContact

Pola dostępne w zapytaniu metody purchasedByContact:

Pole	Max. długość	Opis
shopName*	255	nazwa źródła danych
smClient*	255	wartość ciasteczka smclient

Rezultat zapytania:

{
  "message" : [  ],
  "success" : true,
  "productIds" : [
    6754,
    6755
  ]
}

W rezultacie zapytania otrzymujemy:

Produkty zakupione wraz z oglądanym produktem

Przykładowa struktura danych zapytania:

{  
  "clientId": "axf46o35hgrf015q",  
  "apiKey": "Hh39uCkBdxTAXAvQE9Ng",  
  "requestTime": 1481543324302,  
  "sha": "480f4dc004753394507ec94cf8c84fa26f413623",  
  "productId": "5",  
  "shopName": "name"
}

Produkty zakupione wraz z oglądanym produktem pobieramy wywołując metodę:
https://www.salesmanago.pl/api/recommendation/purchasedTogether

Pola dostępne w zapytaniu metody purchasedTogether:

Pole	Max. długość	Opis
shopName*	64	nazwa źródła danych
productId*	32	id produktu

Rezultat zapytania:

{
  "message" : [  ],
  "success" : true,
  "productIds" : [
    6754,
    6755
  ]
}

Rezultat zapytania (error):

{
  "success": false,  
  "message": [
    "Product Id is invalid"  
  ],  
  "productIds": null
}

W rezultacie zapytania otrzymujemy:

API - Cinderella AI

Pobieranie rekomendacji produktowych na podstawie rozpoznawania obrazów

Przykładowa struktura danych zapytania:

{
  "clientId": "a1b2-...-c3d4",
  "apiKey": "e5f6-...-g7h8",
  "requestTime": 1659938888000,
  "sha": "2aa3-...-e00c",

  "imageUrl": "https://example.com/temp/uploads/a1b2c3d4e5.jpg",
  "location": "examplecom"
}

Description:

Możesz pobrać listę ID produktów zbliżonych wizualnie do zdjęcia przesłanego przez kontakt korzystając z metody API:

Endpoint

https://www.salesmanago.pl/api/vision

Pola dostępne w metodzie vision:

Pole	Max. długość	Opis
imageUrl*	2048	Adres URL przesłanego przez kontakt zdjęcia, które może zostać pobrane przez serwery SALESmanago
location*	64	Pole location zdefiniowane podczas tworzenia Feedu Produktowego XML / Katalogu Produktowego. Wartość pola możesz sprawdzić w SALESmanago → Centrum Integracji → Katalogi Produktowe.

Rezultat zapytania:

{
  "success": true,
  "message": [],

  "vision": {
    "status": "ok",
    "photo": "https://example.com/temp/uploads/a1b2c3d4e5.jpg",
    "result": [
      {
        "id": "p0123",
        "score": 0.9589041829109192
      },
      {
        "id": "p3456",
        "score": 0.94405747056007385
      },
      {
        "id": "p5678",
        "score": 0.9198060393333435
      }
    ],
    "bq_errors": 0
  }
}

W rezultacie zapytania otrzymujemy:

success – wartość logiczna informująca o rezultacie zapytania (udane/nieudane)
message – tablica dodatkowych informacji zawierająca komunikaty błędów
status – status wyszukiwania przy pomocy zdjęcia
photo – adres URL przesłanego zdjęcia
result – tablica obiektów zawierająca wyniki wyszukiwania
id – ID produktu
score – wartość dziesiętna pomiędzy 0 i 1 określająca podobieństwo wizualne produktu do zdjęcia przesłanego przez kontakt
bq_errors – liczba błędnych dopasowań

API - Centrum Preferencji Klienta

Centrum Preferencji Klienta

Aby otrzymać wstępnie autoryzowany widok Centrum Preferencji Klienta wywołaj:
https://www.salesmanago.pl/api/customerPreferenceCenter/generateEndpoint

Przykładowa struktura danych zapytania:

{
  "clientId": "5vvtmri5ocom6n8g",
  "apiKey": "-8773203084919279780-2743038323156910252",
  "requestTime": 1391167514795,
  "sha": "184db1df6ec4893a1f50809bf8d1a4fe88cde4dc",
  "preferenceCenterId" : "7bd071c1-cb96-45a7-8e95-c512c76189a2",
  "contactId": "47d82f5a-87d3-11eb-a567-f8a2d6e832bf"
}

Rezultat zapytania:

{
  "success": true,
  "message": [],
  "endpoint": "https://www.salesmanago.pl/customerPreferenceCenter/#/7bd071c1-cb96-45a7-8e95-c512c76189a2/47d82f5a-87d3-11eb-a567-f8a2d6e832bf/?key=240491"
}

Pola dostępne w zapytaniu metody generateEndpoint:

Field	Max. length	Description
preferenceCenterId*	255	Identyfikator Centrum Preferencji Klienta (może być skopiowany z zakładki Dostęp w ostatnim kroku kreatora Centrum Preferencji Klienta lub z pop-upu pojawiającego się po zapisaniu Centrum)
contactId*	255	Identyfikator kontaktu SALESmanago (możesz użyć wartości ciasteczka „smclient”)

W wyniku zapytania otrzymasz:

success – wartość logiczna informująca o rezultacie zapytania (udane / nieudane)
message – tablica dodatkowych informacji pozwalająca zidentyfikować błąd
endpoint – adres URL zawierający widok dashboardu użytkownika Centrum Preferencji Klienta. Widok jest autoryzowany za pomocą parametru key, co oznacza, że kontakt nie będzie musiał potwierdzać dostępu za pomocą wiadomości e-mail.