# Companies API – Endpoint Examples

Base URL: `/api/v1/web`  
Auth: `Authorization: Bearer {token}`

---

## List companies (with pagination & filters)

**GET** `/api/v1/web/companies`

Query params:

| Param       | Type   | Description                    |
|------------|--------|--------------------------------|
| page       | int    | Page number (default 1)        |
| limit      | int    | Per page (default from server)|
| keyword    | string | Search by name                 |
| countryId  | int    | Filter by country id           |
| country_id | int    | Same as countryId              |
| embed      | string | Relations, e.g. `country`      |

**Example – all companies, page 1:**
```http
GET /api/v1/web/companies?page=1&limit=10
Authorization: Bearer {token}
```

**Example – filter by country:**
```http
GET /api/v1/web/companies?page=1&limit=10&countryId=1
Authorization: Bearer {token}
```

**Example – search by keyword:**
```http
GET /api/v1/web/companies?keyword=Company%201&page=1
Authorization: Bearer {token}
```

**Example – with country relation:**
```http
GET /api/v1/web/companies?page=1&embed=country
Authorization: Bearer {token}
```

**Response (200):**
```json
{
  "data": [
    {
      "id": 1,
      "name": "Company 1",
      "description": "...",
      "country_id": 1,
      "country": { "id": 1, "name": "..." },
      "city": "...",
      "address": "...",
      "phone": "...",
      "website": "https://...",
      "is_active": true,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 100
  }
}
```

---

## Get single company

**GET** `/api/v1/web/companies/{id}`

**Example:**
```http
GET /api/v1/web/companies/1
Authorization: Bearer {token}
```

Optional query: `embed=country,customers.user` (or other relations).

---

## Create company

**POST** `/api/v1/web/companies`

**Body (JSON):**
```json
{
  "name": "New Company",
  "description": "Optional description",
  "country_id": 1,
  "city": "Cairo",
  "address": "Optional address",
  "phone": "Optional phone",
  "website": "https://example.com",
  "is_active": true,
  "order": 0
}
```

**Example:**
```http
POST /api/v1/web/companies
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "New Company",
  "website": "https://example.com",
  "country_id": 1
}
```

**Response (200):** Company object.

---

## Update company

**PUT** `/api/v1/web/companies/{id}`

**Body (JSON):** Same fields as create (all optional).

**Example:**
```http
PUT /api/v1/web/companies/1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Updated Company Name",
  "country_id": 2
}
```

**Response (200):** Updated company object.

---

## Delete company

**DELETE** `/api/v1/web/companies/{id}`

**Example:**
```http
DELETE /api/v1/web/companies/1
Authorization: Bearer {token}
```

**Response (200):** Success message.

---

## Export companies to Excel

**POST** `/api/v1/web/companies/export-excel`

Optional body params (same filters as list): `keyword`, `countryId`, `name`.

**Example – export all:**
```http
POST /api/v1/web/companies/export-excel
Authorization: Bearer {token}
Content-Type: application/json

{}
```

**Example – export filtered by country:**
```http
POST /api/v1/web/companies/export-excel
Authorization: Bearer {token}
Content-Type: application/json

{
  "countryId": 1
}
```

**Example – export with keyword:**
```http
POST /api/v1/web/companies/export-excel
Authorization: Bearer {token}
Content-Type: application/json

{
  "keyword": "Company 1"
}
```

**Response (200):**
```json
{
  "status": 200,
  "message": "Success",
  "data": {
    "file": "/storage/companies/2026-02-23_1234567890abc.xlsx"
  }
}
```

Use `file` as download URL (e.g. `{APP_URL}{file}`).

---

## Summary

| Method | Endpoint                           | Description           |
|--------|------------------------------------|-----------------------|
| GET    | /api/v1/web/companies              | List (pagination, filters) |
| GET    | /api/v1/web/companies/{id}         | Get one               |
| POST   | /api/v1/web/companies              | Create                |
| PUT    | /api/v1/web/companies/{id}         | Update                |
| DELETE | /api/v1/web/companies/{id}         | Delete                |
| POST   | /api/v1/web/companies/export-excel | Export to Excel       |

Filters for list/export: `keyword`, `countryId` (or `country_id`), `name`.