kirukib
3778801ef5
Deliver role-aware shell (sidebar, breadcrumbs, quick search, tables, detail/create layouts), locale-ready pages, shared backend/feature docs, and Vercel project config so HR, finance, and members can demo against typed mocks. Co-authored-by: Cursor <cursoragent@cursor.com>
186 lines
3.4 KiB
Markdown
186 lines
3.4 KiB
Markdown
# Endpoints: Packages
|
|
|
|
Corporate benefit plan CRUD and member assignment helpers.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
**Entity:** [`../entities/package.md`](../entities/package.md)
|
|
|
|
---
|
|
|
|
## GET /v1/packages
|
|
|
|
List packages.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE (read), MEMBER (own assignment via `/v1/me/package`) |
|
|
|
|
### Query
|
|
|
|
`?page=1&status=active&q=gold`
|
|
|
|
### Response 200
|
|
|
|
Paginated [`Package`](../entities/package.md) list.
|
|
|
|
---
|
|
|
|
## POST /v1/packages
|
|
|
|
Create package.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Request
|
|
|
|
```json
|
|
{
|
|
"name": "Silver Standard",
|
|
"code": "SILVER",
|
|
"description": "Standard employee coverage",
|
|
"allowance": {
|
|
"amount": { "amount": "8000.00", "currency": "ETB" },
|
|
"period": "monthly",
|
|
"rollover": false
|
|
},
|
|
"copay_percent": 15,
|
|
"categories": [
|
|
{ "category_code": "chronic", "coverage_percent": 90, "max_per_order": null }
|
|
],
|
|
"caps": {
|
|
"max_order_amount": { "amount": "5000.00", "currency": "ETB" },
|
|
"max_orders_per_month": 8,
|
|
"max_rx_fills_per_month": 3
|
|
},
|
|
"exclusions": [],
|
|
"perks": [],
|
|
"status": "draft"
|
|
}
|
|
```
|
|
|
|
### Response 201
|
|
|
|
Created package.
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP | When |
|
|
|------|------|------|
|
|
| `DUPLICATE_PACKAGE` | 409 | Code exists |
|
|
| `ORG_PENDING` | 422 | Cannot activate until org active |
|
|
| `VALIDATION_FAILED` | 400 | |
|
|
|
|
---
|
|
|
|
## GET /v1/packages/:id
|
|
|
|
Package detail.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE; MEMBER if assigned |
|
|
|
|
### Response 200
|
|
|
|
Full package including assigned `member_count`.
|
|
|
|
---
|
|
|
|
## PATCH /v1/packages/:id
|
|
|
|
Update package.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Notes
|
|
|
|
- Setting `status: "active"` requires org `active`.
|
|
- Archiving blocked if members assigned without reassignment.
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP |
|
|
|------|------|
|
|
| `PACKAGE_IN_USE` | 422 |
|
|
|
|
---
|
|
|
|
## DELETE /v1/packages/:id
|
|
|
|
Archive package (`status: archived`).
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
---
|
|
|
|
## GET /v1/packages/:id/members
|
|
|
|
Members assigned to package.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Response 200
|
|
|
|
Paginated member summary (id, name, employee_id, status).
|
|
|
|
---
|
|
|
|
## GET /v1/me/package
|
|
|
|
Member's assigned package + allowance (member portal).
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | MEMBER, SUPER_USER (when viewing as member) |
|
|
|
|
### Response 200
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"package": { "id": "pkg_01HGOLD", "name": "Gold Executive", "code": "GOLD", "...": "..." },
|
|
"allowance_summary": {
|
|
"allowance_total": { "amount": "15000.00", "currency": "ETB" },
|
|
"allowance_used": { "amount": "4200.00", "currency": "ETB" },
|
|
"allowance_remaining": { "amount": "10800.00", "currency": "ETB" }
|
|
},
|
|
"overrides": null
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## UI routes
|
|
|
|
| Route | Endpoint(s) |
|
|
|-------|-------------|
|
|
| `/packages` | GET `/v1/packages` |
|
|
| `/packages/new` | POST `/v1/packages` |
|
|
| `/packages/[id]` | GET/PATCH + activate/deactivate mock |
|
|
| `/me` | GET `/v1/me/package` |
|
|
|
|
## Clinical withhold
|
|
|
|
Packages contain coverage rules only — safe for all roles.
|
|
|
|
## Checkout note
|
|
|
|
Remaining allowance displayed in B2B member UI; **entitlement split at checkout** is implemented in Gishen-Ecom — see [`../../coordination/gishen-ecom.md`](../../coordination/gishen-ecom.md).
|