Klienci – eksport danych o aktywności klientów w kanałach komunikacji

Te metody służą do planowania i eksportowania danych o aktywności klientów w kanałach e-mail, SMS i web push dla wybranego zakresu dat.

Dane dostarczane są w postaci pliku CSV. Eksport działa asynchronicznie, więc nie blokuje klienta – planujesz eksport, a następnie sprawdzasz jego status i pobierasz plik, gdy jest gotowy.

POST– zaplanuj eksport

Endpoint

Adres serwera dla tego zapytania to https://api.ecdp.app/exports/channels/activity

Parametry zapytania

Parametr	Lokalizacja	Typ	Wymagany	Opis	Dozwolone wartości / uwagi
x-api-key	header	string	tak	Klucz API do uwierzytelniania.	Pobierz z Ustawienia > API.
Content-Type	header	string	tak	Typ zawartości żądania.	application/json
startDate	body	string	tak	Początek okna eksportu.	Format: YYYY-MM-DD. Zakres dat nie może przekraczać 90 dni. startDate musi być wcześniejsza niż endDate.
endDate	body	string	tak	Koniec okna eksportu.	Format: YYYY-MM-DD. Zakres dat nie może przekraczać 90 dni. endDate musi być późniejsza niż startDate.
channels	body	enum[]	nie	Ogranicza eksport do jednego lub więcej kanałów. Jeśli pominięty, uwzględniane są wszystkie kanały.	Email, SMS, WebPush. Przyjmuje wiele wartości jako tablicę JSON.
eventTypes	body	enum[]	nie	Ogranicza eksport do jednego lub więcej typów zdarzeń. Jeśli pominięty, uwzględniane są wszystkie obsługiwane typy zdarzeń.	Zobacz Obsługiwane typy zdarzeń według kanału poniżej. Przyjmuje wiele wartości jako tablicę JSON. Wartość spoza obsługiwanego zbioru zwraca 400 Bad Request.
fileName	body	string	nie	Własna nazwa pliku eksportu (bez rozszerzenia).	Musi być bezpieczną nazwą pliku (bez znaków specjalnych). Rozszerzenie .csv jest dodawane automatycznie.

Obsługiwane typy zdarzeń według kanału

Typ zdarzenia	Email	SMS	Web Push	Opis
Send	✓	✓	✓	Próba wysyłki lub dodanie do kolejki.
Delivery	✓	–	–	Potwierdzenie dostarczenia (tylko Email).
Bounce	✓	✓	–	Twarde lub miękkie odrzucenie.
Open	✓	–	–	Otwarcie wiadomości email.
View	–	–	✓	Wyświetlenie lub impresja Web Push.
Click	✓	✓	✓	Kliknięcie śledzonego linku.
Unsubscribe	✓	✓	✓	Rezygnacja z subskrypcji kanału.
Order	✓	✓	✓	Zamówienie przypisane do wiadomości.

Odpowiedź

Poprawne zapytanie zwraca 200 OK z następującymi polami:

Pole	Typ	Opis
exportId	integer	Identyfikator do wykorzystania przy sprawdzaniu statusu.
status	string	Początkowy status eksportu. Queued lub Processing.
createdAt	string	Data zaplanowania eksportu. Data w formacie zgodnym z ISO-8601 UTC.
parameters	object	Odzwierciedlenie parametrów żądania: startDate, endDate, channels, eventTypes oraz fileName (jeśli podano).

Kody odpowiedzi

Kod	Status	Opis
200	OK	Eksport został pomyślnie zaplanowany.
400	Bad Request	Nieprawidłowe lub brakujące parametry, nieobsługiwany typ zdarzenia lub zakres dat przekracza 90 dni.
401	Unauthorized	Brakujący lub nieprawidłowy klucz API.
403	Forbidden	Niewystarczające uprawnienia do tej operacji.
500	Internal Server Error	Błąd po stronie serwera. Ponów zapytanie lub skontaktuj się z pomocą techniczną.

GET – sprawdź status eksportu

Endpoint

Adres serwera dla tego zapytania to https://api.ecdp.app/exports/channels/activity/{exportId}

Parametry zapytania

Parametr	Lokalizacja	Typ	Wymagany	Opis	Dozwolone wartości / uwagi
x-api-key	header	string	tak	Klucz API do uwierzytelniania.	Pobierz z Ustawienia > API.
exportId	path	integer	tak	Identyfikator eksportu zwrócony przez żądanie planowania.

Odpowiedź

Pole	Typ	Obecne gdy	Opis
exportId	integer	zawsze	Identyfikator eksportu.
status	string	zawsze	Bieżący status eksportu. Queued, Processing, Completed, Failed lub Expired.
createdAt	string	zawsze	Data zaplanowania eksportu. Data w formacie zgodnym z ISO-8601 UTC.
expiresAt	string	eksport ukończony	Data wygaśnięcia linku do pobrania. Data w formacie zgodnym z ISO-8601 UTC.
fileName	string	eksport ukończony	Ostateczna nazwa pliku z rozszerzeniem .csv.
rows	integer	eksport ukończony	Liczba wierszy zawierających dane w pliku CSV. Wiersz nagłówka nie jest wliczany.
fileUrl	string	eksport ukończony	Tymczasowy adres HTTPS do pobrania pliku CSV.
error	string	błąd eksportu	Opis przyczyny niepowodzenia eksportu.

Kody odpowiedzi

Kod	Status	Opis
200	OK	Status zwrócony pomyślnie.
401	Unauthorized	Brakujący lub nieprawidłowy klucz API.
403	Forbidden	Niewystarczające uprawnienia do tej operacji.
404	Not Found	Nie znaleziono eksportu dla podanego exportId.
500	Internal Server Error	Błąd po stronie serwera. Ponów żądanie lub skontaktuj się z pomocą techniczną.

Przykładowe żądania i odpowiedzi#

Eksport danych z jednego dnia ze wszystkich kanałów

Zaplanuj eksport

{
  "startDate": "2025-03-15",
  "endDate": "2025-03-15"
}

Odpowiedź – 200 OK

{
  "exportId": "123",
  "status": "Queued",
  "createdAt": "2025-03-15T00:00:05Z",
  "parameters": {
    "startDate": "2025-03-15",
    "endDate": "2025-03-15",
    "channels": ["Email", "SMS", "WebPush"],
    "eventTypes": []
  }
}

Sprawdź status

GET /exports/channels/activity/123

Odpowiedź – 200 OK

{
  "exportId": "123",
  "status": "Completed",
  "createdAt": "2025-03-15T00:00:05Z",
  "expiresAt": "2025-03-16T00:00:05Z",
  "fileName": "channels-activity-2025-03-15.csv",
  "rows": 7,
  "fileUrl": "https://download.ecdp.app/exports/123/channels-activity-2025-03-15.csv"
}

Eksport danych z wybranego zakresu dat, filtrowany według kanału i typu zdarzenia

Zaplanuj eksport

Required request format: JSON

{
  "startDate": "2025-03-01",
  "endDate": "2025-03-10",
  "channels": ["Email", "WebPush"],
  "eventTypes": ["Click", "Unsubscribe"],
  "fileName": "activity_clicks"
}

Odpowiedź – 200 OK

{
  "exportId": "312",
  "status": "Queued",
  "createdAt": "2025-03-01T00:00:02Z",
  "parameters": {
    "startDate": "2025-03-01",
    "endDate": "2025-03-10",
    "channels": ["Email", "WebPush"],
    "eventTypes": ["Click", "Unsubscribe"],
    "fileName": "activity_clicks"
  }
}

}

Sprawdź status

GET /exports/channels/activity/312

Response – 200 OK

{
  "exportId": "312",
  "status": "Completed",
  "createdAt": "2025-03-01T00:00:02Z",
  "expiresAt": "2025-03-02T00:00:02Z",
  "fileName": "activity_clicks.csv",
  "rows": 12345,
  "fileUrl": "https://download.ecdp.app/exports/312/activity_clicks.csv"
}

Struktura pliku CSV#

Plik zawiera jedno zdarzenie na wiersz. Kolumny występują w następującej stałej kolejności:

Nr	Kolumna	Opis
1	Date	Data zdarzenia w formacie ISO-8601 UTC.
2	Channel	Email, Sms lub WebPush.
3	EventType	Jeden z obsługiwanych typów zdarzeń.
4	CustomerId	Wewnętrzny identyfikator klienta w ECDP.
5	Email	Adres email klienta.
6	Phone	Numer telefonu klienta.
7	CrmId	Identyfikator klienta w systemie CRM.
8	MessageType	Newsletter, Scenario lub typ właściwy dla danego kanału.
9	MessageId	Wewnętrzny identyfikator wiadomości.
10	MessageSubjectOrName	Temat wiadomości email, nazwa powiadomienia Web Push lub nazwa kampanii SMS (jeśli dostępna).
11	WebsiteId	Tylko Web Push; puste dla pozostałych kanałów.
12	RelatedOrderId	Zamówienie przypisane do wiadomości, jeśli dotyczy; w przeciwnym razie puste.

Puste lub nieznane pola są wy.świetlane jako puste komórki CSV.

Przykładowy plik CSV#

Date,Channel,EventName,CustomerId,Email,Phone,CrmId,MessageType,MessageId,MessageSubjectOrName,WebsiteId,RelatedOrderId
2025-03-01T10:05:33Z,Email,Click,771100,bob@example.com,,101,"Newsletter",11880,"Flash Sale",,
2025-03-01T10:45:09Z,Email,Unsubscribe,771100,bob@example.com,,101,"Newsletter",11880,"Flash Sale",,
2025-03-01T11:20:02Z,WebPush,Click,902233,,,144,"Scenario",4501,"Cart Reminder",12,14577

Reguły walidacji i zachowania

Zakres dat (endDate − startDate + 1) nie może przekraczać 90 dni.
Parametry channels i eventTypes przyjmują wiele wartości jako tablice JSON.
Jeśli channels jest pominięty, uwzględniane są wszystkie trzy kanały (Email, SMS, Web Push).
Jeśli eventTypes jest pominięty, uwzględniane są wszystkie typy zdarzeń obsługiwane przez wybrane kanały.
Sprawdzaj status eksportu do momentu, gdy status przyjmie wartość Completed, Failed lub Expired, zanim podejmiesz próbę pobrania pliku.

Dokumentacja referencyjna

Swagger – Exports

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