コンテンツにスキップ

API リファレンス

リファレンス概要

Basee Payroll Engine の計算・マスタ照会APIのリファレンスです。各エンドポイントの詳細は、このセクション内の各ページを参照してください。

ベースURL

Section titled “ベースURL”
https://api.payroll.basee.io

以降の各ページのパス(例: /v1/payroll/monthly:calculate)は、このベースURLからの相対パスです。

共通ヘッダー

Section titled “共通ヘッダー”
ヘッダー必須説明
X-API-Key必須発行済みAPIキー。詳細は 認証 を参照してください。
Content-Type: application/jsonPOSTで必須リクエストボディを送るすべてのエンドポイントで必要です。
Idempotency-Key任意1〜255文字の文字列。5つの計算エンドポイント(月例給与・賞与・3種のシミュレーション)が受け付けます。本APIはステートレスなため、このヘッダーによる結果のキャッシュや重複リクエストの排除は行われません。 リクエストログに記録されるだけの、呼び出し側の追跡用ヘッダーです。

エンドポイント一覧

Section titled “エンドポイント一覧”
メソッドパス説明ページ
POST/v1/payroll/monthly:calculate月例給与の計算月例給与の計算
POST/v1/payroll/bonus:calculate賞与の計算賞与の計算
POST/v1/simulations/social-insurance:calculate社会保険料のみのシミュレーションシミュレーション
POST/v1/simulations/employment-insurance:calculate雇用保険料のみのシミュレーションシミュレーション
POST/v1/simulations/income-tax:calculate源泉所得税のみのシミュレーションシミュレーション
GET/v1/masters/tax-tables公開済みの所得税表バージョン一覧マスタ照会
GET/v1/masters/rate-tables公開済みの社会保険・厚生年金・雇用保険料率表バージョン一覧マスタ照会

エラー形式

Section titled “エラー形式”

すべてのエラーレスポンスは、次の形式のJSONボディで返ります。

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "075cbd87-37ea-48eb-9850-56fc4684bb5f",
    "details": [
      { "path": ["company_id"], "code": "invalid_type" }
    ]
  }
}

details はリクエストバリデーションエラー(422 validation_error)のときだけ含まれます。エラーコード一覧・ステータスコード・レート制限(429)の扱いは エラーとレート制限 を参照してください。

機械可読仕様

Section titled “機械可読仕様”

リクエスト・レスポンスの型を検証しているのと同じZodスキーマから生成されたOpenAPI 3.1仕様を、次のエンドポイントから取得できます。

GET /v1/openapi.json

OpenAPI仕様(GET /v1/openapi.json)は実装のスキーマ定義から生成されるため、常に実装と一致します。本ページのフィールド表は手動で整備しているため、厳密・最新の仕様が必要な場合は openapi.json を正としてください。コード生成やAPIクライアントの自動生成にもご利用ください。

次のステップ

Section titled “次のステップ”