# python-bol-retailer-api
Wrapper for the bol.com Retailer API (v10)
## Breaking changes
v1.0.0 has breaking changes compared to v0.5.5
- When shipping an order or item using ```api.orders.shipItem``` or ```api.orders.ship```, shipmentReference is **required** and has to be passed as the second argument to the function.
```
api.orders.shipItem(item, shipmentReference, transporterCode=api.transporters.GLS, trackAndTrace='XXXXXX')
api.orders.ship(order, shipmentReference, transporterCode=api.transporters.UPS, trackAndTrace='XXXXXX')
```
## Install
This package is published on PyPi: https://pypi.org/project/python-bol-retailer-api/
Install with pip
pip install python-bol-retailer-api
## Usage
Usage at this point is minimal. I will extend this package as I go and as I need.
Current usage is limited to Orders, Processes and ShippingLabels.
### Create connection
You will need a Client ID and Client Secret generated by Bol. Generate these here: https://partner.bol.com/sdd/settings.html#!/services/api
Create a new API connection
from bol.api import BolAPI
api = BolAPI(clientId, clientSecret)
Access token is automatically stored for later use. In the event that an access token is expired, a new access token will be requested and the initial request will be resend. This should ensure that the connection is never cut off.
The API keeps in account the rate limits that bol.com apply. In the event that the rate limit is almost exhausted within a timeframe, the API will stall until a new timeframe with new rate limits is available.
### Orders
#### Get all orders
By default all orders will be returned
orderlist = api.orders.list()
You can specify the method and status yourself. Standard method is FBR and standard status is ALL.
orderlist = api.orders.list(method='FBB', status='OPEN')
This will return an OrderList object.
You can loop over the orders like so:
for order in orderlist.orders:
print(order.orderId)
Each order contains a list of OrderItem objects:
for item in order.orderItems:
print(item.orderItemId)
#### Get specific order
To get more info about an order, you can get the specific details of an order by its ID.
order = api.orders.get(id)
This will return an Order object.
#### Ship an order
There are two ways to ship an order: you either ship an item of the order, or you ship the whole order at once.
When shipping an item, an OrderItem object is expected. When shipping an order, an Order object is expected.
shipmentReference is required as of v7.
Optionally you can add shippingLabelId, transporterCode and trackAndTrace. Consult the Bol documentation to know what is expected.
There is a list of transportercodes that you can use.
api.orders.shipItem(item, shipmentReference, transporterCode=api.transporters.GLS, trackAndTrace='XXXXXX')
api.orders.ship(order, shipmentReference, transporterCode=api.transporters.UPS, trackAndTrace='XXXXXX')
#### Cancel an order
There are two ways to cancel an order: you either cancel an item of the order, or you cancel the whole order at once.
when cancelling an item, an OrderItem object is expected. When cancelling an order, an Order object is expected.
A cancellation expects a reason for the cancellation. There is a list of reasons that you can use.
api.orders.cancelItem(item, reason=api.reasons.OUT_OF_STOCK)
api.orders.cancel(order, reason=api.reasons.NOT_AVAIL_IN_TIME)
### Processes
You can retrieve the status and additional information of a process by its ID.
proc = api.processes.get(id)
print(proc.processStatusId)
print(proc.entityId)
...
### ShippingLabels
You can request a shipping label for an order. First, retrieve all the available options for the order. Choose an option and create a shipping label from it.
order = api.orders.get(id)
# 1: Retrieve all options
shippingOptions = api.shippingLabels.listOptions(order)
for option in shippingOptions.options:
print(option.shippingLabelOfferId)
...
# 2: Choose an option and create a label for it by using its shippingLabelOfferId
# This return a process, because the API is asynchronous
label = api.shippingLabels.create(order, option.shippingLabelOfferId)
print(label.processStatusId)
Once the label has been created, you can get the label PDF by using its ID. Before retrieving the label PDF, you need to be sure that the process that is responsible for this has finished and the status has been set to 'SUCCESS'.
process = api.process.get(label.processStatusId)
if process.status == 'SUCCESS':
shippingLabelId = process.entityId
shippingLabel = api.shippingLabels.get(shippingLabelId)
fs = FileSystemStorage()
with TemporaryFile() as f:
f.write(shippingLabel.labelBytes)
resultFile = File(f)
file = fs.save('my_shipping_label.pdf', resultFile)
Raw data
{
"_id": null,
"home_page": "https://github.com/alexanderlhsglobal/python-bol-retailer-api",
"name": "python-bol-retailer-api",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "bol.com, api, bol, wrapper",
"author": "Alexander Schillemans",
"author_email": "alexander.schillemans@lhs.global",
"download_url": "https://files.pythonhosted.org/packages/c8/25/aa6add9bf34d3d249ea9e5d1fb7d6e8be4ab8546e0d8c8c15571ab03e63d/python-bol-retailer-api-1.1.1.tar.gz",
"platform": null,
"description": "# python-bol-retailer-api\r\nWrapper for the bol.com Retailer API (v10)\r\n\r\n\r\n## Breaking changes\r\n\r\nv1.0.0 has breaking changes compared to v0.5.5\r\n- When shipping an order or item using ```api.orders.shipItem``` or ```api.orders.ship```, shipmentReference is **required** and has to be passed as the second argument to the function.\r\n\r\n\r\n ```\r\n api.orders.shipItem(item, shipmentReference, transporterCode=api.transporters.GLS, trackAndTrace='XXXXXX')\r\n api.orders.ship(order, shipmentReference, transporterCode=api.transporters.UPS, trackAndTrace='XXXXXX')\r\n ```\r\n\r\n## Install\r\nThis package is published on PyPi: https://pypi.org/project/python-bol-retailer-api/\r\n\r\nInstall with pip\r\n\r\n pip install python-bol-retailer-api\r\n \r\n \r\n## Usage\r\n\r\nUsage at this point is minimal. I will extend this package as I go and as I need.\r\n\r\nCurrent usage is limited to Orders, Processes and ShippingLabels.\r\n\r\n### Create connection\r\nYou will need a Client ID and Client Secret generated by Bol. Generate these here: https://partner.bol.com/sdd/settings.html#!/services/api\r\n\r\nCreate a new API connection\r\n\r\n from bol.api import BolAPI\r\n api = BolAPI(clientId, clientSecret)\r\n\r\nAccess token is automatically stored for later use. In the event that an access token is expired, a new access token will be requested and the initial request will be resend. This should ensure that the connection is never cut off.\r\n\r\nThe API keeps in account the rate limits that bol.com apply. In the event that the rate limit is almost exhausted within a timeframe, the API will stall until a new timeframe with new rate limits is available.\r\n\r\n### Orders\r\n\r\n#### Get all orders\r\n\r\nBy default all orders will be returned\r\n\r\n orderlist = api.orders.list()\r\n\r\nYou can specify the method and status yourself. Standard method is FBR and standard status is ALL.\r\n\r\n orderlist = api.orders.list(method='FBB', status='OPEN')\r\n\r\nThis will return an OrderList object.\r\nYou can loop over the orders like so:\r\n\r\n for order in orderlist.orders:\r\n print(order.orderId)\r\n \r\n Each order contains a list of OrderItem objects:\r\n \r\n for item in order.orderItems:\r\n print(item.orderItemId)\r\n \r\n#### Get specific order\r\n\r\nTo get more info about an order, you can get the specific details of an order by its ID.\r\n\r\n order = api.orders.get(id)\r\n\r\nThis will return an Order object.\r\n \r\n#### Ship an order\r\n\r\nThere are two ways to ship an order: you either ship an item of the order, or you ship the whole order at once.\r\nWhen shipping an item, an OrderItem object is expected. When shipping an order, an Order object is expected.\r\nshipmentReference is required as of v7.\r\nOptionally you can add shippingLabelId, transporterCode and trackAndTrace. Consult the Bol documentation to know what is expected.\r\n\r\nThere is a list of transportercodes that you can use.\r\n\r\n api.orders.shipItem(item, shipmentReference, transporterCode=api.transporters.GLS, trackAndTrace='XXXXXX')\r\n api.orders.ship(order, shipmentReference, transporterCode=api.transporters.UPS, trackAndTrace='XXXXXX')\r\n \r\n#### Cancel an order\r\n\r\nThere are two ways to cancel an order: you either cancel an item of the order, or you cancel the whole order at once.\r\nwhen cancelling an item, an OrderItem object is expected. When cancelling an order, an Order object is expected.\r\nA cancellation expects a reason for the cancellation. There is a list of reasons that you can use.\r\n\r\n api.orders.cancelItem(item, reason=api.reasons.OUT_OF_STOCK)\r\n api.orders.cancel(order, reason=api.reasons.NOT_AVAIL_IN_TIME)\r\n \r\n### Processes\r\n\r\nYou can retrieve the status and additional information of a process by its ID.\r\n\r\n proc = api.processes.get(id)\r\n\r\n print(proc.processStatusId)\r\n print(proc.entityId)\r\n ...\r\n\r\n### ShippingLabels\r\n\r\nYou can request a shipping label for an order. First, retrieve all the available options for the order. Choose an option and create a shipping label from it.\r\n\r\n order = api.orders.get(id)\r\n\r\n # 1: Retrieve all options\r\n shippingOptions = api.shippingLabels.listOptions(order)\r\n\r\n for option in shippingOptions.options:\r\n print(option.shippingLabelOfferId)\r\n ...\r\n\r\n # 2: Choose an option and create a label for it by using its shippingLabelOfferId\r\n # This return a process, because the API is asynchronous\r\n label = api.shippingLabels.create(order, option.shippingLabelOfferId)\r\n print(label.processStatusId)\r\n\r\nOnce the label has been created, you can get the label PDF by using its ID. Before retrieving the label PDF, you need to be sure that the process that is responsible for this has finished and the status has been set to 'SUCCESS'.\r\n\r\n process = api.process.get(label.processStatusId)\r\n if process.status == 'SUCCESS':\r\n shippingLabelId = process.entityId\r\n shippingLabel = api.shippingLabels.get(shippingLabelId)\r\n\r\n fs = FileSystemStorage()\r\n with TemporaryFile() as f:\r\n f.write(shippingLabel.labelBytes)\r\n resultFile = File(f)\r\n file = fs.save('my_shipping_label.pdf', resultFile)\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Wrapper for the bol.com Retailer API (v10)",
"version": "1.1.1",
"project_urls": {
"Download": "https://github.com/alexanderlhsglobal/python-bol-retailer-api/archive/refs/tags/v1.1.1.tar.gz",
"Homepage": "https://github.com/alexanderlhsglobal/python-bol-retailer-api"
},
"split_keywords": [
"bol.com",
" api",
" bol",
" wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c825aa6add9bf34d3d249ea9e5d1fb7d6e8be4ab8546e0d8c8c15571ab03e63d",
"md5": "3b8bc780c44034af22615ca3e1676866",
"sha256": "c852d9bef0632be2b5d72d562100d347281a77af09315ee86d26bbb971d20920"
},
"downloads": -1,
"filename": "python-bol-retailer-api-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3b8bc780c44034af22615ca3e1676866",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24852,
"upload_time": "2024-11-15T15:24:47",
"upload_time_iso_8601": "2024-11-15T15:24:47.383924Z",
"url": "https://files.pythonhosted.org/packages/c8/25/aa6add9bf34d3d249ea9e5d1fb7d6e8be4ab8546e0d8c8c15571ab03e63d/python-bol-retailer-api-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 15:24:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexanderlhsglobal",
"github_project": "python-bol-retailer-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "python-bol-retailer-api"
}
JSON
