Pythonを用いたVertex Tax RESTful API連携ステップバイステップガイド
By JoeVu, at: 2024年9月29日12:00
Estimated Reading Time: __READING_TIME__ minutes


Vertex Tax RESTful API (v2) と Python を使用した統合
1. はじめに
以前のブログ投稿でVertexCloud 間接税についてご紹介したとおり、このブログ投稿では、Vertex の Tax RESTful API と Python を使用した統合のステップバイステッププロセスに焦点を当てます。このチュートリアルの最後に、Vertex のサービスを使用して、税金の計算とトランザクションのプログラムによる処理ができるようになります。
バージョン1 は非推奨となったため、現在サポートされているバージョン2に焦点を当てます。
2. 前提条件
統合プロセスに入る前に、以下の準備が整っていることを確認してください。
- Python (バージョン 3.6 以降)
- Vertex Tax API クレデンシャル:APIキーを生成してサービスにアクセスするには、有効な Vertex アカウントが必要です。APIアクセスにサインアップしてください。
- Python ライブラリ:このガイドでは、HTTP 呼び出しを行うための
requests
と、API 応答を処理するためのjson
を使用します -pip install requests
- RESTful API の基本的な理解:RESTful API とのやり取り方法(GET、POST、PUT リクエストによる)を理解していれば、このガイドを簡単に理解できます。
3. Python 環境の設定
開始するには、新しいプロジェクトフォルダを作成し、依存関係を整理するために仮想環境を設定します。方法は次のとおりです。
プロジェクトディレクトリの作成
mkdir vertex-tax-api
cd vertex-tax-api
仮想環境の設定
python3 -m venv vertex-env
source vertex-env/bin/activate
# MacOS/Linux の場合
# または vertex-env\Scripts\activate
# Windows の場合
必要な依存関係のインストール
pip install requests
これで、Vertex Tax API と統合するためのコードの記述を開始できます。
4. Vertex Tax API (バージョン 2) への認証
API呼び出しを行う前に、OAuth 2.0 を使用して Vertex のシステムで認証する必要があります。認証プロセスでは、client_id
、client_secret
、およびgrant_type
(client_credentials
に設定)を認証エンドポイントに送信してトークンを受け取る必要があります。
認証リクエストの例
Python を使用して認証し、Vertex の API(バージョン 2)からアクセストークンを取得する方法は次のとおりです。
import requests
# 認証トークンを取得する URL
auth_url = 'https://auth.vertexsmb.com/identity/connect/token'
# クライアントクレデンシャル
client_id = 'your_client_id'
client_secret = 'your_client_secret'
# トークンリクエストのデータ
data = {
'grant_type': 'client_credentials',
'client_id': client_id,
'client_secret': client_secret,
}
# ヘッダー
headers = {
'Content-Type': 'application/x-www-form-urlencoded'
}
# トークンを取得するためにリクエストを送信します
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("Authentication failed:", response.text)
正常に認証されると、API はアクセストークンを返します。他のAPIエンドポイントにリクエストを行う際には、このトークンをAuthorization
ヘッダーに含める必要があります。
5. 税金計算リクエストの実行 (バージョン 2)
アクセストークンを取得したら、税金計算リクエストの実行に進みます。以下は、税金計算リクエストのペイロードの例です。販売メッセージタイプ、トランザクションタイプ、通貨、顧客情報、明細行、および割引などの詳細が含まれています。
税金計算リクエストの例
# 税金計算の URL (バージョン 2)
api_url = 'https://calcconnect.vertexsmb.com/vertex-ws/v2/supplies'
# アクセストークンを含むヘッダーの設定
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
}
# 税金計算のサンプルペイロード
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"
}
}
# POST リクエストを行う
response = requests.post(api_url, json=payload, headers=headers)
if response.status_code == 200:
tax_info = response.json()
print("Tax Calculation Result:", tax_info)
else:
print("Error in API call:", response.text)
この例では、詳細なトランザクションを Vertex API に送信しています。ペイロードには、トランザクションタイプ、顧客の詳細、数量、価格、適用された割引を含む明細行などの重要なフィールドが含まれています。
サンプルレスポンス
{
"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. まとめ
Vertex Tax RESTful API と Python を使用した統合により、企業は複雑な税金の計算を効率的に自動化できます。このガイドでは、Vertex API での認証から税金計算リクエストの実行まで、重要な手順を説明しました。Python のパワーと Vertex のバージョン 2 API の柔軟性を活用することで、アプリケーションにおける税務コンプライアンスを効率化し、手作業を削減し、税務報告の正確性を確保できます。
このガイドからの重要なポイントを次に示します。
- OAuth 2.0 を使用した認証を設定してアクセストークンを取得します。
- 顧客の詳細、トランザクション情報、明細行を含む税金計算リクエストを作成して送信します。
- API 応答を処理し、トランザクションをプログラムで管理できるようにします。
この統合により、税務業務をスケールアップし、顧客にリアルタイムの税金計算を提供し、複数の管轄区域全体でコンプライアンスを確保できます。ソリューションの開発を続ける際には、税務免除、申告、監査機能など、Vertex API のその他の機能を調べて、税務ワークフローをさらに強化してください。
より高度な設定や詳細が必要な場合は、Vertex API ドキュメント は、Vertex が提供する機能の全範囲を調べるための優れたリソースです。