QuickBooks Online 接続：注文、顧客、請求書、入金、在庫
QuickBooks で歯車アイコン → Account and settings → Billing & subscription から Realm ID（Company ID）を取得し、Intuit Developer の自分のアプリの OAuth2 playground で access token を取得して、両方を Integration に入力、テスト・マッピング・有効化します。トークンは 1 時間で期限切れになるため、テスト失敗はたいてい新しいトークンが必要という意味です。
QuickBooks Online コネクタは、あなたの QuickBooks 会社と双方向に連携します。販売注文、顧客、請求書、製品、入金を取り込み、顧客、請求書、製品、入金を返送でき、アイテム単位で在庫を確認できます。QuickBooks に送信した入金は、対応する請求書に紐付けて消し込むことができます。接続は Realm ID（Company ID）と貼り付ける access token で識別されます。そのトークンは 1 時間で期限切れになります。突然何かが動かなくなったら、他のものを変える前にまず新しいトークンを取得してください。
前提条件#
- ログインできる QuickBooks Online の会社と、Account and settings を開く権限。
- Intuit Developer にアプリがあり、その OAuth2 playground を実行してその会社の access token を取得できること。
- 会社がある環境が分かっていること：実際の会社は production、Intuit Developer のサンドボックス会社は sandbox です。
- トークン取得後すぐに完了できる時間。access token は 1 時間で期限切れになるため、最後に取得し、すぐに入力してテストしてください。
認証情報の取得#
- Realm ID は QuickBooks 自体の中で取得します。QuickBooks にログインし、右上の歯車アイコン ⚙ をクリックして Account and settings を開き、Billing & subscription に移動して、そこに表示される Company ID をコピーします。その Company ID が Realm ID です。
- access token は Intuit Developer で取得します。Intuit Developer を開き、自分のアプリを開いて、その OAuth2 playground を開きます。
- OAuth2 playground で、同じ会社・同じ環境（production または sandbox）向けに OAuth2 フローを実行し、返された access token をコピーします。
- そのまま入力手順に進んでください。この access token は 1 時間で期限切れになります。トークンの更新には同じ Intuit Developer アプリの Client ID と Client Secret を使うため、そのアプリの値も手元に用意してください。
Integration への入力#
- Integration → コネクタマーケットプレイス → QuickBooks Online → 新規接続 を開きます。
- realm_id、必須、Realm ID（Company ID）：QuickBooks → 歯車アイコン ⚙ → Account and settings → Billing & subscription からコピーした Company ID（例：123456789）を貼り付けます。
- environment、任意、Environment：実際の会社は production、Intuit Developer のサンドボックス会社は sandbox と入力します。空の場合は production が使われます。
- access_token、必須、Access token：Intuit Developer → 自分のアプリ → OAuth2 playground で取得した access token を全文、すぐに貼り付けます。1 時間で期限切れになるためです。パスワード型のフィールドで、秘密情報として保存されます。
接続テスト#
接続テストをクリックします。テストはあなたのトークンを Bearer 認証情報として使い、QuickBooks から会社情報を読み取ります。production の場合は realm_id の会社情報を呼び出し、sandbox の場合は代わりにサンドボックスのアドレスを使います。成功すると会社名が返され、トークンと Realm ID が想定した会社のものであることが分かります。realm_id が未入力の場合、テストは MISSING_REALM_ID で止まります。access_token が未入力の場合は MISSING_TOKEN で止まり、リクエストは送信されません。401 の応答は INVALID_TOKEN として報告されます。トークンが無効か、最も多いケースでは単に 1 時間を過ぎただけです。テストは 12 秒待ってから TEST_TIMEOUT を報告します。
Mapping / テンプレート選択#
QuickBooks Online 標準の Mapping を選択します。この接続が扱うオブジェクト（販売注文、顧客、請求書、製品（items）、入金、アイテム単位の在庫数量）をカバーします。テスト合格後、1 回取得を実行し、実レコードを並べて確認してください（注文番号または請求書番号、顧客、明細、金額）。さらに顧客または製品を 1 件送信し、QuickBooks に表示されることを確認してから有効化します。会社内の名称が標準オブジェクトと異なる場合は、QuickBooks 側の名前を変えず、Mapping でその項目を調整してください。
有効化#
有効化後、接続は設定した頻度で QuickBooks Online から販売注文、顧客、請求書、製品、入金を取り込み、それらのフローが実行される際に顧客、請求書、製品、入金を返送し、アイテム単位の在庫確認に応答します。最初は Runs / Logs で実行を確認し、QuickBooks と照合してから無人運用に移してください。
トークンは新しく保ってください。1 時間で期限切れになるため、実行がトークンエラーで失敗し始めたら、Intuit Developer → 自分のアプリ → OAuth2 playground に戻り、同じ会社・同じ環境向けの新しい access token を取得して access_token に貼り付け、再テストしてください。通常のトークン更新で、接続の他の項目を変更する必要はありません。
よくある質問#
テストが INVALID_TOKEN（401）で失敗する
QuickBooks が access token を拒否しました。最も多い原因は時間です。トークンは 1 時間で期限切れになるため、貼り付けたときは有効でも、テスト時や後の実行開始時にはすでに期限切れのことがあります。別の会社や別の環境向けに取得したトークンも同様に拒否されます。
まず realm_id や environment を変えないでください。Intuit Developer → 自分のアプリ → OAuth2 playground に行き、同じ会社・同じ環境向けにフローを再実行し、新しい access token を access_token に貼り付けて保存し、すぐに再テストしてください。
テストが MISSING_REALM_ID または MISSING_TOKEN で止まる
2 つの識別値のいずれかが空で、両方が揃うまでテストはリクエストを送信しません。MISSING_REALM_ID は realm_id が空、MISSING_TOKEN は access_token が空であることを示します。または貼り付けたトークンが切り取られ、使える内容が保存されなかった場合です。
realm_id は QuickBooks → 歯車アイコン ⚙ → Account and settings → Billing & subscription → Company ID から入力し、access_token は OAuth2 playground から新しいものを全文貼り付けてください。保存し、新しいトークンが古くなる前にすぐ再テストします。
テストが MISSING_SCOPE で失敗する
トークン自体は受け付けられましたが、この接続に必要な会計スコープ（com.intuit.quickbooks.accounting）を持っていないため、QuickBooks が会社情報の読み取りを許可しません。
OAuth2 playground でフローを再実行し、アプリに会計スコープが含まれていることを確認し、新しい access token をコピーして access_token に貼り付け、再テストしてください。
テストで想定と違う会社名が返される
トークンと Realm ID が同じ会社を表していません。テスト結果の会社名は、トークンと realm_id が実際に指す会社のものです。よくあるのは、production を想定していたのにサンドボックス会社につながった、またはトークンを playground で別の会社向けに取得した場合です。
3 つの値をまとめて確認してください：realm_id は対象会社の歯車アイコン ⚙ → Account and settings → Billing & subscription → Company ID から、environment はその会社に合わせて production または sandbox に設定し、トークンは playground で同じ会社・同じ環境向けに実行して取得したものを使います。一致しないものを修正して再テストしてください。
すべて動いていたのに、1 時間後に実行が失敗し始めた
そのタイミングはトークンの寿命であり、Mapping の故障でも会社の変更でもありません。access token は 1 時間で期限切れになるため、テストに合格した接続でも、新しいトークンを貼り付けるまで後の実行がトークンエラーで失敗します。
Intuit Developer → 自分のアプリ → OAuth2 playground で、同じ会社・同じ環境向けの新しい access token を取得し、access_token に貼り付けてテストしてください。トークンの更新にはそのアプリの Client ID と Client Secret を使うため、そのアプリの値を用意しておくと更新が速くなります。
テストが TEST_TIMEOUT または CONNECTION_FAILED を報告する
会社情報のリクエストが完了しませんでした。TEST_TIMEOUT は 12 秒以内に完全な応答が届かなかったことを、CONNECTION_FAILED は QuickBooks へのリクエストが通らなかったことを示します。ネットワークを長く疑う前に、この接続での疑う順序を思い出してください。期限切れ、または環境が違うトークンが、最初に除外すべきものです。
まず同じ会社向けの新しい access token を貼り付け、environment がそれに合っているか（production または sandbox）確認して、再テストしてください。新しく正しく一致したトークンでもタイムアウトする場合は、少し待って再試行し、realm_id を変更する前に Runs / Logs で正確なエラーを確認してください。