APIファースト!10分で分かるPlace Order REST API

みなさん、こんにちは。 Spring '14 から正式リリースされた注文機能、活用していますか?

従来の商談や契約に加えて、受注情報を管理することができる注文機能が利用できるようになりました。 既存の商品や価格表をそのまま活用できますので、販売管理業務での Salesforce 活用に関心のある方は要チェックです。従来の組織は[設定] から、[カスタマイズ] > [注文] > [設定] で [注文を有効化] で利用可能になります。 新組織では自動的に有効化されているようです。

ところで、Salesforce1 プラットフォームの重要なキーワードにAPI ファーストがありました。 Spring '14 では、注文機能が正式リリースされるのと同時に、注文や契約に特化した API である Place Order REST API もリリースされました。まさに API ファーストですね!

Place Order REST API を利用すれば、 従来の ERP や販売管理システム等と Salesforce の契約機能や注文機能を容易に連携・統合することができるようになります。 今回はこの Place Order REST API の機能やクセなどをご紹介し、実際に利用する際の参考にして頂ければと思います。

契約・注文のオブジェクト構成

Place Order REST API をご紹介する前に、契約機能や注文機能のオブジェクト構成をチェックしてみましょう。 ContractOrder_ER

注文は商談や見積と同様に、注文商品という商品や価格、数量を指定する明細オブジェクトとセットになっています。

商談と見積は商談商品と見積品目名を同期させる機能がありますが、注文には同様の機能はありません。 従って、実際の運用では商談商品や見積品目名と、注文商品との整合性には気を付ける必要がありますね。 (Summer '14 ではパイロットプログラムとして、商談または見積から注文を生成することができます!今後は正式にリリースされるかもしれません)

また、契約・注文は商談や見積とは参照関係がありませんので、要件によっては参照項目を追加する必要がありそうです。

少々話が逸れました。 Place Order REST API では、緑枠内のうちオレンジで表記したマスタ類を参照しながら、青で表記した各オブジェクトの生成や抽出を行います。

Place Order REST API

Place Order REST API についての公式情報は英語版のみですが、Developer Guide が公開されています。仕様の詳細についてはこちらをご覧さい。

ここでは、逆引きで Place Order REST API の各リソースをご紹介したいと思います。 なお、実際に試してみる場合には、以前に讃岐の記事でもご紹介した Apigee Salesforce Console が大変便利です。 また、リクエストBody のJSON 編集には JSON Editor Online が使いやすいのでオススメです。


取引先に契約と注文と、関連するカスタムオブジェクトもまとめて一括で作りたい

リソース:/services/data/{API バージョン}/commerce/sale HTTP メソッド:POST

API バージョンは v30.0 以降である必要があります。 (以降の全リソース共通) このリソースでは、取引先に関連する契約、注文を同時に作成するのみならず、作成した契約および注文に関連するカスタムオブジェクトも同時に作成することができます。

また、契約と契約に関連するカスタムオブジェクトは1回のリクエストで1つのみ作成可能ですが、注文とその関連カスタムオブジェクトは1回のリクエストに複数含めることができます。 リクエストBody に取引先、契約、注文、各関連オブジェクトの情報をセットして送信しましょう。


契約は使わずに、取引先に注文を一括で作りたい

リソース:/services/data/{API バージョン}/commerce/sale/order HTTP メソッド:POST

このリソースでは、取引先に関連する注文と、その注文に関連するカスタムオブジェクトを同時に作成することができます。 注文と関連カスタムオブジェクトは1回のリクエストに複数含めることができます。 リクエストBody に注文、関連オブジェクトの情報をセットして送信しましょう。

なお、Salesforce 画面で注文を作成する場合、契約が必須項目であるため、このような取引先のみを指定した注文はできないのではないかと思ってしまいますが、そんなことはありません。ページレイアウト上で必須に設定されているだけですので、ページレイアウトで必須を解除すれば同様の注文が作成可能です。


既存の契約に注文を作りたい

リソース:/services/data/{API バージョン}/commerce/sale/{契約ID} HTTP メソッド:PATCH

このリソースでは、指定した契約に対して、複数の注文と注文に関連するカスタムオブジェクトを作成することができます。 リクエストBody に注文、関連オブジェクトの情報をセットして送信しましょう。 なお、前述の Apigee Salesforce Consoleは PATCH メソッドには残念ながら現時点では対応していません。Salesforce Labs 製のREST Explorer も対応していません。 PATCH メソッドは2010年に RFC 5789 で定められた、部分更新のための新しいメソッドなので、まだ対応できていないんでしょうね。


既存の注文に注文商品を追加したい

リソース:/services/data/{API バージョン}/services/data/v30.0/commerce/sale/order/{注文ID} HTTP メソッド:PATCH

このリソースでは、指定した注文に対して、複数の注文商品と、注文および注文商品に関連するカスタムオブジェクトを作成することができます。 リクエストBody に注文商品、各関連オブジェクトの情報をセットして送信しましょう。 なお、Developer Guide ではメソッドが POST と記載されている部分がありますが、このリソースは GET/PATCH/HEAD メソッドのみ利用可能ですので、ご注意ください。


契約、注文、注文商品や関連するカスタムオブジェクトを一括で取得したい

リソース:/services/data/{API バージョン}/commerce/sale/{契約ID} HTTP メソッド:GET

先ほどと同じリソースで、HTTP メソッドが違いますね。 このリソースでは、指定した契約と関連する注文、注文商品、契約および注文に関連するカスタムオブジェクトをまとめて一括で取得できます。 また、契約や注文、注文商品の抽出条件を指定して、絞込みを行うこともできます。 契約の抽出条件(contract.xxx=yyyy)、注文の抽出条件(contract.Orders.xxx=yyyy)、注文商品の抽出条件(contract.Orders.OrderItems.xxx=yyyy)を GET パラメータに含めることで、絞込が可能です。

【例】 services/data/v30.0/commerce/sale/800100000005yJI?contract.Status='Activated'&contract.Orders.EffectiveDate=2014-05-11&contract.Orders.OrderItems.UnitPrice=1800

抽出条件には色々と気を付けるべき点があります。

  • ・ 関連名(上記の Orders や Orders.OrderItems )は大文字小文字を区別する。これを間違えた場合、エラーになるのではなく、その抽出条件は解除される
  • ・ 抽出条件に不等号は利用できない
  • ・ 抽出条件にORは指定できない

特に1点目は気付かないことがあるので、要注意です。 正直に告白しますと、この記事を書いている際に、結構ハマりました・・・。


注文、注文商品や関連するカスタムオブジェクトを一括で取得したい

リソース:/services/data/{API バージョン}/commerce/sale/order/{注文ID} HTTP メソッド:GET

これも前述のリソースで、HTTP メソッドが違いますね。 このリソースでは、指定した注文と、注文商品、注文および注文商品に関連するカスタムオブジェクトをまとめて一括で取得できます。 抽出条件による絞込みはさきほどと同様に、注文の抽出条件(order.xxx=yyyy)、注文商品の抽出条件(order.OrderItems.xxx=yyyy)を GET パラメータに含めることで、絞込が可能です。

最後に

いかがでしたでしょうか。 汎用的な OAuth2 と REST さえ使えれば SalesCloud の最新機能が API から利用できるため、モバイルや既存システムとの連携など、用途はますます広がりますね。 見積や注文のみならず、その先の在庫管理や出荷・請求管理、購買管理機能など、もっと Salesforce を使い倒したい場合には、このような製品もありますので、是非ご検討ください!