aftership-tracking-sdk
| Name | aftership-tracking-sdk JSON |
| Version |
3.0.0
JSON |
| download | |
| home_page | None |
| Summary | The official AfterShip Tracking Python API library |
| upload_time | 2024-07-29 01:49:24 |
| maintainer | None |
| docs_url | None |
| author | AfterShip |
| requires_python | <4.0,>=3.8 |
| license | MIT |
| keywords | aftership tracking track fedex ups usps dhl shipping fulfillment couriers carriers logistics |
| VCS | |
| bugtrack_url | |
| requirements | No requirements were recorded. |
| Travis-CI | No Travis. |
| coveralls test coverage | No coveralls. |
# AfterShip Tracking API library for Python
This library allows you to quickly and easily use the AfterShip Tracking API via Python.
For updates to this library, see our [GitHub release page](https://github.com/AfterShip/tracking-sdk-python/releases).
If you need support using AfterShip products, please contact support@aftership.com.
## Table of Contents
- [AfterShip Tracking API library for Python](#aftership-tracking-api-library-for-python)
- [Table of Contents](#table-of-contents)
- [Before you begin](#before-you-begin)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Constructor](#constructor)
- [Example](#example)
- [Rate Limiter](#rate-limiter)
- [Error Handling](#error-handling)
- [Error List](#error-list)
- [Endpoints](#endpoints)
- [/trackings](#trackings)
- [/couriers](#couriers)
- [/estimated-delivery-date](#estimated-delivery-date)
- [Help](#help)
- [License](#license)
## Before you begin
Before you begin to integrate:
- [Create an AfterShip account](https://admin.aftership.com/).
- [Create an API key](https://organization.automizely.com/api-keys).
- [Install Python](https://www.python.org/downloads/) version 3.8 or later.
## Quick Start
### Installation
```bash
pip install aftership-tracking-sdk
```
## Constructor
Create AfterShip instance with options
| Name | Type | Required | Description |
| ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| api_key | string | ✔ | Your AfterShip API key |
| auth_type | enum | | Default value: `AuthType.API_KEY` <br > AES authentication: `AuthType.AES` <br > RSA authentication: `AuthType.RSA` |
| api_secret | string | | Required if the authentication type is `AuthType.AES` or `AuthType.RSA` |
| domain | string | | AfterShip API domain. Default value: https://api.aftership.com |
| user_agent | string | | User-defined user-agent string, please follow [RFC9110](https://www.rfc-editor.org/rfc/rfc9110#field.user-agent) format standard. |
| proxy | string | | HTTP proxy URL to use for requests. <br > Default value: `null` <br > Example: `http://192.168.0.100:8888` |
| max_retry | number | | Number of retries for each request. Default value: 2. Min is 0, Max is 10. |
| timeout | number | | Timeout for each request in milliseconds. |
### Example
```python
import tracking
from tracking import exceptions
try:
sdk = tracking.Client(
tracking.Configuration(
api_key="YOUR_API_KEY",
authentication_type=tracking.ApiKey,
)
)
result = sdk.tracking.get_tracking_by_id("<tracking_id>")
print(result)
except exceptions.InvalidOptionError:
pass
except exceptions.InvalidApiKeyError:
pass
except exceptions.RateLimitExceedError:
pass
```
## Rate Limiter
See the [Rate Limit](https://www.aftership.com/docs/tracking/2024-07/quickstart/api-quick-start) to understand the AfterShip rate limit policy.
## Error Handling
The SDK will return an error object when there is any error during the request, with the following specification:
| Name | Type | Description |
| ------------- | ------ | ------------------------------ |
| message | string | Detail message of the error |
| code | enum | Error code enum for API Error. |
| meta_code | number | API response meta code. |
| status_code | number | HTTP status code. |
| response_body | string | API response body. |
### Error List
| code | meta_code | status_code | message |
| --------------------------------- | --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INVALID_REQUEST | 400 | 400 | The request was invalid or cannot be otherwise served. |
| INVALID_JSON | 4001 | 400 | Invalid JSON data. |
| TRACKING_ALREADY_EXIST | 4003 | 400 | Tracking already exists. |
| TRACKING_DOES_NOT_EXIST | 4004 | 404 | Tracking does not exist. |
| TRACKING_NUMBER_INVALID | 4005 | 400 | The value of tracking_number is invalid. |
| TRACKING_REQUIRED | 4006 | 400 | tracking object is required. |
| TRACKING_NUMBER_REQUIRED | 4007 | 400 | tracking_number is required. |
| VALUE_INVALID | 4008 | 400 | The value of [field_name] is invalid. |
| VALUE_REQUIRED | 4009 | 400 | [field_name] is required. |
| SLUG_INVALID | 4010 | 400 | The value of slug is invalid. |
| MISSING_OR_INVALID_REQUIRED_FIELD | 4011 | 400 | Missing or invalid value of the required fields for this courier. Besides tracking_number, also required: [field_name] |
| BAD_COURIER | 4012 | 400 | The error message will be one of the following:<br/>1. Unable to import shipment as the carrier is not on your approved list for carrier auto-detection. Add the carrier here: https://admin.aftership.com/settings/couriers<br/>2. Unable to import shipment as we don’t recognize the carrier from this tracking number.<br/>3. Unable to import shipment as the tracking number has an invalid format.<br/>4. Unable to import shipment as this carrier is no longer supported.<br/>5. Unable to import shipment as the tracking number does not belong to a carrier in that group. |
| INACTIVE_RETRACK_NOT_ALLOWED | 4013 | 400 | Retrack is not allowed. You can only retrack an inactive tracking. |
| NOTIFICATION_REUQIRED | 4014 | 400 | notification object is required. |
| ID_INVALID | 4015 | 400 | The value of id is invalid. |
| RETRACK_ONCE_ALLOWED | 4016 | 400 | Retrack is not allowed. You can only retrack each shipment once. |
| TRACKING_NUMBER_FORMAT_INVALID | 4017 | 400 | The format of tracking_number is invalid. |
| API_KEY_INVALID | 401 | 401 | The API key is invalid. |
| REQUEST_NOT_ALLOWED | 403 | 403 | The request is understood, but it has been refused or access is not allowed. |
| NOT_FOUND | 404 | 404 | The URI requested is invalid or the resource requested does not exist. |
| TOO_MANY_REQUEST | 429 | 429 | You have exceeded the API call rate limit. The default limit is 10 requests per second. |
| INTERNAL_ERROR | 500 502 503 504 | 500 502 503 504 | Something went wrong on AfterShip's end. |
## Endpoints
The AfterShip instance has the following properties which are exactly the same as the API endpoints:
- courier - Get a list of our supported couriers.
- tracking - Create trackings, update trackings, and get tracking results.
- estimated-delivery-date - Get estimated delivery date for your order.
### /trackings
**POST** /trackings
```python
import tracking
from tracking import exceptions
try:
sdk = tracking.Client(
tracking.Configuration(
api_key="YOUR_API_KEY",
api_secret="YOUR_API_SECRET",
authentication_type=tracking.Aes,
)
)
data = tracking.CreateTrackingRequest()
data.tracking_number = "<tracking_number>"
data.slug = "<slug>"
result = sdk.tracking.create_tracking(data)
print(result)
except exceptions.InvalidOptionError:
pass
```
**DELETE** /trackings/:id
```python
sdk.tracking.delete_tracking_by_id("<tracking_id>")
```
**GET** /trackings
```python
result = sdk.tracking.get_trackings(keyword="1234")
print(result)
```
**GET** /trackings/:id
```python
result = sdk.tracking.get_tracking_by_id("<tracking_id>")
print(result)
```
**PUT** /trackings/:id
```python
data = tracking.UpdateTrackingByIdRequest()
data.note = "test"
result = sdk.tracking.update_tracking_by_id("<tracking_id>", data)
print(result)
```
**POST** /trackings/:id/retrack
```python
result = sdk.tracking.retrack_tracking_by_id("<tracking_id>")
print(result)
```
**POST** /trackings/:id/mark-as-completed
```python
data = tracking.MarkTrackingCompletedByIdRequest()
data.reason = "DELIVERED"
result = sdk.tracking.mark_tracking_completed_by_id("<tracking_id>", data)
print(result)
```
### /couriers
**GET** /couriers
```python
result = sdk.courier.get_user_couriers()
print(result)
```
**GET** /couriers/all
```python
result = sdk.courier.get_all_couriers()
print(result)
```
**POST** /couriers/detect
```python
data = tracking.DetectCourierRequest()
data.tracking_number = "<tracking_number>"
result = sdk.courier.detect_courier(data)
print(result)
```
### /estimated-delivery-date
**POST** /estimated-delivery-date/predict-batch
```python
req = tracking.PredictBatchRequest()
date = tracking.EstimatedDeliveryDateRequest()
date.slug = '<slug>'
req.estimated_delivery_dates = [date]
result = sdk.estimated_delivery_date.predict_batch(req)
print(result)
```
## Help
If you get stuck, we're here to help:
- [Issue Tracker](https://github.com/AfterShip/tracking-sdk-python/issues) for questions, feature requests, bug reports and general discussion related to this package. Try searching before you create a new issue.
- Contact AfterShip official support via support@aftership.com
## License
Copyright (c) 2024 AfterShip
Licensed under the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "aftership-tracking-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "aftership, tracking, track, fedex, ups, usps, dhl, shipping, fulfillment, couriers, carriers, logistics",
"author": "AfterShip",
"author_email": "support@aftership.com",
"download_url": "https://files.pythonhosted.org/packages/06/c4/69b2b8e114bd08c1169bc7cbdac00367faf7b220eabc7f6d8e7b764bb2c0/aftership_tracking_sdk-3.0.0.tar.gz",
"platform": null,
"description": "# AfterShip Tracking API library for Python\n\nThis library allows you to quickly and easily use the AfterShip Tracking API via Python.\n\nFor updates to this library, see our [GitHub release page](https://github.com/AfterShip/tracking-sdk-python/releases).\n\nIf you need support using AfterShip products, please contact support@aftership.com.\n\n## Table of Contents\n\n- [AfterShip Tracking API library for Python](#aftership-tracking-api-library-for-python)\n - [Table of Contents](#table-of-contents)\n - [Before you begin](#before-you-begin)\n - [Quick Start](#quick-start)\n - [Installation](#installation)\n - [Constructor](#constructor)\n - [Example](#example)\n - [Rate Limiter](#rate-limiter)\n - [Error Handling](#error-handling)\n - [Error List](#error-list)\n - [Endpoints](#endpoints)\n - [/trackings](#trackings)\n - [/couriers](#couriers)\n - [/estimated-delivery-date](#estimated-delivery-date)\n - [Help](#help)\n - [License](#license)\n\n\n## Before you begin\n\nBefore you begin to integrate:\n\n- [Create an AfterShip account](https://admin.aftership.com/).\n- [Create an API key](https://organization.automizely.com/api-keys).\n- [Install Python](https://www.python.org/downloads/) version 3.8 or later.\n\n## Quick Start\n\n### Installation\n```bash\npip install aftership-tracking-sdk\n```\n\n\n## Constructor\n\nCreate AfterShip instance with options\n\n| Name | Type | Required | Description |\n| ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| api_key | string | \u2714 | Your AfterShip API key |\n| auth_type | enum | | Default value: `AuthType.API_KEY` <br > AES authentication: `AuthType.AES` <br > RSA authentication: `AuthType.RSA` |\n| api_secret | string | | Required if the authentication type is `AuthType.AES` or `AuthType.RSA` |\n| domain | string | | AfterShip API domain. Default value: https://api.aftership.com |\n| user_agent | string | | User-defined user-agent string, please follow [RFC9110](https://www.rfc-editor.org/rfc/rfc9110#field.user-agent) format standard. |\n| proxy | string | | HTTP proxy URL to use for requests. <br > Default value: `null` <br > Example: `http://192.168.0.100:8888` |\n| max_retry | number | | Number of retries for each request. Default value: 2. Min is 0, Max is 10. |\n| timeout | number | | Timeout for each request in milliseconds. |\n\n### Example\n\n```python\nimport tracking\nfrom tracking import exceptions\n\ntry:\n sdk = tracking.Client(\n tracking.Configuration(\n api_key=\"YOUR_API_KEY\",\n authentication_type=tracking.ApiKey,\n )\n )\n result = sdk.tracking.get_tracking_by_id(\"<tracking_id>\")\n print(result)\nexcept exceptions.InvalidOptionError:\n pass\nexcept exceptions.InvalidApiKeyError:\n pass\nexcept exceptions.RateLimitExceedError:\n pass\n```\n\n## Rate Limiter\n\nSee the [Rate Limit](https://www.aftership.com/docs/tracking/2024-07/quickstart/api-quick-start) to understand the AfterShip rate limit policy.\n\n## Error Handling\n\nThe SDK will return an error object when there is any error during the request, with the following specification:\n\n| Name | Type | Description |\n| ------------- | ------ | ------------------------------ |\n| message | string | Detail message of the error |\n| code | enum | Error code enum for API Error. |\n| meta_code | number | API response meta code. |\n| status_code | number | HTTP status code. |\n| response_body | string | API response body. |\n\n\n### Error List\n\n| code | meta_code | status_code | message |\n| --------------------------------- | --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| INVALID_REQUEST | 400 | 400 | The request was invalid or cannot be otherwise served. |\n| INVALID_JSON | 4001 | 400 | Invalid JSON data. |\n| TRACKING_ALREADY_EXIST | 4003 | 400 | Tracking already exists. |\n| TRACKING_DOES_NOT_EXIST | 4004 | 404 | Tracking does not exist. |\n| TRACKING_NUMBER_INVALID | 4005 | 400 | The value of tracking_number is invalid. |\n| TRACKING_REQUIRED | 4006 | 400 | tracking object is required. |\n| TRACKING_NUMBER_REQUIRED | 4007 | 400 | tracking_number is required. |\n| VALUE_INVALID | 4008 | 400 | The value of [field_name] is invalid. |\n| VALUE_REQUIRED | 4009 | 400 | [field_name] is required. |\n| SLUG_INVALID | 4010 | 400 | The value of slug is invalid. |\n| MISSING_OR_INVALID_REQUIRED_FIELD | 4011 | 400 | Missing or invalid value of the required fields for this courier. Besides tracking_number, also required: [field_name] |\n| BAD_COURIER | 4012 | 400 | The error message will be one of the following:<br/>1. Unable to import shipment as the carrier is not on your approved list for carrier auto-detection. Add the carrier here: https://admin.aftership.com/settings/couriers<br/>2. Unable to import shipment as we don\u2019t recognize the carrier from this tracking number.<br/>3. Unable to import shipment as the tracking number has an invalid format.<br/>4. Unable to import shipment as this carrier is no longer supported.<br/>5. Unable to import shipment as the tracking number does not belong to a carrier in that group. |\n| INACTIVE_RETRACK_NOT_ALLOWED | 4013 | 400 | Retrack is not allowed. You can only retrack an inactive tracking. |\n| NOTIFICATION_REUQIRED | 4014 | 400 | notification object is required. |\n| ID_INVALID | 4015 | 400 | The value of id is invalid. |\n| RETRACK_ONCE_ALLOWED | 4016 | 400 | Retrack is not allowed. You can only retrack each shipment once. |\n| TRACKING_NUMBER_FORMAT_INVALID | 4017 | 400 | The format of tracking_number is invalid. |\n| API_KEY_INVALID | 401 | 401 | The API key is invalid. |\n| REQUEST_NOT_ALLOWED | 403 | 403 | The request is understood, but it has been refused or access is not allowed. |\n| NOT_FOUND | 404 | 404 | The URI requested is invalid or the resource requested does not exist. |\n| TOO_MANY_REQUEST | 429 | 429 | You have exceeded the API call rate limit. The default limit is 10 requests per second. |\n| INTERNAL_ERROR | 500 502 503 504 | 500 502 503 504 | Something went wrong on AfterShip's end. |\n\n## Endpoints\n\nThe AfterShip instance has the following properties which are exactly the same as the API endpoints:\n\n- courier - Get a list of our supported couriers.\n- tracking - Create trackings, update trackings, and get tracking results.\n- estimated-delivery-date - Get estimated delivery date for your order.\n\n\n### /trackings\n\n**POST** /trackings\n\n```python\nimport tracking\nfrom tracking import exceptions\n\ntry:\n sdk = tracking.Client(\n tracking.Configuration(\n api_key=\"YOUR_API_KEY\",\n api_secret=\"YOUR_API_SECRET\",\n authentication_type=tracking.Aes,\n )\n )\n data = tracking.CreateTrackingRequest()\n data.tracking_number = \"<tracking_number>\"\n data.slug = \"<slug>\"\n result = sdk.tracking.create_tracking(data)\n print(result)\nexcept exceptions.InvalidOptionError:\n pass\n```\n\n**DELETE** /trackings/:id\n\n```python\nsdk.tracking.delete_tracking_by_id(\"<tracking_id>\")\n```\n\n**GET** /trackings\n\n```python\nresult = sdk.tracking.get_trackings(keyword=\"1234\")\nprint(result)\n```\n\n**GET** /trackings/:id\n\n```python\nresult = sdk.tracking.get_tracking_by_id(\"<tracking_id>\")\nprint(result)\n```\n\n**PUT** /trackings/:id\n\n```python\ndata = tracking.UpdateTrackingByIdRequest()\ndata.note = \"test\"\nresult = sdk.tracking.update_tracking_by_id(\"<tracking_id>\", data)\nprint(result)\n```\n\n**POST** /trackings/:id/retrack\n\n```python\nresult = sdk.tracking.retrack_tracking_by_id(\"<tracking_id>\")\nprint(result)\n```\n\n**POST** /trackings/:id/mark-as-completed\n\n```python\ndata = tracking.MarkTrackingCompletedByIdRequest()\ndata.reason = \"DELIVERED\"\nresult = sdk.tracking.mark_tracking_completed_by_id(\"<tracking_id>\", data)\nprint(result)\n```\n\n### /couriers\n**GET** /couriers\n\n```python\nresult = sdk.courier.get_user_couriers()\nprint(result)\n```\n\n**GET** /couriers/all\n\n```python\nresult = sdk.courier.get_all_couriers()\nprint(result)\n```\n\n**POST** /couriers/detect\n\n```python\ndata = tracking.DetectCourierRequest()\ndata.tracking_number = \"<tracking_number>\"\nresult = sdk.courier.detect_courier(data)\nprint(result)\n```\n\n### /estimated-delivery-date\n\n**POST** /estimated-delivery-date/predict-batch\n\n```python\nreq = tracking.PredictBatchRequest()\ndate = tracking.EstimatedDeliveryDateRequest()\ndate.slug = '<slug>'\nreq.estimated_delivery_dates = [date]\nresult = sdk.estimated_delivery_date.predict_batch(req)\nprint(result)\n```\n\n## Help\n\nIf you get stuck, we're here to help:\n\n- [Issue Tracker](https://github.com/AfterShip/tracking-sdk-python/issues) for questions, feature requests, bug reports and general discussion related to this package. Try searching before you create a new issue.\n- Contact AfterShip official support via support@aftership.com\n\n## License\nCopyright (c) 2024 AfterShip\n\nLicensed under the MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The official AfterShip Tracking Python API library",
"version": "3.0.0",
"project_urls": null,
"split_keywords": [
"aftership",
" tracking",
" track",
" fedex",
" ups",
" usps",
" dhl",
" shipping",
" fulfillment",
" couriers",
" carriers",
" logistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1db107a2016e888e6b4fcdc37df61c670334223602b7d455b42aa452bf0f8691",
"md5": "a0a0098f2ea6ef5340106284f633e98a",
"sha256": "f5aaf51943681f03cacee94cdb76d2d2bc5b7de11b4a3855977781ee3f4b2108"
},
"downloads": -1,
"filename": "aftership_tracking_sdk-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0a0098f2ea6ef5340106284f633e98a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 135908,
"upload_time": "2024-07-29T01:49:22",
"upload_time_iso_8601": "2024-07-29T01:49:22.862474Z",
"url": "https://files.pythonhosted.org/packages/1d/b1/07a2016e888e6b4fcdc37df61c670334223602b7d455b42aa452bf0f8691/aftership_tracking_sdk-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "06c469b2b8e114bd08c1169bc7cbdac00367faf7b220eabc7f6d8e7b764bb2c0",
"md5": "d273f7aea5e14d6326f21c74eedf5f61",
"sha256": "869fd088a6603ace367d5eb047028390955e53b2e9cdf8690a11e444cbcbb224"
},
"downloads": -1,
"filename": "aftership_tracking_sdk-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d273f7aea5e14d6326f21c74eedf5f61",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 36434,
"upload_time": "2024-07-29T01:49:24",
"upload_time_iso_8601": "2024-07-29T01:49:24.078274Z",
"url": "https://files.pythonhosted.org/packages/06/c4/69b2b8e114bd08c1169bc7cbdac00367faf7b220eabc7f6d8e7b764bb2c0/aftership_tracking_sdk-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 01:49:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aftership-tracking-sdk"
}
