外部API リファレンス

概要

見積・請求@SOHO の REST API です。 APIキーを使って、請求書・見積書・領収書・顧客の参照と作成、PDFの取得、メールでの送付ができます。 APIキーで扱えるのは、そのキーを発行したワークスペースのデータだけです。

ベースURL

https://invoice.atsoho.com/api/v1

はじめかた

1. ログインして「設定」の「外部API連携」タブを開き、「新しいAPIキーを発行」を押します
2. 使う機能に合わせてスコープ（権限）を選びます。請求書を作って送付するなら invoices:write と customers:read が要ります
3. 表示されたAPIキーを控えます。APIキーは発行時に一度だけ表示されます
4. GET /api/v1/issuer-profiles で発行者プロフィールの ID を調べます。書類の作成に必要です
5. GET /api/v1/customers で顧客の ID を調べ、書類を作成します

Claude Code などのAIに使わせる場合

この説明書をMarkdownのまま読めるURLを用意しています。

https://invoice.atsoho.com/docs/api.md

AIにこのURLを読ませてから、APIキーを渡してください。 APIキーは、作業に必要なスコープだけを付けたものを発行することをおすすめします。 メールを送る前に test: true でテスト送信させると、宛先と文面を確かめられます。

認証

APIキーの発行と管理

「設定」の「外部API連携」タブで行います。

・発行時にスコープと有効期限（無期限、30日、90日、180日、1年）を選びます ・発行後もスコープは「権限変更」で変えられます ・無効にしたキー、有効期限が切れたキーは使えなくなります（401が返ります） ・各キーの最終使用日時と、直近24時間のリクエスト数が画面に出ます

認証方法

すべてのリクエストに Authorization ヘッダーを付けます。

Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

スコープ（権限）

発行者プロフィール一覧は、書類（請求書・見積書・領収書）のスコープがどれか1つあれば使えます。

共通仕様

リクエスト形式

本文は JSON で送ります。

Content-Type: application/json

日付は YYYY-MM-DD 形式で指定します（例: 2026-10-01）。時刻付きの形式は受け付けません。 金額は円単位の整数です。

レスポンス形式

成功（1件）

{
  "success": true,
  "data": { }
}

成功（一覧）

{
  "success": true,
  "data": [ ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "totalPages": 8
  }
}

エラー

{
  "success": false,
  "error": "エラーメッセージ",
  "code": "VALIDATION_ERROR"
}

削除が成功したときは {"success": true, "data": {"deleted": true}} が返ります。

ページネーション

レート制限

APIキーごとに 1分間に60リクエスト までです（直近60秒の件数で数えます）。 レスポンスヘッダーで残りの回数が分かります。

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1790985600

X-RateLimit-Reset は制限が戻る時刻（UNIX秒）です。 超えると HTTP 429 が返ります。

エラーコード

関連する書類がある顧客・見積書を削除しようとしたときは、HTTP 400 でコード INTERNAL_ERROR が返ります。

CORS

どのオリジンからでも呼び出せます。

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

発行者プロフィール (Issuer Profiles)

書類の発行元（自社の名義）です。書類の作成時に issuerProfileId として指定します。 ID は画面には出ないので、このAPIで調べてください。

発行者プロフィール一覧

GET /api/v1/issuer-profiles

必要なスコープ: 書類のスコープのどれか1つ

アーカイブしたものは含みません。

レスポンス例

{
  "success": true,
  "data": [
    { "id": "clxxxxxxxxxxxxxx", "name": "株式会社サンプル", "isDefault": true }
  ]
}

請求書 (Invoices)

必要なスコープ: invoices:read（参照・PDF）、invoices:write（作成・更新・削除・メール送付）

状態（status）

請求書一覧

GET /api/v1/invoices

search は取得したページの中だけを絞り込みます。pagination.total には反映されません。

各請求書には、明細（items）、入金履歴（payments）、顧客（customer の id name email）、入金済みの額（paidAmount）が付きます。

リクエスト例

curl -H "Authorization: Bearer inv_xxxx" \
  "https://invoice.atsoho.com/api/v1/invoices?status=sent&page=1&perPage=10"

請求書の取得

GET /api/v1/invoices/{id}

明細、顧客（担当者を含む）、入金履歴、元の見積書が付きます。

請求書の作成

POST /api/v1/invoices

請求書番号は、発行者プロフィールの採番設定に従って自動で付きます。

明細（items）

リクエスト例

curl -X POST \
  -H "Authorization: Bearer inv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerProfileId": "clxxxxxxxxxxxxxx",
    "customerId": "clyyyyyyyyyyyyyy",
    "issueDate": "2026-10-01",
    "dueDate": "2026-10-31",
    "subject": "10月分業務委託費用",
    "items": [
      { "description": "システム開発", "quantity": 1, "unit": "式", "unitPrice": 500000, "taxRate": 10 },
      { "description": "交通費", "quantity": 3, "unit": "回", "unitPrice": 1500, "taxRate": 10 }
    ]
  }' \
  "https://invoice.atsoho.com/api/v1/invoices"

請求書の更新

PUT /api/v1/invoices/{id}

本文は作成と同じ形です。明細は送ったもので置き換わります。 isDraft が true でなければ、customerId と1件以上の明細が要ります。 発行者プロフィールは変えられません。

請求書の状態の変更

PATCH /api/v1/invoices/{id}

送ったフィールドだけを変えます。

・paid 以外に変えると、入金日は消えます ・paid に変えると、まだ入金されていない残りの額が入金履歴に記録されます

リクエスト例

curl -X PATCH \
  -H "Authorization: Bearer inv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid", "paidAt": "2026-10-20"}' \
  "https://invoice.atsoho.com/api/v1/invoices/clxxxxxxxxxxxxxx"

請求書の削除

DELETE /api/v1/invoices/{id}

請求書のPDF

GET /api/v1/invoices/{id}/pdf

PDFのファイルが返ります（Content-Type: application/pdf）。

curl -H "Authorization: Bearer inv_xxxx" -o invoice.pdf \
  "https://invoice.atsoho.com/api/v1/invoices/clxxxxxxxxxxxxxx/pdf"

請求書のメール送付

POST /api/v1/invoices/{id}/send-email

必要なスコープ: invoices:write

・宛先のアドレスはすべて形式を確かめます。正しくなければ 400 が返ります ・body を指定したときも、発行者プロフィールのメール署名が末尾に付きます（本文に既に入っていれば付けません） ・本送信は、画面から送ったときと同じ扱いです。送信履歴に残り、開封が計測され、作成中の請求書は送付済になります

テスト送信（test: true）

・件名の先頭に【テスト】が付きます ・送信履歴に残らず、状態も変わりません ・to の先頭の1件にだけ送ります

リクエスト例（テスト送信）

curl -X POST \
  -H "Authorization: Bearer inv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "test": true}' \
  "https://invoice.atsoho.com/api/v1/invoices/clxxxxxxxxxxxxxx/send-email"

レスポンス（テスト送信）

{
  "success": true,
  "data": {
    "test": true,
    "to": "[email protected]",
    "subject": "【テスト】請求書のご送付（202610-001）",
    "attachedPdf": true,
    "message": "[email protected] にテストメールを送信しました（送信履歴・ステータスは変更していません）"
  }
}

レスポンス（本送信）

{
  "success": true,
  "mailTrackingEmailId": "…",
  "trackingEmailId": "…"
}

本送信のレスポンスには data がありません。失敗したときは success: false と error が返ります。

見積書 (Estimates)

必要なスコープ: estimates:read（参照・PDF）、estimates:write（作成・更新・削除・メール送付）

状態（status）: draft（作成中）、sent（送付済）、accepted（成約）、expired（失効）

見積書一覧

GET /api/v1/estimates

パラメータは請求書一覧と同じです（page perPage status customerId search）。

見積書の取得

GET /api/v1/estimates/{id}

見積書の作成

POST /api/v1/estimates

見積書の更新

PUT /api/v1/estimates/{id}

本文は作成と同じ形です。

見積書の状態の変更

PATCH /api/v1/estimates/{id}

見積書の削除

DELETE /api/v1/estimates/{id}

請求書を作成済みの見積書は削除できません。

見積書のPDF

GET /api/v1/estimates/{id}/pdf

見積書のメール送付

POST /api/v1/estimates/{id}/send-email

必要なスコープ: estimates:write

本文の形と動きは、請求書のメール送付と同じです。本送信すると、作成中の見積書は送付済になります。

領収書 (Receipts)

必要なスコープ: receipts:read（参照・PDF）、receipts:write（作成・更新・削除・メール送付）

状態（status）: draft（作成中）、issued（発行済）

領収書一覧

GET /api/v1/receipts

領収書の取得

GET /api/v1/receipts/{id}

領収書の作成

POST /api/v1/receipts

作成した領収書は作成中（draft）になります。発行済にするには、状態の変更かメール送付を使います。

リクエスト例

curl -X POST \
  -H "Authorization: Bearer inv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerProfileId": "clxxxxxxxxxxxxxx",
    "customerId": "clyyyyyyyyyyyyyy",
    "issueDate": "2026-10-20",
    "subject": "コンサルティング費用",
    "amount": 110000,
    "paymentMethod": "銀行振込"
  }' \
  "https://invoice.atsoho.com/api/v1/receipts"

領収書の更新

PUT /api/v1/receipts/{id}

送った内容で全体を置き換えます。省いた項目は空になります。 作成中でなければ、customerId issueDate receiptDate amount が要ります。

領収書の状態の変更

PATCH /api/v1/receipts/{id}

領収書の削除

DELETE /api/v1/receipts/{id}

領収書のPDF

GET /api/v1/receipts/{id}/pdf

領収書のメール送付

POST /api/v1/receipts/{id}/send-email

必要なスコープ: receipts:write

本文の形と動きは、請求書のメール送付と同じです。本送信すると、作成中の領収書は発行済になります。

顧客 (Customers)

必要なスコープ: customers:read（参照）、customers:write（作成・更新・削除）

顧客一覧

GET /api/v1/customers

更新が新しい順に並び、各顧客に担当者（contacts）が付きます。

curl -H "Authorization: Bearer inv_xxxx" \
  "https://invoice.atsoho.com/api/v1/customers?search=サンプル"

顧客の取得

GET /api/v1/customers/{id}

担当者と、直近の見積書・請求書（各5件）が付きます。

顧客の作成

POST /api/v1/customers

担当者（contacts）

顧客の更新

PUT /api/v1/customers/{id}

本文は作成と同じ形です。担当者は送ったもので置き換わります。

顧客の削除

DELETE /api/v1/customers/{id}

請求書または見積書がある顧客は削除できません。

定期請求 (Recurring Invoices)

毎月などの決まった周期で請求書を自動で作る雛形です。実行日になると、この内容で「作成中」の請求書が作られます。

必要なスコープ: invoices:read（参照）、invoices:write（作成・更新・削除）

周期（frequency）

件名・あいさつ文・備考には {{今月}} {{先月}} {{次月}} を書けます。請求書を作るときに「2026年10月」の形に置き換わります。

定期請求一覧

GET /api/v1/recurring-invoices

各定期請求には、明細（items）と顧客（customer の id name email）が付きます。

定期請求の取得

GET /api/v1/recurring-invoices/{id}

明細、顧客、直近10回の実行履歴（executions）が付きます。

定期請求の作成

POST /api/v1/recurring-invoices

定期請求の更新

PATCH /api/v1/recurring-invoices/{id}

送った項目だけが変わります。items を送ると、明細は送ったもので置き換わり、金額も計算し直されます。 frequency dayOfMonth startDate のどれかを送ると、次回の実行日も計算し直されます。 すでに作られた請求書には影響しません。

リクエスト例（明細の品目だけを変える）

curl -X PATCH \
  -H "Authorization: Bearer inv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "description": "システム保守・各種相談", "quantity": 1, "unit": "式", "unitPrice": 25000, "taxRate": 10 }
    ]
  }' \
  "https://invoice.atsoho.com/api/v1/recurring-invoices/{id}"

定期請求の削除

DELETE /api/v1/recurring-invoices/{id}

雛形を消します。すでに作られた請求書は残ります。

利用例

請求書を作ってテスト送信し、確かめてから送付する

KEY="inv_xxxx"
BASE="https://invoice.atsoho.com/api/v1"

# 1. 発行者プロフィールと顧客の ID を調べる
curl -s -H "Authorization: Bearer $KEY" "$BASE/issuer-profiles"
curl -s -H "Authorization: Bearer $KEY" "$BASE/customers?search=サンプル"

# 2. 請求書を作る
INVOICE_ID=$(curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"issuerProfileId":"clxxxxxxxxxxxxxx","customerId":"clyyyyyyyyyyyyyy","issueDate":"2026-10-01","dueDate":"2026-10-31","subject":"10月分","items":[{"description":"保守費用","quantity":1,"unit":"式","unitPrice":50000,"taxRate":10}]}' \
  "$BASE/invoices" | jq -r '.data.id')

# 3. 自分宛てにテスト送信して、文面とPDFを確かめる
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","test":true}' "$BASE/invoices/$INVOICE_ID/send-email"

# 4. 顧客へ送付する
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"to":"[email protected]"}' "$BASE/invoices/$INVOICE_ID/send-email"

未入金の請求書を探す

curl -H "Authorization: Bearer inv_xxxx" \
  "https://invoice.atsoho.com/api/v1/invoices?status=sent"

記録

APIへのリクエストは、メソッド、パス、HTTPステータス、処理時間、IPアドレス、User-Agent を記録しています。 APIキーの認証に失敗したリクエストは記録しません。