Tooon API
自社のアプリやシステムから、Tooonのパートナー・業務委託契約・請求書作成依頼・メンバー・メンバーカードを読み書きし、会社カードを読み取れます。APIで作ったデータはTooonの画面にも出て、画面から直せます。
/v1/mecurl https://tooon.app/api/v1/me \
-H "Authorization: Bearer $TOOON_API_KEY"{
"data": {
"apiKey": {
"id": "clx8k2m0a0001",
"name": "山田 太郎",
"scopes": [
"connect:members:read"
]
},
"workspace": {
"id": "clx8k2m0a0001",
"name": "山田 太郎"
}
}
}3ステップで始める
- APIキーを発行するSolo以上のプランのワークスペースで、管理者が「設定」→「連携」→「APIキー」から名前と権限を選んで発行します。キーはこのとき一度だけ表示されます。
- キーを確かめる
GET /v1/meを呼んで、ワークスペースと権限が返れば準備できています。 - データを読み書きする下のリファレンスから入口を選びます。APIで作ったデータはTooonの画面にも出ます。
リファレンス
扱えるデータごとに、送る項目・返る項目・例をまとめています。
キーが有効か、どの権限を持つかを確かめる
/v1/me運営会社の合意内容を準備・確認し、連携先で提示する
/v1/agreementsPOST/v1/agreementsGET/v1/agreements/{id}経費の記録・集計・削除・復元と、証憑の情報
/v1/expensesPOST/v1/expensesGET/v1/expenses/deleted支払予定・支払済みの記録と明細を取得する
/v1/settlementsGET/v1/settlements/{id}GET/v1/…/{id}/lines発注先・業務委託先と、その事業者情報
/v1/partnersPOST/v1/partnersGET/v1/partners/{id}パートナーとの契約（Tooonの「発注」）
/v1/partner-ordersGET/v1/partner-orders/{id}PATCH/v1/partner-orders/{id}パートナーに請求書を作ってもらう依頼
/v1/partner-invoice-requestsPOST/v1/partner-invoice-requestsGET/v1/partner-invoice-requests/{id}社員・役員・業務委託のスタッフなど会社の人
/v1/peoplePOST/v1/peopleGET/v1/people/{id}会社の人のメンバーカードと、その公開
/v1/business-cardsPOST/v1/business-cardsGET/v1/business-cards/{id}運営会社の取引先を登録・参照・更新する
/v1/clientsPOST/v1/clientsGET/v1/clients/{id}プロジェクトの作成・内容・日程・状態・親子関係
/v1/projectsPOST/v1/projectsGET/v1/projects/{id}運営会社のタスク・担当・期日・状態・案件接続
/v1/tasksPOST/v1/tasksGET/v1/tasks/assignees運営会社の請求・契約名義と請求書用振込先
/v1/business-profileGET/v1/bank-accountPOST/v1/business-profile運営会社の帳票を準備し、確認後に発行する
/v1/invoicesPOST/v1/invoicesGET/v1/invoices/{id}会社の紹介と、公開中のメニュー・実績
/v1/company-page認証と権限
Authorizationヘッダーにキーを付けて呼びます。キーでできることは、選んだ権限（scope）と、発行した人のその時点の権限の両方で決まります。発行した人の権限が外れると、キーでもできなくなります。
キーはサーバーの中だけで使い、ブラウザやアプリの画面のコードには入れないでください。使わなくなったキーは発行した画面で無効にできます。
権限（scope）75
- connect:members:read読み取り
接続先の会員の参照このサービスに登録した外部会員だけを参照できます
- connect:members:write書き込み
接続先の会員の登録・停止外部会員を登録し、退会時に名刺の公開と事業アカウントの利用を停止できます
- connect:cards:read読み取り
会員名刺の参照このサービスの会員名刺だけを参照できます
- connect:cards:write書き込み
会員名刺の下書き編集会員名刺の下書きを編集できます。保存では公開内容は変わりません
- connect:cards:publish読み取り
会員名刺の公開・公開停止本人が確認した名刺を公開し、公開を停止できます
- connect:evidence:read読み取り
会員事業の証憑の情報を参照会員自身の経費に付いた証憑の名前・種類・サイズ・日時を取得する
- connect:expenses:read読み取り
会員事業の経費の参照会員事業の経費の一覧・詳細を取得する
- connect:expenses:write書き込み
会員事業の経費の登録・編集会員事業の経費を手動登録・編集する。支払いは行わない
- connect:expenses:delete読み取り
会員事業の経費の確認・削除本人確認後に経費を削除する。証憑や支払いは変更しない
- connect:expenses:restore読み取り
会員事業の経費の確認・復元本人確認後に経費を復元する。証憑や支払いは変更しない
- connect:settlements:read読み取り
会員事業の支払記録の参照外部会員自身の支払予定・支払記録と明細を取得する
- connect:invoice_requests:cancel読み取り
会員事業の請求書作成依頼の取消会員本人の確認後に提出前の依頼を取り消します。債務や支払いは変更しません
- connect:invoice_requests:present読み取り
会員事業の請求書作成依頼の確認・提示会員本人が確認した依頼を連携先で提示するために確定します。メール送信・提出・承認・支払いは行いません
- connect:invoice_requests:read読み取り
会員事業の請求書作成依頼の参照会員自身の請求書作成依頼の状態と明細を参照できます
- connect:invoice_requests:write書き込み
会員事業の請求書作成依頼の下書き作成・編集依頼を下書きできます。送付・提出・承認・支払い・取消は行いません
- connect:agreements:present読み取り
会員事業の取引合意の確認・提示会員本人が確認した条件を連携先で提示するために確定します。相手の同意・支払い・メール送信は行いません
- connect:agreements:cancel読み取り
会員事業の取引合意の確認・取消本人が確認した未同意の合意を取消します。同意済み契約の解除・支払い・メール送信は行いません
- connect:agreements:revise読み取り
会員事業の取引合意の確認・修正戻し本人が確認した未同意の合意を修正戻しします。同意済み契約の解除・支払い・メール送信は行いません
- connect:agreements:read読み取り
会員事業の取引合意の参照保存された合意内容と状態を参照できます
- connect:agreements:write書き込み
会員事業の取引合意の下書き作成・編集合意内容を下書きできます。相手への提示・送信・同意・支払いは行いません
- connect:partners:read読み取り
会員事業のパートナーの参照会員事業の発注先・業務委託先を参照できます
- connect:partners:write書き込み
会員事業のパートナーの登録・編集会員事業の発注先・業務委託先を登録・編集できます。招待・契約・送付は行いません
- connect:partner_orders:read読み取り
会員事業の発注条件の参照会員事業の発注条件を参照できます
- connect:partner_orders:write書き込み
会員事業の発注条件の下書き作成・編集会員事業の発注条件を下書きできます。実発注・契約締結・送信・支払いは行いません
- connect:invoices:read読み取り
会員事業の帳票の参照会員事業の帳票・発行履歴・PDFを参照できます。発行・送付・支払いは行いません
- connect:invoices:write書き込み
会員事業の帳票の下書き作成・編集会員事業の見積書・請求書を下書き作成・編集できます。発行・送付・支払いは行いません
- connect:invoices:issue読み取り
会員事業の帳票の確認・発行連携先で会員本人が確認した見積書・請求書を発行できます。メール送信や支払いは行いません
- connect:business_profile:read読み取り
会員事業の事業者情報の参照会員事業の事業者情報を参照できます。本人確認や契約締結は行いません
- connect:business_profile:write書き込み
会員事業の事業者情報の保存会員事業の事業者情報を保存できます。本人確認や契約締結は行いません
- connect:bank_account:read読み取り
会員事業の請求書用振込先の参照会員事業の請求書用振込先を参照できます。口座確認や送金は行いません
- connect:bank_account:write書き込み
会員事業の請求書用振込先の保存会員事業の請求書用振込先を保存できます。口座確認や送金は行いません
- connect:tasks:read読み取り
会員事業のタスクの参照このサービスの会員自身のタスクを参照できます
- connect:tasks:write書き込み
会員事業のタスクの作成・更新会員自身のタスクを作成し、内容・本人への担当・期日・状態を変更できます
- connect:projects:read読み取り
会員事業のプロジェクトの参照このサービスの会員自身のプロジェクトを参照できます
- connect:projects:write書き込み
会員事業のプロジェクトの作成・更新会員自身のプロジェクトの作成、内容・状態・親子関係を変更できます
- connect:clients:read読み取り
会員事業の取引先の参照このサービスの会員事業の取引先の連絡先・住所・振込先メモ・内部メモを参照できます
- connect:clients:write書き込み
会員事業の取引先の登録・更新このサービスの会員事業の取引先を登録・更新できます。運営会社の取引先は対象に含みません
- connect:accounts:read読み取り
会員の事業アカウントの参照このサービスの外部会員が持つ事業アカウントの状態を参照できます
- connect:accounts:write書き込み
会員の事業アカウントの管理外部会員の事業アカウントを作成・変更・停止できます。運営会社の業務とは分かれます
- work:read読み取り
ページと構成の参照参照できるページ・データベース・添付ファイルの情報と表示上の関係をMCPから取得する
- evidence:read読み取り
運営会社の証憑の情報を参照経費に付いた証憑の名前・種類・サイズ・日時を取得する
- expenses:read読み取り
運営会社の経費の参照運営会社の経費の一覧・詳細を取得する
- expenses:write書き込み
運営会社の経費の登録・編集運営会社の経費を手動登録・編集する。支払いは行わない
- expenses:delete読み取り
運営会社の経費の確認・削除本人確認後に経費を削除する。証憑や支払いは変更しない
- expenses:restore読み取り
運営会社の経費の確認・復元本人確認後に経費を復元する。証憑や支払いは変更しない
- settlements:read読み取り
運営会社の支払記録の参照運営会社の支払予定・支払記録と明細を取得する
- invoice_requests:cancel読み取り
運営会社の請求書作成依頼の取消本人確認後に提出前の依頼を取り消します。債務や支払いは変更しません
- invoice_requests:present読み取り
運営会社の請求書作成依頼の確認・提示本人が確認した依頼を連携先で提示するために確定します。メール送信・提出・承認・支払いは行いません
- agreements:present読み取り
運営会社の取引合意の確認・提示本人が確認した条件を連携先で提示するために確定します。相手の同意・支払い・メール送信は行いません
- agreements:cancel読み取り
運営会社の取引合意の確認・取消本人が確認した未同意の合意を取消します。同意済み契約の解除・支払い・メール送信は行いません
- agreements:revise読み取り
運営会社の取引合意の確認・修正戻し本人が確認した未同意の合意を修正戻しします。同意済み契約の解除・支払い・メール送信は行いません
- agreements:read読み取り
運営会社の取引合意の参照保存された合意内容と状態を参照できます
- agreements:write書き込み
運営会社の取引合意の下書き作成・編集合意内容を下書きできます。相手への提示・送信・同意・支払いは行いません
- invoices:read読み取り
運営会社の帳票の参照運営会社の帳票・発行履歴・PDFを参照できます。発行・送付・支払いは行いません
- invoices:write書き込み
運営会社の帳票の下書き作成・編集運営会社の見積書・請求書を下書き作成・編集できます。発行・送付・支払いは行いません
- invoices:issue読み取り
運営会社の帳票の確認・発行連携先で本人が確認した見積書・請求書を発行できます。メール送信や支払いは行いません
- business_profile:read読み取り
運営会社の事業者情報の参照運営会社の事業者情報を参照できます。本人確認や契約締結は行いません
- business_profile:write書き込み
運営会社の事業者情報の保存運営会社の事業者情報を保存できます。本人確認や契約締結は行いません
- bank_account:read読み取り
運営会社の請求書用振込先の参照運営会社の請求書用振込先を参照できます。口座確認や送金は行いません
- bank_account:write書き込み
運営会社の請求書用振込先の保存運営会社の請求書用振込先を保存できます。口座確認や送金は行いません
- tasks:read読み取り
タスクの参照運営会社のタスクと担当候補を参照できます
- tasks:write書き込み
タスクの作成・更新運営会社のタスクの内容・担当・期日・状態を変更できます
- projects:read読み取り
プロジェクトの参照運営会社のプロジェクトを参照できます。非公開ユニットの所属制限を引き継ぎます
- projects:write書き込み
プロジェクトの作成・更新プロジェクトの作成、内容・状態・親子関係の変更ができます。公開や招待は行いません
- clients:read読み取り
取引先の参照運営会社の取引先の連絡先・住所・振込先メモ・内部メモを参照できます
- clients:write書き込み
取引先の登録・更新運営会社の取引先を登録し、情報と状態を変更できます。招待やメールは送信しません
- partners:read読み取り
パートナーの参照パートナー（振込先などの事業者情報を含む）と業務委託契約を読み取れます
- partners:write書き込み
パートナーと業務委託契約の登録・更新パートナー（事業者情報を含む）と業務委託契約を登録・更新できます。案件や予算とのつなぎ込みは画面で行います
- invoice_requests:read読み取り
請求書作成依頼の参照請求書作成依頼の状態と中身を読み取れます
- invoice_requests:write書き込み
請求書作成依頼の作成・送付下書きの作成、委託先への送付・取り消し、委託先が自分のアプリで承認した請求書の提出ができます。承認と支払いは画面で行います
- people:read読み取り
メンバー（会社の人）の参照社員・役員・業務委託のスタッフなど、会社の人の登録内容を読み取れます。Tooonの利用者（ログインする人）は含みません
- people:write書き込み
メンバー（会社の人）の登録・更新会社の人を登録・更新し、パートナー（業務委託契約の相手）とつなげます。Tooonの利用者の招待や権限の変更は画面で行います
- business_cards:read読み取り
デジタル名刺の参照会社の人のデジタル名刺の中身・公開状態・公開URLを読み取れます
- business_cards:write書き込み
デジタル名刺の作成・更新・公開会社の人のデジタル名刺を作成・更新し、公開・非公開を切り替えられます。デザイン（テンプレート）は画面で決めます
- company_page:read読み取り
会社のページの参照会社のページの紹介と、公開中の提供メニュー・実績を読み取れます。自社サイトに同じ中身を出すときに使います
Authorization: Bearer tooon_sk_…
Content-Type: application/json
Idempotency-Key: 9b2f6c1e-… # 書き込みのとき{
"error": {
"code": "insufficient_scope",
"message": "このAPIキーには partners:write の権限がありません",
"requestId": "req_8f2c1a",
"requiredScopes": [
"partners:write"
]
}
}使う前に知っておくこと
どの入口でも同じ決まりです。
Idempotency-Key（UUIDなど）を付けると、通信が切れて同じ値でやり直しても、24時間は1回目と同じ結果を返します。externalRefを付けて登録すると、同じ値で何度呼んでも1件のまま、2回目からは中身を書き換えます。limit 件ずつ返ります。nextCursorを次の cursor に渡します。null なら最後です。RateLimit-Remainingに入ります。超えると 429 とRetry-Afterを返します。code を返します。code は v1 の中で意味を変えません。自社サイトに出す
GET /v1/company-pageで、会社カードと同じ中身（紹介・会社概要・リンク・メニュー・実績・メンバー）が取れます。自社サイトのメンバーページや会社概要を、Tooonで直した内容のまま出せます。
メンバーは会社カードに載せているメンバーカードだけを、並べた順に返します。部門（メンバーカードの部門）と、その人のメンバーカードのURLが付きます。キーの権限はcompany_page:readだけで足ります。キーはサーバー側だけで使ってください。
// 例: tooon.co.jp/member（Next.js のサーバー側）
// キーはサーバーだけで使い、ブラウザに出さない
const res = await fetch("https://tooon.app/api/v1/v1/company-page", {
headers: { Authorization: `Bearer ${process.env.TOOON_API_KEY}` },
next: { revalidate: 300 }, // 5分ごとに取り直す
});
const { data } = await res.json();
if (!data.isPublic) return notFound();
// 部門ごとに分ける（メンバーカードの「部門」）
const byDepartment = Object.groupBy(
data.members,
(member) => member.department ?? "その他",
);
// member: { name, image, jobTitle, department, cardUrl }エラー
エラーのときは、HTTPステータスと右の形のJSONを返します。問い合わせのときはrequestIdを伝えてください。
code の一覧11
- 400invalid_request
送った値が正しくない。message にどこが違うかが入ります
- 401unauthorized
APIキーがない、または無効になっている
- 403forbidden
キーを発行した人の今の権限では、この操作ができない
- 403insufficient_scope
キーにこの入口の権限（scope）が付いていない。requiredScopes に必要な権限が入ります
- 404not_found
対象がない、またはこのワークスペースのものではない
- 409invalid_status
今の状態ではその操作ができない（送付済みの依頼を直そうとした、など）
- 409idempotency_in_progress
同じ Idempotency-Key のリクエストを実行中。少し待ってやり直します
- 413payload_too_large
本文が大きすぎる（256KBまで）
- 422idempotency_key_reused
同じ Idempotency-Key を別の内容に使った
- 429rate_limited
呼び出し回数の上限に達した。Retry-After 秒待ってやり直します
- 500internal_error
Tooon側のエラー。時間をおいてやり直します
リファレンスは、APIの定義（OpenAPI）から自動で作られています。
{
"error": {
"code": "not_found",
"message": "請求書作成依頼が見つかりません",
"requestId": "req_8f2c1a"
}
}