オーダー作成

External API でオーダー (DM 送付依頼) を作成する手順です。

前提

orders:write を含む access_token を取得済み (クイックスタート参照)。本ページの手順 (チーム一覧・タッチ一覧・コンタクト検索・コメント追加) を全て行うには scope=read teams:read contacts:read touches:read orders:write comments:write を指定
Current-Team: <team_uuid> ヘッダを把握済み (GET /api/v1/external/teams/ で取得)
送付するタッチ (商品) の touch_id を取得済み (GET /api/v1/external/touches/ で一覧)

コンタクト埋め込み方式

オーダー作成 API は コンタクト情報をリクエスト内に直接埋め込む 方式です。埋め込んだ内容で新しいコンタクトが作成されます。既存コンタクトを使う場合は contact.id を指定します。

最小リクエスト

curl -X POST https://api.sendwow.jp/api/v1/external/orders/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Current-Team: <team_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "last_name": "山田",
      "first_name": "太郎",
      "shipping_addresses": [{
        "postcode": "1000001",
        "pref": "東京都",
        "city": "千代田区",
        "street1": "丸の内1-1-1"
      }],
      "account": {"name": "株式会社サンプル"}
    },
    "touch_ids": ["<touch-uuid>"],
    "shipping_date": "2026-05-01"
  }'

既存コンタクトの指定

SendWOW 上の既存コンタクトを使う場合は contact.id (コンタクト UUID) を指定します。この場合、送付先にはそのコンタクトの既定の送付先住所 (primary shipping address) が使われます。

{
  "contact": {"id": "<contact-uuid>"},
  ...
}

id を指定しない場合は、埋め込んだ内容で常に新しいコンタクトが作成されます (氏名・メールアドレスが既存コンタクトと同じでも自動では紐付きません)。既存コンタクトへの重複登録を避けたい場合は、GET /api/v1/external/contacts/ で検索して contact.id を指定してください。

詳細仕様は API リファレンスを参照してください。

配送日の制約

shipping_date に必要なリードタイムは通常商品で 5 営業日、スピードDM 商品で 3 営業日です。最短配送可能日は以下で取得できます (touch_id クエリを付けるとその商品のリードタイムで計算されます。未指定時は通常商品の 5 営業日基準)。

curl "https://api.sendwow.jp/api/v1/external/orders/delivery_date/?touch_id=<touch-uuid>" \
  -H "Authorization: Bearer <access_token>" \
  -H "Current-Team: <team_uuid>"

営業日カレンダーは /api/v1/external/orders/holidays/ で取得できます。

オーダー状態の確認

curl https://api.sendwow.jp/api/v1/external/orders/<order_id>/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Current-Team: <team_uuid>"

レスポンスの status フィールドが現在のステータスを示します:

status	意味
0	オーダー済み
3	送付準備中
5	送付手続き中
6	発送済み
7	到着済み
その他	詳細は API リファレンスを参照

オーダーにコメントを追加

社内連携用のメモ等を残す場合:

curl -X POST https://api.sendwow.jp/api/v1/external/orders/<order_id>/comments/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Current-Team: <team_uuid>" \
  -H "Content-Type: application/json" \
  -d '{"text": "発注元: 営業 山田"}'

コメント追加には comments:write scope が必要です (orders:write には含まれません)。

よくあるエラー

エラー	原因
`400 delivery_date_invalid`	`shipping_date` が最短配送可能日より前
`403 Forbidden`	トークンに `orders:write` (コメント追加なら `comments:write`) が含まれていない、または `Current-Team` のチームのメンバーでない
`400 invalid` (`contact.shipping_addresses`)	必須フィールド (postcode / pref / city / street1) 漏れ

詳細はトラブルシューティングを参照してください。