sarlinkportal-webui/docs/api-endpoints.md

# API Endpoints

Every backend endpoint the frontend calls. Paths are shown **after** the API base (today `SARLINK_API_BASE_URL`; in the target architecture the base becomes `API_URL` → nginx `/api`). Auth = requires `Authorization: Token <token>`.

Third-party integrations use different bases (`PERSON_VERIFY_BASE_URL`, `OMADA_BASE_URL`, hardcoded Invoice Ninja) — flagged inline.

## Summary

| Method | Path | Purpose | Auth |
|---|---|---|:--:|
| **Auth & onboarding** ||||
| GET | `/api/auth/users/filter/?mobile=&id_card=` | Does a permanent user exist / is verified | No |
| GET | `/api/auth/users/temp/filter/?mobile=&id_card=` | Does a pending (temp) user exist | No |
| POST | `/auth/mobile/` | Send login OTP to a mobile | No |
| POST | `/api/auth/register/` | Register a new (temp) user | No |
| POST | `/api/auth/register/verify/` | Verify registration OTP | No |
| POST | `/callback/auth/` | Exchange OTP PIN → API token + user | No |
| POST | `/auth/logout/` | Invalidate token on sign-out | Yes |
| POST | `/auth/login/` | Username/password login — **DEAD** | No |
| **Billing** ||||
| POST | `/api/billing/payment/` | Create a device payment | Yes |
| GET | `/api/billing/payment/?…&all_payments=` | List payments | Yes |
| GET | `/api/billing/payment/{id}` | Get one payment | Yes |
| PATCH | `/api/billing/payment/{id}/cancel/` | Cancel a payment | Yes |
| PUT | `/api/billing/payment/{id}/verify/` | Verify/complete payment (TRANSFER/WALLET) | Yes |
| POST | `/api/billing/topup/` | Create a wallet top-up | Yes |
| GET | `/api/billing/topup/?…&all_topups=` | List top-ups | Yes |
| GET | `/api/billing/topup/{id}` | Get one top-up | Yes |
| PATCH | `/api/billing/topup/{id}/cancel/` | Cancel a top-up | Yes |
| PUT | `/api/billing/topup/{id}/verify/` | Verify a top-up payment | Yes |
| POST | `/api/billing/admin-topup/` | Admin credits a user's wallet | Yes |
| GET | `/api/billing/wallet-transactions/?…&all_transactions=` | List wallet transactions | Yes |
| **Devices** ||||
| GET | `/api/devices/?…&all_devices=` | List devices | Yes |
| GET | `/api/devices/{id}/` | Get one device | Yes |
| POST | `/api/devices/` | Register/add a device | Yes |
| PUT | `/api/devices/{id}/block/` | Block/unblock a device | Yes |
| **Users / profile / geo** ||||
| GET | `/api/auth/atolls/` | List atolls (+ nested islands) | No |
| GET | `/api/auth/users/?…` | List users (admin) | Yes |
| GET | `/api/auth/users/{id}/` | Get a user profile by id | Yes |
| GET | `/api/auth/profile/` | Logged-in user's own profile | Yes |
| PUT | `/api/auth/users/{id}/verify/` | Admin verify a user | Yes |
| DELETE | `/api/auth/users/{id}/reject/` | Admin reject a user | Yes |
| PUT | `/api/auth/users/{id}/update/` | Update a user's details | Yes |
| PUT | `/api/auth/users/{id}/agreement/` | Upload/update agreement (multipart) | Yes |
| **Third-party** ||||
| GET | `{PERSON_VERIFY}/api/person/{idCard}` | National identity lookup | No |
| — | Omada group/block endpoints | **DEAD** (moving to RADIUS) | X-API-key |
| POST | `{ninja}/api/v1/clients` | Invoice Ninja client — **DEAD** | x-api-token |

## Auth & onboarding

- **GET `/api/auth/users/filter/`** — `signin()` (auth-actions) + `checkIdOrPhone()`. Checks a phone/ID exists & is verified before OTP; signup dupe-check. → `{ ok, verified }`.
- **GET `/api/auth/users/temp/filter/`** — `checkTempIdOrPhone()`. Pending-registration lookup. → `{ ok, otp_verified, t_verified }`.
- **POST `/auth/mobile/`** — `signin()`. Sends login OTP. Body `{ mobile }`. → `{ detail }`.
- **POST `/api/auth/register/`** — `backendRegister()` from `signup()`. Body `{ firstname, lastname, username, address, id_card, dob, mobile, island, atoll, acc_no, terms_accepted, policy_accepted }`. → `{ t_username }`.
- **POST `/api/auth/register/verify/`** — `VerifyRegistrationOTP()`. Body `{ mobile, otp }`. → `{ message, verified }`.
- **POST `/callback/auth/`** — the login token exchange (was NextAuth `authorize`, now `verify-otp-form`). Body `{ token: pin }`. → `{ user, token, expiry }`. 400/403/429 return error payloads (`token[0]` / `message`).
- **POST `/auth/logout/`** — `logout()`. Expects `204`.
- **POST `/auth/login/`** — DEAD (`login()` via `axiosInstance`, unused; login goes through `/callback/auth/`).

## Billing

`actions/payment.ts`, `queries/wallet.ts`, `actions/user-actions.ts`.

- **POST `/api/billing/payment/`** `createPayment()` — pay for cart devices. Body `{ device_ids[], number_of_months }` → `Payment`.
- **GET `/api/billing/payment/`** `getPayments()` — list; `all_payments=true` for admin. → `ApiResponse<Payment>`.
- **GET `/api/billing/payment/{id}`** `getPayment()` → `Payment`.
- **PATCH `…/payment/{id}/cancel/`** `cancelPayment()` → `Payment`.
- **PUT `…/payment/{id}/verify/`** `verifyPayment()` / `verifyDevicePayment()` — Body `{ method: "TRANSFER" | "WALLET" }`. MIB verification is **server-side**; the frontend just sends the method. → `Payment`.
- **POST `/api/billing/topup/`** `createTopup()` — Body `{ amount }` → `Topup`.
- **GET `/api/billing/topup/`** `getTopups()` — `all_topups=true` for admin. → `ApiResponse<Topup>`.
- **GET `/api/billing/topup/{id}`** `getTopup()` → `Topup`.
- **PATCH `…/topup/{id}/cancel/`** `cancelTopup()` → `Topup`.
- **PUT `…/topup/{id}/verify/`** `verifyTopupPayment()` → `{ status, message, transaction? { ref, sourceBank, trxDate } }`.
- **POST `/api/billing/admin-topup/`** `adminUserTopup()` — Body `{ amount, user_id, description }`.
- **GET `/api/billing/wallet-transactions/`** `getWaleltTransactions()` → `ApiResponse<WalletTransaction>` (`transaction_type: "DEBIT" | "TOPUP"`).

## Devices

`queries/devices.ts` (`checkSession()` for token).

- **GET `/api/devices/`** `getDevices()` — params `name, offset, limit, page, sortBy, status`, `all_devices=true` for admin. → `ApiResponse<Device>`.
- **GET `/api/devices/{id}/`** `getDevice()` → `Device`.
- **POST `/api/devices/`** `addDeviceAction()` — Body `{ name, mac, registered: true }` → `Device`.
- **PUT `/api/devices/{id}/block/`** `blockDeviceAction()` — Body `{ blocked, reason_for_blocking, blocked_by: "ADMIN" | "PARENT" }`. Parents forced to `PARENT`. → `Device`.

## Users / profile / geo

`queries/users.ts`, `queries/islands.ts`, `actions/user-actions.ts`.

- **GET `/api/auth/atolls/`** `getAtolls()` — atoll+island dropdowns on signup. → `Atoll[]` (each with nested `islands`).
- **GET `/api/auth/users/`** `getUsers()` — admin user list. → `ApiResponse<UserProfile>`.
- **GET `/api/auth/users/{id}/`** `getProfileById()` — profile & admin user pages. → `UserProfile`.
- **GET `/api/auth/profile/`** `getProfile()` — own profile (agreements, payment detail). → `User`.
- **PUT `/api/auth/users/{id}/verify/`** `verifyUser()` — → `{ ok, mismatch_fields, … }`; surfaces field mismatches.
- **DELETE `/api/auth/users/{id}/reject/`** `rejectUser()` — Body `{ rejection_details }`; `204` → revalidate/redirect.
- **PUT `/api/auth/users/{id}/update/`** `updateUser()` — Body = non-empty form fields. → `User` or per-field errors.
- **PUT `/api/auth/users/{id}/agreement/`** `updateUserAgreement()` — multipart FormData (PDF). → `{ agreement }`.

## Third-party

- **GET `{PERSON_VERIFY_BASE_URL}/api/person/{idCard}`** `getNationalPerson()` (`lib/person.ts`) — **LIVE**. National identity lookup to cross-check user data during admin verification. ISR `revalidate: 60`. → `TNationalPerson { nic, name(_en), dob, gender, house_name(_en), island_name(_en), atoll(_en), constituency, … }`. *Memory note: planned to route through the backend instead of calling directly.*
- **Omada** (`actions/omada-actions.ts`) — group profiles / add-to-group / block — **DEAD**, none imported by UI. Device blocking now uses backend `/api/devices/{id}/block/`. Consistent with the Omada→RADIUS migration.
- **Invoice Ninja** (`actions/ninja/client.ts`) — hardcoded staging URL, create client — **DEAD**.

## Frontend's own API routes (`app/api/`) — not backend

- **`app/api/auth/[...nextauth]/route.ts`** — NextAuth handler. **To be removed** in the static migration.
- **`app/api/check-devices/route.ts`** — stub returning `{ message: "Request received" }`; no backend call. Dead/placeholder.

## Response envelope

List endpoints return `ApiResponse<T> = { meta, links, data: T[] }` (pagination). Errors surface as `{ message }` / `{ detail }` (see `handleApiResponse` in `utils/tryCatch.ts`, which is hardened against non-JSON error bodies).

## Dead code to drop during the port

`/auth/login/` (#8), `/islands/`, `/inventory/`, all Omada, Invoice Ninja, `backendMobileLogin`, `app/api/check-devices`, and the two axios helpers `utils/axios-client.ts` / `utils/axiosInstance.ts` (only used by dead calls).