zerp/API_DOCUMENTATION.md

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

POST /auth/login

Request Body:

{
  "email": "gm@atmata.com",
  "password": "Admin@123"
}

Response:

{
  "success": true,
  "message": "تم تسجيل الدخول بنجاح - Login successful",
  "data": {
    "user": {
      "id": "uuid",
      "email": "gm@atmata.com",
      "employee": { ... }
    },
    "accessToken": "jwt_token",
    "refreshToken": "refresh_token",
    "expiresIn": "7d"
  }
}

Refresh Token

POST /auth/refresh

Get Current User

GET /auth/me

Logout

POST /auth/logout

---

Module 1: Contact Management

Contacts

List All Contacts

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:

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

Get Contact by ID

GET /contacts/:id

Response includes:

• Basic contact info
• Categories
• Parent/children (hierarchy)
• Relationships
• Activities (last 20)
• Deals (last 10)
• Notes
• Attachments

Create Contact

POST /contacts

Request Body:

{
  "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

PUT /contacts/:id

Archive Contact

POST /contacts/:id/archive

Request Body:

{
  "reason": "سبب الأرشفة"
}

Delete Contact (Hard Delete - GM Only)

DELETE /contacts/:id

Request Body:

{
  "reason": "سبب الحذف النهائي"
}

Merge Contacts

POST /contacts/merge

Request Body:

{
  "sourceId": "uuid",
  "targetId": "uuid",
  "reason": "سبب الدمج"
}

Add Relationship

POST /contacts/:id/relationships

Request Body:

{
  "toContactId": "uuid",
  "type": "REPRESENTATIVE",
  "startDate": "2024-01-01"
}

Get Contact History

GET /contacts/:id/history

---

Module 2: CRM

Deals

List All Deals

GET /crm/deals?page=1&pageSize=20&structure=B2B&stage=OPEN&status=ACTIVE&ownerId=&fiscalYear=2024

Get Deal by ID

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

POST /crm/deals

Request Body:

{
  "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

PUT /crm/deals/:id

Update Deal Stage

PATCH /crm/deals/:id/stage

Request Body:

{
  "stage": "NEGOTIATION"
}

Win Deal

POST /crm/deals/:id/win

Request Body:

{
  "actualValue": 480000,
  "wonReason": "Competitive pricing and good proposal"
}

Lose Deal

POST /crm/deals/:id/lose

Request Body:

{
  "lostReason": "Client chose competitor"
}

Quotes

Get Quotes for Deal

GET /crm/deals/:dealId/quotes

Get Quote by ID

GET /crm/quotes/:id

Create Quote

POST /crm/quotes

Request Body:

{
  "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

POST /crm/quotes/:id/approve

Send Quote

POST /crm/quotes/:id/send

---

Module 3: Inventory & Assets

Products

GET    /inventory/products
POST   /inventory/products
PUT    /inventory/products/:id
DELETE /inventory/products/:id

Warehouses

GET    /inventory/warehouses
POST   /inventory/warehouses
GET    /inventory/warehouses/:id

Inventory Items

GET /inventory/items?warehouseId=&productId=

Assets

GET    /inventory/assets
POST   /inventory/assets
GET    /inventory/assets/:id
PUT    /inventory/assets/:id

---

Module 4: Projects & Tasks

Projects

GET    /projects/projects
POST   /projects/projects
GET    /projects/projects/:id
PUT    /projects/projects/:id
DELETE /projects/projects/:id

Tasks

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

GET    /hr/employees?departmentId=&status=
POST   /hr/employees
GET    /hr/employees/:id
PUT    /hr/employees/:id
POST   /hr/employees/:id/terminate

Attendance

GET  /hr/attendance/:employeeId?month=1&year=2024
POST /hr/attendance

Leaves

GET  /hr/leaves
POST /hr/leaves
POST /hr/leaves/:id/approve
POST /hr/leaves/:id/reject

Salaries

POST /hr/salaries/process
GET  /hr/salaries?employeeId=&month=&year=

---

Module 6: Marketing

Campaigns

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

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Paginated Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

Error Response

{
  "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/