Branches

Branches represent physical locations, offices, or outlets that belong to the company. Each user is assigned to a branch, and branches can be used to scope data and reports by location.

Purpose

• Model the company's physical locations (headquarters, regional offices, warehouses)
• Assign users to specific branches
• Support filtering and reporting by branch
• Designate one branch as the main (headquarters) branch

Entity Attributes

Field	Type	Description
id	integer	Primary key
company_id	integer	Foreign key to the company
name	string	Branch name (English)
name_ar	string	Branch name (Arabic)
code	string	Short code (e.g., HQ, SB)
phone	string?	Branch phone number
email	string?	Branch email address
address	string?	Address (English)
address_ar	string?	Address (Arabic)
city	string?	City name
country	string?	Country code (e.g., KW)
is_active	boolean	Whether the branch is active
is_main	boolean	Whether this is the main (HQ) branch
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp
deleted_at	datetime?	Soft-delete timestamp

Relationships

API Endpoints

Method	Path	Description
GET	/api/core/branches	List all branches (paginated)
POST	/api/core/branches	Create a new branch
GET	/api/core/branches/{id}	Get a specific branch
PUT	/api/core/branches/{id}	Update a branch
DELETE	/api/core/branches/{id}	Soft-delete a branch

Request/Response Examples

GET /api/core/branches

Retrieve a paginated list of branches.

curl

curl -X GET https://moon-erp.test/api/core/branches \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

Dart

final response = await http.get(
  Uri.parse('https://moon-erp.test/api/core/branches'),
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer $token',
  },
);

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "company_id": 1,
      "name": "Main Branch",
      "name_en": "Main Branch",
      "name_ar": "الفرع الرئيسي",
      "code": "HQ",
      "phone": "+965-22334455",
      "email": "hq@moon-trading.com",
      "address": "Gulf Road, Kuwait City",
      "city": "Kuwait City",
      "country": "KW",
      "is_active": true,
      "is_main": true,
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z"
    },
    {
      "id": 2,
      "company_id": 1,
      "name": "South Branch",
      "name_en": "South Branch",
      "name_ar": "الفرع الجنوبي",
      "code": "SB",
      "phone": "+965-22998877",
      "email": "south@moon-trading.com",
      "address": "Fahaheel, Block 2",
      "city": "Fahaheel",
      "country": "KW",
      "is_active": true,
      "is_main": false,
      "created_at": "2026-01-15T10:00:00.000000Z",
      "updated_at": "2026-01-15T10:00:00.000000Z"
    }
  ],
  "links": { "first": "...?page=1", "last": "...?page=1", "prev": null, "next": null },
  "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 25, "to": 2, "total": 2 }
}

POST /api/core/branches

Create a new branch.

curl

curl -X POST https://moon-erp.test/api/core/branches \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "name": "North Branch",
    "name_ar": "الفرع الشمالي",
    "code": "NB",
    "phone": "+965-22112233",
    "email": "north@moon-trading.com",
    "address": "Jahra, Block 1",
    "address_ar": "الجهراء، قطعة 1",
    "city": "Jahra",
    "country": "KW",
    "is_active": true,
    "is_main": false
  }'

Dart

final response = await http.post(
  Uri.parse('https://moon-erp.test/api/core/branches'),
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer $token',
  },
  body: jsonEncode({
    'name': 'North Branch',
    'name_ar': 'الفرع الشمالي',
    'code': 'NB',
    'phone': '+965-22112233',
    'city': 'Jahra',
    'country': 'KW',
    'is_active': true,
    'is_main': false,
  }),
);

Response 201 Created

{
  "data": {
    "id": 3,
    "company_id": 1,
    "name": "North Branch",
    "name_en": "North Branch",
    "name_ar": "الفرع الشمالي",
    "code": "NB",
    "phone": "+965-22112233",
    "email": "north@moon-trading.com",
    "address": "Jahra, Block 1",
    "city": "Jahra",
    "country": "KW",
    "is_active": true,
    "is_main": false,
    "created_at": "2026-02-16T10:00:00.000000Z",
    "updated_at": "2026-02-16T10:00:00.000000Z"
  }
}

DELETE /api/core/branches/{id}

Soft-delete a branch.

curl

curl -X DELETE https://moon-erp.test/api/core/branches/3 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

Dart

final response = await http.delete(
  Uri.parse('https://moon-erp.test/api/core/branches/3'),
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer $token',
  },
);

Response 200 OK

{
  "message": "Deleted"
}

Business Rules

• Company scoping -- branches are automatically scoped to the authenticated user's company. You cannot access branches from another company.
• company_id auto-assigned -- when creating a branch, the company_id is set from the authenticated user. Do not send it in the request body.
• One main branch -- only one branch should have is_main set to true. This represents the company headquarters.
• Soft deletes -- deleting a branch performs a soft delete. The record is retained in the database with a deleted_at timestamp.
• Users depend on branches -- users are assigned to branches via branch_id. Deleting a branch does not cascade to users.
• Code uniqueness -- the code field should be unique within the company to avoid confusion (e.g., HQ, SB, NB).