Step-by-Step Guide to Integrating with Vertex Tax RESTful API using Python

Tích hợp với Vertex Tax RESTful API (v2) Sử dụng Python

1. Giới thiệu

Như chúng ta đã giới thiệu về Thuế gián tiếp VertexCloud trong bài đăng trên blog trước đây của chúng tôi, 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 Vertex’s Tax RESTful API bằng Python. Sau khi hoàn thành 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 Vertex Tax API: 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
Kiến thức cơ bản về RESTful API: Việc biết cách tương tác với RESTful API (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 Vertex Tax API.

4. Xác thực với Vertex Tax API (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 được mã thông báo.

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 mã thông báo truy cập từ API của Vertex (phiên bản 2):

import requests

# URL để lấy mã thông báo xác thực 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 mã thông báo 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 mã thông báo response = requests.post(auth_url, data=data, headers=headers)

if response.status_code == 200: token = response.json().get('access_token') print(f"Mã Thông Báo Truy Cập: {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 mã thông báo truy cập. Mã thông báo này phải được bao gồm trong tiêu đề Authorization khi thực hiện 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 mã thông báo truy cập, bạn có thể tiến hành thực hiện yêu cầu tính toán thuế. Dưới đâ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, loại 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 mã thông báo 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 của 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",

              "userDefined": false,

              "value": "Local Sales and Use Tax"

            },

            "impositionType": {

              "impositionTypeId": "v1",

              "userDefined": false,

              "value": "General Sales and Use Tax"

            },

            "inclusionRuleId": {

              "salesTaxHolidayIndicator": false,

              "userDefined": false,

              "value": "v302021096"

            },

            "isService": false,

            "jurisdiction": {

              "effectiveDate": "1900-01-01",

              "expirationDate": "9999-12-31",

              "jurisdictionId": "20023",

              "jurisdictionType": "COUNTY",

              "value": "CAMDEN"

            },

            "maxTaxIndicator": false,

            "nominalRate": 0.015,

            "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": "v301032380"

            },

            "effectiveRate": 0.015,

            "exempt": 0,

            "imposition": {

              "impositionId": "1",

              "jurisdictionId": "20035",

              "userDefined": false,

              "value": "Local Sales and Use Tax"

            },

            "impositionType": {

              "impositionTypeId": "v1",

              "userDefined": false,

              "value": "General Sales and Use Tax"

            },

            "inclusionRuleId": {

              "salesTaxHolidayIndicator": false,

              "userDefined": false,

              "value": "v302021099"

            },

            "isService": false,

            "jurisdiction": {

              "effectiveDate": "1900-01-01",

              "expirationDate": "9999-12-31",

              "jurisdictionId": "20035",

              "jurisdictionType": "CITY",

              "value": "VILLAGE OF FOUR SEASONS"

            },

            "maxTaxIndicator": false,

            "nominalRate": 0.015,

            "nonTaxable": 0,

            "notRegisteredIndicator": false,

            "situs": "DESTINATION",

            "taxCollectedFromParty": "BUYER",

            "taxResult": "TAXABLE",

            "taxStructure": "SINGLE_RATE",

            "taxType": "SALES",

            "taxable": 2760.46

          }

        ],

        "totalTax": 199.44,

        "transactionType": "SALE",

        "unitPrice": 212.343

      }

    ],

    "originalCurrency": {

      "isoCurrencyCodeAlpha": "USD",

      "isoCurrencyCodeNum": 0,

      "isoCurrencyName": "US Dollar"

    },

    "returnAssistedParametersIndicator": true,

    "roundAtLineLevel": false,

    "saleMessageType": "QUOTATION",

    "subTotal": 2760.46,

    "total": 2959.9,

    "totalTax": 199.44,

    "transactionId": "998822",

    "transactionType": "SALE"

  },

  "meta": {

    "app": "vertex-ws.war v9.0.17.1.3",

    "timeElapsed(ms)": 3,

    "timeReceived": "2024-09-04T22:57:19.594Z"

  }

}

6. Kết luận

Tích hợp với Vertex Tax RESTful API bằng Python cho phép các doanh nghiệp tự động hóa việc tính toán thuế phức tạp một cách hiệu quả. Trong hướng dẫn này, chúng ta đã hướng dẫn từng bước cần thiết, từ việc xác thực với API của Vertex đến việc thực hiện yêu cầu tính toán thuế. Bằng cách tận dụng sức mạnh của Python và tính linh hoạt của API phiên bản 2 của Vertex, bạn có thể sắp xếp hợp lý việc tuân thủ thuế trong các ứng dụng của mình, giảm thiểu công việc thủ công và đảm bảo tính chính xác trong báo cáo thuế.

Những điểm chính cần nhớ từ hướng dẫn này bao gồm:

Thiết lập xác thực bằng OAuth 2.0 để lấy mã thông báo truy cập.
Xây dựng và gửi yêu cầu tính toán thuế, bao gồm chi tiết khách hàng, thông tin giao dịch và các mục hàng.
Xử lý phản hồi API và đảm bảo bạn có thể quản lý các giao dịch bằng lập trình.

Với việc tích hợp này, bạn hiện có thể mở rộng hoạt động thuế của mình, cung cấp tính toán thuế thời gian thực cho khách hàng của mình và đảm bảo tuân thủ trên nhiều khu vực pháp lý. Khi tiếp tục phát triển giải pháp của mình, hãy đảm bảo khám phá các tính năng khác của API Vertex, chẳng hạn như miễn thuế, nộp tờ khai thuế và các chức năng kiểm toán, để nâng cao hơn nữa quy trình làm việc về thuế của bạn.

Nếu bạn cần cấu hình nâng cao hơn hoặc thêm chi tiết, Tài liệu API của Vertex là một nguồn tài nguyên tuyệt vời để khám phá toàn bộ phạm vi khả năng mà Vertex cung cấp.