QuickBooks Onlineをデータパイプラインソースとして設定 ​

QuickBooks Onlineをデータパイプラインソースとして設定し、顧客、ベンダー、請求書、請求、支払いなどの会計レコードを宛先に抽出します。

このガイドを使用して、コネクションの設定、パイプラインの設定、オブジェクトの追加、同期動作とスキーマ処理の確認、既知の制限の理解を行います。

サポートされている機能 ​

QuickBooks Onlineをパイプラインソースとして使用する場合、次の機能がサポートされます:

• クラウド接続: QuickBooks Onlineは完全にクラウドでホストされるサービスです。 コネクターにはオンプレミスエージェント、プロキシ、VPNは不要です。
• サンドボックスサポート: プロダクションデータを同期する前にパイプラインを検証するため、QuickBooks Onlineサンドボックス会社に接続します。 コネクションを作成するときに、サンドボックスドロップダウンメニューでEnvironmentを選択します。
• 完全同期と増分同期: サポートされているほとんどのオブジェクトは、初回の完全同期後にQuickBooksの変更データキャプチャ（CDC）メカニズムを通じて増分同期されます。 会社情報、基本設定、税務機関、カスタムフィールド定義は常に完全に再読み込みされます。 詳細については、同期モードを参照してください。
• オブジェクトレベルの選択: トランザクションオブジェクトの明細子テーブルを含め、同期するQuickBooks Onlineオブジェクトを選択します。 完全なリストについては、サポートされているオブジェクトを参照してください。
• 削除追跡: コネクターは、QuickBooks Onlineで非アクティブ化または削除されたレコードを追跡し、合成_workato_is_deleted列でマークします。 詳細については、削除追跡を参照してください。
• スキーマドリフト処理: パイプラインがソースに追加された新しいフィールドを自動的に同期する（新規フィールドを自動同期）か、スキーマを固定したままにする（新規フィールドをブロック）かを選択します。
• フィールドレベルのデータ保護: 個人を特定できる情報（PII）などの機密フィールド値が宛先に到達する前にハッシュ化します。 詳細については、機密データの処理を参照してください。
• 同時実行制限: パイプラインがQuickBooks Onlineに対して実行する同時オペレーション数を制限します。

前提条件 ​

QuickBooks Onlineをデータパイプラインソースとして接続する前に、次の要件を満たしてください。

• QuickBooks Onlineアカウント。 すべてのQuickBooks Onlineプランがサポートされています。
• 同期する予定のQuickBooks Online会社のサインイン認証情報。 コネクターはOAuth 2.0を使用し、com.intuit.quickbooks.accountingスコープを通じて会計データへの読み取りアクセスをリクエストします。
• プロダクションに接続する前にサンプルデータに対してパイプラインをテストする予定がある場合は、QuickBooks Onlineサンドボックス会社。

サポートされるコネクションタイプ ​

QuickBooks Onlineデータパイプラインは、1つの認証方式をサポートしています:

• OAuth 2.0（認可コードグラント）: QuickBooks Online認証情報でサインインし、会社データへのアクセスをWorkatoに許可します。 Workatoは認可中に会社ID（Realm ID）を自動的に取得します。

QuickBooks Onlineコネクターは、APIキーまたは基本認証をサポートしていません。

QuickBooks Onlineに接続 ​

QuickBooks Onlineをデータパイプラインソースとして接続するには、次の手順を実行します。

パイプラインの設定 ​

QuickBooks Onlineをデータパイプラインソースとして設定するには、次の手順を実行します:

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

サポートされるオブジェクト ​

QuickBooks Onlineデータパイプラインは、QuickBooks Online Accounting API v3エンティティからデータを同期します。 次の表は、サポートされているオブジェクトをカテゴリ別に示しています。 各オブジェクトは、宛先内の個別のテーブルとして同期されます。

リストエンティティ ​

リストエンティティは、勘定科目表、顧客、製品などのマスターレコードです。 QuickBooks Onlineはこれらのレコードを削除する代わりに非アクティブ化し、コネクターは非アクティブ化をソフト削除として追跡します。

トランザクションエンティティ ​

トランザクションエンティティは財務活動を記録します。 QuickBooks Onlineは削除されたトランザクションをCDCを通じて報告し、コネクターはそれらをソフト削除として追跡します。

明細テーブル ​

明細テーブルは、トランザクションエンティティのネストされた明細配列を、親レコードを参照する列を持つ明細項目ごとに1行に展開します。 各明細テーブルを個別に選択してスケジュールします。親オブジェクトをパイプラインに追加する必要はありません。 コネクターは親トランザクションを読み取って行を作成し、各行の同期位置は親レコードの最終更新時刻から取得されます。

明細テーブルは、完全同期モードで同期する場合にのみ削除追跡をサポートします。 詳細については、削除追跡を参照してください。

参照と設定 ​

参照オブジェクトと設定オブジェクトは、会社プロファイル、会計設定、カスタムフィールド定義を記述します。 これらのオブジェクトは各実行時に常に完全に再読み込みされます。

カスタムフィールド定義の可用性 ​

Custom Field Definitionsオブジェクトには、拡張カスタムフィールドを含むQuickBooks Onlineプランが必要であり、OAuth認可でカスタムフィールド定義の読み取りスコープを付与する必要があります。 Workatoはオブジェクトリストを読み込むときにこのアクセス権を確認し、アカウントにアクセス権がない場合はそのオブジェクトを省略します。

このオブジェクトを使用して、販売トランザクションテーブルのcustom_field JSON値を、会社で定義されたカスタムフィールドラベルにマッピングします。

同期モード ​

QuickBooks Onlineデータパイプラインは、完全同期と増分同期をサポートします。 同期モードは、パイプラインに追加するときにオブジェクトごとに設定されます。

フル同期 ​

完全同期はオブジェクトのすべてのレコードを取得し、各実行時に完全なレコードセットを再読み込みします。 すべてのパイプラインの初回実行では、選択した各オブジェクトの完全同期が実行され、履歴開始日を設定している場合はその日付から開始されます。

増分同期 ​

増分同期は、QuickBooks Onlineの変更データキャプチャ（CDC）を使用して、前回正常に同期されてから変更されたレコードのみを取得します。 コネクターは、各オブジェクトの同期位置を合成_workato_cursor列で追跡します。 詳細については、合成列を参照してください。

会社情報、基本設定、税務機関、カスタムフィールド定義は増分同期をサポートしておらず、各実行時に完全に再読み込みされます。

明細テーブルは、親レコードの最終更新時刻から同期位置を追跡します。

CDCは30日分の変更履歴を保持します。 パイプラインがそれより長く一時停止した場合、コネクターはギャップを自動的に埋めます。 詳細については、長時間の一時停止後の増分同期を参照してください。

削除追跡 ​

QuickBooks Onlineは、APIを通じてレコードを完全に削除しません。 代わりに、レコードは非アクティブ化されるか削除済みとしてマークされ、コネクターは両方のパターンをソフト削除として追跡します:

• CustomersやItemsなどのリストエンティティは、QuickBooks Onlineで非アクティブ化されます。 コネクターはアクティブなレコードと非アクティブなレコードの両方を同期し、非アクティブなレコードを削除済みとしてマークします。
• InvoicesやBillsなどのトランザクションエンティティは、CDCを通じて削除済みステータスで削除を報告します。 コネクターはこれらのレコードを削除済みとしてマークします。

削除されたレコードは宛先から削除されません。 コネクターは、影響を受ける行の合成_workato_is_deleted列をtrueに設定します。

QuickBooks Onlineは、個々の明細項目の削除シグナルを提供しません。 増分モードで明細テーブルを同期する場合、_workato_is_deleted列はなく、削除されたトランザクションの明細行は宛先に残ります。 それらを識別するには、明細テーブルを親テーブルに結合し、親の_workato_is_deleted列でフィルタリングします。

完全同期モードで明細テーブルを同期する場合、_workato_is_deleted列が存在し、QuickBooks Onlineに表示されなくなった行について宛先がそれをtrueに設定します。

スキーマとデータ型の処理 ​

コネクターは、次のルールを使用してQuickBooks Online APIフィールドを宛先列にマッピングします。

列の命名 ​

コネクターは、QuickBooks Onlineフィールド名をアンダースコア付きの小文字に変換します。 たとえば、DisplayNameはdisplay_name列になり、ARAccountRefはar_account_refになります。

ネストされたフィールドでは、親オブジェクト名が削除されます。 たとえば、MetaData.LastUpdatedTimeはlast_updated_time列になり、MetaData.CreateTimeはcreate_timeになります。

宛先での列名の大文字と小文字 ​

宛先は、テーブルを作成するときに列名の大文字と小文字を調整します。 Snowflakeは列名を大文字で保存し、ほとんどの宛先は小文字で保存します。BigQueryとSQL Serverは、コネクターが出力したとおりに保持します。

ネストされたオブジェクトと配列 ​

bill_addr、currency_ref、txn_tax_detail、linked_txnなどのネストされたオブジェクトと配列は、JSONシリアル化された値を含む単一の列として同期されます。 これらの列から個々の値を宛先で抽出できます。たとえば、ウェアハウスのJSON関数やモデリングレイヤーを使用します。

トランザクションエンティティの明細配列は例外です。コネクターはそれらを専用の明細テーブルに展開します。 詳細については、明細テーブルと詳細タイプを参照してください。

明細テーブルと詳細タイプ ​

各明細テーブル行には、parent_invoice_idやparent_bill_idなど、親レコードを参照するparent_<object>_id列と、その親内の明細を識別するid列が含まれます。 これら2つの列が一緒にテーブルの主キーを形成し、QuickBooks Online自体が番号を付けない小計や割引などの計算行を含め、各行を一意に識別します。

QuickBooks Onlineの明細項目はポリモーフィックです。 各明細には、存在する詳細フィールドを決定するSalesItemLineDetailなどの詳細タイプがあります。 明細テーブルには、detail_type列と、一致したタイプの完全な詳細オブジェクトを含むdetail_json列が含まれます。

Payment Linesは例外です。 支払い明細はポリモーフィックではないため、このテーブルにはdetail_type列またはdetail_json列がなく、主キーはparent_payment_idとline_numの組み合わせです。 その列はparent_payment_id、line_num、amount、linked_txn、line_ex、last_updated_timeです。

カスタムフィールド ​

QuickBooks Onlineは、販売トランザクションオブジェクトでユーザー定義カスタムフィールドを限定的にサポートしています。 コネクターはこれらをInvoices、Estimates、Credit Memos、Sales Receiptsで同期します。 コネクターは、各フィールドを個別の宛先列に展開するのではなく、完全なカスタムフィールド配列を単一のcustom_field JSON列として同期します。 特定のカスタムフィールドを使用するには、宛先でDefinitionIdキーとStringValueキーを使用してJSONを解析します。

データ型 ​

QuickBooks OnlineエンティティIDは整数の文字列表現であり、コネクターはid列を文字列として保存します。

customer_refなどの参照列には、valueキーとnameキーを持つJSONオブジェクトが保持されます。 参照先テーブルに結合する場合は、valueキーを外部キーとして使用します。

タイムスタンプは、2026-01-15T10:30:00-08:00など、タイムゾーンオフセットを含むISO 8601値です。 コネクターはそれらをタイムゾーン対応のタイムスタンプ列として同期します。

小数フィールドは、デフォルトの精度とスケール(28, 12)で同期されます。 QuickBooks Onlineは数値フィールドの精度やスケールを報告しません。このデフォルトがない場合、一部の宛先は小数値をNUMERIC(38, 0)として保存し、暗黙的に丸めるため、為替レートなどの小数値に影響します。

合成列 ​

Workatoは、特定のオブジェクトの宛先テーブルに次の合成列を追加します:

機密データの処理 ​

QuickBooks Onlineオブジェクトには、重要なPIIと機密性の高い財務データが含まれています。 次のオブジェクトには、一般的に機密フィールドが含まれます:

PIIが送信先に到達する前に保護するには、パイプライン設定中にフィールドレベルのデータ保護でHashオプションを使用します。 Workatoでは、前の表のフィールドに対してフィールドレベルのハッシュ化を推奨しています。 詳細については、パイプラインを構成手順を参照してください。

制限事項 ​

QuickBooks Onlineをデータパイプラインソースとして使用する場合、次の制限が適用されます。

長時間の一時停止後の増分同期 ​

QuickBooks Online CDCは30日分の変更履歴を保持します。 パイプラインが30日を超えて一時停止または失敗した場合、コネクターは最後の同期位置より後に更新されたすべてのレコードを取得するフィルタリング済みクエリに自動的にフォールバックするため、変更が失われることはありません。 このフォールバックは、Invoicesなどの大容量オブジェクトでは、CDCベースの増分同期よりも大幅に時間がかかる場合があります。 高速な増分同期を維持するため、パイプラインを定期スケジュールで実行し続けてください。

履歴開始日は変更できません ​

初回開始時に、このパイプラインは次の日付からレコードを取得する必要がありますの値は、パイプラインがレコードを抽出する最も早い日付を定義します。 初回実行後にこの値を変更することはできません。 より早い日付からレコードを同期するには、新しいパイプラインを作成します。

最小同期頻度 ​

サポートされる最小同期間隔は15分です。 これより高い頻度で同期をトリガーすることはできません。