emSzmal Banking API - uniwersalne API bankowe

Dokumentacja usługi sieciowej

Informacje ogólne

Usługa emSzmal Banking API pozwala na bezpośrednią komunikację z serwisami bankowości internetowej za pośrednictwem zunifikowanego interfejsu webowego.
Zapytania do API przekazywane są przez protokół HTTP(s) w formacie JSON.
Format odpowiedzi (JSON lub XML) zależy od ustawień nagłówka Accept ("application/json" lub "application/xml") zapytania.
Dane przesyłane do / pobierane z usługi nie są utrwalane, ani w żaden sposób przetwarzane.
Cała transmisja danych jest szyfrowana z użyciem protokołu SSL/TLS.

Ograniczenia dostępu

Z usługi mogą korzystać użytkownicy z wykupioną i ważną (w okresie prawa do bezpłatnych aktualizacji) licencją na oprogramowanie emSzmal 3 PRO, z aktywnymi dodatkami "eCommerce" oraz "Biznes".
W przyszłości dostęp do niej może wymagać spełnienia także innych, dodatkowych warunków.

Sposób komunikacji z API

Zalogowanie do usługi

Metoda POST: /Common/SayHello
Opis: Metoda otwiera nową sesję użytkownika i zwraca "ciasteczko" z jej identyfikatorem.
Pamiętaj o przekazywaniu "ciasteczka" otrzymanego po zalogowaniu do usługi, w każdym kolejnym zapytaniu.
Uwaga: Sesja ważna jest tylko na jedno wołanie metody GetAccountsList lub GetAccountHistory.
Pobranie listy rachunków bankowych

Metoda POST: /Accounts/GetAccountsList
Opis: Metoda pobiera wszystkie rachunki użytkownika.
Czas odpowiedzi: 5-25s
Pobranie historii operacji bankowych z rachunku bankowego

Metoda POST: /Accounts/GetAccountHistory
Opis: Metoda pobiera historię operacji bankowych z zadanego okresu czasu.
Parametry metody: AccountNumber, DateSince, DateTo
Uwagi: Maksymalny, dopuszczalny zakres pomiędzy datami to 7 dni, wartość DateSince nie może być starsza niż miesiąc.
Czas odpowiedzi: 15s+
Inne

Metoda POST: /SessionManager/GetSecondPhaseAuthenticationData
Opis: Metoda pozwala pobrać informacje potrzebne do przeprowadzenia dodatkowej autentykacji (dotyczy wybranych banków).
W bankach stosujących tokeny oparte na zasadzie zapytanie-odpowiedź metoda ta pozwala pobrać treść zapytania. Odpowiedź należy przekazać za pomocą metody DoSecondPhaseAuthentication.
Możliwe typy autoryzacji: SMS, TOKEN, MOBILE_APP (wymaga potwierdzenia logowania w aplikacji mobilnej).
Uwaga: metodę należy wywołać z min. 10 sek. opóźnieniem, niezbędnym do przeprowadzenia pierwszego etapu logowania.

Metoda POST: /SessionManager/DoSecondPhaseAuthentication
Opis: Metoda pozwala dokonać dodatkowej autentykacji (dotyczy wybranych banków).
W bankach stosujących dwuetapowe logowanie pozwala na przekazanie jednorazowego hasła SMS lub aktualnego wskazania tokena.
Wylogowanie się z usługi

Metoda POST: /Common/SayBye
Opis: Metoda kończy sesję użytkownika.
Uwaga: Zawsze zamykaj sesję po uzyskaniu odpowiedzi z metody GetAccountsList lub GetAccountHistory.

Punkt dostępowy do usługi

https://web.emszmal.pl/api (produkcyjny)
https://web.emszmal.pl/apidev (testowy)

Przykładowe zapytania i odpowiedzi HTTP(s)

POST: /Common/SayHello

{
	"License": {
		"APIId": "emSzmal 3 PRO + eCommerce + Biznes xxx@xxx.pl 06.07.2016",
		"APIKey": "3B58041CCB7B356F6D5C94D8B01754B9"
	}
}

{
	"SessionId":"0d37bcd7-9ec1-4d28-95b9-b0cdc15f5254"
}

POST: /Accounts/GetAccountsList

{
	"SessionId": "0d37bcd7-9ec1-4d28-95b9-b0cdc15f5254",
	"ProviderId": 0,
	"ProviderConfiguration": "",
	"Authentication": {
		"UserLogin": "LOGIN",
		"UserPassword": "HASŁO",
		"UserContext": "NAZWA PROFILU (tylko gdy pod loginem użytkownika jest ich więcej niż jeden)",
		"TokenValue": ""
	},
	"License": {
		"APIId": "emSzmal 3 PRO + eCommerce + Biznes xxx@xxx.pl 06.07.2016",
		"APIKey": "3B58041CCB7B356F6D5C94D8B01754B9"
	}
}

{
	"Accounts": [
		{
			"AccountNumber": "15114020040000300276195487",
			"AccountCurrency": "PLN",
			"AccountAvailableFunds": 50.5,
			"AccountBalance": 100.5
		},
		{
			"AccountNumber": "65114020040000341200653930",
			"AccountCurrency": "EUR",
			"AccountAvailableFunds": 75.56,
			"AccountBalance": 158.23
		},
		{
			"AccountNumber": "02114020040000760238012537",
			"AccountCurrency": "CHF",
			"AccountAvailableFunds": 0,
			"AccountBalance": 0
		}
	]
}

POST: /Accounts/GetAccountHistory

{
	"SessionId": "0d37bcd7-9ec1-4d28-95b9-b0cdc15f5254",
	"ProviderId": 0,
	"ProviderConfiguration": "",
	"Authentication": {
		"UserLogin": "LOGIN",
		"UserPassword": "HASŁO",
		"UserContext": "NAZWA PROFILU (tylko gdy pod loginem użytkownika jest ich więcej niż jeden)",
		"TokenValue": ""
	},
	"License": {
		"APIId": "emSzmal 3 PRO + eCommerce + Biznes xxx@xxx.pl 06.07.2016",
		"APIKey": "3B58041CCB7B356F6D5C94D8B01754B9"
	},
	"Data": {
		"AccountNumber": "15114020040000300276195487",
		"DateSince": "2016-07-01",
		"DateTo": "2016-07-02"
	}
}

{
	"Transactions": [
		{
			"TransactionRefNumber": "7767",
			"TransactionOperationDate": "2016-07-01T00:00:00",
			"TransactionBookingDate": "2016-07-01T00:00:00",
			"TransactionAmount": -0.01,
			"TransactionBalance": 2.43,
			"TransactionType": "PRZELEW ZEWNĘTRZNY WYCHODZĄCY",
			"TransactionDescription": "XXX"
		},
		{
			"TransactionRefNumber": "7768",
			"TransactionOperationDate": "2016-07-01T00:00:00",
			"TransactionBookingDate": "2016-07-01T00:00:00",
			"TransactionAmount": -0.01,
			"TransactionBalance": 2.42,
			"TransactionType": "PRZELEW ZEWNĘTRZNY WYCHODZĄCY",
			"TransactionDescription": "XXXYYYZZZ"
		},
		{
			"TransactionRefNumber": "7769",
			"TransactionOperationDate": "2016-07-01T00:00:00",
			"TransactionBookingDate": "2016-07-01T00:00:00",
			"TransactionAmount": -100.01,
			"TransactionBalance": 899.04,
			"TransactionType": "PRZELEW ZEWNĘTRZNY WYCHODZĄCY",
			"TransactionDescription": "XXX\r\n71260414621844457350000001\r\nZ MB DO BNP PARIBAS FIRMOWY"
		}
	]
}

POST: /SessionManager/GetSecondPhaseAuthenticationData

{
	"SessionId": "0d37bcd7-9ec1-4d28-95b9-b0cdc15f5254",
	"ProviderId": 0,
	"ProviderConfiguration": "",
	"Authentication": {
		"UserLogin": "LOGIN",
		"UserPassword": "HASŁO",
		"UserContext": "NAZWA PROFILU (tylko gdy pod loginem użytkownika jest ich więcej niż jeden)",
		"TokenValue": ""
	},
	"License": {
		"APIId": "emSzmal 3 PRO + eCommerce + Biznes xxx@xxx.pl 06.07.2016",
		"APIKey": "3B58041CCB7B356F6D5C94D8B01754B9"
	}
}

{
	AuthenticationMethod: "SMS",
	PreAuthenticationCode: "",
	AuthenticationCodeHint: "SMS nr X z dn. dd.MM.rrrr"
}

POST: /SessionManager/DoSecondPhaseAuthentication

{
	"SessionId": "0d37bcd7-9ec1-4d28-95b9-b0cdc15f5254",
	"ProviderId": 0,
	"ProviderConfiguration": "",
	"Authentication": {
		"UserLogin": "LOGIN",
		"UserPassword": "HASŁO",
		"UserContext": "NAZWA PROFILU (tylko gdy pod loginem użytkownika jest ich więcej niż jeden)",
		"TokenValue": ""
	},
	"License": {
		"APIId": "emSzmal 3 PRO + eCommerce + Biznes xxx@xxx.pl 06.07.2016",
		"APIKey": "3B58041CCB7B356F6D5C94D8B01754B9"
	},
	"AuthenticationCode": "kod SMS lub wskaznie tokena"
}

{
	
}

POST: /Common/SayBye

{
	"SessionId": "0d37bcd7-9ec1-4d28-95b9-b0cdc15f5254",
	"License": {
		"APIId": "emSzmal 3 PRO + eCommerce + Biznes xxx@xxx.pl 06.07.2016",
		"APIKey": "3B58041CCB7B356F6D5C94D8B01754B9"
	}
}

{
	
}

Uwagi

W przypadku wykrycia błędnej autentykacji użytkownika (przy logowania do serwisu banku) następuje automatyczne, czasowe zablokowanie licencji.
Aby zapoznać się z działaniem usługi poproś o udostępnienie testowego klucza licencji.
Listę obsługiwanych serwisów bankowych (parametr ProviderId) można uzyskać drogą emailową.

Wywołanie usługi z użyciem JavaScript (jQuery)

Przykładowy skrypt znajdziesz tutaj.

APIId: APIKey:

Wywołanie usługi z użyciem PHP

Nieoficjalny wrapper PHP - autor: Krystian Duma - link.

Ostatnie zmiany w usłudze:

1.24.0406.1400

- aktualizacja obsługi wybranych serwisów bankowości internetowej