feat: Complete Z.CRM system with all 6 modules
✨ Features: - Complete authentication system with JWT - Dashboard with all 6 modules visible - Contact Management module (Salesforce-style) - CRM & Sales Pipeline module (Pipedrive-style) - Inventory & Assets module (SAP-style) - Tasks & Projects module (Jira/Asana-style) - HR Management module (BambooHR-style) - Marketing Management module (HubSpot-style) - Admin Panel with user management and role matrix - World-class UI/UX with RTL Arabic support - Cairo font (headings) + Readex Pro font (body) - Sample data for all modules - Protected routes and authentication flow - Backend API with Prisma + PostgreSQL - Comprehensive documentation 🎨 Design: - Color-coded modules - Professional data tables - Stats cards with metrics - Progress bars and status badges - Search and filters - Responsive layout 📊 Tech Stack: - Frontend: Next.js 14, TypeScript, Tailwind CSS - Backend: Node.js, Express, Prisma - Database: PostgreSQL - Auth: JWT with bcrypt 🚀 Production-ready frontend with all features accessible
This commit is contained in:
Talal Sharabi
541
API_DOCUMENTATION.md
Normal file
541
API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,541 @@
|
||||
# Z.CRM - API Documentation
|
||||
## مجموعة أتمتة - توثيق واجهة برمجة التطبيقات
|
||||
|
||||
Base URL: `http://localhost:5000/api/v1`
|
||||
|
||||
## Authentication
|
||||
|
||||
All API endpoints (except `/auth/login` and `/auth/register`) require authentication via JWT token.
|
||||
|
||||
### Headers
|
||||
|
||||
```
|
||||
Authorization: Bearer <access_token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Authentication Endpoints
|
||||
|
||||
#### Login
|
||||
```http
|
||||
POST /auth/login
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"email": "gm@atmata.com",
|
||||
"password": "Admin@123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "تم تسجيل الدخول بنجاح - Login successful",
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"email": "gm@atmata.com",
|
||||
"employee": { ... }
|
||||
},
|
||||
"accessToken": "jwt_token",
|
||||
"refreshToken": "refresh_token",
|
||||
"expiresIn": "7d"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Refresh Token
|
||||
```http
|
||||
POST /auth/refresh
|
||||
```
|
||||
|
||||
#### Get Current User
|
||||
```http
|
||||
GET /auth/me
|
||||
```
|
||||
|
||||
#### Logout
|
||||
```http
|
||||
POST /auth/logout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 1: Contact Management
|
||||
|
||||
### Contacts
|
||||
|
||||
#### List All Contacts
|
||||
```http
|
||||
GET /contacts?page=1&pageSize=20&search=&type=&status=
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
- `page` (number): Page number
|
||||
- `pageSize` (number): Items per page
|
||||
- `search` (string): Search term
|
||||
- `type` (string): INDIVIDUAL, COMPANY, HOLDING, GOVERNMENT
|
||||
- `status` (string): ACTIVE, INACTIVE, ARCHIVED, BLOCKED
|
||||
- `category` (string): Category ID
|
||||
- `source` (string): Source type
|
||||
- `rating` (number): 1-5
|
||||
- `createdFrom` (date): Filter from date
|
||||
- `createdTo` (date): Filter to date
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalPages": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Contact by ID
|
||||
```http
|
||||
GET /contacts/:id
|
||||
```
|
||||
|
||||
**Response includes:**
|
||||
- Basic contact info
|
||||
- Categories
|
||||
- Parent/children (hierarchy)
|
||||
- Relationships
|
||||
- Activities (last 20)
|
||||
- Deals (last 10)
|
||||
- Notes
|
||||
- Attachments
|
||||
|
||||
#### Create Contact
|
||||
```http
|
||||
POST /contacts
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"type": "COMPANY",
|
||||
"name": "ABC Corporation",
|
||||
"nameAr": "شركة ABC",
|
||||
"email": "contact@abc.com",
|
||||
"phone": "+966112345678",
|
||||
"mobile": "+966501234567",
|
||||
"companyName": "ABC Corporation",
|
||||
"taxNumber": "123456789",
|
||||
"commercialRegister": "1010123456",
|
||||
"address": "123 King Fahd Road",
|
||||
"city": "Riyadh",
|
||||
"country": "Saudi Arabia",
|
||||
"source": "EXHIBITION",
|
||||
"categories": ["category-uuid-1"],
|
||||
"tags": ["VIP", "Tech"],
|
||||
"customFields": {}
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Contact
|
||||
```http
|
||||
PUT /contacts/:id
|
||||
```
|
||||
|
||||
#### Archive Contact
|
||||
```http
|
||||
POST /contacts/:id/archive
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"reason": "سبب الأرشفة"
|
||||
}
|
||||
```
|
||||
|
||||
#### Delete Contact (Hard Delete - GM Only)
|
||||
```http
|
||||
DELETE /contacts/:id
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"reason": "سبب الحذف النهائي"
|
||||
}
|
||||
```
|
||||
|
||||
#### Merge Contacts
|
||||
```http
|
||||
POST /contacts/merge
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"sourceId": "uuid",
|
||||
"targetId": "uuid",
|
||||
"reason": "سبب الدمج"
|
||||
}
|
||||
```
|
||||
|
||||
#### Add Relationship
|
||||
```http
|
||||
POST /contacts/:id/relationships
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"toContactId": "uuid",
|
||||
"type": "REPRESENTATIVE",
|
||||
"startDate": "2024-01-01"
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Contact History
|
||||
```http
|
||||
GET /contacts/:id/history
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 2: CRM
|
||||
|
||||
### Deals
|
||||
|
||||
#### List All Deals
|
||||
```http
|
||||
GET /crm/deals?page=1&pageSize=20&structure=B2B&stage=OPEN&status=ACTIVE&ownerId=&fiscalYear=2024
|
||||
```
|
||||
|
||||
#### Get Deal by ID
|
||||
```http
|
||||
GET /crm/deals/:id
|
||||
```
|
||||
|
||||
**Response includes:**
|
||||
- Deal info
|
||||
- Contact info
|
||||
- Owner info
|
||||
- Pipeline & stages
|
||||
- Quotes (all versions)
|
||||
- Cost sheets
|
||||
- Activities (last 20)
|
||||
- Notes
|
||||
- Attachments
|
||||
- Contracts
|
||||
- Invoices
|
||||
|
||||
#### Create Deal
|
||||
```http
|
||||
POST /crm/deals
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "ABC Corp - ERP System",
|
||||
"contactId": "uuid",
|
||||
"structure": "B2B",
|
||||
"pipelineId": "uuid",
|
||||
"stage": "OPEN",
|
||||
"estimatedValue": 500000,
|
||||
"probability": 70,
|
||||
"expectedCloseDate": "2024-06-30",
|
||||
"ownerId": "uuid",
|
||||
"fiscalYear": 2024
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Deal
|
||||
```http
|
||||
PUT /crm/deals/:id
|
||||
```
|
||||
|
||||
#### Update Deal Stage
|
||||
```http
|
||||
PATCH /crm/deals/:id/stage
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"stage": "NEGOTIATION"
|
||||
}
|
||||
```
|
||||
|
||||
#### Win Deal
|
||||
```http
|
||||
POST /crm/deals/:id/win
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"actualValue": 480000,
|
||||
"wonReason": "Competitive pricing and good proposal"
|
||||
}
|
||||
```
|
||||
|
||||
#### Lose Deal
|
||||
```http
|
||||
POST /crm/deals/:id/lose
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"lostReason": "Client chose competitor"
|
||||
}
|
||||
```
|
||||
|
||||
### Quotes
|
||||
|
||||
#### Get Quotes for Deal
|
||||
```http
|
||||
GET /crm/deals/:dealId/quotes
|
||||
```
|
||||
|
||||
#### Get Quote by ID
|
||||
```http
|
||||
GET /crm/quotes/:id
|
||||
```
|
||||
|
||||
#### Create Quote
|
||||
```http
|
||||
POST /crm/quotes
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"dealId": "uuid",
|
||||
"items": [
|
||||
{
|
||||
"description": "Software License",
|
||||
"quantity": 10,
|
||||
"unitPrice": 5000,
|
||||
"total": 50000
|
||||
}
|
||||
],
|
||||
"subtotal": 50000,
|
||||
"taxRate": 15,
|
||||
"taxAmount": 7500,
|
||||
"total": 57500,
|
||||
"validUntil": "2024-03-31",
|
||||
"paymentTerms": "Net 30",
|
||||
"deliveryTerms": "On-site installation",
|
||||
"notes": "Special offer for Q1 2024"
|
||||
}
|
||||
```
|
||||
|
||||
#### Approve Quote
|
||||
```http
|
||||
POST /crm/quotes/:id/approve
|
||||
```
|
||||
|
||||
#### Send Quote
|
||||
```http
|
||||
POST /crm/quotes/:id/send
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 3: Inventory & Assets
|
||||
|
||||
### Products
|
||||
```http
|
||||
GET /inventory/products
|
||||
POST /inventory/products
|
||||
PUT /inventory/products/:id
|
||||
DELETE /inventory/products/:id
|
||||
```
|
||||
|
||||
### Warehouses
|
||||
```http
|
||||
GET /inventory/warehouses
|
||||
POST /inventory/warehouses
|
||||
GET /inventory/warehouses/:id
|
||||
```
|
||||
|
||||
### Inventory Items
|
||||
```http
|
||||
GET /inventory/items?warehouseId=&productId=
|
||||
```
|
||||
|
||||
### Assets
|
||||
```http
|
||||
GET /inventory/assets
|
||||
POST /inventory/assets
|
||||
GET /inventory/assets/:id
|
||||
PUT /inventory/assets/:id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 4: Projects & Tasks
|
||||
|
||||
### Projects
|
||||
```http
|
||||
GET /projects/projects
|
||||
POST /projects/projects
|
||||
GET /projects/projects/:id
|
||||
PUT /projects/projects/:id
|
||||
DELETE /projects/projects/:id
|
||||
```
|
||||
|
||||
### Tasks
|
||||
```http
|
||||
GET /projects/tasks?projectId=&assignedToId=&status=
|
||||
POST /projects/tasks
|
||||
GET /projects/tasks/:id
|
||||
PUT /projects/tasks/:id
|
||||
DELETE /projects/tasks/:id
|
||||
```
|
||||
|
||||
**Task Statuses:**
|
||||
- TODO
|
||||
- IN_PROGRESS
|
||||
- REVIEW
|
||||
- COMPLETED
|
||||
- CANCELLED
|
||||
|
||||
---
|
||||
|
||||
## Module 5: HR Management
|
||||
|
||||
### Employees
|
||||
```http
|
||||
GET /hr/employees?departmentId=&status=
|
||||
POST /hr/employees
|
||||
GET /hr/employees/:id
|
||||
PUT /hr/employees/:id
|
||||
POST /hr/employees/:id/terminate
|
||||
```
|
||||
|
||||
### Attendance
|
||||
```http
|
||||
GET /hr/attendance/:employeeId?month=1&year=2024
|
||||
POST /hr/attendance
|
||||
```
|
||||
|
||||
### Leaves
|
||||
```http
|
||||
GET /hr/leaves
|
||||
POST /hr/leaves
|
||||
POST /hr/leaves/:id/approve
|
||||
POST /hr/leaves/:id/reject
|
||||
```
|
||||
|
||||
### Salaries
|
||||
```http
|
||||
POST /hr/salaries/process
|
||||
GET /hr/salaries?employeeId=&month=&year=
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module 6: Marketing
|
||||
|
||||
### Campaigns
|
||||
```http
|
||||
GET /marketing/campaigns?type=EMAIL&status=RUNNING
|
||||
POST /marketing/campaigns
|
||||
GET /marketing/campaigns/:id
|
||||
PUT /marketing/campaigns/:id
|
||||
POST /marketing/campaigns/:id/approve
|
||||
POST /marketing/campaigns/:id/launch
|
||||
GET /marketing/campaigns/:id/stats
|
||||
```
|
||||
|
||||
**Campaign Types:**
|
||||
- EMAIL
|
||||
- WHATSAPP
|
||||
- SOCIAL
|
||||
- EXHIBITION
|
||||
- MULTI_CHANNEL
|
||||
|
||||
**Campaign Statuses:**
|
||||
- DRAFT
|
||||
- PENDING_APPROVAL
|
||||
- APPROVED
|
||||
- SCHEDULED
|
||||
- RUNNING
|
||||
- COMPLETED
|
||||
- CANCELLED
|
||||
|
||||
---
|
||||
|
||||
## Common Response Format
|
||||
|
||||
### Success Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Operation completed successfully",
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Paginated Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalPages": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Error message in Arabic and English",
|
||||
"error": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | HTTP Status | Description |
|
||||
|------|-------------|-------------|
|
||||
| UNAUTHORIZED | 401 | Missing or invalid token |
|
||||
| FORBIDDEN | 403 | Insufficient permissions |
|
||||
| NOT_FOUND | 404 | Resource not found |
|
||||
| VALIDATION_ERROR | 400 | Invalid input data |
|
||||
| DUPLICATE_RECORD | 409 | Duplicate entry |
|
||||
| INTERNAL_ERROR | 500 | Server error |
|
||||
|
||||
## Permissions System
|
||||
|
||||
Each endpoint requires specific permissions based on:
|
||||
- **Module**: contacts, crm, inventory, etc.
|
||||
- **Resource**: contacts, deals, products, etc.
|
||||
- **Action**: create, read, update, delete, approve, etc.
|
||||
|
||||
Permissions are managed through the HR module and assigned to positions.
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- **Window**: 15 minutes
|
||||
- **Max Requests**: 100 per window
|
||||
- Headers included in response:
|
||||
- `X-RateLimit-Limit`
|
||||
- `X-RateLimit-Remaining`
|
||||
- `X-RateLimit-Reset`
|
||||
|
||||
---
|
||||
|
||||
**For complete module-specific API documentation, see the source code in `/backend/src/modules/`**
|
||||
|
||||
Reference in New Issue
Block a user