APIリファレンス取引先

取引先

運営会社の取引先を登録・参照・更新する

エンドポイント

GET/v1/clients
POST/v1/clients
GET/v1/clients/{id}
PATCH/v1/clients/{id}

GET/v1/clients

取引先の一覧・検索

この事業の取引先だけを返します。統合済みの記録は一覧から除きます。連絡先・住所・振込先メモ・内部メモを含むため、権限を持つサーバーで扱ってください。メール送信や招待は行いません。

権限 clients:readnextCursor で続き

クエリ

externalRefstring
200文字まで
emailstring (email)
320文字まで
statusenum
activeinactivepending
querystring
160文字まで
cursorstring
100文字まで
limitinteger
1〜100

返る項目data の中身 · 200

namestring
companyNamestring | null
contactPersonstring | null
departmentstring | null
postalCodestring | null
addressstring | null
buildingNamestring | null
phoneNumberstring | null
emailstring | null
bankAccountstring | null
commentstring | null
statusenum
activeinactivepending
idstring
externalRefstring | null
mergedIntoClientIdstring | null
mergedAtstring | null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

400invalid_request
送った値が正しくない。message にどこが違うかが入ります
403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります

GET/v1/clients

curl https://tooon.app/api/v1/clients \
  -H "Authorization: Bearer $TOOON_API_KEY"

レスポンス

{
  "data": [
    {
      "name": "山田 太郎",
      "companyName": "山田デザイン事務所",
      "contactPerson": "…",
      "department": "…",
      "postalCode": "…",
      "address": "東京都渋谷区神南1-2-3",
      "buildingName": "…",
      "phoneNumber": "090-1234-5678",
      "email": "…",
      "bankAccount": "○○銀行 渋谷支店 普通 1234567",
      "comment": "…",
      "status": "active",
      "id": "clx8k2m0a0001",
      "externalRef": "staff-0001",
      "mergedIntoClientId": "clx8k2m0a0001",
      "mergedAt": "2026-11-01T09:00:00.000Z",
      "createdAt": "2026-11-01T09:00:00.000Z",
      "updatedAt": "2026-11-01T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/v1/clients

取引先を登録する

名前だけで登録できます。externalRefを指定すると事業内で一意になり、同じ内容の再送は既存の取引先を返します。異なる内容や統合済みは409 external_ref_conflictです。externalRefを省略する場合も再試行には同じIdempotency-Keyを使ってください。ログインユーザー・招待・メール・決済顧客は作りません。

権限 clients:writeIdempotency-Key

送る項目JSON · 13項目

namestring必須
160文字まで
companyNamestring | null
160文字まで
contactPersonstring | null
160文字まで
departmentstring | null
160文字まで
postalCodestring | null
30文字まで
addressstring | null
500文字まで
buildingNamestring | null
160文字まで
phoneNumberstring | null
80文字まで
emailstring (email) | null
320文字まで
bankAccountstring | null
1,000文字まで
commentstring | null
5,000文字まで
statusenum
activeinactivepending
externalRefstring
200文字まで

返る項目data の中身 · 200

namestring
companyNamestring | null
contactPersonstring | null
departmentstring | null
postalCodestring | null
addressstring | null
buildingNamestring | null
phoneNumberstring | null
emailstring | null
bankAccountstring | null
commentstring | null
statusenum
activeinactivepending
idstring
externalRefstring | null
mergedIntoClientIdstring | null
mergedAtstring | null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

400invalid_request
送った値が正しくない。message にどこが違うかが入ります
403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります
409external_ref_conflict
異なる内容や統合済みのとき

POST/v1/clients

curl -X POST https://tooon.app/api/v1/clients \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "山田 太郎",
  "externalRef": "staff-0001"
}'

レスポンス

{
  "data": {
    "name": "山田 太郎",
    "companyName": "山田デザイン事務所",
    "contactPerson": "…",
    "department": "…",
    "postalCode": "…",
    "address": "東京都渋谷区神南1-2-3",
    "buildingName": "…",
    "phoneNumber": "090-1234-5678",
    "email": "…",
    "bankAccount": "○○銀行 渋谷支店 普通 1234567",
    "comment": "…",
    "status": "active",
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "mergedIntoClientId": "clx8k2m0a0001",
    "mergedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

GET/v1/clients/{id}

取引先の詳細を取得する

権限 clients:read

パスの値

idstring必須
100文字まで

返る項目data の中身 · 200

namestring
companyNamestring | null
contactPersonstring | null
departmentstring | null
postalCodestring | null
addressstring | null
buildingNamestring | null
phoneNumberstring | null
emailstring | null
bankAccountstring | null
commentstring | null
statusenum
activeinactivepending
idstring
externalRefstring | null
mergedIntoClientIdstring | null
mergedAtstring | null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります
404not_found
対象がない、またはこのワークスペースのものではない

GET/v1/clients/{id}

curl https://tooon.app/api/v1/clients/clx8k2m0a0001 \
  -H "Authorization: Bearer $TOOON_API_KEY"

レスポンス

{
  "data": {
    "name": "山田 太郎",
    "companyName": "山田デザイン事務所",
    "contactPerson": "…",
    "department": "…",
    "postalCode": "…",
    "address": "東京都渋谷区神南1-2-3",
    "buildingName": "…",
    "phoneNumber": "090-1234-5678",
    "email": "…",
    "bankAccount": "○○銀行 渋谷支店 普通 1234567",
    "comment": "…",
    "status": "active",
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "mergedIntoClientId": "clx8k2m0a0001",
    "mergedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}

PATCH/v1/clients/{id}

取引先の情報・状態を変更する

expectedUpdatedAtに直前のupdatedAtを指定します。古い値は409 version_conflict、統合済みは409 invalid_statusです。省略した項目は保持し、nullで任意項目を消せます。externalRef・所有者・ログインユーザーは変更できません。inactiveへの変更はデータを削除しません。

権限 clients:writeIdempotency-Key

パスの値

idstring必須
100文字まで

送る項目JSON · 13項目

namestring
160文字まで
companyNamestring | null
160文字まで
contactPersonstring | null
160文字まで
departmentstring | null
160文字まで
postalCodestring | null
30文字まで
addressstring | null
500文字まで
buildingNamestring | null
160文字まで
phoneNumberstring | null
80文字まで
emailstring (email) | null
320文字まで
bankAccountstring | null
1,000文字まで
commentstring | null
5,000文字まで
statusenum
activeinactivepending
expectedUpdatedAtstring (date-time)必須
直前のGETで取得したupdatedAt。Tooon画面からの変更も競合として検出します

返る項目data の中身 · 200

namestring
companyNamestring | null
contactPersonstring | null
departmentstring | null
postalCodestring | null
addressstring | null
buildingNamestring | null
phoneNumberstring | null
emailstring | null
bankAccountstring | null
commentstring | null
statusenum
activeinactivepending
idstring
externalRefstring | null
mergedIntoClientIdstring | null
mergedAtstring | null
createdAtstring
updatedAtstring

起こりうるエラー共通のエラー

400invalid_request
送った値が正しくない。message にどこが違うかが入ります
403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります
404not_found
対象がない、またはこのワークスペースのものではない
409version_conflict
古い値
409invalid_status
今の状態ではその操作ができない（送付済みの依頼を直そうとした、など）

PATCH/v1/clients/{id}

curl -X PATCH https://tooon.app/api/v1/clients/clx8k2m0a0001 \
  -H "Authorization: Bearer $TOOON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "山田 太郎",
  "expectedUpdatedAt": "2026-11-01T09:00:00.000Z"
}'

レスポンス

{
  "data": {
    "name": "山田 太郎",
    "companyName": "山田デザイン事務所",
    "contactPerson": "…",
    "department": "…",
    "postalCode": "…",
    "address": "東京都渋谷区神南1-2-3",
    "buildingName": "…",
    "phoneNumber": "090-1234-5678",
    "email": "…",
    "bankAccount": "○○銀行 渋谷支店 普通 1234567",
    "comment": "…",
    "status": "active",
    "id": "clx8k2m0a0001",
    "externalRef": "staff-0001",
    "mergedIntoClientId": "clx8k2m0a0001",
    "mergedAt": "2026-11-01T09:00:00.000Z",
    "createdAt": "2026-11-01T09:00:00.000Z",
    "updatedAt": "2026-11-01T09:00:00.000Z"
  }
}