| Name | nmbrs-soap-api JSON |
| Version |
0.0.300
JSON |
| download |
| home_page | |
| Summary | Python SDK for the Visma Nmbrs SOAP API. |
| upload_time | 2024-03-09 19:19:24 |
| maintainer | Lars Kluijtmans |
| docs_url | None |
| author | Lars Kluijtmans |
| requires_python | >=3.11 |
| license | Lars Kluijtmans |
| keywords |
nmbrs
soap
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Visma-NMBRS-SOAP-API-SDK
***
Python SDK for the Visma Nmbrs SOAP API. Simplifying integration and enhancing developer productivity.
# Installation
***
To install this packages run:
```shell
pip install nmbrs_soap_api
```
# Getting started
***
This (SDK)Software development Kit uses the **Nmbrs Soap API** to access nmbrs.
There is also a **Rest API** available but this is not included in this SDK.
For more info on the Soap api go [here](https://support.nmbrs.nl/hc/nl/articles/205903718-Nmbrs-API-for-developers#topic_basics).
TO read about the rest api here is a good [source to get started](https://developer.nmbrs.com/docs).
In case of dificultis in developing anything nmbrs related contact:
- [Rene Dijkgraaf](https://www.linkedin.com/in/ren%C3%A9-dijkgraaf-226b9b2a/)
- [Wilko Kluijtmans](https://www.linkedin.com/in/wilko-kluijtmans-5437b3122/)
- [Lars Kluijtmans](https://www.linkedin.com/in/lars-kluijtmans-aa4a10243/)
- [Incomme](https://www.incomme.nl/)
## Authentication
***
There are two authentication options build into the SDk:
1. Using the username and token
2. Using the username, token and domain
When only using the username and token the call [**DebtorService:Environment_Get**](https://api.nmbrs.nl/soap/v3/DebtorService.asmx?op=Environment_Get) will be used to retrieve the domain from nmbrs. Seeing as this call is only available on the debtor level, you might not want to activate it for your users or cant at all.
In this case use option 2, here you specify the domain yourself, but this way the validity of your credentials(username, token and domain) is never verified.
### Getting the nmbrs token
Retrieving a nmbrs api token can be done through the nmbrs website, as shown [here](https://support.nmbrs.com/hc/en-us/articles/360013305712-How-to-get-an-API-token).
Managing api access cen be done using the User Templates, as shown [here](https://support.nmbrs.com/hc/en-us/articles/360013527371-API-User-Template).
### Initialize SDK using username and token
***
```python
from nmbrs import Nmbrs
api = Nmbrs(username="__username__", token="__token__", auth_type="token")
print(api.debtor_service.auth_header)
```
The created credentials are saved in the SDK for later use.
If not all needed parameters are specified an MissingParams exception will the thrown.
### Initialize SDK using username, token and domain
***
```python
from nmbrs import Nmbrs
api = Nmbrs(username="__username__", token="__token__", domain="__domain__", auth_type="with domain")
print(api.debtor_service.auth_header)
```
The created credentials are saved in the SDK for later use.
**Note:** these credentials are not authenticated and may not be valid.
## Testing environment: Sandbox
For testing Nmbrs provides a Sandbox feature. To read more about the sandbox, its usages and limitations go [here](https://support.nmbrs.nl/hc/nl/articles/204054506-Sandbox).
By default, the SDK uses the sandbox instead of the live environment, this is done to prevent accidental modifying of data in the live environment.
To access the live environment you can use the following code:
```python
from nmbrs import Nmbrs
api = Nmbrs(sandbox=False)
print(api.sandbox)
```
**Note:** the usage of the sandbox is set when the SDK is initialized and can not be modified after.
## Retrieving data
Now that you have set up the needed authentication its possible to retrieve data from nmbrs.
The nmbrs Soap API, and by extension this SDK, are split into 5 services:
- [Debtor service](https://api.nmbrs.nl/soap/v3/DebtorService.asmx)
- [Company service](https://api.nmbrs.nl/soap/v3/CompanyService.asmx)
- [Employee service](https://api.nmbrs.nl/soap/v3/EmployeeService.asmx)
- [Single Sign-on service](https://api.nmbrs.nl/soap/v3/SingleSignOn.asmx)
- [Report service](https://api.nmbrs.nl/soap/v3/ReportService.asmx)
**Note:** the **Report service** is not yet included into this SDK.
```python
from nmbrs import Nmbrs
api = Nmbrs(username="__username__", token="__token__", auth_type="token")
debtors = api.debtor_service.get_all()
print(len(debtors))
```
## Single Sign-on(SSO)
When it comes to Nmbrs Single Sign-On service:
- Username and Token
- Username and Password
- Username, Password and Domain
SSO Flow:
- First get a sso token that is valid for 30 seconds.
- This token can be used to creat an url that automatically sign the user into Nmbrs.
For details on how to implement the entire SSO Flow go [here](https://support.nmbrs.com/hc/en-us/articles/360013311952-Single-Sign-On-Service-Flow-SSO).
### SSO Token:
#### Username and Token
```python
from nmbrs import SingleSingOnService
sso_service = SingleSingOnService()
sso_token = sso_service.sso_auth_with_token("__username__", "__token__")
print(sso_token)
```
#### Username and Password
```python
from nmbrs import SingleSingOnService
sso_service = SingleSingOnService()
sso_token = sso_service.sso_auth_with_password("__username__", "__token__")
print(sso_token)
```
**Note:** this function will raise an exception if you have accounts in multiple Nmbrs environments. In this case use the following call where you specify the domain you want to log in to.
#### Username, password, and domain
```python
from nmbrs import SingleSingOnService
sso_service = SingleSingOnService()
sso_token = sso_service.sso_auth_with_domain("__username__", "__password__", "__domain__")
print(sso_token)
```
### SSO url:
Using the token reverence from the aforementioned functions we can create an url that automatically refers the user to nmbrs.
```python
from nmbrs import SingleSingOnService
sso_service = SingleSingOnService()
sso_token = sso_service.sso_auth_with_password("__username__", "__password__")
sso_url = sso_service.get_sso_url(sso_token, "__domain__")
print(sso_url)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "nmbrs-soap-api",
"maintainer": "Lars Kluijtmans",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "info@lk-software.com",
"keywords": "nmbrs,soap",
"author": "Lars Kluijtmans",
"author_email": "info@lk-software.com",
"download_url": "https://files.pythonhosted.org/packages/5a/c0/75029452ced88559d63627be0a4134f2e58304fbcdc0e9622b0df51533a9/nmbrs_soap_api-0.0.300.tar.gz",
"platform": null,
"description": "# Visma-NMBRS-SOAP-API-SDK\r\n\r\n***\r\n\r\nPython SDK for the Visma Nmbrs SOAP API. Simplifying integration and enhancing developer productivity.\r\n\r\n\r\n# Installation\r\n\r\n***\r\n\r\nTo install this packages run:\r\n\r\n```shell\r\npip install nmbrs_soap_api\r\n```\r\n\r\n# Getting started\r\n\r\n***\r\n\r\nThis (SDK)Software development Kit uses the **Nmbrs Soap API** to access nmbrs.\r\n\r\nThere is also a **Rest API** available but this is not included in this SDK.\r\n\r\nFor more info on the Soap api go [here](https://support.nmbrs.nl/hc/nl/articles/205903718-Nmbrs-API-for-developers#topic_basics).\r\n\r\nTO read about the rest api here is a good [source to get started](https://developer.nmbrs.com/docs).\r\n\r\nIn case of dificultis in developing anything nmbrs related contact:\r\n- [Rene Dijkgraaf](https://www.linkedin.com/in/ren%C3%A9-dijkgraaf-226b9b2a/)\r\n- [Wilko Kluijtmans](https://www.linkedin.com/in/wilko-kluijtmans-5437b3122/)\r\n- [Lars Kluijtmans](https://www.linkedin.com/in/lars-kluijtmans-aa4a10243/)\r\n- [Incomme](https://www.incomme.nl/)\r\n\r\n## Authentication\r\n\r\n***\r\n\r\nThere are two authentication options build into the SDk:\r\n\r\n1. Using the username and token\r\n2. Using the username, token and domain\r\n\r\nWhen only using the username and token the call [**DebtorService:Environment_Get**](https://api.nmbrs.nl/soap/v3/DebtorService.asmx?op=Environment_Get) will be used to retrieve the domain from nmbrs. Seeing as this call is only available on the debtor level, you might not want to activate it for your users or cant at all.\r\n\r\nIn this case use option 2, here you specify the domain yourself, but this way the validity of your credentials(username, token and domain) is never verified.\r\n\r\n### Getting the nmbrs token\r\n\r\nRetrieving a nmbrs api token can be done through the nmbrs website, as shown [here](https://support.nmbrs.com/hc/en-us/articles/360013305712-How-to-get-an-API-token).\r\n\r\nManaging api access cen be done using the User Templates, as shown [here](https://support.nmbrs.com/hc/en-us/articles/360013527371-API-User-Template).\r\n\r\n### Initialize SDK using username and token\r\n\r\n***\r\n\r\n```python\r\nfrom nmbrs import Nmbrs\r\n\r\napi = Nmbrs(username=\"__username__\", token=\"__token__\", auth_type=\"token\")\r\n\r\nprint(api.debtor_service.auth_header)\r\n```\r\n\r\nThe created credentials are saved in the SDK for later use.\r\n\r\nIf not all needed parameters are specified an MissingParams exception will the thrown.\r\n\r\n### Initialize SDK using username, token and domain\r\n\r\n***\r\n\r\n```python\r\nfrom nmbrs import Nmbrs\r\n\r\napi = Nmbrs(username=\"__username__\", token=\"__token__\", domain=\"__domain__\", auth_type=\"with domain\")\r\n\r\nprint(api.debtor_service.auth_header)\r\n```\r\n\r\nThe created credentials are saved in the SDK for later use.\r\n\r\n**Note:** these credentials are not authenticated and may not be valid.\r\n\r\n## Testing environment: Sandbox\r\n\r\nFor testing Nmbrs provides a Sandbox feature. To read more about the sandbox, its usages and limitations go [here](https://support.nmbrs.nl/hc/nl/articles/204054506-Sandbox).\r\n\r\nBy default, the SDK uses the sandbox instead of the live environment, this is done to prevent accidental modifying of data in the live environment.\r\n\r\nTo access the live environment you can use the following code:\r\n\r\n```python\r\nfrom nmbrs import Nmbrs\r\n\r\napi = Nmbrs(sandbox=False)\r\n\r\nprint(api.sandbox)\r\n```\r\n\r\n**Note:** the usage of the sandbox is set when the SDK is initialized and can not be modified after.\r\n\r\n## Retrieving data\r\n\r\nNow that you have set up the needed authentication its possible to retrieve data from nmbrs.\r\n\r\nThe nmbrs Soap API, and by extension this SDK, are split into 5 services:\r\n\r\n- [Debtor service](https://api.nmbrs.nl/soap/v3/DebtorService.asmx)\r\n- [Company service](https://api.nmbrs.nl/soap/v3/CompanyService.asmx)\r\n- [Employee service](https://api.nmbrs.nl/soap/v3/EmployeeService.asmx)\r\n- [Single Sign-on service](https://api.nmbrs.nl/soap/v3/SingleSignOn.asmx)\r\n- [Report service](https://api.nmbrs.nl/soap/v3/ReportService.asmx)\r\n\r\n**Note:** the **Report service** is not yet included into this SDK.\r\n\r\n```python\r\nfrom nmbrs import Nmbrs\r\n\r\napi = Nmbrs(username=\"__username__\", token=\"__token__\", auth_type=\"token\")\r\n\r\ndebtors = api.debtor_service.get_all()\r\n\r\nprint(len(debtors))\r\n```\r\n\r\n## Single Sign-on(SSO)\r\n\r\nWhen it comes to Nmbrs Single Sign-On service:\r\n\r\n - Username and Token\r\n - Username and Password\r\n - Username, Password and Domain\r\n\r\nSSO Flow:\r\n\r\n- First get a sso token that is valid for 30 seconds.\r\n- This token can be used to creat an url that automatically sign the user into Nmbrs.\r\n\r\nFor details on how to implement the entire SSO Flow go [here](https://support.nmbrs.com/hc/en-us/articles/360013311952-Single-Sign-On-Service-Flow-SSO).\r\n\r\n### SSO Token:\r\n\r\n#### Username and Token\r\n\r\n```python\r\nfrom nmbrs import SingleSingOnService\r\n\r\nsso_service = SingleSingOnService()\r\n\r\nsso_token = sso_service.sso_auth_with_token(\"__username__\", \"__token__\")\r\n\r\nprint(sso_token)\r\n```\r\n\r\n#### Username and Password\r\n\r\n```python\r\nfrom nmbrs import SingleSingOnService\r\n\r\nsso_service = SingleSingOnService()\r\n\r\n\r\nsso_token = sso_service.sso_auth_with_password(\"__username__\", \"__token__\")\r\n\r\nprint(sso_token)\r\n```\r\n\r\n**Note:** this function will raise an exception if you have accounts in multiple Nmbrs environments. In this case use the following call where you specify the domain you want to log in to. \r\n\r\n#### Username, password, and domain\r\n\r\n```python\r\nfrom nmbrs import SingleSingOnService\r\n\r\nsso_service = SingleSingOnService()\r\n\r\n\r\nsso_token = sso_service.sso_auth_with_domain(\"__username__\", \"__password__\", \"__domain__\")\r\n\r\nprint(sso_token)\r\n```\r\n\r\n### SSO url:\r\n\r\nUsing the token reverence from the aforementioned functions we can create an url that automatically refers the user to nmbrs.\r\n\r\n```python\r\nfrom nmbrs import SingleSingOnService\r\n\r\nsso_service = SingleSingOnService()\r\n\r\nsso_token = sso_service.sso_auth_with_password(\"__username__\", \"__password__\")\r\nsso_url = sso_service.get_sso_url(sso_token, \"__domain__\")\r\n\r\nprint(sso_url)\r\n```\r\n",
"bugtrack_url": null,
"license": "Lars Kluijtmans",
"summary": "Python SDK for the Visma Nmbrs SOAP API.",
"version": "0.0.300",
"project_urls": {
"Homepage": "https://github.com/LarsKluijtmans/Visma-NMBRS-SOAP-API-SDK",
"Issues": "https://github.com/LarsKluijtmans/Visma-NMBRS-SOAP-API-SDK/issues",
"Source": "https://github.com/LarsKluijtmans/Visma-NMBRS-SOAP-API-SDK"
},
"split_keywords": [
"nmbrs",
"soap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73acebd164f8775af01e55f3e85b9e965f602dadc504dcdf0f21865f547b7502",
"md5": "9680ebc2d5fc5572075b09e5e802a17f",
"sha256": "105ca2cb4722cdbe5f9a63e66598b48895ce0672f951a3cd3940402e535badb0"
},
"downloads": -1,
"filename": "nmbrs_soap_api-0.0.300-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9680ebc2d5fc5572075b09e5e802a17f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 32676,
"upload_time": "2024-03-09T19:19:23",
"upload_time_iso_8601": "2024-03-09T19:19:23.204712Z",
"url": "https://files.pythonhosted.org/packages/73/ac/ebd164f8775af01e55f3e85b9e965f602dadc504dcdf0f21865f547b7502/nmbrs_soap_api-0.0.300-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ac075029452ced88559d63627be0a4134f2e58304fbcdc0e9622b0df51533a9",
"md5": "634f56be8212716cc8becad4cff5a294",
"sha256": "54b6f8ae562b54dbf811236c5490ec4f79214a17d4277a0c745b5f8b16ff180b"
},
"downloads": -1,
"filename": "nmbrs_soap_api-0.0.300.tar.gz",
"has_sig": false,
"md5_digest": "634f56be8212716cc8becad4cff5a294",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 21820,
"upload_time": "2024-03-09T19:19:24",
"upload_time_iso_8601": "2024-03-09T19:19:24.914814Z",
"url": "https://files.pythonhosted.org/packages/5a/c0/75029452ced88559d63627be0a4134f2e58304fbcdc0e9622b0df51533a9/nmbrs_soap_api-0.0.300.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-09 19:19:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LarsKluijtmans",
"github_project": "Visma-NMBRS-SOAP-API-SDK",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nmbrs-soap-api"
}
