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': 'hoa.vuquang@glinteco.com'},
 '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': 'info@glinteco.com'},
 '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': ''