Postać zapytania SOAP
Standardowe zapytanie SOAP jest w postaci:
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="ns1">
<soapenv:Header/>
<soapenv:Body>
<ns1:nazwa_soap soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<argument1 xsi:type="xsd:string">wartość1</argument1>
<argument2 xsi:type="xsd:string">wartość2</argument2>
<!-- ... -->
</ns1:nazwa_soap>
</soapenv:Body>
</soapenv:Envelope>
Gdzie: nazwa_soap to nazwa zapytania (np. hello, startRegister, itp.), argument1, argument2 to nazwy poszczególnych argumentów (np. billonUserName), a wartość1, wartość2 to odpowiadające im wartości.
Standardowa odpowiedź SOAP
Odpowiedź SOAP zwykle ma następującą postać:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="ns1">
<SOAP-ENV:Header/>
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns1:nazwa_odpowiedzi_soap>
<return xsi:type="ns1:typ_odpowiedzi">
<requestStatus>status</requestStatus>
<requestStatusDescription>opis</requestStatusDescription>
<taskId>id</taskId>
</return>
</ns1:nazwa_odpowiedzi_soap>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Gdzie poszczególne pola oznaczają:
| nazwa pola | typ | opis |
|---|---|---|
| requestStatus | string | informacja zwrotna czy zadanie zostało poprawnie przyjęte |
| requestStatusDescription | string | Dodatkowy opis odpowiedzi |
| taskId | string | id utworzonego zadania (zwykle potrzebny aby sprawdzić status zadania, lub jego wynik) |
W większości zapytań (np. hello, readSettings, getMpin itp.) dostajemy wszystkie informacje bezpośrednio w odpowiedzi.
Na ogół jednak odpowiedź nie zawiera żądanej informacji, ale zwraca tylko link do tworzonego zadania w systemie (taskId), po którego odpytaniu możemy poznać rezultat lub postęp zadania. Wtedy status zadania lub odpowiedź można uzyskać odpowiednią metodą SOAP’ową getTaskStatus, lub korzystając z callbacku.
Zwracane statusy
W przypadku niepowodzenia są zwracane kody błędów. Główne kody błędów zostały przedstawione poniżej.
| nazwa | opis |
|---|---|
| SUCCESS | operacja zakończona sukcesem |
| ERR_TECHNICAL_PROBLEM | Problem techniczny |
| ERR_TIMEOUT | Przekroczono czas odpowiedzi |
| ERR_NO_PERMISSION | Brak uprawnień do wykonania operacji |
| ERR_VUI_NOT_CONNECTED | Aplikacja nie połączona z siecią |
| ERR_VUI_NOT_LOGGEDIN | Użytkownik niezalogowany |
| ERR_VUI_CANT_READ | Nie można jeszcze odczytać danych |
| ERR_VUI_CANT_WRITE | Nie można jeszcze zapisać danych |
| ERR_VUI_NO_VAULT | Brak dostępu do sejfu |
| ERR_VUI_LOGGING_IN_OR_REGISTERING | Trwa logowanie |
| ERR_ONGOING_SYNC_TRY_AGAIN_LATER | Trwa synchronizacja, spróbuj później |
| ERR_JSON_PARSE_ERROR | Błąd przetwarzania json’a |
Kody błędów specyficzne dla poszczególnych operacji, zostały przedstawione w ich opisach.