Companies

Company management endpoints: list, create, view, update (with image upload), archive, restore, and delete.

Common Notes

• Most endpoints require authentication.
• Access is controlled by policies (viewAny, view, create, update, archive, restore, delete).

---

​

Get All Companies

GET /api/companies

Returns a paginated list of companies, with optional search by label.

Authorization

• Policy: viewAny on Company

Query Params

Field	Type	Required	Description
per_page	integer	❌ No	Items per page. Default: 10
page	integer	❌ No	Page number. Default: 1
search	string	❌ No	Search by label (LIKE query)

Response Shape The API returns:

• data: array of companies (simplified fields)
• pagination: only per_page and page

Each company may include company_image if available:

• id
• file_name
• url

Response

200

✅ 200 OK

{
  "data": [
    {
      "id": 1,
      "company_id": null,
      "label": "Acme Academy",
      "description": "Training company",
      "currency": "TND",
      "company_image_id": 12,
      "created_at": "2026-01-01T10:00:00.000000Z",
      "updated_at": "2026-01-05T10:00:00.000000Z",
      "archived_at": null,
      "deleted_at": null,
      "company_image": {
        "id": 12,
        "file_name": "1700000000_logo.png",
        "url": "files/1700000000_logo.png"
      }
    }
  ],
  "pagination": {
    "per_page": 10,
    "page": 1
  }
}

500

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." } 

​

Create Company

POST /api/companies

Creates a new company. Optionally accepts an uploaded image (company_image) and stores it under public/files.

Authorization

• Policy: create on Company

Content-Type This endpoint supports file upload, so use:

Name	Value
Content-Type	multipart/form-data

Body (Validation Rules)

Field	Type	Required	Description
company_id	integer	❌ No	Must exist in companies table.
label	string	✅ Yes	min 1, max 255
description	string	✅ Yes	min 1
currency	string	✅ Yes	min 1, max 255
company_image	file	❌ No	Image file (jpeg/png/jpg/gif/svg), max 5MB

Example (multipart)

• label: Acme Academy

• description: Training company

• currency: TND

• company_image: (file upload)

Response

200

✅ 200 OK

{ "message": "Company created successfully" } 

422

⚠️ 422 Validation Error

{ 
    "message": "The label field is required.", 
    "errors": 
    { 
        "label": ["The label field is required."] 
    } 
} 

500

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." } 

Notes If company_image is uploaded:

• A File record is created

• The file is stored under public/files

• The company is updated with company_image_id

​

Get Company By ID

GET /api/companies/{id}

Returns a single company (simplified fields) with optional company_image.

Authorization

• Policy: view on Company

Path Params

Param	Type	Required	Description
id	integer	✅ Yes	Company ID

Response

200

✅ 200 OK

{ 
    "id": 1, 
    "company_id": null, 
    "label": "Acme Academy", 
    "description": "Training company", 
    "currency": "TND", 
    "company_image_id": 12, 
    "created_at": "2026-01-01T10:00:00.000000Z", 
    "updated_at": "2026-01-05T10:00:00.000000Z", 
    "archived_at": null, 
    "deleted_at": null, 
    "company_image": 
    { 
        "id": 12, 
        "file_name": "1700000000_logo.png", 
        "url": "files/1700000000_logo.png" 
    } 
} 

404

❌ 404 Not Found

{ "message": "No query results for model" } 

​

Update Company

POST /api/companies/

Updates company fields and optionally replaces company_image.

Authorization

• Policy: update on Company

Content-Type

Name	Value
Content-Type	multipart/form-data

Body (Validation Rules)

Field	Type	Required	Description
company_id	integer	❌ No	Must exist in companies table
label	string	❌ No	min 1, max 255
description	string	❌ No	min 1
currency	string	❌ No	min 1, max 255
company_image	file	❌ No	Image file (jpeg/png/jpg/gif/svg), max 5MB

Image Replacement Behavior f a new company_image is uploaded:

1. Deletes the old physical file from public/files/ (if exists)

2. Deletes the old File record

3. Creates a new File record

4. Stores the new file

5. Updates company_image_id

Response

200

✅ 200 OK

{ "message": "Company updated successfully !!!!" } 

422

⚠️ 422 Validation Error

{ 
    "message": "The currency must be a string.", 
    "errors": { "currency": ["The currency must be a string."] } 
} 

500

❌ 500 Internal Server Error

{ "message": "Failed to update company: <error details>" } 

​

Archive Company

POST /api/companies/{id}/archive

Archives a company.

Authorization

• Policy: archive on Company

---

200

✅ 200 OK

{ "message": "Company archived successfully." } 

500

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." } 

​

Unarchive (Restore) Company

POST /api/companies/{id}/unarchive

Restores an archived company.

Authorization

• Policy: restore on Company

Response

200

✅ 200 OK

{ "message": "Company restored successfully." } 

500

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." } 

​

Delete Company

DELETE /api/companies/{id}

Soft-deletes a company (uses Eloquent delete()).

Authorization

• Policy: delete on Company

Response

200

✅ 200 OK

{ "message": "Company force deleted successfully." } 

500

❌ 500 Internal Server Error

{ "message": "An unexpected error occurred." }