Raporty – SMS – raport pojedynczej wiadomości
Ta metoda zwraca statystyki dostarczalności i zaangażowania dla pojedynczej wiadomości SMS typu newsletter lub scenariusz. Użyj go, aby pobrać takie dane jak liczba wysłanych wiadomości, współczynnik dostarczalności, kliknięcia i przychód dla konkretnej wiadomości.
Endpoint
GET reports/sms/singleMessage/{id}
Host: https://api.ecdp.app
Parametry zapytania
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Dozwolone wartości / Uwagi |
| x-api-key | header | string | tak | Llucz API do uwierzytelnienia | Dostępny w Ustawienia > API |
| id | path | integer | tak | Identyfikator wiadomości SMS w ECDP | Nie może być pusty. |
| includeDetails | query | integer | nie | Określa, czy odpowiedź ma zawierać szczegóły wiadomości | 0 (domyślnie) lub 1 |
| startDate | query | string | warunkowy | Początek zakresu dat raportu | Format: YYYY-MM-DD. Wymagany dla wiadomości typu Scenariusz. Niedozwolony dla wiadomości typu Newsletter. |
| endDate | query | string | warunkowy | Koniec zakresu dat raportu | Format: YYYY-MM-DD. Wymagany dla wiadomości typu Scenariusz. Niedozwolony dla wiadomości typu Newsletter. startDate ≤ endDate. |
| sender | query | string | nie | Zawęża wyniki do konkretnego nadawcy | Dozwolony tylko jeden typ filtra na żądanie. Podanie wielu filtrów lub wielu wartości zwraca błąd 400 Bad Request. |
| grouping | query | string | nie | Poziom agregacji danych w odpowiedzi | Message (domyślnie), Sender. Dozwolona tylko jedna wartość grupowania. Podanie wielu wartości zwraca błąd 400 Bad Request. |
| messageDetails | query | boolean | nie | Wyświetla szczegóły wiadomości w odpowiedzi | true lub false (domyślnie) |
Opcje grupowania
Na jedno żądanie dozwolona jest dokładnie jedna wartość grupowania. Domyślnie: grouping=Message.
| Wartość grupowania | Kolumna grupowania w odpowiedzi |
| Message | messageId, messageName |
| Sender | sender |
Odpowiedź
Odpowiedź zawiera następujące dane w zależności od użytych filtrów.
SMS message details
Obecne tylko gdy includeDetails=1.
| Pole | Typ | Opis |
| messageId | string | Identyfikator wiadomości SMS |
| name | string | Nazwa wiadomości skonfigurowana w ECDP |
| type | string | Typ wiadomości: Newsletter lub Scenariusz |
| sender | string | Nazwa nadawcy wyświetlana odbiorcom |
| sentDate | string | Data i godzina wysłania wiadomości. Format: YYYY-MM-DD |
| utms[] | array | Parametry śledzenia UTM. Każdy element zawiera name i value. |
SMS report data
Każdy obiekt w tablicy reprezentuje jeden wiersz zagregowanych statystyk, określony przez wybrane grupowanie.
| Pole | Typ | Opis |
| messageId | string | Obecne gdy grouping=Message |
| messageName | string | Obecne gdy grouping=Message |
| sender | string | Obecne gdy grouping=Sender |
| sent | integer | Łączna liczba wiadomości SMS przekazanych do dostarczenia |
| partsSent | integer | Łączna liczba wysłanych części SMS (długa wiadomość może składać się z wielu części) |
| bounced | integer | Liczba wiadomości, których nie udało się dostarczyć |
| bouncedPercent | number | Bounced / sent. Zwraca 0.0, jeśli sent = 0. |
| delivered | integer | Liczba wiadomości potwierdzonych jako dostarczone |
| deliveredPercent | number | Delivered / sent. Zwraca 0.0, jeśli sent = 0. |
| clicks | integer | Łączna liczba kliknięć linków |
| clicksPercent | number | Clicks / sent. Zwraca 0.0, jeśli sent = 0. |
| clickers | integer | Liczba unikalnych odbiorców, którzy kliknęli co najmniej jeden link |
| clicksToDeliveredPercent | number | Clicks / delivered. Zwraca 0.0, jeśli delivered = 0. |
| unsubscribes | integer | Liczba odbiorców, którzy wypisali się po otrzymaniu wiadomości |
| revenue | number | Łączny przypisany przychód z tej wiadomości |
| currency | string | Kod waluty dla wartości revenue (ISO 4217) |
Kody odpowiedzi#
| Kod | Status | Opis |
| 200 | OK | Żądanie przetworzone pomyślnie. Odpowiedź zawiera statystyki wiadomości. |
| 204 | No content | Żądanie jest poprawne, ale żadne dane nie pasują do podanych parametrów. |
| 400 | Bad request | Nieprawidłowe lub brakujące parametry. Sprawdź reguły zakresu dat, filtrów i grupowania. |
| 401 | Unauthorized | Klucz API jest brakujący, nieprawidłowy lub wygasł. Zweryfikuj klucz w Settings > API. |
| 403 | Forbidden | Klucz API nie ma uprawnień dostępu do tego zasobu. |
| 500 | Internal server error | Błąd po stronie serwera. Ponów żądanie lub skontaktuj się z pomocą techniczną, jeśli problem się utrzymuje. |
Przykładowe zapytania i odpowiedzi
Pobierz szczegóły wybranej wiadomości SMS (newsletter)
Zapytanie:
GET /reports/sms/singleMessage/8421?includeDetails=1
Odpowiedź: 200 OK
{
"messageDetails": {
"messageId": "8421",
"type": "Newsletter",
"name": "kampania ZIMA",
"sender": "SKLEP",
"sentDate": "2025-01-18T09:30:00Z",
"utms": [
{ "name": "utm_source", "value": "sms" },
{ "name": "utm_campaign", "value": "zima-10" }
]
},
"data": [
{
"messageId": "8421",
"messageName": "zima-2025",
"sent": 10000,
"partsSent": 11250,
"bounced": 15,
"bouncedPercent": 0.0015,
"delivered": 9985,
"deliveredPercent": 0.9985,
"clicks": 720,
"clicksPercent": 0.0720,
"clickers": 610,
"clicksToDeliveredPercent": 0.0721,
"unsubscribes": 22,
"revenue": 5140.90,
"currency": "PLN"
}
]
}Pobierz szczegóły wiadomości scenariuszowej filtrując po dacie oraz nadawcy
Zapytanie:
GET /reports/sms/singleMessage/301?startDate=2025-03-01&endDate=2025-03-07&sender=ECOMMERCE
Odpowiedź: 200 OK
{
"data": [
{
"messageId": "301",
"messageName": "latnia-wyprzedaz",
"sent": 5200,
"partsSent": 5650,
"bounced": 6,
"bouncedPercent": 0.0012,
"delivered": 5194,
"deliveredPercent": 0.9988,
"clicks": 390,
"clicksPercent": 0.0751,
"clickers": 335,
"clicksToDeliveredPercent": 0.0755,
"unsubscribes": 11,
"revenue": 1896.40,
"currency": "PLN"
}
]
}Reguły walidacji i zachowania
- id musi wskazywać na istniejącą wiadomość SMS w ECDP.
- includeDetails przyjmuje tylko wartości 0 lub 1. Każda inna wartość zwraca błąd 400 Bad Request.
- Wiadomości typu Newsletter nie obsługują filtrowania według zakresu dat. Podanie parametru startDate lub endDate dla wiadomości Newsletter zwraca błąd 400 Bad Request.
- Wiadomości typu Scenariusz wymagają podania zarówno startDate, jak i endDate. Pominięcie któregokolwiek z nich zwraca błąd 400 Bad Request.
- Gdy oba parametry dat są podane: startDate musi być mniejsze lub równe endDate.
- Na jedno zapytanie dozwolona jest tylko jedna wartość grupowania. Podanie wielu wartości zwraca błąd 400 Bad Request.
- Na jedno zapytanie dozwolony jest tylko jeden typ filtra z dokładnie jedną wartością. Podanie wielu filtrów lub wielu wartości zwraca błąd 400 Bad Request.
- Dzielenie przez zero w polach procentowych zwraca 0.0.
Dokumentacja referencyjna
Swagger – Reports SMS