# Operator Onboarding And System Auth API

This reference covers non-customer onboarding and internal PI authentication.

Base URL:
- `http://localhost:5000/api/v1`

## 1) System/Admin PI Login

Endpoint:
- `POST /auth/system/login`

Body:
```json
{
  "piNumber": "PI-ADMIN-0001"
}
```

Response:
- Standard auth response (`user` + `tokens`).

## 2) Operator Application Submission

Supported operator roles:
- `vendor`
- `service_provider`
- `agent`
- `logistics` (normalized to rider)

Endpoint:
- `POST /auth/operator/applications`

Body:
```json
{
  "role": "vendor",
  "email": "owner@business.com",
  "fullName": "Business Owner",
  "phone": "+2547...",
  "businessName": "Kaifway Fresh",
  "registeredOwner": "Business Owner",
  "registrationNumber": "PVT-1234",
  "kraPin": "A001234567X",
  "documents": [
    {
      "name": "kra-certificate",
      "type": "kra_pin_certificate",
      "url": "https://ik.imagekit.io/..."
    }
  ],
  "metadata": {
    "vehicleType": "boda",
    "preferredDistance": "short",
    "operatingRadius": "25"
  }
}
```

Response:
```json
{
  "applicationId": "...",
  "applicationNumber": "STORE-123456-APP",
  "status": "pending",
  "role": "vendor",
  "submittedAt": "..."
}
```

## 3) Application Status Lookup

Endpoint:
- `GET /auth/operator/applications/:applicationId?email=user@domain.com`

Response includes:
- `status`
- `reviewedAt`
- `reviewReason`
- `dashboardCode` (after approval)
- `credentialsIssuedAt` (after approval)

## 4) Admin/System Manual Verification

Requires Bearer token from system/admin login.

Queue:
- `GET /admin/verification-queue?status=pending`

Approve:
- `POST /admin/businesses/:businessId/approve`

Reject:
- `POST /admin/businesses/:businessId/reject`

Decision payload:
```json
{
  "reason": "optional reviewer note"
}
```

On approve, backend does all of the following:
- marks application approved
- verifies the user
- generates dashboard identifier (`STORE-*`, `SERVICE-*`, `AGENT-*`, `LOGI-*`)
- generates temporary password
- triggers credential email delivery (Brevo provider)

## 5) Dashboard Login For Approved Operators

Endpoint:
- `POST /auth/dashboard/login`

Body:
```json
{
  "identifier": "STORE-123456",
  "password": "Kw!123abcdef"
}
```

Response:
- Standard auth response (`user` + `tokens`)

## 6) Create PI System User

Requires Bearer token from system/admin login.

Endpoint:
- `POST /admin/system-users`

Body:
```json
{
  "piNumber": "PI-SYS-9001",
  "fullName": "Ops Supervisor",
  "email": "ops@kaifway.com",
  "role": "system"
}
```

Response includes created user and generated temporary password.

## 7) Email Provider

Credential emails are sent through Brevo when configured:
- `EMAIL_PROVIDER=brevo`
- `BREVO_API_KEY=...`
- `BREVO_API_URL=https://api.brevo.com/v3/smtp/email`
- `EMAIL_FROM_NAME=Kaifway`
- `EMAIL_FROM=noreply@kaifway.com`