クイックスタート

エンジニア向けに、クライアント登録から最初のリクエスト送信までを最短で解説します。

全体フロー

1. (一度だけ) DCR でクライアント登録      → client_id / client_secret 入手
2. ユーザーをブラウザで authorize へ誘導 → authorization code
3. token endpoint でコード交換           → access_token / refresh_token
4. Authorization: Bearer で External API を呼び出し
5. 期限切れたら refresh_token で更新

詳細は認証ガイド (OAuth 2.0 + DCR) を参照してください。

1. クライアント登録 (DCR)

curl -X POST https://api.sendwow.jp/api/v1/oauth/register/ \
  -H 'Content-Type: application/json' \
  -d '{
    "redirect_uris": ["https://your-app.example.com/oauth/callback"],
    "token_endpoint_auth_method": "client_secret_post",
    "scope": "read teams:read orders:read orders:write",
    "client_name": "Acme Integration"
  }'

レスポンスの client_id / client_secret を永続保存してください。

scope は必要な操作に合わせて選びます (上の例はチーム一覧・オーダー参照・オーダー作成)。一覧は認証ガイドの scope 一覧を参照してください。

2. 認可コード取得 (PKCE 必須)

import base64, hashlib, secrets

verifier = secrets.token_urlsafe(64)
challenge = base64.urlsafe_b64encode(
    hashlib.sha256(verifier.encode("utf-8")).digest()
).decode("ascii").rstrip("=")

ユーザーをブラウザで誘導:

https://api.sendwow.jp/api/v1/oauth/authorize/
  ?client_id=<client_id>
  &redirect_uri=https://your-app.example.com/oauth/callback
  &response_type=code
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &scope=read teams:read orders:read orders:write
  &state=<csrf-state>

3. トークン取得

curl -X POST https://api.sendwow.jp/api/v1/oauth/token/ \
  -d grant_type=authorization_code \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d code=<authorization_code> \
  -d redirect_uri=https://your-app.example.com/oauth/callback \
  -d code_verifier=<verifier>

4. API 呼び出し

まず利用可能なチーム一覧を取得します (Current-Team ヘッダ不要):

curl https://api.sendwow.jp/api/v1/external/teams/ \
  -H "Authorization: Bearer <access_token>"

teams/ 以外のエンドポイント (orders / contacts / touches / products / order_campaigns 系) は Current-Team: <team_uuid> ヘッダが必須です。上で取得したチーム ID を渡します:

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

エンドポイント一覧と詳細仕様は External API リファレンスをご参照ください。

Python サンプル

from requests_oauthlib import OAuth2Session

base = "https://api.sendwow.jp"
client_id = "..."
client_secret = "..."
redirect_uri = "https://your-app.example.com/oauth/callback"

session = OAuth2Session(
    client_id,
    redirect_uri=redirect_uri,
    scope=["read", "teams:read", "orders:read", "orders:write"],
    pkce="S256",
)
auth_url, state = session.authorization_url(f"{base}/api/v1/oauth/authorize/")
print("Open in browser:", auth_url)

callback_url = input("Paste full callback URL: ")
token = session.fetch_token(
    f"{base}/api/v1/oauth/token/",
    authorization_response=callback_url,
    client_secret=client_secret,
)

teams = session.get(f"{base}/api/v1/external/teams/").json()
team_id = teams["results"][0]["id"]

r = session.get(
    f"{base}/api/v1/external/orders/",
    headers={"Current-Team": team_id},
)
print(r.json())

困ったら

401 / 403 / invalid_grant: トラブルシューティングを参照
操作ごとに必要な scope: 認証ガイドを参照
お問い合わせ: support@sendwow.jp