API docs by Redocly

Attendance Management API (1.0.0)

Download OpenAPI specification:

API Support: support@example.com License: MIT

勤怠管理システムのバックエンドAPI仕様書

認証について

ほとんどのエンドポイントでJWT Bearer認証が必要です。

  1. /api/v1/auth/register でユーザー登録
  2. /api/v1/auth/login でログインしてトークンを取得
  3. 取得したトークンを Authorization: Bearer {token} ヘッダーに含めてリクエスト

ロールについて

ユーザーには以下のロールが存在します。

ロール 説明
employee 一般社員。自分の勤怠情報のみ操作可能
admin 管理者。全社員の情報を参照・管理可能

admin タグのエンドポイントは admin ロールのユーザーのみアクセスできます。

health

ヘルスチェック

ヘルスチェック

サーバーの稼働状態を確認します

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

auth

認証関連のエンドポイント

社員登録

新規社員を登録します

Request Body schema: application/json
required
email
required
string <email>

メールアドレス

password
required
string <password> >= 6 characters

パスワード（6文字以上）

name
required
string

名前

role
string
Default: "employee"
Enum: "admin" "employee"

ロール（省略時はemployee）

Responses

Request samples

Content type
application/json
{
  • "email": "yamada@example.com",
  • "password": "password123",
  • "name": "山田太郎",
  • "role": "employee"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "email": "yamada@example.com",
  • "name": "山田太郎",
  • "role": "employee",
  • "created_at": "2024-01-01T18:00:00+09:00",
  • "updated_at": "2024-01-01T18:00:00+09:00"
}

ログイン

メールアドレスとパスワードでログインし、JWTトークンを取得します

Request Body schema: application/json
required
email
required
string <email>

メールアドレス

password
required
string <password>

パスワード

Responses

Request samples

Content type
application/json
{
  • "email": "yamada@example.com",
  • "password": "password123"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbXBsb3llZV9pZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInJvbGUiOiJlbXBsb3llZSJ9.example",
  • "employee": {
    }
}

認証情報取得

現在ログイン中の社員情報を取得します

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "employee_id": "550e8400-e29b-41d4-a716-446655440000",
  • "role": "employee"
}

attendance

勤怠管理のエンドポイント

勤怠一覧取得

指定した年月の勤怠一覧を取得します。 自分の勤怠のみ取得できます。

Authorizations:
bearerAuth
query Parameters
year_month
required
string^\d{4}-(0[1-9]|1[0-2])$
Example: year_month=2026-04

対象年月（YYYY-MM形式）

Responses

Response samples

Content type
application/json
[
  • {
    }
]

出勤

出勤時刻を記録します

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "employee_id": "550e8400-e29b-41d4-a716-446655440001",
  • "date": "2024-01-01",
  • "clock_in": "2024-01-01T09:00:00+09:00",
  • "clock_out": "2024-01-01T18:00:00+09:00",
  • "created_at": "2024-01-01T18:00:00+09:00",
  • "updated_at": "2024-01-01T18:00:00+09:00"
}

退勤

退勤時刻を記録します

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "employee_id": "550e8400-e29b-41d4-a716-446655440001",
  • "date": "2024-01-01",
  • "clock_in": "2024-01-01T09:00:00+09:00",
  • "clock_out": "2024-01-01T18:00:00+09:00",
  • "created_at": "2024-01-01T18:00:00+09:00",
  • "updated_at": "2024-01-01T18:00:00+09:00"
}

application

申請関連のエンドポイント（打刻修正申請など）

自分の申請一覧取得

ログイン中の社員自身の申請一覧を取得します。

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "PENDING" "APPROVED" "REJECTED"
Example: status=PENDING

ステータスでフィルタリング

page
integer >= 1
Default: 1
Example: page=1

ページ番号（1始まり）

per_page
integer [ 1 .. 100 ]
Default: 20
Example: per_page=20

1ページあたりの件数

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ],
  • "total": 5,
  • "page": 1,
  • "per_page": 20
}

打刻修正申請を作成

勤怠打刻の修正申請を行います。

requested_clock_in と requested_clock_out の少なくとも一方は必須です。

Authorizations:
bearerAuth
Request Body schema: application/json
required
type
required
string
Value: "ATTENDANCE_CORRECTION"

申請種別

date
required
string <date>

修正対象の日付

requested_clock_in
string or null <date-time>

修正後の出勤時刻（requested_clock_out と少なくとも一方必須）

requested_clock_out
string or null <date-time>

修正後の退勤時刻（requested_clock_in と少なくとも一方必須）

reason
required
string

申請理由

Responses

Request samples

Content type
application/json
Example
{
  • "type": "ATTENDANCE_CORRECTION",
  • "date": "2024-01-15",
  • "requested_clock_in": "2024-01-15T09:30:00+09:00",
  • "reason": "電車の遅延により出勤時刻が遅れました"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "employee": {
    },
  • "type": "ATTENDANCE_CORRECTION",
  • "status": "PENDING",
  • "reason": "電車の遅延により出勤時刻が遅れました",
  • "created_at": "2024-01-15T09:00:00+09:00",
  • "updated_at": "2024-01-15T09:00:00+09:00",
  • "details": {
    }
}

申請取り消し

自分の申請を取り消します。

PENDING（申請中）状態の申請のみ取り消し可能です。 APPROVED（承認済み）または REJECTED（却下済み）の申請は取り消しできません。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440001

申請ID

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "employee": {
    },
  • "type": "ATTENDANCE_CORRECTION",
  • "status": "PENDING",
  • "reason": "電車の遅延により出勤時刻が遅れました",
  • "details": {
    },
  • "created_at": "2024-01-15T09:00:00+09:00",
  • "updated_at": "2024-01-15T09:00:00+09:00"
}

admin

管理者専用のエンドポイント（adminロールのみ）

社員一覧取得

全社員の一覧を取得します。

このエンドポイントはadminロールの社員のみ実行できます。

Authorizations:
bearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

ページ番号（1始まり）

per_page
integer [ 1 .. 100 ]
Default: 20
Example: per_page=20

1ページあたりの件数

role
string
Enum: "admin" "employee"
Example: role=employee

ロールでフィルタリング

Responses

Response samples

Content type
application/json
{
  • "employees": [
    ],
  • "total": 42,
  • "page": 1,
  • "per_page": 20
}

社員情報更新

指定したIDの社員情報を更新します。

このエンドポイントはadminロールの社員のみ実行できます。

name / email / role のうち少なくとも1つを指定してください。 自分自身の role を変更することはできません。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

更新する社員のUUID

Request Body schema: application/json
required
name
string

名前

email
string <email>

メールアドレス

role
string
Enum: "admin" "employee"

ロール

Responses

Request samples

Content type
application/json
Example
{
  • "name": "山田花子"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "email": "yamada@example.com",
  • "name": "山田太郎",
  • "role": "employee",
  • "created_at": "2024-01-01T09:00:00+09:00",
  • "updated_at": "2026-05-09T18:00:00+09:00"
}

社員詳細取得

指定したIDの社員詳細情報と勤怠一覧を取得します。

このエンドポイントはadminロールのユーザーのみ実行できます。

year_month で勤怠の取得対象年月を絞り込めます。 page / per_page で勤怠一覧のページネーションを制御できます。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

社員のUUID

query Parameters
year_month
string^\d{4}-(0[1-9]|1[0-2])$
Example: year_month=2024-01

勤怠取得の対象年月（YYYY-MM形式）

page
integer >= 1
Default: 1
Example: page=1

勤怠一覧のページ番号（1始まり）

per_page
integer [ 1 .. 100 ]
Default: 20
Example: per_page=20

勤怠一覧の1ページあたりの件数

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "email": "yamada@example.com",
  • "name": "山田太郎",
  • "role": "employee",
  • "created_at": "2024-01-01T09:00:00+09:00",
  • "updated_at": "2024-01-01T09:00:00+09:00",
  • "attendances": {
    }
}

社員削除

指定したIDの社員を削除します。

このエンドポイントはadminロールの社員のみ実行できます。

削除した社員に紐づく勤怠レコードも合わせて削除されます。 自分自身のアカウントは削除できません。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

削除する社員のUUID

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "email": "yamada@example.com",
  • "name": "山田太郎",
  • "role": "employee",
  • "created_at": "2024-01-01T18:00:00+09:00",
  • "updated_at": "2024-01-01T18:00:00+09:00"
}

申請一覧取得（管理者）

全社員の申請一覧を取得します。

このエンドポイントはadminロールの社員のみ実行できます。

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "PENDING" "APPROVED" "REJECTED"
Example: status=PENDING

ステータスでフィルタリング

page
integer >= 1
Default: 1
Example: page=1

ページ番号（1始まり）

per_page
integer [ 1 .. 100 ]
Default: 20
Example: per_page=20

1ページあたりの件数

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ],
  • "total": 42,
  • "page": 1,
  • "per_page": 20
}

申請詳細取得（管理者）

指定した申請の詳細を取得します。承認者情報や管理者コメントを含みます。

このエンドポイントはadminロールの社員のみ実行できます。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440001

申請ID

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "employee": {
    },
  • "type": "ATTENDANCE_CORRECTION",
  • "status": "PENDING",
  • "reason": "電車の遅延により出勤時刻が遅れました",
  • "created_at": "2024-01-15T09:00:00+09:00",
  • "updated_at": "2024-01-15T09:00:00+09:00",
  • "details": {
    },
  • "approved_by": {
    },
  • "approved_at": "2024-01-16T10:00:00+09:00",
  • "admin_comment": "確認しました。修正を承認します。"
}

申請承認（管理者）

指定した申請を承認します。

PENDING（申請中）状態の申請のみ承認可能です。

このエンドポイントはadminロールの社員のみ実行できます。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440001

申請ID

Request Body schema: application/json
optional
admin_comment
string or null

管理者コメント（任意）

Responses

Request samples

Content type
application/json
{
  • "admin_comment": "確認しました。修正を承認します。"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "employee": {
    },
  • "type": "ATTENDANCE_CORRECTION",
  • "status": "APPROVED",
  • "reason": "電車の遅延により出勤時刻が遅れました",
  • "details": {
    },
  • "approved_by": {
    },
  • "approved_at": "2024-01-16T10:00:00+09:00",
  • "admin_comment": "確認しました。修正を承認します。",
  • "created_at": "2024-01-15T09:00:00+09:00",
  • "updated_at": "2024-01-16T10:00:00+09:00"
}

申請却下（管理者）

指定した申請を却下します。

PENDING（申請中）状態の申請のみ却下可能です。 申請者に理由を伝えるため admin_comment の入力を推奨します。

このエンドポイントはadminロールの社員のみ実行できます。

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440001

申請ID

Request Body schema: application/json
optional
admin_comment
string or null

却下理由

Responses

Request samples

Content type
application/json
{
  • "admin_comment": "勤務実績と合致しないため却下します。再申請してください。"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440001",
  • "employee": {
    },
  • "type": "ATTENDANCE_CORRECTION",
  • "status": "REJECTED",
  • "reason": "電車の遅延により出勤時刻が遅れました",
  • "details": {
    },
  • "approved_by": {
    },
  • "approved_at": "2024-01-16T10:00:00+09:00",
  • "admin_comment": "勤務実績と合致しないため却下します。再申請してください。",
  • "created_at": "2024-01-15T09:00:00+09:00",
  • "updated_at": "2024-01-16T10:00:00+09:00"
}