Khắc phục lỗi API QuickBooks: Thiếu danh mục thuế bán hàng do MinorVersion

Debugging QuickBooks Online API: Missing Sales Tax Category Due to MinorVersion Parameter

Giới thiệu

Trong khi làm việc với QuickBooks Online (QBO) API, tôi đã gặp phải một sự không nhất quán giữa môi trường UAT và Production khi truy xuất dữ liệu hóa đơn và mục. Vấn đề là gì? Trường TaxClassificationRef, giúp xác định loại thuế bán hàng của một mục, đã bị thiếu trong môi trường Production nhưng có trong UAT.

Sau khi gỡ lỗi, tôi đã phát hiện ra nguyên nhân gốc rễ là tham số minorversion trong yêu cầu API. Bài đăng trên blog này ghi lại những phát hiện của tôi, quá trình gỡ lỗi và giải pháp cuối cùng.

Vấn đề: Thiếu TaxClassificationRef trong Production

Tôi đã chạy các truy vấn QuickBooks bằng Python sau đây cho Invoice và Item trong cả UAT và Production:

Đáp ứng API Production (Thiếu TaxClassificationRef)

Đáp ứng truy vấn Invoice

Invoice.get(9999, qb=qb).to_dict()

Đoạn trích đầu ra liên quan

{'Id': '9999',

 'SyncToken': '1',

 'sparse': False,

 'domain': 'QBO',

 'Deposit': 0,

 'Balance': 455.73,

 'AllowIPNPayment': False,

 'AllowOnlineCreditCardPayment': True,

 'AllowOnlineACHPayment': True,

 'DocNumber': '1927',

 'PrivateNote': '',

 'DueDate': '2025-04-04',

 'ShipDate': '',

 'TrackingNum': '',

 'TotalAmt': 455.73,

 'TxnDate': '2025-03-05',

 'ApplyTaxAfterDiscount': False,

 'PrintStatus': 'NeedToPrint',

 'EmailStatus': 'NotSet',

 'ExchangeRate': 1,

 'GlobalTaxCalculation': 'TaxExcluded',

 'InvoiceLink': '',

 'HomeBalance': 0,

 'HomeTotalAmt': 0,

 'FreeFormAddress': False,

 'EInvoiceStatus': None,

 'BillAddr': {'Id': '715',

  'Line1': 'Glinteco',

  'Line2': '132 My Street',

  'Line3': 'Kingston, New York 12401 US',

  'Line4': '',

  'Line5': '',

  'City': '',

  'CountrySubDivisionCode': '',

  'Country': '',

  'PostalCode': '',

  'Lat': '',

  'Long': '',

  'Note': ''},

 'ShipAddr': {'Id': '716',

  'Line1': 'Glinteco',

  'Line2': '132 My Street',

  'Line3': 'Kingston, New York 12401 US',

  'Line4': '',

  'Line5': '',

  'City': '',

  'CountrySubDivisionCode': '',

  'Country': '',

  'PostalCode': '',

  'Lat': '',

  'Long': '',

  'Note': ''},

 'BillEmail': {'Address': '[email protected]'},

 'BillEmailCc': None,

 'BillEmailBcc': None,

 'CustomerRef': {'value': '145', 'name': 'Glinteco', 'type': ''},

 'CurrencyRef': {'value': 'USD', 'name': 'United States Dollar', 'type': ''},

 'CustomerMemo': None,

 'DepartmentRef': None,

 'TxnTaxDetail': {'TotalTax': 34.73,

  'TxnTaxCodeRef': {'value': '3', 'name': '', 'type': ''},

  'TaxLine': [{'Amount': 26.31,

    'DetailType': 'TaxLineDetail',

    'TaxLineDetail': {'PercentBased': True,

     'TaxPercent': 6.25,

     'NetAmountTaxable': 0,

     'TaxRateRef': {'value': '3', 'name': '', 'type': ''}}},

   {'Amount': 0,

    'DetailType': 'TaxLineDetail',

    'TaxLineDetail': {'PercentBased': True,

     'TaxPercent': 0,

     'NetAmountTaxable': 0,

     'TaxRateRef': {'value': '4', 'name': '', 'type': ''}}},

   {'Amount': 5.26,

    'DetailType': 'TaxLineDetail',

    'TaxLineDetail': {'PercentBased': True,

     'TaxPercent': 1.25,

     'NetAmountTaxable': 0,

     'TaxRateRef': {'value': '5', 'name': '', 'type': ''}}},

   {'Amount': 3.16,

    'DetailType': 'TaxLineDetail',

    'TaxLineDetail': {'PercentBased': True,

     'TaxPercent': 0.75,

     'NetAmountTaxable': 0,

     'TaxRateRef': {'value': '6', 'name': '', 'type': ''}}}]},

 'DeliveryInfo': None,

 'RecurDataRef': None,

 'TaxExemptionRef': None,

 'MetaData': {'CreateTime': '2025-03-04T20:02:58-08:00',

  'LastUpdatedTime': '2025-03-04T20:03:02-08:00'},

 'CustomField': [{'DefinitionId': '1',

   'Type': 'StringType',

   'Name': 'PO Number',

   'StringValue': ''}],

 'Line': [{'Id': '1',

   'LineNum': 1,

   'Description': None,

   'Amount': 421.0,

   'DetailType': 'SalesItemLineDetail',

   'LinkedTxn': [],

   'CustomField': [],

   'SalesItemLineDetail': {'UnitPrice': 421,

    'Qty': 1,

    'ServiceDate': '9999-12-31',

    'TaxInclusiveAmt': 0,

    'MarkupInfo': None,

    'ItemRef': {'value': '1010000001',

     'name': 'Services:glinteco',

     'type': ''},

    'ClassRef': None,

    'TaxCodeRef': {'value': 'TAX', 'name': '', 'type': ''},

    'PriceLevelRef': None}},

  {'Id': None,

   'LineNum': 0,

   'Description': None,

   'Amount': 421.0,

   'DetailType': 'SubTotalLineDetail',

   'LinkedTxn': [],

   'CustomField': [],

   'SubtotalLineDetail': None,

   'SubTotalLineDetail': {}}],

 'LinkedTxn': [],

 'AllowOnlinePayment': False,

 'SalesTermRef': {'value': '3', 'name': 'Net 30', 'type': ''}}

Đáp ứng truy vấn Item

Item.get(20812, qb=qb).to_dict()

Đoạn trích đầu ra liên quan

{'Id': '20812',

 'SyncToken': '0',

 'sparse': False,

 'domain': 'QBO',

 'Name': 'glinteco',

 'Description': '',

 'Active': True,

 'SubItem': True,

 'FullyQualifiedName': 'Services:glinteco',

 'Taxable': True,

 'SalesTaxIncluded': None,

 'UnitPrice': 0,

 'Type': 'Service',

 'Level': 1,

 'PurchaseDesc': None,

 'PurchaseTaxIncluded': None,

 'PurchaseCost': 0,

 'TrackQtyOnHand': False,

 'QtyOnHand': None,

 'InvStartDate': None,

 'AssetAccountRef': None,

 'ExpenseAccountRef': None,

 'IncomeAccountRef': {'value': '1', 'name': 'Services', 'type': ''},

 'SalesTaxCodeRef': None,

 'ParentRef': {'value': '15', 'name': 'Services', 'type': ''},

 'PurchaseTaxCodeRef': None,

 'AbatementRate': None,

 'ReverseChargeRate': None,

 'ServiceType': None,

 'ItemCategoryType': None,

 'Sku': None,

 'MetaData': {'CreateTime': '2025-03-04T20:02:29-08:00',

  'LastUpdatedTime': '2025-03-04T20:02:29-08:00'}}

Đáp ứng API UAT (Chứa TaxClassificationRef)

Trong UAT, các truy vấn tương tự trả về một tập dữ liệu đầy đủ, bao gồm cả TaxClassificationRef:

{'Id': '152',

 'SyncToken': '0',

 'sparse': False,

 'domain': 'QBO',

 'Deposit': 0,

 'Balance': 35.0,

 'AllowIPNPayment': False,

 'AllowOnlineCreditCardPayment': False,

 'AllowOnlineACHPayment': False,

 'DocNumber': '1045',

 'PrivateNote': '',

 'DueDate': '2025-04-04',

 'ShipDate': '',

 'TrackingNum': '',

 'TotalAmt': 35.0,

 'TxnDate': '2025-03-05',

 'ApplyTaxAfterDiscount': False,

 'PrintStatus': 'NeedToPrint',

 'EmailStatus': 'NotSet',

 'ExchangeRate': 1,

 'GlobalTaxCalculation': 'TaxExcluded',

 'InvoiceLink': 'https://developer.intuit.com/comingSoonview/scs-v1-12312?locale=en_US&cta=v3invoicelink',

 'HomeBalance': 0,

 'HomeTotalAmt': 0,

 'FreeFormAddress': True,

 'EInvoiceStatus': None,

 'BillAddr': {'Id': '2',

  'Line1': '4581 Finch St.',

  'Line2': '',

  'Line3': '',

  'Line4': '',

  'Line5': '',

  'City': 'Bayshore',

  'CountrySubDivisionCode': 'CA',

  'Country': '',

  'PostalCode': '94326',

  'Lat': 'INVALID',

  'Long': 'INVALID',

  'Note': ''},

 'ShipAddr': {'Id': '2',

  'Line1': '4581 Finch St.',

  'Line2': '',

  'Line3': '',

  'Line4': '',

  'Line5': '',

  'City': 'Bayshore',

  'CountrySubDivisionCode': 'CA',

  'Country': '',

  'PostalCode': '94326',

  'Lat': 'INVALID',

  'Long': 'INVALID',

  'Note': ''},

 'BillEmail': {'Address': '[email protected]'},

 'BillEmailCc': None,

 'BillEmailBcc': None,

 'CustomerRef': {'value': '1', 'name': "Amy's Bird Sanctuary", 'type': ''},

 'CurrencyRef': {'value': 'USD', 'name': 'United States Dollar', 'type': ''},

 'CustomerMemo': {'value': 'Thank you for your business and have a great day!'},

 'DepartmentRef': None,

 'TxnTaxDetail': {'TotalTax': 0,

  'TxnTaxCodeRef': {'value': '4', 'name': '', 'type': ''},

  'TaxLine': [{'Amount': 0,

    'DetailType': 'TaxLineDetail',

    'TaxLineDetail': {'PercentBased': True,

     'TaxPercent': 0,

     'NetAmountTaxable': 35.0,

     'TaxRateRef': {'value': '6', 'name': '', 'type': ''}}}]},

 'DeliveryInfo': None,

 'RecurDataRef': None,

 'TaxExemptionRef': {'value': '', 'name': '', 'type': ''},

 'MetaData': {'CreateTime': '2025-03-04T18:50:26-08:00',

  'LastUpdatedTime': '2025-03-04T18:50:26-08:00',

  'LastModifiedByRef': {'value': '9341454203477221'}},

 'CustomField': [],

 'Line': [{'Id': '1',

   'LineNum': 1,

   'Description': 'Tree and Shrub Trimming',

   'Amount': 35.0,

   'DetailType': 'SalesItemLineDetail',

   'LinkedTxn': [],

   'CustomField': [],

   'SalesItemLineDetail': {'UnitPrice': 35,

    'Qty': 1,

    'ServiceDate': ''



                    
                        Tag list:

                        
                        - QuickBooks

                        
                        - Fix missing TaxClassificationRef in QBO

                        
                        - QuickBooks Online integration troubleshooting

                        
                        - QuickBooks API missing fields

                        
                        - QuickBooks Item API

                        
                        - QuickBooks Online API issue

                        
                        - QuickBooks API sales tax category

                        
                        - QuickBooks API tax classification

                        
                        - QuickBooks API minorversion impact

                        
                        - QuickBooks python-quickbooks library issue

                        
                        - QBO minorversion parameter

                        
                        - QBO API UAT vs PROD differences

                        
                        - QuickBooks Invoice API