Skip to content

Commit cab9678

Browse files
author
Pascal Wink
committed
update readme
1 parent d37bc89 commit cab9678

File tree

2 files changed

+2
-183
lines changed

2 files changed

+2
-183
lines changed

README.md

Lines changed: 1 addition & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1 @@
1-
# bunq Python SDK
2-
3-
## Introduction
4-
Hi developers!
5-
6-
Welcome to the bunq Python SDK! 👨‍💻
7-
8-
We're very happy to introduce yet another unique product: complete banking SDKs!
9-
Now you can build even bigger and better apps and integrate them with your bank of the free! 🌈
10-
11-
Before you dive into this brand new SDK, please consider:
12-
- Learning how bunq works and what objects you will work with by reading [the intro to our API](https://github.com/bunq/doc/blob/develop/README.md) 🤓
13-
- Checking out [our developer portal](https://developer.bunq.com/) 🙌
14-
- Grabbing your Production API key from [our developer portal](https://developer.bunq.com/) or the bunq app 🗝
15-
- Generating a Sandbox API key using [our developer portal](https://developer.bunq.com/) or [Tinker](https://www.bunq.com/developer) 🗝
16-
- Visiting [our forum](https://together.bunq.com/t/api) where you can share your creations,
17-
questions and experience 🎤
18-
19-
Give us your feedback, create pull requests, build your very own bunq apps and most importantly:
20-
have fun! 💪
21-
22-
This SDK is in **beta**. We cannot guarantee constant availability or stability.
23-
Thanks to your feedback we will make improvements on it.
24-
25-
## Installation
26-
pip install bunq_sdk --upgrade
27-
28-
## Usage
29-
30-
### Creating an API context
31-
In order to start making calls with the bunq API, you must first register your API key and device,
32-
and create a session. In the SDKs, we group these actions and call it "creating an API context". The
33-
context can be created by using the following code snippet:
34-
35-
36-
apiContext = ApiContext.create(ENVIRONMENT_TYPE, API_KEY, DEVICE_DESCRIPTION)
37-
apiContext.save(API_CONTEXT_FILE_PATH)
38-
39-
40-
**Please note**: initialising your application is a heavy task and it is recommended to do it only once per device.
41-
42-
apiContext = ApiContext.restore(self.API_CONTEXT_FILE_PATH)
43-
BunqContext.loadApiContext(apiContext)
44-
45-
After saving the context, you can restore it at any time:
46-
47-
#### Example
48-
49-
See [`tinker/setup_context`](https://github.com/bunq/tinker_python/blob/2182b8be276fda921657ad22cfe0b8b48a585ccf/tinker/libs/bunq_lib.py#L44-L59)
50-
51-
#### PSD2
52-
It is possible to create an ApiContext as PSD2 Service Provider. Although this might seem a complex task, we wrote some
53-
helper implementations to get you started. You need to create a certificate and private key to get you started.
54-
Our sandbox environment currently accepts all certificates, if these criteria are met:
55-
56-
- Up to 64 characters
57-
- PISP and/or AISP used in the end.
58-
59-
Make sure you have your unique eIDAS certificate number and certificates ready when you want to perform these tasks on
60-
our production environment.
61-
62-
Creating a PSD2 context is very easy:
63-
64-
apiContext = ApiContext.create_for_psd2(ENVIRONMENT_TYPE, CERTIFICATE, PRIVATE_KEY, CERTIFICATE_CHAIN, DEVICE_DESCRIPTION)
65-
66-
#### Safety considerations
67-
The file storing the context details (i.e. `bunq.conf`) is a key to your account. Anyone having
68-
access to it is able to perform any Public API actions with your account. Therefore, we recommend
69-
choosing a truly safe place to store it.
70-
71-
### Making API calls
72-
There is a class for each endpoint. Each class has functions for each supported action. These
73-
actions can be `create`, `get`, `update`, `delete` and `list`.
74-
75-
Sometimes API calls have dependencies, for instance `MonetaryAccount`. Making changes to a monetary
76-
account always also needs a reference to a `User`. These dependencies are required as arguments when
77-
performing API calls. Take a look at [doc.bunq.com](https://doc.bunq.com) for the full
78-
documentation.
79-
80-
#### Creating objects
81-
Creating objects through the API requires an `ApiContext`, a `requestMap` and identifiers of all
82-
dependencies (such as User ID required for accessing a Monetary Account). Optionally, custom headers
83-
can be passed to requests.
84-
85-
payment_id = Payment.create(
86-
amount=Amount(amount_string, self._CURRENCY_EURL),
87-
counterparty_alias=Pointer(self._POINTER_TYPE_EMAIL, recipient),
88-
description=description
89-
)
90-
91-
##### Example
92-
See [`tinker/make_payment`](https://github.com/bunq/tinker_python/blob/2182b8be276fda921657ad22cfe0b8b48a585ccf/tinker/libs/bunq_lib.py#L140-L151)
93-
94-
#### Reading objects
95-
Reading objects through the API requires an `ApiContext`, identifiers of all dependencies (such as
96-
User ID required for accessing a Monetary Account), and the identifier of the object to read (ID or
97-
UUID) Optionally, custom headers can be passed to requests.
98-
99-
This type of calls always returns a model.
100-
101-
monetary_account = generated.MonetaryAccountBank.get(
102-
_MONETARY_ACCOUNT_ITEM_ID
103-
)
104-
105-
##### Example
106-
See [`tinker/list_all_payment`](https://github.com/bunq/tinker_python/blob/2182b8be276fda921657ad22cfe0b8b48a585ccf/tinker/libs/bunq_lib.py#L85-L103)
107-
108-
#### Updating objects
109-
Updating objects through the API goes the same way as creating objects, except that also the object to update identifier
110-
(ID or UUID) is needed.
111-
112-
Card.update(
113-
card_id=int(card_id),
114-
monetary_account_current_id=int(account_id)
115-
)
116-
117-
##### Example
118-
See [`tinker/update_card`](https://github.com/bunq/tinker_python/blob/2182b8be276fda921657ad22cfe0b8b48a585ccf/tinker/libs/bunq_lib.py#L167-L174)
119-
120-
#### Deleting objects
121-
Deleting objects through the API requires an `ApiContext`, identifiers of all dependencies (such as User ID required for
122-
accessing a Monetary Account), and the identifier of the object to delete (ID or UUID) Optionally, custom headers can be
123-
passed to requests.
124-
125-
Session.delete(self._SESSION_ID)
126-
127-
##### Example
128-
129-
#### Listing objects
130-
Listing objects through the API requires an `ApiContext` and identifiers of all dependencies (such as User ID required
131-
for accessing a Monetary Account). Optionally, custom headers can be passed to requests.
132-
133-
users = User.list(api_context)
134-
135-
##### Example
136-
See [`UserListExample.py`](./examples/user_list_example.py)
137-
138-
## Running Samples
139-
To get an indication on how the SDK works you can use the python tinker which is located at https://github.com/bunq/tinker_python
140-
141-
## Running Tests
142-
143-
Information regarding the test cases can be found in the [README.md](./tests/README.md)
144-
located in [test](/tests).
145-
146-
## Exceptions
147-
The SDK can raise multiple exceptions. For an overview of these exceptions please
148-
take a look at [EXCEPTIONS.md](./bunq/sdk/exception/EXCEPTIONS.md).
1+
📚 For full documentation about this sdk, visit [doc.bunq.com](https://doc.bunq.com/getting-started/tools/software-development-kits-sdks/python/usage).

tests/README.md

Lines changed: 1 addition & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1 @@
1-
# bunq Python SDK
2-
3-
## Introduction
4-
Hi developers!
5-
6-
7-
Welcome to the bunq Python SDK integration tests. Currently we are not
8-
targeting the 100% test coverage, but rather want to be certain that the most
9-
common scenarios can run without any errors.
10-
11-
## Installation and Execution
12-
13-
openssl req -x509 -newkey rsa:4096 -keyout tests/key.pem -out tests/certificate.pem -days 365 -nodes -subj "/CN=adsadsahjksbhjbdjhasds/C=NL" && \
14-
echo -e "\n--- KEY ---\n" && cat tests/key.pem && \
15-
echo -e "\n--- CERTIFICATE ---\n" && cat tests/certificate.pem
16-
17-
18-
You can install all the required dependencies with the following command:
19-
20-
python3 setup.py install
21-
22-
You can run all the tests via command line:
23-
24-
python3 -m unittest discover -s tests/context && \
25-
python3 -m unittest discover -s tests/http && \
26-
python3 -m unittest discover -s tests/model/generated
27-
28-
or via PyCharm, but first you must configure PyCharm by doing the following:
29-
* Go to `Preferences` --> `Tools` --> `Python integrated tools` and change default
30-
test runner to `unittests`.
31-
* Configure your Python interpreter to an supported Python version. Python 3 is
32-
recommended.
33-
34-
Afterwards you can right click on the tests folders and should be able to run
35-
the tests cases form the IDE.
1+
📚 For full API Test documentation, visit [doc.bunq.com](https://doc.bunq.com/getting-started/tools/software-development-kits-sdks/python/tests).

0 commit comments

Comments
 (0)