Hướng dẫn từng bước tích hợp với Vertex Tax RESTful API bằng Python
By JoeVu, at: 12:00 Ngày 29 tháng 9 năm 2024
Thời gian đọc ước tính: __READING_TIME__ minutes


1. Giới thiệu
Như chúng ta đã giới thiệu về VertexCloud Thuế Gián Tiếp trong bài đăng trên blog trước, trong bài đăng này, chúng ta sẽ tập trung vào quy trình từng bước tích hợp với API RESTful Thuế của Vertex bằng Python. Vào cuối hướng dẫn này, bạn sẽ có thể tính toán thuế và xử lý giao dịch bằng lập trình bằng cách sử dụng dịch vụ của Vertex.
Vì phiên bản 1 đã lỗi thời, nên chúng ta sẽ tập trung vào phiên bản 2 hiện đang được hỗ trợ.
2. Điều kiện tiên quyết
Trước khi bắt đầu quá trình tích hợp, hãy đảm bảo bạn đã có những điều sau:
- Python (phiên bản 3.6 trở lên)
- Thông tin đăng nhập API Thuế Vertex: Bạn sẽ cần một tài khoản Vertex hợp lệ để tạo khóa API và truy cập dịch vụ. Đăng ký để truy cập API.
- Thư viện Python: Hướng dẫn này sẽ sử dụng
requests
để thực hiện các cuộc gọi HTTP vàjson
để xử lý phản hồi API -pip install requests
- Hiểu biết cơ bản về API RESTful: Việc biết cách tương tác với API RESTful (thông qua các yêu cầu GET, POST, PUT) sẽ giúp bạn dễ dàng làm theo hướng dẫn này.
3. Cài đặt môi trường Python của bạn
Để bắt đầu, hãy tạo một thư mục dự án mới và thiết lập một môi trường ảo để giữ cho các phụ thuộc của bạn được sắp xếp. Dưới đây là cách bạn có thể làm điều đó:
Tạo một thư mục dự án
mkdir vertex-tax-api
cd vertex-tax-api
Thiết lập môi trường ảo
python3 -m venv vertex-env
source vertex-env/bin/activate
# Đối với MacOS/Linux
# HOẶC vertex-env\Scripts\activate
# Đối với Windows
Cài đặt các phụ thuộc cần thiết
pip install requests
Bây giờ bạn đã sẵn sàng để bắt đầu viết mã để tích hợp với API Thuế Vertex.
4. Xác thực với API Thuế Vertex (Phiên bản 2)
Trước khi thực hiện bất kỳ cuộc gọi API nào, bạn cần phải xác thực với hệ thống của Vertex bằng OAuth 2.0. Quá trình xác thực yêu cầu gửi client_id
, client_secret
và grant_type
(đặt thành client_credentials
) đến điểm cuối xác thực để nhận một token.
Ví dụ về yêu cầu xác thực
Dưới đây là cách bạn có thể xác thực bằng Python và lấy token truy cập từ API của Vertex (phiên bản 2):
import requests
# URL để lấy token auth
auth_url = 'https://auth.vertexsmb.com/identity/connect/token'
# Thông tin đăng nhập của bạn
client_id = 'your_client_id'
client_secret = 'your_client_secret'
# Dữ liệu cho yêu cầu token
data = {
'grant_type': 'client_credentials',
'client_id': client_id,
'client_secret': client_secret,
}
# Tiêu đề
headers = {
'Content-Type': 'application/x-www-form-urlencoded'
}
# Gửi yêu cầu để lấy token
response = requests.post(auth_url, data=data, headers=headers)
if response.status_code == 200:
token = response.json().get('access_token')
print(f"Access Token: {token}")
else:
print("Xác thực thất bại:", response.text)
Sau khi bạn xác thực thành công, API sẽ trả về một token truy cập. Token này phải được bao gồm trong tiêu đề Authorization
khi thực hiện các yêu cầu đến các điểm cuối API khác.
5. Thực hiện yêu cầu tính toán thuế (Phiên bản 2)
Sau khi lấy được token truy cập, bạn có thể tiến hành thực hiện các yêu cầu tính toán thuế. Sau đây là ví dụ về tải trọng cho yêu cầu tính toán thuế, bao gồm các chi tiết như loại tin nhắn bán hàng, loại giao dịch, tiền tệ, thông tin khách hàng, các mục hàng và bất kỳ khoản giảm giá nào.
Ví dụ về yêu cầu tính toán thuế
# URL để tính toán thuế (phiên bản 2)
api_url = 'https://calcconnect.vertexsmb.com/vertex-ws/v2/supplies'
# Đặt tiêu đề bao gồm token truy cập
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
}
# Tải trọng mẫu để tính toán thuế
payload = {
"saleMessageType": "QUOTATION",
"transactionType": "SALE",
"transactionId": "998822",
"originalCurrency": {
"isoCurrencyCodeAlpha": "USD"
},
"currency": {
"isoCurrencyCodeAlpha": "USD"
},
"customer": {
"administrativeDestination": {
"city": "Joe Vu",
"country": "US",
"mainDivision": "MO",
"postalCode": "65049",
"streetAddress1": ""
},
"customerCode": {
"classCode": "TAX",
"value": "GUEST"
},
"destination": {
"city": "Lake Ozark",
"country": "US",
"mainDivision": "MO",
"postalCode": "65049",
"streetAddress1": ""
},
"isTaxExempt": "false"
},
"documentDate": "2024-09-04",
"documentNumber": "3065",
"lineItems": [
{
"lineItemNumber": "0",
"product": {
"value": "Stuff:Concrete"
},
"quantity": {
"unitOfMeasure": "UOM",
"value": 13
},
"discount": {
"discountType": "DiscountAmount",
"discountValue": "-0"
},
"unitPrice": "212.343",
"vendorSKU": None
}
],
"discount": {
"discountType": "DiscountAmount",
"discountValue": 0,
"userDefinedDiscountCode": "string"
}
}
# Thực hiện yêu cầu POST
response = requests.post(api_url, json=payload, headers=headers)
if response.status_code == 200:
tax_info = response.json()
print("Kết quả tính toán thuế:", tax_info)
else:
print("Lỗi trong cuộc gọi API:", response.text)
Trong ví dụ này, bạn đang gửi một giao dịch chi tiết đến API Vertex. Tải trọng chứa các trường cần thiết như loại giao dịch, chi tiết khách hàng và các mục hàng, bao gồm số lượng, giá và bất kỳ khoản giảm giá nào được áp dụng.
Phản hồi mẫu
{
"data": {
"currency": {
"isoCurrencyCodeAlpha": "USD",
"isoCurrencyCodeNum": 0,
"isoCurrencyName": "US Dollar"
},
"customer": {
"administrativeDestination": {
"city": "Joe Vu",
"country": "US",
"locationCode": "",
"mainDivision": "MO",
"postalCode": "65049",
"streetAddress1": "",
"taxAreaId": "260294565"
},
"customerCode": {
"classCode": "TAX",
"isBusinessIndicator": false,
"value": "GUEST"
},
"destination": {
"city": "Joe Vu",
"country": "US",
"locationCode": "",
"mainDivision": "MO",
"postalCode": "65049",
"streetAddress1": "",
"taxAreaId": "260294565"
},
"isTaxExempt": false,
"taxRegistrations": []
},
"discount": {
"userDefinedDiscountCode": "string"
},
"documentDate": "2024-09-04",
"documentNumber": "998822",
"lineItems": [
{
"customer": {
"administrativeDestination": {
"city": "Joe Vu",
"country": "US",
"locationCode": "",
"mainDivision": "MO",
"postalCode": "65049",
"streetAddress1": "",
"taxAreaId": "260294565"
},
"customerCode": {
"classCode": "TAX",
"isBusinessIndicator": false,
"value": "GUEST"
},
"destination": {
"city": "Lake Ozark",
"country": "US",
"locationCode": "",
"mainDivision": "MO",
"postalCode": "65049",
"streetAddress1": "",
"taxAreaId": "260294565"
},
"isTaxExempt": false,
"taxRegistrations": []
},
"discount": {
"userDefinedDiscountCode": "string"
},
"extendedPrice": 2760.459,
"fairMarketValue": 2760.459,
"lineItemNumber": 0,
"locationCode": "",
"product": {
"value": "book 1"
},
"quantity": {
"unitOfMeasure": "UOM",
"value": 13
},
"taxIncludedIndicator": false,
"taxes": [
{
"calculatedTax": 116.62,
"calculationRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v301028065"
},
"effectiveRate": 0.04225,
"exempt": 0,
"imposition": {
"impositionId": "1",
"jurisdictionId": "19873",
"userDefined": false,
"value": "Sales and Use Tax"
},
"impositionType": {
"impositionTypeId": "v1",
"userDefined": false,
"value": "General Sales and Use Tax"
},
"inclusionRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v315534188"
},
"isService": false,
"jurisdiction": {
"effectiveDate": "1900-01-01",
"expirationDate": "9999-12-31",
"jurisdictionId": "19873",
"jurisdictionType": "STATE",
"value": "MISSOURI"
},
"maxTaxIndicator": false,
"nominalRate": 0.04225,
"nonTaxable": 0,
"notRegisteredIndicator": false,
"situs": "DESTINATION",
"taxCollectedFromParty": "BUYER",
"taxResult": "TAXABLE",
"taxStructure": "SINGLE_RATE",
"taxType": "SALES",
"taxable": 2760.46
},
{
"calculatedTax": 41.41,
"calculationRuleId": {
"salesTaxHolidayIndicator": false,
"userDefined": false,
"value": "v309207820"
},
"effectiveRate": 0.015,
"exempt": 0,
"imposition": {
"impositionId": "1",
"jurisdictionId": "20023",
&