名刺交換を始める（スキャン）

POST/card-exchanges

相手のマイ QR コード（`https://4s.link/{slug}?ref=code&token=...`）の token を送り、名刺交換を始めます。相手のプロフィールの要約を返すので、「交換を申し込む」画面に表示してください。token は QR をその場で読んだ証拠なので、slug だけでは交換を始められません。交換中のデータは 1 ユーザーにつき常に最新の 1 件だけで、それまで交換中だった交換は消えます。コミュニティの名刺の QR コード（`https://4s.link/communities/{communityId}?ref=code&token=...`。token はその名刺を出している管理者のもの）を読んだときは、パスのコミュニティ ID を targetCommunityId に入れて送ります。自分が管理者のコミュニティとして申し込むときは asCommunityId を送ります。

認証	要ログイン

リクエストボディ

tokenstring必須

マイ QR コード（またはコミュニティの名刺の QR コード）の URL の token クエリ。

targetCommunityIdstring | null任意

コミュニティの名刺の QR コードを読んだときの、そのコミュニティの ID。token の持ち主が、そのコミュニティの管理者として交換します。

asCommunityIdstring | null任意

自分がコミュニティとして申し込むときの、そのコミュニティの ID。承認済みの管理者（ADMIN）であること。

補足

token が無効・相手が退会済みなら 404（errorCode 40201）、自分の QR コードなら 400（errorCode 40202）を返します。

targetCommunityId を指定したのに、token の持ち主がそのコミュニティの管理者でない（またはコミュニティが削除済み）なら 404（errorCode 40201）。asCommunityId のコミュニティの管理者でなければ 403（errorCode 40208）。コミュニティどうしは交換できないので、両方を指定すると 400（errorCode 40209）です。

相手がコミュニティのときは counterpartCommunity にその要約が入り、counterpart は交換を担当する管理者になります。自分の番では defaultSubscribeNewsletter（「メルマガを受け取る」の初期値）も返します。自分がコミュニティとして申し込むときは myCommunity が入り、defaultShareEmail は返しません。

スキャンした交換は 10 分で期限切れになります。

レスポンス

CardExchange を返します。

リクエスト

curl https://api.4s.link/card-exchanges \
  -X POST \
  -H "Authorization: Bearer 4s_at_..." \
  -H "Content-Type: application/json" \
  -d '{
  "token": "Qm9vZ2xlLWNoZWNraW4tdG9rZW4..."
}'

レスポンス例

{
  "id": "6f1c2d3e-...",
  "status": "SCANNED",
  "role": "REQUESTER",
  "counterpart": {
    "id": "u-taro",
    "slug": "taro",
    "firstName": "Taro",
    "lastName": "Yamada",
    "nativeName": "山田 太郎",
    "avatarUrl": "https://...",
    "title": "代表取締役",
    "bio": "企業の新規事業を支えるサービスを開発しています。",
    "cardDesign": "gradient-01-cobalt-mint",
    "cardPhoto": null,
    "organization": {
      "id": "org-1",
      "name": "株式会社HORIZON",
      "slug": "horizon",
      "logoUrl": null,
      "title": "ビジネス開発チーム"
    }
  },
  "counterpartCommunity": null,
  "myCommunity": null,
  "expiresAt": "2026-07-10T06:33:00.000Z",
  "createdAt": "2026-07-10T06:29:40.000Z",
  "requestedAt": null,
  "respondedAt": null,
  "myShareEmail": null,
  "defaultShareEmail": true,
  "mySubscribeNewsletter": null,
  "previousExchange": null,
  "result": null
}