API Documentation

This document outlines the available API endpoints for the React frontend.

Base URL: /api (Relative to the application root)

Common Headers

All requests should include the following headers to ensure correct JSON handling and authentication with Laravel Sanctum:

• Accept: application/json (Required to receive JSON responses instead of redirects on errors)
• Content-Type: application/json (Required when sending JSON data in the request body)
• Authorization: Bearer <access_token> (Required for protected routes)

Error Responses

API requests may return error responses with appropriate HTTP status codes and JSON bodies.

422 Unprocessable Entity (Validation Error)

Returned when request data fails validation rules.

{
    "message": "The given data was invalid.",
    "errors": {
        "field_name": [
            "The field name field is required."
        ]
    }
}

401 Unauthorized

Returned when authentication fails (e.g., missing or invalid token).

{
    "message": "Unauthenticated."
}

403 Forbidden

Returned when the user is authenticated but does not have permission to perform the action.

{
    "message": "This action is unauthorized."
}

Authentication

Register

Create a new user account.

• Endpoint: POST /register

• cURL:

  curl -X POST http://tuohua-work-api.test/api/register \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@tuohuacm.com", "password": "secret_password", "password_confirmation": "secret_password"}'
  

• Request Body:

  {
    "name": "John Doe",
    "email": "john@tuohuacm.com",
    "password": "secret_password",
    "password_confirmation": "secret_password"
  }
  

  • name (string, required): User's full name.
  • email (string, required): Valid email address.
  • password (string, required): Min 8 characters.
  • password_confirmation (string, required): Must match password.

• Response (201 Created):

  {
    "access_token": "1|laravel_sanctum_token...",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@tuohuacm.com",
      "created_at": "...",
      "updated_at": "..."
    }
  }
  

• Error Response (422 Unprocessable Entity): See Error Responses for validation errors (e.g., duplicate email, invalid password, non-tuohuacm.com email).

Login

Authenticate a user.

• Endpoint: POST /login

• cURL:

  curl -X POST http://tuohua-work-api.test/api/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@tuohuacm.com", "password": "secret_password"}'
  

• Request Body:

  {
    "email": "john@tuohuacm.com",
    "password": "secret_password"
  }
  

  • email (string, required)
  • password (string, required)

• Response (200 OK):

  {
    "access_token": "2|laravel_sanctum_token...",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@tuohuacm.com",
      "..."
    }
  }
  

• Error Response (422 Unprocessable Entity): See Error Responses for invalid credentials.

Logout

Invalidate the current session token.

• Endpoint: POST /logout
• cURL:

  curl -X POST http://tuohua-work-api.test/api/logout \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>"
  

• Headers:
  • Authorization: Bearer <access_token>
• Response (200 OK):

  {
    "message": "Logged out successfully"
  }
  

• Error Response (401 Unauthorized): See Error Responses if authentication token is missing or invalid.

DingTalk Login Redirect

Get the DingTalk OAuth login URL.

• Endpoint: GET /auth/dingtalk/redirect

• cURL:

  curl -X GET http://tuohua-work-api.test/api/auth/dingtalk/redirect \
  -H "Accept: application/json"
  

• Response (200 OK):

  {
    "url": "https://login.dingtalk.com/oauth2/auth?redirect_uri=...&response_type=code&client_id=...&scope=openid%20corpid&state=...&prompt=consent",
    "state": "random_state_string"
  }
  

  • url (string): The DingTalk OAuth authorization URL to redirect the user to.
  • state (string): Random state string for CSRF protection.

• Usage: Frontend should redirect the user to the url. After user authorizes, DingTalk will redirect back to the configured redirect_uri with a code parameter.

DingTalk Login Callback

Handle the DingTalk OAuth callback and authenticate/register the user.

• Endpoint: POST /auth/dingtalk/callback

• cURL:

  curl -X POST http://tuohua-work-api.test/api/auth/dingtalk/callback \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"code": "authorization_code_from_dingtalk"}'
  

• Request Body:

  {
    "code": "authorization_code_from_dingtalk"
  }
  

  • code (string, required): Authorization code returned by DingTalk after user authorization.

• Response (200 OK):

  {
    "access_token": "1|laravel_sanctum_token...",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "zhangsan",
      "email": "zhangsan@alibaba-inc.com",
      "avatar": "https://xxx",
      "dingtalk_open_id": "123",
      "created_at": "...",
      "updated_at": "..."
    }
  }
  

  • If the user doesn't exist, a new user will be created automatically.
  • If the user exists, their information (name, email, avatar) will be updated.

• Error Response (400 Bad Request): See Error Responses for errors from DingTalk API (e.g., invalid code, failed to get user info).

• Error Response (422 Unprocessable Entity): See Error Responses for validation errors (e.g., missing code).

User & Profile

Get Current User

Fetch the currently authenticated user's details.

• Endpoint: GET /user
• cURL:

  curl -X GET http://tuohua-work-api.test/api/user \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>"
  

• Headers:
  • Authorization: Bearer <access_token>
• Response (200 OK):

  {
    "id": 1,
    "name": "John Doe",
    "email": "john@tuohuacm.com",
    "email_verified_at": null,
    "created_at": "2023-10-27T10:00:00.000000Z",
    "updated_at": "2023-10-27T10:00:00.000000Z",
    "is_admin": false
  }
  

• Error Response (401 Unauthorized): See Error Responses if authentication token is missing or invalid.

Update Profile

Update the user's name and/or email.

• Endpoint: PUT /profile

• cURL:

  curl -X PUT http://tuohua-work-api.test/api/profile \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"name": "Jane Doe", "email": "jane@tuohuacm.com"}'
  

• Headers:

  • Authorization: Bearer <access_token>

• Request Body:

  {
    "name": "Jane Doe",
    "email": "jane@tuohuacm.com"
  }
  

  • name (string, optional): User's new full name.
  • email (string, optional): User's new email address.

• Response (200 OK):

  {
    "message": "Profile updated successfully.",
    "user": {
      "id": 1,
      "name": "Jane Doe",
      "email": "jane@tuohuacm.com",
      "..."
    }
  }
  

• Error Response (401 Unauthorized): See Error Responses if authentication token is missing or invalid.

• Error Response (422 Unprocessable Entity): See Error Responses for validation errors (e.g., duplicate email, invalid email format).

Update Password

Change the user's password.

• Endpoint: PUT /profile/password

• cURL:

  curl -X PUT http://tuohua-work-api.test/api/profile/password \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"current_password": "old_password", "password": "new_secure_password", "password_confirmation": "new_secure_password"}'
  

• Headers:

  • Authorization: Bearer <access_token>

• Request Body:

  {
    "current_password": "old_password",
    "password": "new_secure_password",
    "password_confirmation": "new_secure_password"
  }
  

  • current_password (string, required): Must match the current password.
  • password (string, required): New password (min 8 chars).
  • password_confirmation (string, required): Must match password.

• Response (200 OK):

  {
    "message": "Password updated successfully."
  }
  

• Error Response (401 Unauthorized): See Error Responses if authentication token is missing or invalid.

• Error Response (422 Unprocessable Entity): See Error Responses for validation errors (e.g., current password mismatch, new password not confirmed).

List All Users (Admin Only)

Get a paginated list of all users. Only users with is_admin set to true can access this endpoint.

• Endpoint: GET /users
• cURL:

  curl -X GET http://tuohua-work-api.test/api/users \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>"
  

• Headers:
  • Authorization: Bearer <access_token>
• Query Params:
  • search (optional): Search users by name or email.
  • page (optional): Page number (default: 1).
• Response (200 OK):

  {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john@tuohuacm.com",
        "is_admin": false,
        "created_at": "2023-10-27T10:00:00.000000Z",
        "updated_at": "2023-10-27T10:00:00.000000Z"
      },
      {
        "id": 2,
        "name": "Jane Smith",
        "email": "jane@tuohuacm.com",
        "is_admin": true,
        "created_at": "2023-10-28T10:00:00.000000Z",
        "updated_at": "2023-10-28T10:00:00.000000Z"
      }
    ],
    "total": 2,
    "per_page": 20,
    "last_page": 1
    // ... pagination meta
  }
  

• Error Response (401 Unauthorized): See Error Responses if authentication token is missing or invalid.
• Error Response (403 Forbidden): See Error Responses if the current user is not an admin.

Update User Admin Status (Admin Only)

Update any user's is_admin attribute. Only users with is_admin set to true can access this endpoint.

• Endpoint: PUT /users/{id}/admin-status

• cURL:

  curl -X PUT http://tuohua-work-api.test/api/users/123/admin-status \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{"is_admin": true}'
  

• Headers:

  • Authorization: Bearer <access_token>

• Request Body:

  {
    "is_admin": true
  }
  

  • is_admin (boolean, required): The new admin status for the user.

• Response (200 OK):

  {
    "id": 123,
    "name": "Jane Doe",
    "email": "jane@tuohuacm.com",
    "is_admin": true,
    "created_at": "...",
    "updated_at": "..."
  }
  

• Error Response (401 Unauthorized): See Error Responses if authentication token is missing or invalid.

• Error Response (403 Forbidden): See Error Responses if the current user is not an admin.

• Error Response (404 Not Found): If the target user does not exist.

• Error Response (422 Unprocessable Entity): See Error Responses for validation errors (e.g., missing or invalid is_admin field).

File Upload

Upload File

Upload an image or PDF file (Max 10MB).

• Endpoint: POST /upload
• Headers:
  • Authorization: Bearer <token>
  • Content-Type: multipart/form-data
• Request Body:
  • file (File, required): The file to upload (jpg, jpeg, png, webp, pdf).
• Response (201 Created):

  {
    "path": "uploads/hash.jpg",
    "url": "http://tuohua-work-api.test/storage/uploads/hash.jpg"
  }
  

Reimbursements

List My Reimbursements

Get a paginated list of the current user's reimbursement reports.

• Endpoint: GET /reimbursements
• Headers: Authorization: Bearer <token>
• Query Params:
  • status (optional): Filter by status (e.g., draft, submitted, approved, rejected).
  • page (optional): Page number (default: 1).
• Response (200 OK):

  {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "title": "December 2025 Expenses",
        "status": "draft",
        "total_amount_cny": "1250.00",
        "created_at": "...",
        "user": { ... }
      }
    ],
    "total": 1
    // ... pagination meta
  }
  

List All Reimbursements (Admin Only)

Get a paginated list of all users' reimbursement reports (default excludes drafts).

• Endpoint: GET /reimbursements/all
• Headers: Authorization: Bearer <token>
• Query Params:
  • user_id (optional): Filter by specific user.
  • status (optional): Filter by status.
• Response (200 OK): Same structure as List My Reimbursements.
• Error Response (403 Forbidden): If user is not an admin.

Create Reimbursement Report

Create a new reimbursement group (e.g., "Jan 2025").

• Endpoint: POST /reimbursements
• Request Body:

  {
    "title": "January 2025 Trip"
  }
  

• Response (201 Created): Returns the created report object.

Show Reimbursement Report

Get details of a specific report, including its items.

• Endpoint: GET /reimbursements/{id}
• Response (200 OK):

  {
    "id": 1,
    "title": "January 2025 Trip",
    "items": [
      {
        "id": 10,
        "type": "transport",
        "amount_cny": "100.00",
        "payment_proofs": ["url1", "url2"]
        // ...
      }
    ],
    "offset_invoices": ["url_to_pdf"]
  }
  

Update Reimbursement Report

Update report details (title, offset invoices) while in draft or rejected status.

• Endpoint: PUT /reimbursements/{id}
• Request Body:

  {
    "title": "Updated Title",
    "offset_invoices": ["http://example.com/invoice.pdf"]
  }
  

• Response (200 OK): Returns updated report.

Submit Report

Submit a draft report for approval.

• Endpoint: PUT /reimbursements/{id}/submit
• Response (200 OK): Returns updated report with status submitted.

Add Item

Add a specific expense item to a report.

• Endpoint: POST /reimbursements/{id}/items
• Request Body:

  {
    "type": "transport", // transport, accommodation, general
    "date": "2025-12-01",
    "currency": "CNY",
    "amount_original": 100.50, // Optional, only needed for non-CNY currencies
    "amount_cny": 100.50,
    "description": "Taxi to airport",
    "payment_proofs": ["http://url.to/image.jpg"], // Required array
    "invoice_files": ["http://url.to/invoice.pdf"], // Optional array
    "meta": { "start": "Home", "end": "Airport" } // Optional generic data
  }
  

• Response (201 Created): Returns created item.

Update Item

Update an existing item.

• Endpoint: PUT /reimbursements/{reportId}/items/{itemId}
• Request Body: Same as Add Item (fields are optional/sometimes).

Delete Item

Remove an item from a draft report.

• Endpoint: DELETE /reimbursements/{reportId}/items/{itemId}
• Response (200 OK): {"message": "Item deleted"}

Approve Report (Admin Only)

Approve a submitted report.

• Endpoint: PUT /reimbursements/{id}/approve
• Response (200 OK): Returns report with status approved, audited_at, and auditor_id.

Reject Report (Admin Only)

Reject a submitted report.

• Endpoint: PUT /reimbursements/{id}/reject
• Request Body:

  {
    "reason": "Missing invoices for hotel."
  }
  

• Response (200 OK): Returns report with status rejected.

DingTalk Table (Generic)

Get Table Data

Fetch all records from a specified DingTalk AI Table (Notable). Supports generic filtering.

• Endpoint: GET /dingtalk/table

• Headers: Authorization: Bearer <token>

• cURL:

  curl -X GET "http://tuohua-work-api.test/api/dingtalk/table?table_id=TABLE_ID&sheet_id=SHEET_ID&Status=Active" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"
  

• Query Params:

  • table_id (string, required): The ID of the DingTalk Table App (Node ID).
  • sheet_id (string, required): The ID of the specific Sheet.
  • [Column Name] (optional): Any other query parameter is treated as a filter for that column name. (e.g., Status=Active, Name=John).

• Response (200 OK):

  {
    "success": true,
    "data": [
      {
        "_index": 1,
        "Name": "John Doe",
        "Status": "Active",
        "Phone": "13800138000",
        "Created At": "2025-01-01"
      },
      // ...
    ]
  }
  

• Error Response (422 Unprocessable Entity): Missing table_id or sheet_id.

  {
    "success": false,
    "message": "Validation Error",
    "errors": {
      "table_id": ["The table id field is required."]
    }
  }
  

• Error Response (500 Internal Server Error): DingTalk API error or other server issues.

  {
    "success": false,
    "message": "DingTalk API Error (invalidRequest.resource.notFound): The requested resource was not found..."
  }