Xeroに接続する

PlaidCloudをXeroのAccounting APIに接続すると、クエリを手書きすることなく、勘定科目表、取引先、請求書、クレジットノート、支払、手動仕訳などを取得し、ドキュメントを書き戻すことができます。このガイドでは、接続、インポートステップ、転記ステップについて説明します。

注意

インポートは必ず最初にデモ組織で実行してください。また、本番で転記する前に、すべての転記バッチで下記の Test Only Mode を実施してください。

前提条件

Xeroで次のものが必要です。

• 読み取りと転記の対象にする組織にアクセスできるXeroのログイン。
• その組織に対して接続アプリを承認する権限。セットアップ中に、Xeroが許可の承認を求めます。

必要なものは以上です。PlaidCloudがOAuthアプリを登録するため、開発者アカウント、クライアントID、クライアントシークレットを取得する必要はありません。

接続を作成する

1. Tools > Connections を開き、New Connection をクリックします。

2. メニューから REST - Xero を選択します。

3. 接続に名前を付けます（例: Xero Prod）。

4. Xeroに接続 をクリックし、Xeroにサインインして、PlaidCloudが到達できるようにしたい組織へのアクセスを承認します。

5. 接続ステータス に、この許可が対象とする組織の数が報告されます。この接続の対象にする組織を 組織 から選択します。

6. Create をクリックします。

ノート

PlaidCloudはXeroのトークンを自動的に更新し、ローテーションされた各リフレッシュトークンを保存するため、数週間アイドル状態だった接続も引き続き動作します。1つの許可で複数の組織を対象にできますが、1つの接続が対象にするのは常にちょうど1つの組織です。2つ目の組織に到達するには、2つ目のXero接続を作成してください。XeroのDemo Companyは他の組織と同じ組織であるため、サンドボックス接続とは、組織 がそれを指している接続のことです。

接続をスモークテストする

1. ワークフローに Xero: エンティティのインポート ステップを追加します。

2. Xero接続 に作成した接続を、エンティティタイプ に Chart of Accounts を、ターゲットテーブル に作業用テーブルを設定します。

3. ステップを実行します（ワークフロー内で1つのステップを実行するを参照）。

ターゲットテーブルにデータが入っていれば、許可と組織の選択がどちらも正しいことを確認できます。エラーが発生した場合は、問題が示されます。たとえば、期限切れの許可や、ログインがアクセスできなくなった組織などです。

データをインポートする

1. Xero: エンティティのインポート ステップを追加し、Xero接続 と ターゲットテーブル を設定します。

2. エンティティタイプ に、取得したいレコードを設定します。勘定科目表、取引先、請求書、クレジットノート、支払、手動仕訳、銀行取引、アイテム、トラッキングカテゴリ、税率、通貨から選べます。

3. 任意のフィルターで取得範囲を絞り込みます。ステータス（AUTHORISED や PAID など、Xeroの単一のステータス）、開始日 と 終了日（エンティティの日付に対する YYYY-MM-DD の境界）、更新日時以降（更新日時による切り捨ての基準）です。

4. ステップを実行し、ターゲットテーブルを確認します。

ノート

更新日時以降 には保存されたウォーターマークがありません。PlaidCloudは前回の実行がどこで止まったかを記憶しないため、増分で取得するには、実行のたびに自分で基準日時を指定してください。アイテムと通貨にはフィルターがまったく文書化されておらず、勘定科目表と取引先はステータスを受け付けますが日付範囲は受け付けません。Xeroは、エンティティがサポートしないフィルターを拒否するため、ステップは誤った結果セットを返すのではなく、エラーを報告します。

ドキュメントを転記する

Xero: ドキュメントの転記 ステップは、すべてのERP転記ステップが使用するのと同じ共有書き込みパイプラインを通じて、5種類のドキュメントを転記します。ManualJournal、Invoice、Bill、Payment、CreditNote です。

1. ヘッダーテーブル を作成します。ドキュメント1件につき1行で、ref（ドキュメントの識別子）、doc_type（ManualJournal、Invoice、Bill、Payment、CreditNote）、posting_date の列と、ドキュメントタイプが必要とする場合は currency_id、party_id（Xeroの取引先）、memo、due_date を含めます。Paymentには total_amt、deposit_account_id、bank_account_id、linked_invoice_id も必要で、CreditNoteには credit_note_type（販売の場合はデフォルトの ACCRECCREDIT、購買の場合は ACCPAYCREDIT）が必要です。1つのバッチにドキュメントタイプを混在させることができ、PlaidCloudは転記の前に doc_type でバッチを分割します。

2. 明細テーブル を作成します。ref ごとに1行以上で、各行にその ref を持たせ、ドキュメントタイプに合わせた形にします。

   ドキュメントタイプ	明細列
   ManualJournal	account_id、debit、credit、およびトラッキング用の任意の class_id / department_id
   Invoice	item_id、qty、unit_price、amount
   Bill	account_id、amount
   CreditNote	item_id、qty、unit_price、amount
   Payment	linked_txn_id（明細が適用される請求書）、amount

   tax_type と memo は、どの明細でも任意です。

3. Xero: ドキュメントの転記 ステップを追加し、Xero接続、環境（接続のPlaidCloud環境のうち、転記に使用するもの）、ヘッダーテーブル、明細テーブル、結果テーブル を設定します。

4. ヘッダーフィールド タブと 明細フィールド タブで、独自の列名をこれらのフィールドにマッピングします。

5. Test Only Mode をオンのままにしてステップを実行します。PlaidCloudは、台帳の要求（ledger claim）を行わず、何も転記せずに、すべてのドキュメントを作成してチェックします。

6. 結果テーブルを確認します（ドキュメント1件につき1行: ref、doc_type、natural_key、xero_id、status、message）。error の行があれば修正して、再度検証します。

7. Test Only Mode をオフにして再度実行し、実際に転記します。最初に失敗したドキュメントでバッチを即座に停止したい場合を除き、Continue posting remaining documents if one document fails はオンのままにしてください。

転記の仕組み

各ドキュメントは、送信される前にPlaidCloudの冪等性台帳で要求（claim）されるため、再実行によって、すでに posted に達したドキュメントが転記されることはありません。台帳のキーにはドキュメントタイプが接頭辞として付くため、同じ ref を持つ請求書と請求は、Xeroが両方を同じエンドポイントで転記する場合でも衝突しません。

タイムアウトやレスポンスの欠落など、結果が不明確な場合、PlaidCloudはスタンプしたドキュメント番号でXeroに問い合わせ直し、ドキュメントが最終的な転記済みステータスにある場合にのみ、一致を証拠として扱います。Xeroの請求書番号とクレジットノート番号は一意であることが保証されていないため、下書き、無効化、または番号が重複して一致したものは、この書き込みの結果として記録されるのではなく、隔離されます。

機能の制限事項: 本番で転記する前にお読みください

注意

• 手動仕訳と支払は検索できません。 手動仕訳の摘要と支払の参照は、Xeroでクエリできないため、不確実な書き込みをPlaidCloudのリクエストに結び付けるためのフィールドがありません。それらは推測されるのではなく、Xeroで直接解決できるように隔離されます。
• 取り消しは、手動仕訳と請求書のみが対象です。 手動仕訳は、借方と貸方を入れ替えた仕訳として取り消され、請求書は、対になるクレジットノートとして取り消されます。請求、支払、クレジットノートには、XeroのAPIに文書化された取り消しのペイロードがないため、PlaidCloudは取り消しを自前で作り出さずに拒否します。それらはXeroで直接修正してください。
• レート制限は組織ごとです。 Xeroは、組織ごとに1分あたり60回、1日あたり5,000回、同時5回の呼び出しを許可します。PlaidCloudは、1分あたりの制限と同時実行の制限を接続ごとに制御し、スロットルされた応答があるとバックオフするため、非常に大きなバッチはそれに比例して時間がかかります。同じ組織に対して多数のXeroステップを一度に実行するのではなく、広範囲の取得はスケジュールしてください。

関連情報

• Xero RESTコネクタ — フィールドリファレンス。
• Xero: エンティティのインポート
• Xero: ドキュメントの転記
• ERP転記履歴を確認する — Xeroへのすべての転記試行と、その最新の状態を記録した常設の履歴。
• 接続の作成と管理