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>
292 lines
4.8 KiB
Markdown
292 lines
4.8 KiB
Markdown
# Endpoints: Organisation
|
|
|
|
Org profile, registration, departments, and verification settings.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
**Entities:** [`organisation`](../entities/organisation.md), [`org-registration`](../entities/org-registration.md), [`department`](../entities/department.md)
|
|
|
|
---
|
|
|
|
## POST /v1/org/register
|
|
|
|
Self-register organisation + first SUPER_USER.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Public |
|
|
| **Roles** | — |
|
|
|
|
### Request
|
|
|
|
See sample in [`org-registration.md`](../entities/org-registration.md).
|
|
|
|
### Response 201
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"registration_id": "oreg_01HABC",
|
|
"org_id": "org_01HNEW",
|
|
"status": "submitted",
|
|
"org_status": "pending_activation",
|
|
"session": { "user_id": "usr_01HNEW", "roles": ["SUPER_USER"], "org_id": "org_01HNEW" }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Validation / errors
|
|
|
|
| Code | HTTP | When |
|
|
|------|------|------|
|
|
| `DUPLICATE_ORG` | 409 | TIN exists |
|
|
| `DUPLICATE_USER` | 409 | Email taken |
|
|
| `WEAK_PASSWORD` | 400 | Password policy |
|
|
| `VALIDATION_FAILED` | 400 | Field errors |
|
|
|
|
### Event
|
|
|
|
`org.registration_submitted`
|
|
|
|
### Clinical withhold
|
|
|
|
N/A.
|
|
|
|
---
|
|
|
|
## POST /v1/org/register/request
|
|
|
|
Request-to-register (email or phone lead).
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Public |
|
|
|
|
### Request / Response
|
|
|
|
See [`org-registration.md`](../entities/org-registration.md).
|
|
|
|
### Event
|
|
|
|
`org.registration_requested`
|
|
|
|
---
|
|
|
|
## GET /v1/org
|
|
|
|
Current organisation profile.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE |
|
|
|
|
### Response 200
|
|
|
|
Full [`Organisation`](../entities/organisation.md). `commercial` null if pending.
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP | When |
|
|
|------|------|------|
|
|
| `FORBIDDEN` | 403 | MEMBER role |
|
|
| `UNAUTHENTICATED` | 401 | |
|
|
|
|
### Clinical withhold
|
|
|
|
No clinical fields.
|
|
|
|
---
|
|
|
|
## PATCH /v1/org
|
|
|
|
Update HR-managed org fields (not commercial).
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Request (partial)
|
|
|
|
```json
|
|
{
|
|
"display_name": "Acme Bank",
|
|
"dependant_limit": 4,
|
|
"join_rules": {
|
|
"join_code": "ACME-2026",
|
|
"allowed_email_domains": ["acme.et"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Response 200
|
|
|
|
Updated organisation.
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP | When |
|
|
|------|------|------|
|
|
| `ORG_PENDING` | 422 | Some actions blocked — read still allowed |
|
|
| `FORBIDDEN` | 403 | Attempt to mutate `commercial` |
|
|
|
|
---
|
|
|
|
## GET /v1/org/registration-status
|
|
|
|
Pending org activation status for SUPER_USER.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER |
|
|
|
|
### Response 200
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"org_status": "pending_activation",
|
|
"submitted_at": "2026-03-01T09:00:00Z",
|
|
"message": "Gishen is reviewing your application. You will be notified when activated."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## PATCH /v1/org/verification
|
|
|
|
Verification method settings.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Request
|
|
|
|
```json
|
|
{
|
|
"method": "employee_id",
|
|
"require_at_checkout": true
|
|
}
|
|
```
|
|
|
|
### Response 200
|
|
|
|
Updated `verification` object.
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP | When |
|
|
|------|------|------|
|
|
| `ORG_PENDING` | 422 | Org not active |
|
|
|
|
---
|
|
|
|
## GET /v1/org/departments
|
|
|
|
List departments.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE (read) |
|
|
|
|
### Query
|
|
|
|
`?page=1&page_size=25&q=addis&parent_id=dept_root`
|
|
|
|
### Response 200
|
|
|
|
Paginated [`Department`](../entities/department.md) list.
|
|
|
|
---
|
|
|
|
## POST /v1/org/departments
|
|
|
|
Create department.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Request
|
|
|
|
```json
|
|
{
|
|
"name": "Hawassa Branch",
|
|
"code": "HAW",
|
|
"parent_id": null,
|
|
"sub_limit": { "amount": "100000.00", "currency": "ETB" }
|
|
}
|
|
```
|
|
|
|
### Response 201
|
|
|
|
Created department.
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP |
|
|
|------|------|
|
|
| `DUPLICATE_DEPARTMENT` | 409 |
|
|
| `ORG_PENDING` | 422 |
|
|
| `VALIDATION_FAILED` | 400 |
|
|
|
|
---
|
|
|
|
## GET /v1/org/departments/:id
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE |
|
|
|
|
---
|
|
|
|
## PATCH /v1/org/departments/:id
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
---
|
|
|
|
## DELETE /v1/org/departments/:id
|
|
|
|
Soft-deactivate (`is_active: false`).
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Auth** | Required |
|
|
| **Roles** | SUPER_USER, HR_ADMIN |
|
|
|
|
### Errors
|
|
|
|
| Code | HTTP |
|
|
|------|------|
|
|
| `DEPARTMENT_IN_USE` | 422 |
|
|
|
|
---
|
|
|
|
## UI routes
|
|
|
|
| Route | Endpoint(s) |
|
|
|-------|-------------|
|
|
| `/organisation` | GET/PATCH `/v1/org` + spend charts |
|
|
| `/departments` | Department list |
|
|
| `/departments/new` | POST `/v1/org/departments` |
|
|
| `/departments/[id]` | GET/PATCH department detail |
|
|
| `/settings/verification` | PATCH `/v1/org/verification` |
|
|
| `/register/organisation` | POST `/v1/org/register` |
|
|
| `/register/request` | POST `/v1/org/register/request` |
|
|
|
|
## Clinical withhold
|
|
|
|
Organisation and department endpoints expose no clinical data.
|