Digital - API Contracts

Generated: 2025-10-16 API Type: RESTful JSON API Authentication: Laravel Sanctum (Bearer token) Base URL: /api/

API Overview

Total Controllers: 99 API controllers
Route File: /routes/api.php (~1,775 lines)
Authentication: All routes require auth:sanctum middleware
Response Format: JSON
Versioning: Not versioned (single version)

Authentication

Auth Endpoints

POST   /api/auth/login              # Login with email/password
POST   /api/auth/register           # Register new account
POST   /api/auth/logout             # Logout current session
POST   /api/auth/refresh            # Refresh auth token
POST   /api/auth/forgot-password    # Request password reset
POST   /api/auth/reset-password     # Reset password with token
POST   /api/auth/phone-auth         # SMS-based authentication
POST   /api/auth/verify-phone       # Verify SMS code

Request Headers

Authorization: Bearer {sanctum_token}
Content-Type: application/json
Accept: application/json

API Controllers by Module

HR & User Management Module

UserController

Purpose: Employee/user account management

Standard CRUD: GET /api/users # List users (filtered by permissions) POST /api/users # Create new user GET /api/users/{id} # Get user details PUT /api/users/{id} # Update user DELETE /api/users/{id} # Deactivate user (soft delete)

Additional Endpoints: GET /api/users/{id}/subordinates # Get subordinate users GET /api/users/{id}/skills # Get user skills POST /api/users/{id}/skills # Assign skill DELETE /api/users/{id}/skills/{skillId} # Remove skill GET /api/users/{id}/evaluations # Get evaluations GET /api/users/{id}/documents # Get user files POST /api/users/{id}/avatar # Upload avatar PUT /api/users/{id}/password # Change password PUT /api/users/{id}/settings # Update settings POST /api/users/{id}/assign-right # Assign permission

DepartmentController

Purpose: Organizational department management

GET    /api/departments                # List departments
POST   /api/departments                # Create department
GET    /api/departments/{id}           # Get details
PUT    /api/departments/{id}           # Update
DELETE /api/departments/{id}           # Delete
GET    /api/departments/{id}/users     # Department members
GET    /api/departments/{id}/children  # Child departments
GET    /api/departments/tree           # Full hierarchy tree

RoleController

Purpose: Job position management (NOT permissions)

GET    /api/roles                      # List roles
POST   /api/roles                      # Create role
GET    /api/roles/{id}                 # Get details
PUT    /api/roles/{id}                 # Update
DELETE /api/roles/{id}                 # Delete
GET    /api/roles/{id}/users           # Users with this role
GET    /api/roles/{id}/procedures      # Role procedures
POST   /api/roles/{id}/responsibilities # Add responsibility

Other HR Controllers

Controller	Purpose
`RightController`	Permission management
`SkillController`	Skills catalog management
`UserFileController`	Employee document management
`UserEvaluationController`	Performance evaluations
`EvaluationBonusController`	Bonus system
`VacantJobController`	Job posting management
`OrganizationalChartController`	Org chart visualization

CRM Module

DealController

Purpose: Sales deal management

GET    /api/deals                      # List deals (filtered)
POST   /api/deals                      # Create deal
GET    /api/deals/{id}                 # Get details
PUT    /api/deals/{id}                 # Update deal
DELETE /api/deals/{id}                 # Delete deal
POST   /api/deals/{id}/move-stage      # Move to different stage
GET    /api/deals/{id}/history         # Deal change history
POST   /api/deals/{id}/comment         # Add comment
GET    /api/deals/{id}/comments        # List comments
POST   /api/deals/{id}/attach-file     # Attach document

OrganizationController

Purpose: Company/client organization management

GET    /api/organizations              # List organizations
POST   /api/organizations              # Create organization
GET    /api/organizations/{id}         # Get details
PUT    /api/organizations/{id}         # Update
DELETE /api/organizations/{id}         # Delete
GET    /api/organizations/{id}/deals   # Organization deals
GET    /api/organizations/{id}/persons # Contact persons
POST   /api/organizations/{id}/merge   # Merge with another org

PersonController

Purpose: Individual contact management

GET    /api/persons                    # List persons
POST   /api/persons                    # Create person
GET    /api/persons/{id}               # Get details
PUT    /api/persons/{id}               # Update
DELETE /api/persons/{id}               # Delete
GET    /api/persons/{id}/deals         # Person's deals
GET    /api/persons/{id}/organizations # Linked organizations

Other CRM Controllers

Controller	Purpose
`PipelineController`	Sales pipeline management
`StageController`	Deal stage configuration
`DealSourceController`	Lead source tracking
`ActivityController`	Activity logging
`DiscountLinkController`	Discount/promo management
`BrandController`	Brand/product line management

Projects & Tasks Module

ProjectController

Purpose: Project management

GET    /api/projects                   # List projects
POST   /api/projects                   # Create project
GET    /api/projects/{id}              # Get details
PUT    /api/projects/{id}              # Update
DELETE /api/projects/{id}              # Delete
GET    /api/projects/{id}/tasks        # Project tasks
GET    /api/projects/{id}/members      # Project team
POST   /api/projects/{id}/add-member   # Add team member
POST   /api/projects/{id}/meetings     # Schedule meeting

TaskController

Purpose: Task management and assignment

GET    /api/tasks                      # List tasks (filtered)
POST   /api/tasks                      # Create task
GET    /api/tasks/{id}                 # Get details
PUT    /api/tasks/{id}                 # Update
DELETE /api/tasks/{id}                 # Delete
POST   /api/tasks/{id}/assign          # Assign to user
POST   /api/tasks/{id}/complete        # Mark complete
POST   /api/tasks/{id}/start-timer     # Start time tracking
POST   /api/tasks/{id}/stop-timer      # Stop time tracking
GET    /api/tasks/{id}/watchers        # Task watchers
POST   /api/tasks/{id}/add-watcher     # Add watcher
GET    /api/tasks/{id}/comments        # Task comments
GET    /api/tasks/{id}/logs            # Task activity logs

Other Project Controllers

Controller	Purpose
`MeetingController`	Meeting management
`MeetingSessionController`	Meeting execution tracking
`MeetingSummaryController`	Meeting notes/minutes
`TaskTimerController`	Time tracking
`ChecklistController`	Task checklist management
`PromiseController`	Commitment tracking

Procedures Module

ProcedureController

Purpose: Business process documentation

GET    /api/procedures                 # List procedures
POST   /api/procedures                 # Create procedure
GET    /api/procedures/{id}            # Get details
PUT    /api/procedures/{id}            # Update
DELETE /api/procedures/{id}            # Delete (archive)
POST   /api/procedures/{id}/execute    # Start execution
GET    /api/procedures/{id}/history    # Execution history
GET    /api/procedures/{id}/analytics  # Performance metrics

ProcedureLogController

Purpose: Procedure execution tracking

GET    /api/procedure-logs             # List executions
GET    /api/procedure-logs/{id}        # Get execution details
POST   /api/procedure-logs/{id}/submit # Submit completed step
GET    /api/procedure-logs/{id}/progress # Execution progress

Other Procedure Controllers

Controller	Purpose
`ProcessController`	Process definition management
`ProcessVersionController`	Process versioning
`ProcedureCheckController`	Procedure checklist items
`ProcedureApprovalRequestController`	Approval workflows
`ProcedureAnalyticController`	Procedure analytics

OKR Module

ObjectiveController

Purpose: Objective management

GET    /api/objectives                 # List objectives
POST   /api/objectives                 # Create objective
GET    /api/objectives/{id}            # Get details
PUT    /api/objectives/{id}            # Update
DELETE /api/objectives/{id}            # Delete
GET    /api/objectives/{id}/key-results # Linked key results

KeyResultController

Purpose: Key result tracking

GET    /api/key-results                # List key results
POST   /api/key-results                # Create key result
GET    /api/key-results/{id}           # Get details
PUT    /api/key-results/{id}           # Update
DELETE /api/key-results/{id}           # Delete
POST   /api/key-results/{id}/log-progress # Log progress update
GET    /api/key-results/{id}/logs      # Progress history

Other OKR Controllers

Controller	Purpose
`MasterGoalController`	Company-wide goal management
`IndicatorController`	KPI indicators
`IndicatorLogController`	KPI tracking logs

Vacation Module

VacationDayController

Purpose: Vacation request management

GET    /api/vacation-days              # List vacation requests
POST   /api/vacation-days              # Create request
GET    /api/vacation-days/{id}         # Get details
PUT    /api/vacation-days/{id}         # Update
DELETE /api/vacation-days/{id}         # Cancel request
POST   /api/vacation-days/{id}/approve # Approve request
POST   /api/vacation-days/{id}/reject  # Reject request
GET    /api/vacation-days/balance      # User vacation balance

Other Vacation Controllers

Controller	Purpose
`VacationTypeController`	Vacation type configuration (paid, sick, etc.)
`VacationPlannerController`	Team vacation planning
`VacationExcuseController`	Medical excuse documentation
`VacationApprovalController`	Approval workflow
`UserVacationDayController`	User-specific vacation management

Asset Management Module

AssetManagementController

Purpose: Asset catalog management

GET    /api/asset-management            # List asset types
POST   /api/asset-management            # Create asset type
GET    /api/asset-management/{id}       # Get details
PUT    /api/asset-management/{id}       # Update
DELETE /api/asset-management/{id}       # Delete

AssetManagementItemController

Purpose: Individual asset tracking

GET    /api/asset-items                 # List assets
POST   /api/asset-items                 # Add new asset
GET    /api/asset-items/{id}            # Get details
PUT    /api/asset-items/{id}            # Update
DELETE /api/asset-items/{id}            # Delete
POST   /api/asset-items/{id}/assign     # Assign to user
POST   /api/asset-items/{id}/return     # Return asset
GET    /api/asset-items/{id}/history    # Assignment history

Other Asset Controllers

Controller	Purpose
`AssetManagementTemplateController`	Asset templates
`WorkstationController`	Workstation/desk management
`CategoryController`	Asset categorization

AI Module

AIController

Purpose: AI feature orchestration

POST   /api/ai/generate                 # Generate AI content
POST   /api/ai/chat                     # Chat with AI agent
GET    /api/ai/threads                  # List conversation threads
POST   /api/ai/threads                  # Create new thread
GET    /api/ai/threads/{id}             # Get thread messages
POST   /api/ai/embed                    # Generate embeddings
POST   /api/ai/search                   # Semantic search

Other AI Controllers

Controller	Purpose
`AiAgentController`	AI agent management
`AiModelController`	AI model configuration
`AiPromptController`	Prompt template management
`AiThreadController`	Conversation threading

Shared/Universal Controllers

CommentController

Purpose: Universal commenting system (polymorphic)

POST   /api/comments                    # Create comment
PUT    /api/comments/{id}               # Update comment
DELETE /api/comments/{id}               # Delete comment

Usage: Attach to any commentable entity (Task, Deal, Meeting, etc.)

TagController

Purpose: Universal tagging system (polymorphic)

GET    /api/tags                        # List tags
POST   /api/tags                        # Create tag
PUT    /api/tags/{id}                   # Update tag
DELETE /api/tags/{id}                   # Delete tag
POST   /api/tags/attach                 # Attach tag to entity
POST   /api/tags/detach                 # Detach tag

FileController

Purpose: File upload and management

POST   /api/files/upload                # Upload file
GET    /api/files/{id}                  # Get file metadata
GET    /api/files/{id}/download         # Download file
DELETE /api/files/{id}                  # Delete file

NotificationLogController

Purpose: In-app notification management

GET    /api/notifications               # List user notifications
GET    /api/notifications/{id}          # Get notification
POST   /api/notifications/{id}/mark-read # Mark as read
POST   /api/notifications/mark-all-read # Mark all read
DELETE /api/notifications/{id}          # Delete notification

Other Shared Controllers

Controller	Purpose
`CustomFieldController`	Dynamic field management
`CustomFieldSectionController`	Field section organization
`DashboardController`	Dashboard data aggregation
`FeedController`	Activity feed
`SearchController`	Global search
`ReportController`	Report generation
`MailController`	Email management

Standard Response Formats

Success Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Example Resource",
    "created_at": "2025-10-16T12:00:00Z"
  },
  "message": "Operation successful"
}

Error Response

{
  "success": false,
  "message": "Validation error",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name must be at least 3 characters."]
  }
}

Paginated List Response

{
  "success": true,
  "data": {
    "data": [
      {"id": 1, "name": "Item 1"},
      {"id": 2, "name": "Item 2"}
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3
  }
}

Common Query Parameters

Filtering

GET /api/users?department_id=5&status=active
GET /api/deals?pipeline_id=2&stage_id=10
GET /api/tasks?assigned_to=15&status=pending

Pagination

GET /api/users?page=2&per_page=25

Sorting

GET /api/deals?sort_by=created_at&order=desc
GET /api/users?sort_by=name&order=asc

Search

GET /api/users?search=john
GET /api/organizations?search=acme

Includes (Eager Loading)

GET /api/users?include=department,role,skills
GET /api/deals?include=organization,person,stage

Error Status Codes

Code	Meaning
`200`	Success
`201`	Resource created
`204`	Success, no content
`400`	Bad request
`401`	Unauthorized (invalid/missing token)
`403`	Forbidden (insufficient permissions)
`404`	Resource not found
`422`	Validation error
`429`	Too many requests (rate limit)
`500`	Server error

Rate Limiting

Throttle: 60 requests per minute per authenticated user

Headers: X-RateLimit-Limit: 60 X-RateLimit-Remaining: 42 X-RateLimit-Reset: 1634567890