|
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). |
0 commit comments