DoorDash から注文を受け取る

Marketplace APIs are limited access

弊社のマーケットプレイス統合パイプラインは、現在上限に達しています。加盟店オンボーディング用セルフサービスツール開発する当面の間は、新しいパートナーを受け付けておりません。統合の構築前にDoorDashにお問い合わせいただくには、 マーケットプレイス統合に関するお問い合わせ フォームにご入力ください。

以下の画像では、弊社の注文 API の仕組みに関し、大まかな概要を示しています。

DoorDash から注文を受け取る

DoorDash には、進行中の新しい注文を受けたことを通知する Webhook もあります。この Webhook には、「メニューステータスの更新を受け取る」で説明した Webhook と同じ認証ヘッダーが含まれます。注文を受け取る URL は、メニューの場合と同じでも、別の URL でも構いません。現時点では手動プロセスとなっているため、DoorDash に連絡して URL を設定してください。これらのリクエストには、以下の形式のペイロードが含まれます。

{
  "event": {
    "type": "OrderCreate",
    "status": "NEW"
  },
  "order": "<Order json object>"
}

注文オブジェクトについては、Swagger のドキュメントで詳しい説明を確認できます。また、こちらからサンプルインスタンスをご覧ください。この注文オブジェクトには、「id」フィールドが含まれています。これは、後から PATCH エンドポイントで注文を確定するときに必要になるので、保存しておいてください。新しく受けた注文はすべてステータスが「新着」になります。

注意すべきフィールド

special_instructions（任意）: DoorDash では、お客様が商品ごとに店舗への要望を入力できます。これは加盟店レベルの設定となり、特定の要望の入力をブロックできるようにしたり、指定した長さの上限までであれば特定のご要望を入力できるようにしたりなど、ご希望に合わせて構成できます。

is_tax_remitted_by_doordash: 店舗がマーケットプレイスファシリテーター指定州にある場合は、税金を納める責任が DoorDash に課されます。DoorDash は、DoorDash から納税されたかどうかを示すフラグをその注文に対して送信します。

tax_amount_remitted_by_doordash: 「is_tax_remitted_by_doordash」が「TRUE」の場合、このフィールドで納税額を示します。

estimated_pickup_time: DoorDash の内部アルゴリズムに基づいて推測されたダッシャーの店舗への到着時刻です。これは、準備時間がプロバイダからの注文確認メッセージによって返信されない場合に使用されます（このフィールドの詳細については、このドキュメントの後半をご覧ください）。

delivery_short_code: このフィールドを使用すると、短い一意の配達識別子を共有して、注文の受け取りのためにダッシャー用アプリに提供することができます。

fulfillment_type: このフィールドを見れば、注文がダッシャーによる配達、加盟店による配達（セルフデリバリー）、お客様によるテイクアウトのいずれであるかを確認できます。設定値の詳細は、注文モデルで確認できます。

experience: このフィールドにより、注文が DoorDash、Caviar、ストアフロントのいずれで行われたかを確認できます。設定値の詳細は、注文モデルで確認できます。

merchant_tip_amount: エンドユーザーがスタッフに渡したチップの金額です。

注文の確定

PATCH /api/v1/orders/{id}

注文を受けたら、その注文に対応できるかどうかを DoorDash に知らせる必要があります。注文のid（Webhook から受信したもの）を URL パラメータに含めます。パートナーは、非同期または同期の注文確定方法を使用できます。

同期の注文確定

DoorDash 注文 Webhook コールで注文を確定します。注文成功の場合は 200 が返され、2xx 以外は注文の失敗として扱われます。レスポンスペイロードは、非同期の注文確定ペイロードと同じです。現在のところ、1 分を超過すると HTTP がタイムアウトしますが、呼び出しが定期的に 20 秒を超過することが予想される場合は、同期確定は使わず非同期で確定するようお願いいたします。

非同期の注文確定

注文を受注したものの後でステータスを更新したい場合は、ステータスコード 202 を使ってその旨を示します。その後、注文確定のエンドポイントを使用して注文のステータスが「成功」となっていることを確認してください。「失敗」の場合は理由を確認してください。3 ～ 8 分以内に注文を確定しない場合、DoorDash はその注文を注文確定のタイムアウトによる失敗として扱います。この 3 ～ 8 分の SLA は、注文が作成された時間から、スケジューラーが DoorDash 側で実行されてその注文を古いものとしてマークした時間まで、そのタイミングに基づき注文ごとに異なります。注文のキャンセル率が高くならないようにするためにも、システムがこの 3 ～ 8 分の SLA を満たしていることを確認してください。

非同期の注文確定の場合、DD からは以下のレスポンスが返されます。

ステータスコード	レスポンスメッセージ	説明
202	OK	注文の確定が承認されました
400		リクエスト形式が正しくないか、注文がすでに確定されていたか、注文確定がタイムアウトしました
404	指定された ID のオーダーが存在しません	DD において指定された注文 ID の注文記録が見つかりません
500	加盟店によるオーダー確定の処理中にエラーが発生しました	内部サーバーエラー

注意すべきフィールド

prep_time（任意）: ドライバーの受け取り時刻は、デフォルトでは DoorDash の内部アルゴリズムによって決定され、「estimate_pickup_time」で送信されます。さらに、注文確定ペイロード内に日時オブジェクトの「prep_time」パラメータがあります。これは、DoorDash の内部アルゴリズムへの入力としての「prep_time」を決定するのに使用できます。このフィールドは省略可能です。異なる準備時間を指示するロジックが別途ある場合にのみ使用してください。このフィールドで DoorDash の「Estimate_pickup_time」をそのまま送り返すことはしないでください。これは DoorDash 準備時間ロジックのダウンストリームなので、過剰な準備時間が予測されることになります。

注意: 時刻は UTC で入力する必要があります。

注意: DoorDash のダッシャー割り当てロジックでは、スケジュール済みの注文に対して準備時間が使用されません。配達予定時間範囲が開始する 10 分前に注文された商品を受け取ることが常に目標とされます。

オプション 1: DoorDash モデルの準備時間を使用する（推奨）

ペイロードは、以下の形式になっている必要があります。詳細は、「注文エンドポイント」セクションをご覧ください。

{
  "merchant_supplied_id": merchant provided order id,
  "order_status": "success" or "fail",
  "failure_reason": string detailing reason for failure
}

オプション 2: プロバイダ/加盟店が計算した準備時間を使用する

プロバイダまたは加盟店が準備時間を指示する別のロジックがある場合は、各自で計算した準備時間を含む以下のペイロードを渡すことができます。

{
  "merchant_supplied_id": merchant provided order id,
  "order_status": "success" or "fail",
  "prep_time": a datetime object with the time you expect the order to be prepared by in UTC,
  "failure_reason": string detailing reason for failure
}

自動注文リリース（AOR）

自動注文リリース（AOR）は加盟店が料理の質を高め、ダッシャーの待ち時間を減らすために利用できる DoorDash の機能です。この機能は、ダッシャーがレストランから指定された距離（500 メートルなど）に達するまで、注文をステージング段階に保留することによって実現されます。ダッシャーがこの範囲内に達すると、料理の準備に向けて DoorDash から POS システムへリリースイベントが送信されます。自動注文リリースでは、料理の受け取り準備完了に対するダッシャー到着のタイミングがより正確に把握できるので、特にクイックサービスのレストランにとって有益な機能です。

ダッシャーが店舗の近くに来ると、加盟店が提供した設定済みエンドポイントに対して新しいコールがトリガーされます。加盟店は、注文を確定するときに自社内での注文 ID を「merchant_supplied_id」フィールドに入力して提供することができます。DoorDash は、この値を「client_order_id」として保存します。これは、リリースペイロードの一部として送信されます。これには、カーブサイドデリバリーをサポートする加盟店の引き渡しがより簡単にサポートされるよう、ダッシャーの車両情報も含まれます。「参照」にサンプルがあります。

注文イベントの更新

現在、DoorDash は料理の受け取り準備がいつ完了したかが分からないため、この情報をダッシャーに提供することができません。その結果、注文商品の受け取りを待っているダッシャー全員が次は自分の番であることを期待して加盟店の外に群がることになるため、ダッシャーにとっても加盟店にとってもストレスの多い受け取りのエクスペリエンスとなります。

この問題を修正するために、加盟店がイベントを共有できる機能を導入しました 。加盟店は、注文の受け渡しの準備ができたら、ダッシャーに情報を送れるように DoorDash に知らせることができます。加盟店は、注文の「id」（注文作成 Webhook から受け取ったもの）を URL パラメータに入力します。詳細は、注文エンドポイントの「パッチ注文イベント」セクションをご覧ください。

注文の失敗と望ましい失敗の理由

注文に失敗した場合は、「failure_reason」パラメータを含めることが重要です。これは、障害を追跡し、システム問題のトラブルシューティングを行ううえで不可欠です。以下は、「failure_reason」エラーの詳細と、DoorDash が各エラーを受け取る可能性のある状況についての説明です。注文失敗の具体的な原因に関連するカスタムされた failure_reason を御社からご提供いただくことも可能です。返される failure_reason が、以下の例の failure_reason のいずれかに該当する必要はありません。

失敗の理由	説明
加盟店を利用できません - 接続に関する問題	加盟店に POS 接続/ネットワークの問題（一時的）が発生したときに注文が受信された。
加盟店を利用できません - 営業時間が一致しない	加盟店の休業中に注文を受け取った（営業時間が間違っている）。
加盟店を利用できません - 休業中またはリモデル中	加盟店の休業中に注文を受け取った（店舗閉鎖、改装など永続的な休業）。
商品を利用できません - [商品名] - [商品 ID] - 在庫切れ	注文内の商品または商品オプションが削除された場合。エラーの原因となった商品を指定する。
商品を利用できません - [商品名] - [商品 ID] - この店舗では販売されていない	注文された商品または商品オプションがその加盟店では販売されていないか、メニューに記載されるべきではない。エラーの原因となった商品を指定する。
オーダーでのビジネスの検証に失敗	MX 側のビジネス上の規則が原因で注文が失敗した（必須オプションがマークされていない、最大数を超過している、配達先住所の問題など）。各ビジネスの検証ごとに個別に失敗を指定することが望まれます。
タイムアウトエラー - 504	接続の問題によるゲートウェイタイムアウト（504 エラー）
不正なゲートウェイ - 502	無効な応答を受信した（502 エラー）
その他 - 500	その他の問題（500 エラー）

失敗の理由が「在庫切れ」の場合は、注文失敗の原因となった商品/代替品の名前と一緒に、商品または代替品のmerchant_supplied_idを含めることを推奨しています。 これにより、DoorDash 内部システムが問題を解決するための自動修正アクションを実行して、その加盟店で以降に同じ注文の失敗が発生するのを防ぐことができます。

注文確定後の更新

すでに受け入れた注文を加盟店がキャンセルすることを可能にする新機能が OpenAPI に追加されました。POS 統合の加盟店の多くは、注文が一連の検証に合格すれば注文を自動的に受け付けるように設定されています。まれに、最初は注文が自動的に確定されても、その後さまざまな理由でキャンセルが必要になる場合があります。この場合、加盟店は DoorDash サポートに電話してキャンセルを開始する必要がありますが、これはどちらにとっても時間のかかるプロセスです。この機能によって、加盟店が POS 統合を通じて注文レベルのキャンセルを開始できるようになります。