Nazwa

URL

Opis

Lista respondentów

/respondents/:id_survey

Zwraca listę wszystkich respondentów z ankiety określonej parametrem :id_survey. Respondenci posortowani są wg. adresu email w kolejności alfabetycznej.

Wyszukiwanie respondentów

/respondents/search/:id_survey

Wyszukuje respondentów wg. kryteriów przekazanych w tablicy POST

Dodanie respondenta do ankiety

/respondents/add

Przypisuje kontakt do ankiety

Usunięcie respondenta

/respondents/delete

Przypisuje kontakt do ankiety

Batch upload respondentów

/respondents/batch

Przesyłanie respondentów zgrupowanymi paczkami, dla których można stworzyć na końcu jeden mailing

Lista operacji dla zasobu

Opis parametrów odpowiedzi

Nazwa/ścieżka

Opis

Możliwe wartości

id

ID respondenta

token

Unikalny token jednoznacznie identyfikujący respondenta. Używany do jednorazowego wypełniania ankiety przez respondenta. Parametr aktywny tylko przy najwyższym poziomie bezpieczeństwa ankiety.

offline_distribution

Informacja o tym, czy zaproszenie do wypełnienia ankiety realizowane jest przez webankieta.pl czy ze strony autora ankiety. Przekazywanie user_tokena w linku do wypełnienia ankiety jest traktowane również jako dystrybucja ze strony autora.

0 – Link do ankiety wysyłany z webankieta.pl
1 – Link do ankiety wysyłany przez autora (dystrybucja tokenów offline)

date_generate

Data dodania respondenta do ankiety

date_invitaion_send

Data i godzina wysyłki zaproszenia

null – Nie wysyłano zaproszenia do respondenta
0000-00-00 00:00:00 – Zaproszenie oczekuje na wysyłkę
2012-12-06 12:00:00 – Data i godzina wysyłki zaproszenia

date_survey_open

Data i godzina pierwszego otwarcia ankiety. Parametr aktywny tylko przy najwyższym poziomie bezpieczeństwa ankiety.

null – Ankieta nie była otwierana przez respondenta
2012-12-06 12:00:00 – Data i godzina otwarcia ankiety

date_survey_answer

Data i godzina wypełnienia ankiety. Parametr aktywny tylko przy najwyższym poziomie bezpieczeństwa ankiety.

null – Ankieta nie była wypełniana przez respondenta
2012-12-06 12:00:00 – Data i godzina otwarcia ankiety

answer_postponed

Czy odpowiedź respondenta odłożona na później w trakcie wypełniania. Parametr aktywny tylko przy najwyższym poziomie bezpieczeństwa ankiety.

null – Ankieta nie wypełniona
0 – Wypełnianie nie odkładane
1 – Wypełnianie odłożone na później

email

Adres e-mail respondenta

label1

Wartość pierwszej opcjonalnej etykiety. Etykieta aktywna, jeśli respondent jest dodany z kontaktów użytkownika.

label2

Wartość drugiej opcjonalnej etykiety. Etykieta aktywna, jeśli respondent jest dodany z kontaktów użytkownika.

label3

Wartość trzeciej opcjonalnej etykiety. Etykieta aktywna, jeśli respondent jest dodany z kontaktów użytkownika.

label4

Wartość czwartej opcjonalnej etykiety. Etykieta aktywna, jeśli respondent jest dodany z kontaktów użytkownika.

label5

Wartość piątej opcjonalnej etykiety. Etykieta aktywna, jeśli respondent jest dodany z kontaktów użytkownika.

survey_link

Unikalny link do ankiety przeznaczony dla danego respondenta. Parametr aktywny tylko przy najwyższym poziomie bezpieczeństwa ankiety.

Lista respondentów

URL

(GET) https://www.webankieta.pl/api/v2/respondents/:id_survey

Parametry opcjonalne (POST)

Nazwa

Opis

limit

Limit na liczbę wypełnień

offset

Offset na listę

Przykładowa odpowiedź

{
"total":"20",
"list":[{
"id":100824,
"token":"549E56",
"date_token_generate":"2011-11-25 22:27:42",
"date_invitaion_send":null,
"date_survey_open":null,
"date_survey_answer":null,
"email":"jan@kowalski.pl",
"label1":"Jan",
"label2":"Kowalski",
"label3":"600 700 800",
"label4":"",
"label5":"",
"answer_postponed":null
},{
...
}]
}

Zwracane błędy

  • 401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu.

  • 404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.

  • 404 Not Found – Jeżeli nie znaleziono respondentów.

  • 406 Not Acceptable – Jeżeli nie przekazano parametru :id_survey.

Wyszukiwanie respondentów

URL

(GET) https://www.webankieta.pl/api/v2/respondents/search/:id_survey

Parametry opcjonalne (POST)

Nazwa

Opis

limit

Limit na liczbę wypełnień

offset

Offset na listę

token

Wyszukiwanie respondenta po tokenie

email

Wyszukiwanie respondenta po adresie email

date_generate

Wyszukiwanie respondenta po dacie dodania go do ankiety. Data musi być przekazana w formacie YYYY-MM-DD (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci dodani tego dnia.

date_invitaion_send

Wyszukiwanie respondenta po dacie wysyłki zaproszenia. Data musi być przekazana w formacie YYYY-MM-DD (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci, do których wysłano zaproszenie tego dnia.

date_survey_open

Wyszukiwanie respondenta po dacie pierwszego otwarcia ankiety. Data musi być przekazana w formacie YYYY-MM-DD (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci, którzy otworzyli ankietę tego dnia.

date_survey_answer

Wyszukiwanie respondenta po dacie pierwszego wypełnienia ankiety. Data musi być przekazana w formacie YYYY-MM-DD (np. 2011-11-20). Zostaną wyszukani wszyscy respondenci, którzy otworzyli ankietę tego dnia.

label1

Wyszukiwanie respondenta po wartości etykiety 1

label2

Wyszukiwanie respondenta po wartości etykiety 2

label3

Wyszukiwanie respondenta po wartości etykiety 3

label4

Wyszukiwanie respondenta po wartości etykiety 4

label5

Wyszukiwanie respondenta po wartości etykiety 5

Przykładowa odpowiedź

{
"total":"20",
"list":[{
"id":100824,
"token":"549E56",
"date_token_generate":"2011-11-25 22:27:42",
"date_invitaion_send":null,
"date_survey_open":null,
"date_survey_answer":null,
"email":"jan@kowalski.pl",
"label1":"Jan",
"label2":"Kowalski",
"label3":"600 700 800",
"label4":"",
"label5":"",
"answer_postponed":null
},{
...
}]
}

Zwracane błędy

  • 401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu.

  • 404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.

  • 404 Not Found – Jeżeli nie znaleziono respondentów.

  • 406 Not Acceptable – Jeżeli nie przekazano parametru :id_survey.

Dodanie respondenta do ankiety

URL

(GET) https://www.webankieta.pl/api/v2/respondents/add

Parametry (POST)

Nazwa

Opis

id_survey

ID ankiety do której przypisujemy kontakt

id_contact

ID kontaktu, który przypisujemy do ankiety

date_invitaion_send

Data wysyłki zaproszenia do respondenta (wysyłka nastąpiła po stronie aplikacji klienckiej).
Parametr opcjonalny

Przykładowa odpowiedź

{ 
"id_respondent":"101019"
}

Zwracane błędy

  • 401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).

  • 404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.

  • 404 Not Found – Jeżeli nie znaleziono kontaktu o podanym :id_contact.

  • 406 Not Acceptable – Jeżeli nie przekazano parametru :id_survey.

  • 406 Not Acceptable – Jeżeli nie przekazano parametru :id_contact.

  • 409 Conflict – Jeżeli kontakt został dodany już wcześniej do ankiety.

Usuwanie respondenta

URL

(GET) https://www.webankieta.pl/api/v2/respondents/delete

Parametry (POST)

Nazwa

Opis

id_survey

ID ankiety do której należy respondent

id_respondent

ID respondenta

Przykładowa odpowiedź

{ 
"status":"ok"
}

Zwracane błędy

  • 401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).

  • 404 Not Found – Jeżeli nie znaleziono ankiety o podanym :id_survey.

  • 404 Not Found – Jeżeli nie znaleziono respondenta o podanym :id_respondent.

Batch upload respondentów

Proces ma umożliwić przesyłanie respondentów zgrupowanymi paczkami, dla których można stworzyć na końcu jeden mailing. Cały proces wygląda w skrócie następująco:

1. Tworzymy nowy tzw. batch (POST webankieta.pl/api/v2/respondents/batch) po sukcesywnym utworzeniu batcha odtrzymamy jego id pod którym będziemy grupować poszczególne paczki respondentów.

POST

(POST) webankieta.pl/api/respondents/batch

Parametry (POST)

Nazwa

Opis

survey_id

ID ankiety do której będziemy importować respondentów

Przykładowa odpowiedź

{ 
"batch_id":"89f7fcdb-c8c9-4414-8ec7-423780f66901"
}

GET

(GET) webankieta.pl/api/respondents/batch

Parametry (GET)

Nazwa

Opis

batch_id

ID batch’a

Zwracane wartości w json:

Nazwa

Opis

Id

ID batch’a

account_id

ID konta

survey_id

ID ankiety

patches

lista ID przynależnych patchów

Zwracane błędy

  • 401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).

  • 400 An error ocured – Jeżeli opracja skończy się niepowodzeniem

Troubleshooting:

  • znane są nam przypadki, gdzie w jednym batchu importowanych jest wiele takich samych adresów e-mail. Przy wysyłce mailingu z użyciem stworzonego batcha wszystkie wiadomości są wysyłane w jednej chwili - może się zdarzyć, że serwer pocztowy zablokuje te wiadomości ze względu na potencjalny SPAM (wiele takich samych wiadomości w jednej sekundzie). Proponujemy, aby w ramach jednej wysyłki maksymalnie ograniczyć istnienie wielu takich samych adresów mailowych w batchu.

2. Dodajemy do wcześniej utworzonego batcha kolejne paczki respondentów (POST webankieta.pl/api/v2/respondents/patch). Każda paczka musi zostać wysłana z parametrem batch_id równym utworzonemu wcześniej, zalecana ilość respondentów w jednej paczce to 20 sztuk.

POST

(POST) webankieta.pl/api/v2/respondents/patch

Parametry (POST)

Nazwa

Opis

batch_id

ID batch’a

respondents

tablica respondentów (zalecana ilość do 20 sztuk)

respondents

email

labels

tablica wartości etykiet respondenta (max 15)

Zwracane wartości json:

Nazwa

Opis

patch_id

ID patch’a

GET

(GET) webankieta.pl/api/v2/respondents/patch

Parametry (GET)

Nazwa

Opis

patch_id

ID patch’a

Zwracana wartości json:

Nazwa

Opis

respondents

lista ID respondentów utworzonych w ramach danego patcha

Zwracane błędy

  • 401 Unauthorized – Jeżeli użytkownik odwołuje się do obcego zasobu (ankiety/kontaktu).

  • 400 An error ocured – Jeżeli opracja skończy się niepowodzeniem

3. Jeśli dodaliśmy już wszystkich respondentów, możemy dla nich wszystkich zlecić wysyłkę zaproszeń podając wcześniejsze batch_id (POST webankieta.pl/api/v2/mailing/batch). Dokumentacja dotycząca tego kroku znajduje się tutaj.


Czy udało Ci się znaleźć odpowiedź na swoje pytanie?