Camel Public API

Camel Public APIはCamelで統合されたデリバリーサービスの注文や店舗、メニューなどの情報を連携出来るようにするためのAPIです。

Camelから情報を取得するパターンとCamelへ情報を登録するパターンの2つがあり、連携開始までのフロー概要は下記のようになります。

<Camelから情報を取得するパターン>

1. NDA締結後、招待用のメールアドレスを確認させていただき弊社側で以下3つの対応をさせていただきます。

• Slackチャンネルへのご招待
• API質問ページへのご招待
  • APIに関するご質問等はNotionにて承ります。ご担当者様のメールアドレス宛に下記リンクの招待をお送りいたしますのでご確認ください。
  • https://www.notion.so/tacoms/Camel-PublicAPI-5a3b0b6000c94a23a871c10d86af1e69
• 検証環境用「client_id」と「client_secret」のご共有
  • 2つの情報を使用するとAPIアクセスに必要なトークンを発行できます。詳しくはAuthorizationのセクションをご確認ください。

2. 弊社側でテスト店舗を作成いたします。（webhook用URLをご提供ください）
3. パートナー企業様で開発

• こちらを確認しテストを進めてください。

4. 開発完了後、本番開始のタイミングで本番環境用の「client_id」と「client_secret」をご共有いたします。
5. 本番環境用のwebhook用URLをご共有ください。
6. 店舗連携の作業を行っていただき本番店舗で運用開始。

<Camelへ情報を登録するパターン>

1. NDA締結後、招待用のメールアドレスを確認させていただき弊社側で以下3つの対応をさせていただきます。

• Slackチャンネルへのご招待
• API質問ページへのご招待
  • APIに関するご質問等はNotionにて承ります。ご担当者様のメールアドレス宛に下記リンクの招待をお送りいたしますのでご確認ください。
  • https://www.notion.so/tacoms/Camel-PublicAPI-5a3b0b6000c94a23a871c10d86af1e69
• 検証環境用「client_id」と「client_secret」のご共有
  • 2つの情報を使用するとAPIアクセスに必要なトークンを発行できます。詳しくはAuthorizationのセクションをご確認ください。

2. Camelに表示するための情報として以下の情報をご提供ください。（ロゴ以外はオプションです）

• テスト環境における店舗ID
• サービスロゴ画像
• サービスヘルプへのリンク
• サービスのコールセンター電話番号

3. 弊社側でテスト店舗を作成いたします。（webhookをご利用予定の場合は、webhook用URLをご提供ください）
4. パートナー企業様で開発
5. 開発完了後、本番開始のタイミングで本番環境用の「client_id」と「client_secret」をご共有いたします。
6. 本番環境用のwebhook用URLをご共有ください。
7. 店舗連携の作業を行っていただき本番店舗で運用開始

※webhookURLについてはPRD環境と同一でも異なるものでも構いません。

1. 弊社からテストアカウントを発行いたします。テストアカウントにおけるメニューコードの設定が必要な場合は別途お申し付けください
2. 弊社のテスト注文機能等を使用しながらWebhookやその他APIのテストを行ってください

※テスト注文機能利用方法

1. 注文一覧画面、左のスライドバーからテスト注文機能を選択します
2. テスト注文画面にてデリバリーサービスを選択してください
3. 商品を選択したい場合、右のチェックボックスを選択してください
4. メニューが登録されている場合メニューが一覧表示されます
5. 商品右のチェックボックスを入れて画面上部の注文ボタンを押してください
6. トップページに戻り注文を確認してください

※尚、上記のテスト注文機能は注文形式や商品パターン等、全てを網羅的にテストすることは出来ません。テスト注文機能で実施できないテストは弊社がサポートいたしますのでご連絡ください。

※全ての処理において、文字コードはUTF-8を使用してください。

<Camelから情報を取得するパターン>

1. 弊社が用意するフォームにて連携店舗の申請をしていただきます。＊この時CAMELログインアカウントの入力をお願いしております。連携事業者様ではなくサービス利用企業様がご入力いただくことが望ましいです。
2. 連携が完了した場合、事前にお渡しするAPI連携企業様向けの連携店舗一覧シートに店舗情報が追記されています。連携する店舗のIDや店舗名を確認してください。
3. API連携企業様システムのWebhook受信準備が整ったタイミングでUpdate Webhook StatusAPIを使用しステータスを「ENABLED」に更新してください。該当店舗のWebhook連携が開始されます。

<Camelへ情報を登録するパターン>

1. 弊社が用意するフォームにて連携店舗の申請をしていただきます。＊この時CAMELログインアカウントの入力をお願いしております。連携事業者様ではなくサービス利用企業様がご入力いただくことが望ましいです。
2. 連携が完了した場合、事前にお渡しするAPI連携企業様向けの連携店舗一覧シートに店舗情報が追記されています。連携する店舗のIDや店舗名を確認してください。
3. （仮）サービス利用企業様が保有するパートナー企業様における店舗IDを確認し、弊社内部で紐付け作業を行います。
4. API連携企業様システムのWebhook受信準備が整ったタイミングでUpdate Webhook StatusAPIを使用しステータスを「ENABLED」に更新してください。該当店舗のWebhook連携が開始されます。

<商品コード連携の流れ>

連携事業者様の商品コードとCAMELで保持する商品IDを統合するためのフローになります。
2022年3月現在、メニューAPIが準備出来ていないためCAMELの管理画面にて連携事業者様の商品コードを入力することで紐付けしていただくフローとなっております。

1. CAMELに店舗を連携させ、各デリバリーサービスのメニューがCAMELに取り込まれていることを確認してください。＊店舗への連携が完了されたタイミングでメニューは取り込まれます
2. 連携開始時に「商品コード設定のパターン」をご教示ください。システム側で設定いたします。（詳しくは後述の商品コード設定時の仕様をご確認ください）
3. CAMELの管理画面、もしくはCSVにて商品一覧を確認しながら「連携事業者様の商品コード」を入力してください
   ex)業態 × デリバリーサービスごとパターンをUIで登録する時のイメージ画面
4. 1が完了していれば、連携する注文データの中に統合された商品コードが含まれております。詳しくはGetOrderDetailsAPIのセクションをご確認ください。

※1 CSV一括登録とUI経由の2つの手段がございます。
※2 こちらの作業を担当いただくのはクライアント企業のご担当者様を想定しておりますが、代行いただいても問題ございません。
※3 商品コード設定のパターンは運用途中で変更できません。どうしても変更が必要な場合は弊社担当者へご連絡ください。
※4 商品IDの統合をしなくても注文連携は可能です。

<商品コード設定時のパターン>

連携事業者様のシステムの仕様や、クライアント企業様の方針等により「商品コードがどの単位で設定されているか」のパターンがいくつかあると認識しております。
CAMELでは標準で下記の4パターンに対応しております。これらのパターンに沿って商品コードをご設定いただけます。

① 業態ごと

• 業態ごとに商品コードが振られている。

• ex) テストブランド1とテストブランド2で販売している緑茶という商品のコードは異なる。ただデリバリーサービスごとには分かれていない。

  商品名	業態名	デリバリーサービス名	商品コード
  緑茶	テストブランド1	UberEats, Wolt	100
  緑茶	テストブランド2	UberEats, Wolt	200

② 業態 × デリバリーサービスごと

• 業態ごと及びデリバリーサービスごとに商品コードが振られている。

• ex) テストブランド1とテストブランド2で販売している緑茶という商品のコードは業態及びデリバリーサービスごとに異なる。

  商品名	業態名	デリバリーサービス名	商品コード
  緑茶	テストブランド1	UberEats	100
  緑茶	テストブランド2	Wolt	300
  緑茶	テストブランド1	UberEats	200
  緑茶	テストブランド2	Wolt	400

③ デリバリーサービスごと

• デリバリーサービスごとに商品コードが振られている。

• ex) UberEatsとWoltで販売している緑茶という商品のコードは異なる。ただ業態ごとには分かれていない。

  商品名	業態名	デリバリーサービス名	商品コード
  緑茶	テストブランド1,テストブランド2	UberEats	100
  緑茶	テストブランド1,テストブランド2	Wolt	200

④ 拠点（店舗）ごと

• 拠点（店舗）ごとに商品コードが振られている。

• ex) 緑茶という商品のコードは拠点ごとに異なる。テストストア渋谷店とテストストア新宿店ではブランド単位で同じ商品でもコードが異なる

  商品名	拠点（店舗）名	デリバリーサービス名	業態名	商品コード
  緑茶	テストストア新宿店	UberEats, Wolt	テストブランド1	100
  緑茶	テストストア渋谷店	UberEats, Wolt	テストブランド1	300

• リクエスト制限表

  エンドポイント	時間あたりリクエスト制限
  /oauth/token	10/10s
  /orders/:order_id	150/10s
  /orders/:order_id/state	150/10s
  /stores	10/10s
  /stores/:store_id	50/10s
  /stores/:store_id/state	50/10s
  /stores/:store_id/webhook-status	50/10s

Camel Public APIではOAuth2.0に対応しています。2022年3月現在、AuthorizationAPIのグラントタイプは「Client Credentials」のみに対応しております。
APIの詳細仕様はAuthorizationAPIのセクションをご確認ください。

＊OAuth2.0 仕様概要
RFC6749 The OAuth 2.0 Authorization Framework（他にもRFCが存在しますがここでは割愛します）

注文のステータスイベントなどを通知するためWebhookとして送信します。
正常にWebhookイベントの受信が完了した場合HTTP 200のステータスコードを返してください。
HTTP 200の応答が確認できない場合、最大6回再送信を試みます。

Webhook Security

Webhookの送信元がtacomsであることを受信元で確認するため、全てのWebhookにはX-Camel-Signatureヘッダーが含まれています。
tacomsではセキュリティの観点からこの署名を検証することを推奨しています。

署名を検証する

1. クライアントシークレットを鍵とし、HMAC-SHA256アルゴリズムでリクエストボディの署名を取得します。
2. 取得した署名とX-Camel-Signatureヘッダーに含まれる値が一致することを確認します。

＊Goでの実装例

    // X-Camel-Signature: 76b95b9a9d50b72c4347784708b4121cdd778d5278f89437b8fb506a386877e4

    clientSecretSample := "y_6e01JuPLO2tu0IavWoNJuOPN-2Nm6FpZsQe21-"
    requestBodySample := `{"event_type": "OrderCreated", "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7", "event_time": 1640962800, "event_data": {"order_id": "f3d34064-k93c-4f33-12f4-0570d7e3e123", "store_id": 100}}`
    
    h := hmac.New(sha256.New, []byte(clientSecretSample))
    io.WriteString(h, requestBodySample)
    fmt.Println(hex.EncodeToString(h.Sum(nil)))
    // 76b95b9a9d50b72c4347784708b4121cdd778d5278f89437b8fb506a386877e4

注文情報に関するAPIです。

Camelから情報を取得するパターンとCamelへ情報を登録するパターンの2つがあり、それぞれ下記のようなフローになります。

<Camelから情報を取得するパターン>

<Camelへ情報を登録するパターン>

Create OrderAPIやCancel OrderAPIで注文情報及びキャンセル情報を連携してください。
Camelでステータス変更がされた時、webhookを発行いたしますのでそちらを受け取ることで連携事業者様側で注文確定処理をすることも可能になります。

店舗連携・webhook受信設定のフローに関しましては、Integration Flowを別途参照してください。