<h1 align="center">Belvo Python SDK</h1>
<p align="center">
<a href="https://pypi.org/project/belvo-python/"><img alt="PyPI" src="https://img.shields.io/pypi/v/belvo-python?style=for-the-badge"></a>
<a href="https://pypistats.org/packages/belvo-python"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/belvo-python?style=for-the-badge"></a>
<a href="https://app.circleci.com/pipelines/github/belvo-finance/belvo-python"><img alt="CircleCI (.com)" src="https://img.shields.io/travis/com/belvo-finance/belvo-python/master?style=for-the-badge"></a>
<a href="https://coveralls.io/github/belvo-finance/belvo-python"><img alt="Coveralls github" src="https://img.shields.io/coveralls/github/belvo-finance/belvo-python?style=for-the-badge"></a>
<a href="https://github.com/psf/black"><img alt="Coveralls github" src="https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge"></a>
</p>
## 📕 Documentation
How to use `belvo-python`: https://belvo-finance.github.io/belvo-python/
If you want to check the full documentation about Belvo API: https://docs.belvo.com
Or if you want to more information about:
* [Getting Belvo API keys](https://developers.belvo.com/docs/get-your-belvo-api-keys)
* [Using Connect Widget](https://developers.belvo.com/docs/connect-widget)
* [Testing in sandbox](https://developers.belvo.com/docs/test-in-sandbox)
* [Using webhooks and recurrent links](https://developers.belvo.com/docs/webhooks)
## 📋 Requirements
* Python 3.6+
## 🚀 Getting started
Install using `pip`:
```
$ pip install belvo-python
```
## Usage (create link via widget)
When your user successfully links their account using the [Connect Widget](https://developers.belvo.com/docs/connect-widget), your implemented callback funciton will return the `link_id` required to make further API to retrieve information.
```python
from pprint import pprint
from belvo.client import Client
from belvo.enums import AccessMode
# Login to Belvo API
client = Client("your-secret-key-id", "your-secret-key", "sandbox")
# Get the link_id from the result of your widget callback function
link_id = result_from_callback_function.id
# Get all accounts
client.Accounts.create(link=link_id)
# Pretty print all checking accounts
for account in client.Accounts.list(type="checking"):
pprint(account)
```
## Usage (create link via SDK)
You can also manually create the link using the SDK. However, for security purposes, we highly recommend, that you use the [Connect Widget](https://developers.belvo.com/docs/connect-widget) to create the link and follow the **Usage (create link via widget)** example.
```python
from pprint import pprint
from belvo.client import Client
from belvo.enums import AccessMode
# Login to Belvo API
client = Client("your-secret-key-id", "your-secret-key", "sandbox")
# Register a link
link = client.Links.create(
institution="erebor_mx_retail",
username="johndoe",
password="supersecret",
access_mode=AccessMode.SINGLE
)
# Get all accounts
client.Accounts.create(link=link["id"])
# Pretty print all checking accounts
for account in client.Accounts.list(type="checking"):
pprint(account)
```
## Errors and exceptions
By default, when you use our SDK, we automatically return the [error](https://developers.belvo.com/docs/integration-overview#error-handling). However, if you prefer to receive the exception, you need to set the `raise_exception` optional parameter to `True`.
```python
from pprint import pprint
from belvo.client import Client
from belvo.enums import AccessMode
from belvo.exceptions import RequestError
# Login to Belvo API
client = Client("my-secret-key-id", "my-secret-key", "sandbox")
try:
# Register a link
link = client.Links.create(
access_mode=AccessMode.SINGLE,
institution="erebor_mx_retail",
username="<username>",
password="<pass>",
raise_exception=True, # Set this optional paramter
)
except RequestError as e:
# do something with the error
pprint(e)
else:
# do something with the link
pprint(link)
```
## 🐍 Development
To release a new version of the SDK to PyPI:
- Create a new branch from master.
- Use `make new-version major|minor|patch` to bump a new version.
- Create a new pull request for the new version.
- Once the new version is merged in `master`, create a `tag` matching the new version.
## 👥 Contributing
**Anyone** can do something to make `belvo-python` better, so contributors are always welcome!
If you wish to submit a pull request, please be sure check the items on this list:
- [ ] Tests related to the changed code were executed
- [ ] The source code has been coded following the OWASP security best practices (https://owasp.org/www-pdf-archive/OWASP_SCP_Quick_Reference_Guide_v2.pdf).
- [ ] Commit message properly labeled
- [ ] There is a ticket associated to each PR.
For more details about contributing to this project, please take a look to our [guidelines](CONTRIBUTING.md).