# SPECIFICATIONS/06_API/06_09_SHARES_ENDPOINTS.md

**PURPOSE:** Specifies the shares management API surface.

> **Business rules enforced by these endpoints:** `../01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-005-*
> **Balance formula:** `../05_ALGORITHMS/04_COMPUTED_FIELDS.md` → Section 5.2

**Domain Independence:** Shares management is a separate domain (`app/Domains/Shares/`). It is NOT part of the Agent or Investor domain. Endpoints operate on any client that has the `investor` flag.

> **Investor flag guard rule (404 for non-investors):** `../01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-005-9

---

## POST /api/v1/shares/{client}

**Permission:** `shares.add_transaction`

**Inputs:**

| Field | Type | Required | Validation |
|:---|:---|---|:---|
| `transaction_type` | string | Yes | `deposit` or `withdraw` |
| `shares_count` | integer | Yes | min 1 |
| `acquisition_date` | date | Yes | — |

**Outputs:**
```json
{
    "success": true,
    "message": "string",
    "data": {
        "id": 1,
        "transaction_type": "deposit",
        "shares_count": 10,
        "acquisition_date": "2024-01-15T00:00:00+03:00",
        "status": "active",
        "created_at": "timestamp",
        "updated_at": null
    }
}
```

**Behavior:**
- Guard: client must have `investor` flag → 404 if not
- Creates record in `client_shares_logs` with `status = 'active'`
- If `transaction_type = 'withdraw'`: calculates projected balance BEFORE creating record → rejects if balance would be negative

**Errors:**

| Condition | Key | HTTP |
|:---|:---|:---|
| Not an investor | `errors/shares.not_investor` | 404 |
| Withdrawal exceeds balance | `errors/shares.insufficient_balance` | 422 |
| Acquisition date missing | `errors/shares.acquisition_date_required` | 422 |

---

## DELETE /api/v1/shares/{client}/shareLog/{shareLog}

**Permission:** `shares.delete_transaction`

**Inputs:** None

**Outputs:**
```json
{
    "success": true,
    "message": "string",
    "data": null
}
```

**Behavior:**
- Guard: `investor` flag + must be the most recently created record for the client AND it must have `active` status + within 30 days of the record creation date
- Logical deletion: sets `status = 'deleted'`, updates `updated_at`
- Record remains in database — never physically removed

**Errors:**

| Condition | Key | HTTP |
|---|---|:---|
| Not an investor | `errors/shares.not_investor` | 404 |
| Not the latest record or not active | `errors/shares.not_latest` | 403 |
| 30-day lock expired | `errors/shares.lock_period_expired` | 403 |

---

## GET /api/v1/shares/{client}/shares-log

**Permission:** `shares.view_log`

**Inputs (Query Params):**

| Field | Type | Required | Validation |
|:---|:---|---|:---|
| `cursor` | string | No | Valid cursor |
| `per_page` | integer | No | Default 20, max 100 |

**Outputs:**
```json
{
    "success": true,
    "message": "string",
    "data": [
        {
            "id": 1,
            "transaction_type": "deposit",
            "shares_count": 10,
            "acquisition_date": "2024-01-15T00:00:00+03:00",
            "status": "active",
            "created_at": "timestamp",
            "updated_at": "timestamp|null"
        }
    ],
    "meta": {
        "current_cursor": "string|null",
        "has_more": false,
        "per_page": 20
    }
}
```

**Behavior:**
- Guard: `investor` flag → 404 if not
- Reverse chronological order
- Include all statuses (active, deleted)