Skip to Content
FrontendAppsPunchAPI Calls

API Calls

Table of Contents

  1. Introduction
  2. External API Endpoints
  3. Internal API Routes

Introduction

An overview of the API calls that we make in the app and its purpose. The API url is : https://demo-ecs.phpreaction.com/open-api/v3  The API Doc : https://phpreaction.com/interfaces-2025/support/utilisation-apiv4-phpreaction/ 

All external API calls go through the /api/callOut route which acts as a proxy to the external API.

External API Endpoints

Project Tasks

open-api/v3/project_tasks/{task_id}/

  • Description: Get a specific task by ID.
  • Method: GET
  • Used in: src/app/[locale]/task-details/[slug]/page.tsx - Task details page
  • Parameters:
    • Path: task_id - The ID of the task to retrieve
  • Role: ROLE_MOD_PROJECT_TASK_MANAGER_LISTING

open-api/v3/project_tasks/task_manager/listing/

  • Description: Get the task manager listing with filters and pagination.
  • Method: GET
  • Used in:
    • src/utils/getTasks.ts - getTasks() - Initial task loading
    • src/containers/TaskManager/index.tsx - searchFilters() - Filtered task search
  • Parameters:
    • Query/Filter:
      • page: Page number (e.g., 1)
      • itemsPerPage: Items per page (e.g., 25)
      • receiver: Array of employee IDs to filter by
      • status: Array of status IDs to filter by (e.g., [3, 4] for approved and in-progress)
      • sector: Array of sector IDs to filter by
      • priority: Array of priority IDs to filter by
      • project: Array of project IDs to filter by
      • order[deadline]: Sort order (e.g., asc or desc)
      • search: Search term for filtering tasks
  • Role: ROLE_MOD_PROJECT_TASK_MANAGER_LISTING

open-api/v3/project_tasks/{task_id}/task_manager/punch

  • Description: Punch in/out for a task (Punch-in, Punch-out, Punch-swap).
  • Method: POST
  • Used in:
    • src/components/ui/QuickPunchButton.tsx - quickPunchAPICall() - Quick punch action
    • src/components/ui/DescriptionModal.tsx - sendTimesheetModification() - Punch out with description
    • src/components/ui/TaskTable.tsx - Task table punch actions
  • Request Body:
{
  "csrf": "csrf_jwt_token",
  "description": "Punch description (optional)"
}
  • Role: ROLE_MOD_PROJECT_TASK_MANAGER_PUNCH

open-api/v3/project_tasks/dropdown/get/

  • Description: Get project tasks for a dropdown/search functionality.
  • Method: GET
  • Used in: Dropdown components for task selection
  • Parameters:
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_PROJECT_TASK_DROPDOWN

Timesheets

open-api/v3/timesheets/

  • Description: Get or create timesheets.
  • Method: GET & POST
  • Used in:
    • src/contexts/TimesheetContext.tsx - handleGetCurrentTimesheet() - Get current active timesheet
    • src/containers/TaskDetails/Body/index.tsx - handleGetTimesheets() - Get timesheets for a task
    • src/components/ui/AddTimesheetModal.tsx - onSubmit() - Create a new timesheet
  • GET Parameters:
    • Query/Filter:
      • employee: Employee ID
      • status: Timesheet status ID (e.g., 6 for in-progress)
      • exists[datetimeEnd]: Boolean filter (e.g., false for active timesheets)
      • entryMode: Entry mode ID (e.g., 2 for punch entry mode)
      • task: Task ID (for filtering timesheets by task)
      • page: Page number
      • itemsPerPage: Items per page
      • order[datetimeStart]: Sort order (e.g., desc)
  • POST Request Body:
{
  "csrf": "csrf_jwt_token",
  "employee": "/open-api/v3/person_employees/{employee_id}",
  "task": "/open-api/v3/project_tasks/{task_id}",
  "datetimeStart": "timestamp_in_milliseconds",
  "datetimeEnd": "timestamp_in_milliseconds",
  "description": "Timesheet description",
  "notes": "Additional notes",
  "entryMode": "/open-api/v3/timesheet_entry_modes/{entry_mode_id}",
  "status": "/open-api/v3/timesheet_statuses/{status_id}",
  "type": "/open-api/v3/timesheet_types/{type_id}",
  "ratio": "1",
  "slug": "uuid_v4",
  "chargeable": true
}
  • Role:
    • GET: ROLE_MOD_TIMESHEET_LISTING or ROLE_MOD_TIMESHEET_SHOW
    • POST: ROLE_MOD_TIMESHEET_ADD

open-api/v3/timesheets/dropdown/get/

  • Description: Get timesheets for a dropdown/search functionality.
  • Method: GET
  • Used in: Dropdown components for timesheet selection
  • Parameters:
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_TIMESHEET_DROPDOWN

Person Employees

open-api/v3/person_employees/{person_id}/

  • Description: Get person employee information by person ID.
  • Method: GET
  • Used in: Employee information retrieval
  • Parameters:
    • Path: person_id - The ID of the person
  • Role: ROLE_MOD_PERSON_EMPLOYEE

open-api/v3/person_employees/dropdown/get/

  • Description: Get person employees for a dropdown/search functionality.
  • Method: GET
  • Used in:
    • src/utils/getPersonEmployee.ts - getEmployee() - Get employee by person ID
    • src/containers/TaskManager/Filters/index.tsx - Employee filter dropdown
  • Parameters:
    • Query: person - Person ID to filter by
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_PERSON_EMPLOYEE_DROPDOWN

Projects

open-api/v3/projects/dropdown/get/

  • Description: Get projects for a dropdown/search functionality.
  • Method: GET
  • Used in: src/containers/TaskManager/Filters/index.tsx - Project filter dropdown
  • Parameters:
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_PROJECT_DROPDOWN

Project Statuses

open-api/v3/project_statuses/dropdown/get/

  • Description: Get project statuses for a dropdown.
  • Method: GET
  • Used in: src/containers/TaskManager/Filters/index.tsx - Status filter dropdown
  • Parameters:
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_PROJECT_STATUS_DROPDOWN

Project Sectors

open-api/v3/project_sectors/dropdown/get/

  • Description: Get project sectors for a dropdown.
  • Method: GET
  • Used in: src/containers/TaskManager/Filters/index.tsx - Sector filter dropdown
  • Parameters:
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_PROJECT_SECTOR_DROPDOWN

Project Priorities

open-api/v3/project_priorities/dropdown/get/

  • Description: Get project priorities for a dropdown.
  • Method: GET
  • Used in: src/containers/TaskManager/Filters/index.tsx - Priority filter dropdown
  • Parameters:
    • Query/Filter: Standard dropdown filters (page, itemsPerPage, search, etc.)
  • Role: ROLE_MOD_PROJECT_PRIORITY_DROPDOWN

Users

open-api/v3/users/logged_user_kvs/get/

  • Description: Get the logged user key-value store entries.
  • Method: GET
  • Used in: src/contexts/KVSContext.tsx - Get user KVS for configuration
  • Role: ROLE_MOD_TIMESHEET (for punch-related KVS)

open-api/v3/users/logged_user_roles/get/

  • Description: Get the logged user roles.
  • Method: GET
  • Used in: User role verification and authorization
  • Role: (No specific role required, uses current user context)

open-api/v3/users/logged_user_informations/get/

  • Description: Get the logged user information.
  • Method: GET
  • Used in: User information retrieval
  • Role: (No specific role required, uses current user context)

Status

open-api/v3/status/

  • Description: Get the API status.
  • Method: GET
  • Used in: Status checks and health monitoring
  • Role: (No specific role required)

Key-Value Store

open-api/v3/keyvaluestore_keyvalues

  • Description: Get or create key-value store entries.
  • Method: GET & POST
  • Used in: src/contexts/KVSContext.tsx - Store and retrieve user preferences
  • GET Parameters:
    • Query: user - User ID to filter by
    • Query: key - Key name to filter by
  • POST Request Body:
{
  "key": "key_name",
  "value": "value_string",
  "user": "/open-api/v3/users/{user_id}",
  "clearanceLevel": 7
}
  • Role:
    • GET: ROLE_MOD_KEYVALUESTORE_KEYVALUE_LISTING
    • POST: ROLE_MOD_KEYVALUESTORE_KEYVALUE_ADD

Internal API Routes

These are Next.js API routes that serve as endpoints within the application or proxy to external services.

/api/callOut

  • Description: Proxy route for all external API calls. Handles GET, POST, and PUT requests. Validates CSRF tokens and forwards requests to the external API.
  • Methods: GET, POST, PUT
  • Location: src/app/api/callOut/route.ts
  • Usage: All CallAPI() calls go through this route
  • CSRF Protection: Validates CSRF token from X-CSRF-TOKEN header

Status Routes

/api/status ------> [https://demo1.dev.punch.phpr.link/api/status ]

  • Description: Get basic status information.
  • Method: GET
  • Location: src/app/api/status/route.ts
  • Returns: {status: 'ok'}

/api/status/all ------> [https://demo1.dev.punch.phpr.link/api/status/all ]

  • Description: Get comprehensive status information including app info, API status, configs, cache, and user token.
  • Method: GET
  • Location: src/app/api/status/all/route.ts
  • Returns: Complete status information with app name, version, NextJS version, React version, etc.

/api/status/api ------> [https://demo1.dev.punch.phpr.link/api/status/api ]

  • Description: Get the status of the external API connection.
  • Method: GET
  • Location: src/app/api/status/api/route.ts

/api/status/configs ------> [https://demo.dev.punch.phpr.link/api/status/configs ]

  • Description: Get the status of configuration services.
  • Method: GET
  • Location: src/app/api/status/configs/route.ts
  • Returns: Configuration status including whether config API login is available

/api/status/cache ------> [https://demo.dev.punch.phpr.link/api/status/cache ]

  • Description: Get the status of cache tables (AppCache and ConfigCache).
  • Method: GET
  • Location: src/app/api/status/cache/route.ts
  • Returns: Cache status including table status, item count, creation date/time

/api/status/user-token/check ------> [https://demo.dev.punch.phpr.link/api/status/user-token/check ]

  • Description: Validate and check the user token.
  • Method: GET
  • Location: src/app/api/status/user-token/check/route.ts
  • Authentication: Reads token from currentUser cookie

/api/status/user-token/display ------> [https://demo.dev.punch.phpr.link/api/status/user-token/display ]

  • Description: Get user token display information.
  • Method: GET
  • Location: src/app/api/status/user-token/display/route.ts
  • Authentication: Reads token from currentUser cookie

/api/status/user-token/expected ------> [https://demo.dev.punch.phpr.link/api/status/user-token/expected ]

  • Description: Get expected user token information.
  • Method: GET
  • Location: src/app/api/status/user-token/expected/route.ts

Authentication Routes

/api/oauth/authorize

  • Description: Initiate OAuth 2.0 authorization code flow.
  • Method: GET
  • Location: src/app/api/oauth/authorize/route.ts
  • Flow: Authorization Code Flow (OAuth 2.0)

/api/oauth/callback

  • Description: Handle OAuth 2.0 callback after authorization.
  • Method: GET
  • Location: src/app/api/oauth/callback/route.ts

/api/logout

  • Description: Handle user logout.
  • Method: GET
  • Location: src/app/api/logout/route.ts

/api/configs-login

  • Description: Handle configuration-based login.
  • Method: POST
  • Location: src/app/api/config-login/route.ts

Cache Management

/api/clear-cache

  • Description: Clear all cache tables (requires ROLE_ADMIN).
  • Method: DELETE
  • Location: src/app/api/clear-cache/route.ts
  • Authorization: Requires ROLE_ADMIN role
  • Actions: Deletes all entries from AppCache and ConfigCache tables
Last updated on
phpreaction-frontend-punch-reactEnvironment Variables