aftership-tracking-sdk
| Name | aftership-tracking-sdk JSON |
| Version |
4.0.0
JSON |
| download | |
| home_page | None |
| Summary | The official AfterShip Tracking Python API library |
| upload_time | 2024-10-25 03:24:21 |
| 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)
- [API and SDK Version](#api-and-sdk-version)
- [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.
### API and SDK Version
Each SDK version is designed to work with a specific API version. Please refer to the table below to identify the supported API versions for each SDK version, ensuring you select the appropriate SDK version for the API version you intend to use.
| SDK Version | Supported API Version | Branch |
| ----------- | --------------------- | ------------------------------------------------------------- |
| 4.x.x | 2024-10 | https://github.com/AfterShip/tracking-sdk-python/tree/2024-10 |
| 3.x.x | 2024-07 | https://github.com/AfterShip/tracking-sdk-python/tree/2024-07 |
| 2.x.x | 2024-04 | https://github.com/AfterShip/tracking-sdk-python/tree/2024-04 |
| <=1.x.x | Legacy API | https://github.com/AfterShip/aftership-sdk-python |
## 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: `auth.ApiKey` <br > AES authentication: `auth.Aes` <br > RSA authentication: `auth.Rsa` |
| api_secret | string | | Required if the authentication type is `auth.Aes` or `auth.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
from tracking import auth
try:
sdk = tracking.Client(
tracking.Configuration(
api_key="YOUR_API_KEY",
authentication_type=auth.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-10/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 (
auth,
exceptions
)
try:
sdk = tracking.Client(
tracking.Configuration(
api_key="YOUR_API_KEY",
api_secret="YOUR_API_SECRET",
authentication_type=auth.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/c0/e4/da2037d4ef86c1ffacddac8aa3fa18217296c0be2e7ddfbddb2c88771216/aftership_tracking_sdk-4.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 - [API and SDK Version](#api-and-sdk-version)\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### API and SDK Version\n\nEach SDK version is designed to work with a specific API version. Please refer to the table below to identify the supported API versions for each SDK version, ensuring you select the appropriate SDK version for the API version you intend to use.\n\n| SDK Version | Supported API Version | Branch |\n| ----------- | --------------------- | ------------------------------------------------------------- |\n| 4.x.x | 2024-10 | https://github.com/AfterShip/tracking-sdk-python/tree/2024-10 |\n| 3.x.x | 2024-07 | https://github.com/AfterShip/tracking-sdk-python/tree/2024-07 |\n| 2.x.x | 2024-04 | https://github.com/AfterShip/tracking-sdk-python/tree/2024-04 |\n| <=1.x.x | Legacy API | https://github.com/AfterShip/aftership-sdk-python |\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: `auth.ApiKey` <br > AES authentication: `auth.Aes` <br > RSA authentication: `auth.Rsa` |\n| api_secret | string | | Required if the authentication type is `auth.Aes` or `auth.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\nfrom tracking import auth\n\ntry:\n sdk = tracking.Client(\n tracking.Configuration(\n api_key=\"YOUR_API_KEY\",\n authentication_type=auth.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-10/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 (\n auth,\n exceptions\n)\n\ntry:\n sdk = tracking.Client(\n tracking.Configuration(\n api_key=\"YOUR_API_KEY\",\n api_secret=\"YOUR_API_SECRET\",\n authentication_type=auth.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": "4.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": "cc48706ad48ca238b251d9fe39650488201a70c46f8d6d9ddb5e0cb3fc4c89ab",
"md5": "af5fa45d8d178529848144b3ef7e0552",
"sha256": "e3030c0dbdf50eb7e71366f146126c5a0ceeebaa3b44aefdbe28db1caa19199d"
},
"downloads": -1,
"filename": "aftership_tracking_sdk-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af5fa45d8d178529848144b3ef7e0552",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 104823,
"upload_time": "2024-10-25T03:24:20",
"upload_time_iso_8601": "2024-10-25T03:24:20.060709Z",
"url": "https://files.pythonhosted.org/packages/cc/48/706ad48ca238b251d9fe39650488201a70c46f8d6d9ddb5e0cb3fc4c89ab/aftership_tracking_sdk-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0e4da2037d4ef86c1ffacddac8aa3fa18217296c0be2e7ddfbddb2c88771216",
"md5": "639a9639184e8f890b8f439d3637e05a",
"sha256": "80297e85e0cd4c162ac0e33522149630bb4666cd1ded3317935d8ff9977e92b5"
},
"downloads": -1,
"filename": "aftership_tracking_sdk-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "639a9639184e8f890b8f439d3637e05a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 32819,
"upload_time": "2024-10-25T03:24:21",
"upload_time_iso_8601": "2024-10-25T03:24:21.566264Z",
"url": "https://files.pythonhosted.org/packages/c0/e4/da2037d4ef86c1ffacddac8aa3fa18217296c0be2e7ddfbddb2c88771216/aftership_tracking_sdk-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 03:24:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aftership-tracking-sdk"
}
