FinTech XML-RPC Server
The FinTech XML-RPC-Server enables third-party programming languages like PHP, Ruby, Java or Perl to make use of the functionality of the Python FinTech library. It provides a global API which is mapped to the internal structure of PyFinTech.
How it works
First of all the FinTech XML-RPC service is meant to be used only within a LAN for security reasons. Do not use it over the internet.
All you need is an XML-RPC client in your favourite programming language. Make sure that it supports the RPC null/nil type.
An XML-RPC request consists of a method name (hereafter called RPC method) and an arbitrary number of unlabeled positional parameters (hereafter called RPC parameter). That is how an XML-RPC service generally works.
Each RPC method is mapped onto the functions and classes of the different FinTech modules. For example the RPC method iban.create_iban calls the function create_iban of the module iban. The RPC method ebics.EbicsClient.C53 creates an instance of the class EbicsClient from the ebics module and then calls its method C53.
The passed RPC parameters are assigned to the functions and/or classes that were addressed by the RPC method. If an RPC parameter is a structure, its values are passed to the function or class based on the corresponding key names. If it is an array, its values are passed in the respective order. Any other data type will be passed as a single argument. For example the RPC method iban.create_iban requires exactly one RPC parameter (a structure or an array with the expected parameters). The RPC method ebics.EbicsClient.C53 requires one or two RPC parameters. The first one is passed to the EbicsClient class as described above to create an instance, the second one is then passed to the method C53 of the just created EbicsClient instance.
For the most part you can refer to the standard FinTech documentation with one exception: Whenever an Account instance is expected you can alternatively pass a simple structure which represents an account. Such a structure can be filled with any parameter the Account instantiation method expects (iban, name, country, city, postcode, street). In addition a value can be set for the keys ultimate_name, creditor_id and mandate. The latter must be again a structure of arguments that can be passed to the method set_mandate of an Account instance (mref, signed, first, last).
Return values are converted to the corresponding data types of the XML-RPC protocol. However if the return value is an object that cannot be represented by an XML-RPC data type (like the instance of a class), the object will be cached and a unique object identifier is returned. With this object id it is then possible to access the methods of the cached object and also to use it as an argument for other RPC calls.
Each session has its own object cache. A session is always based on the username set by the HTTP Basic Authorization header. It can be a fictional name if HTTP Basic Authorization was not activated on the server-side (see option --auth-user below). If there is no HTTP Basic Authorization header available, a global session is used.
There are some additional RPC methods that do not belong to the FinTech library itself:
- Returns a copy of the passed RPC parameters for testing purposes.
- Returns the current version of the used FinTech library.
- Checks whether the passed string is a valid object id for an actual object within the current session or not.
- Removes objects from the object cache of the current session. The optional RPC parameter must be either a string with an object id or an array of object ids to be removed. If it is omitted, all existing objects are removed. This method should be called at least once at the end of each procedure to clear the object cache. It returns the number of removed objects.
The XML-RPC server also supports multicall requests. This is useful if you want to call an RPC method repeatedly. For example if you want to add a large number of transactions to a SEPA document, you can use this to combine all calls to add_transaction into one single request.
Starting the server
To start the server just run the fintech-rpc command.
There are several options available to start the server:
-h, --help Shows a help message and exits. -c FILE, --config-file=FILE Loads the specified configuration file (see below). -b ADDRESS, --bind-address=ADDRESS Binds the server to the given address (default: localhost) -p PORT, --port=PORT The port number to listen on (default: 8830) -t, --threaded Creates a threaded server. -f FILE, --log-file=FILE Writes log messages to the specified file instead to stdout. -l LEVEL, --log-level=LEVEL The log level to use. One of debug, info, warning, error or critical.
User management options
- -a USER:HASH, --auth-user=USER:HASH
- Enables HTTP Basic Authorization and adds the specified user. HASH must be set to the hash (SHA1) of the password.
- Secure Socket Layer:
Options to enable SSL
-K FILE, --ssl-key=FILE The path to the SSL key file. -C FILE, --ssl-cert=FILE The path to the SSL certificate file.
Options to register a licensed version
-n NAME, --license-name=NAME The name of the licensee. -k KEYCODE, --license-key=KEYCODE The license key code. -u USERID, --license-user=USERID The EBICS user id (must be applied for each EBICS user id).
All options can be set by loading a specified configuration file based on the INI file format. Each property is mapped to its corresponding long option name listed above, whereas hyphens can be replaced with blanks. The main section is named [Main]. For reasons of clarity properties can be grouped into other sections by splitting off one or more words from the beginning of the option name and using this part as the section name and the remaining part as the property name. Therefore the following two examples have the same meaning:
[Main] Bind Address = localhost Port = 8830 Threaded = true Log File = /path/to/rpc.log Log Level = info Auth User = user1:e38ad214943daad1d64c102faec29de4afe9da3d user2:2aa60a8ff7fcd473d321e0146afd9e26df395147 License Name = Company License Key = MY-KEY-CODE License User = MYUSERID
[Main] Bind Address = localhost Port = 8830 Threaded = true [Log] File = /path/to/rpc.log Level = info [Auth] User = user1:e38ad214943daad1d64c102faec29de4afe9da3d user2:2aa60a8ff7fcd473d321e0146afd9e26df395147 [License] Name = Company Key = MY-KEY-CODE User = MYUSERID
If an option supports a list of values, you can accomplish this by adding each extra value on a separate line which must begin with at least one whitespace character (see option Auth User in the example above).
At time the XML-RPC server is not included in the main FinTech package. So you have to download and install the script by hand. Released under the GNU/GPL.
To be written ...
- v0.3.1 [2015-04-22]
- Now Amount objects are converted to dictionaries
- v0.3.0 [2015-04-14]
- Added Python 2/3 compatibility
- v0.2.0 [2015-01-26]
- Adjusted some imports to be conform with the new package name
- Renamed the script from ebics-rpc.py to fintech-rpc.py
- v0.1.3 [2014-10-10]
- Fixed a bug converting datetime arguments
- First public release