Raporty – atrybucja rekomendacji - ExpertSender Centrum pomocy

Ta metoda zwraca produkty, które klienci kupili dzięki rekomendacjom ECDP w wybranym zakresie dat. Każdy rekord to jeden zakupiony produkt przypisany do rekomendacji wyświetlonej w wiadomości e-mail, pop-upie lub banerze.

Każdy rekord zawiera informacje o zamówieniu, kliencie, kanale oraz wiadomości lub kampanii, która dostarczyła rekomendację, a także wartość produktu. Opcjonalnie możesz dodać opisowe pola przypisanego produktu oraz pełną listę produktów z tego samego zamówienia.

Użyj tej metody, aby weryfikować skuteczność rekomendacji.

Endpoint

GET /reports/attribution/recommendations

Host: https://api.ecdp.app

Parametry zapytania

Parametr	Lokalizacja	Typ	Wymagany	Opis	Dozwolone wartości / Uwagi
x-api-key	header	string	tak	Klucz API do uwierzytelniania	Dostępny w Ustawienia > API
startDate	query	string	tak	Początek okna raportowania	Format: YYYY-MM-DD. Interpretowana w strefie czasowej jednostki biznesowej. Musi być wcześniejsza lub równa endDate
endDate	query	string	tak	Koniec okna raportowania	Format: YYYY-MM-DD. Interpretowana w strefie czasowej jednostki biznesowej. Uwzględniany jest cały dzień końcowy
website	query	string	nie	Filtruje wyniki po ID lub nazwie strony	ID strony (liczba całkowita)
channel	query	enum	warunkowy	Ogranicza wyniki do jednego kanału	Email, PopUp, Banner, Sms, WebPush. Wielkość liter nie ma znaczenia. Wymagany, gdy podano messageType, messageId lub campaignId. Wartości Sms i WebPush są akceptowane, ale rekomendacje nie są dostępne dla tych kanałów, więc odpowiedź jest pusta
messageType	query	enum	nie	Ogranicza wyniki do jednego typu wiadomości	Newsletter, Scenario, Confirmation. Wymaga channel=Email, Sms lub WebPush. Confirmation dostępny wyłącznie dla kanału Email
messageId	query	integer	nie	Ogranicza wyniki do konkretnej wiadomości	Wymaga channel=Email, Sms lub WebPush
campaignId	query	integer	nie	Ogranicza wyniki do konkretnej kampanii pop-up lub baneru	Wymaga channel=PopUp lub Banner
includeProductDetails	query	boolean	nie	Uwzględnia opisowe pola przypisanego produktu	true lub false. Domyślnie: false
includeOrderDetails	query	boolean	nie	Uwzględnia wszystkie produkty z zamówienia dla każdego rekordu	true lub false. Domyślnie: false

Odpowiedź

Odpowiedź zawiera tablicę data. Każdy element reprezentuje jeden zakupiony produkt przypisany do rekomendacji.

Dane raportu atrybucji rekomendacji

Pole	Typ	Opis
dateTime	string	Data i godzina rekordu w strefie czasowej jednostki biznesowej. Format: YYYY-MM-DDThh:mm:ss, bez przesunięcia UTC
websiteId	integer	Strona, z której pochodzi zamówienie
channel	string	Kanał, który dostarczył rekomendację: Email, PopUp lub Banner
messageType	string	Typ wiadomości: Newsletter, Scenario lub Confirmation. Pomijane dla PopUp i Banner
messageId	integer	Identyfikator przypisanej wiadomości. Pomijane dla PopUp i Banner
campaignId	integer	Identyfikator przypisanej kampanii pop-up lub baneru. Pomijane dla Email
orderId	string	Identyfikator zamówienia zawierającego przypisany produkt
customer	object	Dane klienta. Zobacz tabelę Dane klienta. Pomijane, gdy zamówienie nie jest powiązane z klientem
productId	string	Identyfikator przypisanego produktu zgodny ze źródłem e-commerce
productValueConverted	number	Wartość przypisanego produktu przeliczona na walutę raportowania jednostki biznesowej
productDetails	object	Obecne, gdy includeProductDetails=true. Ma strukturę opisaną w tabeli Szczegóły produktu
orderDetails	array	Obecne, gdy includeOrderDetails=true. Każdy element ma strukturę opisaną w tabeli Szczegóły produktu

Dane klienta

Obiekt customer zawiera następujące pola.

Pole	Typ	Opis
id	integer	Wewnętrzny identyfikator klienta w ECDP
email	string	Adres e-mail klienta
phone	string	Numer telefonu klienta
crmId	string	Identyfikator klienta w systemie CRM

Szczegóły produktu

Gdy includeProductDetails=true, każdy rekord zawiera obiekt productDetails opisujący przypisany produkt. Gdy includeOrderDetails=true, każdy rekord zawiera tablicę orderDetails ze wszystkimi produktami z zamówienia. Oba pola mają tę samą strukturę, taką samą jak pozycje zamówienia w raporcie atrybucji zamówień. Jeśli ustawisz oba parametry na true, przypisany produkt pojawi się zarówno w productDetails, jak i w orderDetails.

Pole	Typ	Opis
id	string	Identyfikator produktu zgodny ze źródłem e-commerce
name	string	Nazwa produktu
price	number	Cena jednostkowa w oryginalnej walucie transakcji
quantity	integer	Zakupiona ilość
returned	integer	Zwrócona ilość. Pomijane, jeśli nie ustawiono
category	string	Kategoria produktu. Pomijane, jeśli nie ustawiono
productAttributes	array	Tablica par { name, value } z niestandardowymi cechami produktu. Pomijane, jeśli brak
recommendationAttribution	object	Obecne, gdy produkt został dodany za pośrednictwem rekomendacji ECDP. Zobacz strukturę poniżej

Obiekt atrybucji rekomendacji

Pole	Typ	Opis
scope	string	Zakres atrybucji: Channel (Email) lub Onsite (PopUp, Banner)
type	string	Typ rekomendatora: Personalized, Complementary, Bestsellers, Popular, SimilarProducts, CrossSell, VisuallySimilar, SimilarProperties, Emailing lub RecentlyViewed
id	integer	Identyfikator wiadomości (Email) lub kampanii (PopUp, Banner), która dostarczyła rekomendację
channel	string	Powierzchnia rekomendacji: Email, PopUp lub Banner

Przykładowe zapytania i odpowiedzi

Zakupy przypisane do rekomendacji w wybranym zakresie dat

GET /reports/attribution/recommendations?startDate=2025-03-01&endDate=2025-03-07

Odpowiedź (200 OK):

{
  "data": [
    {
      "dateTime": "2025-03-03T11:24:15",
      "websiteId": 1,
      "channel": "Banner",
      "campaignId": 310,
      "orderId": "100042",
      "customer": {
        "id": 981245,
        "email": "customer@example.com",
        "phone": "48123456789",
        "crmId": "778"
      },
      "productId": "SKU-225",
      "productValueConverted": 29.95
    }
  ]
}

Zakupy przypisane do newslettera e-mail, ze szczegółami produktu

GET /reports/attribution/recommendations?startDate=2025-03-01&endDate=2025-03-07&website=21&channel=Email&messageType=Newsletter&messageId=12045&includeProductDetails=true

Odpowiedź (200 OK):

{
  "data": [
    {
      "dateTime": "2025-03-05T19:02:41",
      "websiteId": 1,
      "channel": "Email",
      "messageType": "Newsletter",
      "messageId": 12045,
      "orderId": "100057",
      "customer": {
        "id": 771100,
        "email": "customer@example.com",
        "phone": "",
        "crmId": "101"
      },
      "productId": "SKU-101",
      "productValueConverted": 39.90,
      "productDetails": {
        "id": "SKU-101",
        "name": "Canvas Tote",
        "price": 39.90,
        "quantity": 1,
        "returned": 0,
        "category": "Bags"
      }
    }
  ]
}

Zakupy przypisane do kampanii banerowej, ze szczegółami produktu i zamówienia

GET /reports/attribution/recommendations?startDate=2025-03-15&endDate=2025-03-15&website=21&channel=Banner&campaignId=310&includeProductDetails=true&includeOrderDetails=true

Odpowiedź (200 OK):

{
  "data": [
    {
      "dateTime": "2025-03-15T09:41:06",
      "websiteId": 1,
      "channel": "Banner",
      "campaignId": 310,
      "orderId": "100063",
      "customer": {
        "id": 332100,
        "email": "customer@example.com",
        "phone": "",
        "crmId": "551"
      },
      "productId": "SKU-555",
      "productValueConverted": 51.40,
      "productDetails": {
        "id": "SKU-555",
        "name": "Insulated Mug",
        "price": 51.40,
        "quantity": 1,
        "returned": 0,
        "category": "Kitchen",
        "recommendationAttribution": {
          "scope": "Onsite",
          "type": "Bestsellers",
          "id": 310,
          "channel": "Banner"
        }
      },
      "orderDetails": [
        {
          "id": "SKU-101",
          "name": "Canvas Tote",
          "price": 39.90,
          "quantity": 1,
          "returned": 0,
          "category": "Bags",
          "productAttributes": [
            { "name": "color", "value": "natural" }
          ]
        },
        {
          "id": "SKU-555",
          "name": "Insulated Mug",
          "price": 51.40,
          "quantity": 1,
          "returned": 0,
          "category": "Kitchen",
          "recommendationAttribution": {
            "scope": "Onsite",
            "type": "Bestsellers",
            "id": 310,
            "channel": "Banner"
          }
        }
      ]
    }
  ]
}

Kody odpowiedzi

Kod	Status	Opis
200	OK	Żądanie zostało przetworzone pomyślnie. Odpowiedź zawiera listę przypisanych produktów. Gdy żadne dane nie spełniają kryteriów zapytania, tablica data jest pusta
400	Bad Request	Błędne żądanie. Nieprawidłowe lub brakujące parametry. Odpowiedź zawiera pola substatus i errors, które wskazują problem
401	Unauthorized	Brak autoryzacji. Klucz API jest brakujący, nieprawidłowy lub wygasł. Sprawdź swój klucz w Ustawienia > API

Reguły walidacji i zachowania

startDate i endDate są wymagane i muszą mieć format YYYY-MM-DD. startDate musi być wcześniejsza lub równa endDate. W przeciwnym razie zapytanie zwraca błąd 400 Bad Request.
website musi wskazywać istniejące ID. W przeciwnym razie zapytanie zwraca błąd 400 Bad Request.
channel jest wymagany, gdy podano messageType, messageId lub campaignId.
messageType i messageId można stosować wyłącznie z channel=Email, Sms lub WebPush. campaignId można stosować wyłącznie z channel=PopUp lub Banner. Niepasująca kombinacja zwraca błąd 400 Bad Request.
Wartość Confirmation parametru messageType jest prawidłowa wyłącznie gdy channel=Email.
messageId i campaignId muszą wskazywać istniejącą wiadomość lub kampanię. W przeciwnym razie zapytanie zwraca błąd 400 Bad Request.
Rekomendacje są dostępne dla kanałów Email, PopUp i Banner. Zapytanie z channel=Sms lub channel=WebPush jest prawidłowe, ale zawsze zwraca pustą tablicę data.
Gdy zamówienie nie jest powiązane z klientem, obiekt customer jest pomijany w rekordzie.

Dokumentacja referencyjna

Swagger — Raporty atrybucji

https://api.ecdp.app/swagger/index.html