Add API documentation for Representation, Secretary, Settlement, SMS, Specialty, Tag, and User Profile endpoints

2026-06-11 10:27:27 +03:30
parent e88ae9bf9c
commit cced85456a
22 changed files with 5691 additions and 0 deletions
@@ -0,0 +1,284 @@
+# Authentication API
+
+> **Prefix:** `/api/v1/user` and `/oauth`  
+> **Permission:** All endpoints in this module are **PUBLIC** (no JWT required) except `userinfo` and `logout`
+
+---
+
+## POST `/api/v1/user/send-code`
+
+Send OTP code to mobile number.
+
+**Permission:** `PUBLIC`
+
+### Request Body
+```json
+{
+  "mobile": "09123456789"
+}
+```
+
+| Field | Type | Required | Validation |
+|-------|------|----------|------------|
+| `mobile` | string | ✅ | Format: `09XXXXXXXXX` (11 digits) |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "550e8400-e29b-41d4-a716-446655440000",
+    "message": "کد تأیید ارسال شد"
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_VALIDATION_001` | 422 | Invalid mobile format |
+| `ERR_AUTH_004` | 429 | OTP rate limit exceeded |
+
+---
+
+## POST `/api/v1/user/verify-code`
+
+Verify OTP code. Returns whether this is a new or existing user.
+
+**Permission:** `PUBLIC`
+
+### Request Body
+```json
+{
+  "uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "code": "123456"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `uuid` | string | ✅ | UUID returned from `send-code` |
+| `code` | string | ✅ | 6-digit OTP |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "message": "کد تأیید شد",
+    "is_new_user": false,
+    "uuid": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_002` | 401 | Invalid OTP code |
+| `ERR_AUTH_003` | 401 | OTP expired |
+| `ERR_VALIDATION_002` | 422 | Missing required field |
+
+---
+
+## POST `/api/v1/user/register`
+
+Complete registration for new users (called only when `is_new_user: true`).
+
+**Permission:** `PUBLIC`
+
+### Request Body
+```json
+{
+  "uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "real_name": "علی احمدی"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `uuid` | string | ✅ | Verified UUID from `verify-code` |
+| `real_name` | string | ❌ | User's full name |
+
+### Response `201`
+```json
+{
+  "success": true,
+  "data": {
+    "message": "ثبت‌نام با موفقیت انجام شد",
+    "uuid": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_VALIDATION_002` | 422 | Missing uuid |
+| `ERR_CONFLICT_001` | 409 | User already registered |
+
+---
+
+## POST `/api/v1/user/login`
+
+Login with mobile number and password (for users who set a password).
+
+**Permission:** `PUBLIC`
+
+### Request Body
+```json
+{
+  "mobile_number": "09123456789",
+  "password": "mypassword"
+}
+```
+
+| Field | Type | Required |
+|-------|------|----------|
+| `mobile_number` | string | ✅ |
+| `password` | string | ✅ |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+    "refresh_token": "def50200..."
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_005` | 401 | Wrong credentials |
+| `ERR_AUTH_006` | 403 | Account suspended |
+| `ERR_AUTH_004` | 429 | Too many attempts |
+
+---
+
+## POST `/oauth/token`
+
+Exchange verified UUID for JWT access token.
+
+**Permission:** `PUBLIC`
+
+### Request Body
+```json
+{
+  "grant_type": "mobile",
+  "uuid": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `grant_type` | string | ✅ | Must be `"mobile"` |
+| `uuid` | string | ✅ | UUID from verified OTP flow |
+
+### Response `200`
+```json
+{
+  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+  "refresh_token": "def50200..."
+}
+```
+
+> JWT payload: `{ username: mobile_number, roles: [...], iat, exp }`  
+> Access token TTL: **1 hour** | Refresh token TTL: **30 days** (stored in Redis)
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_002` | 400 | Invalid or expired UUID |
+
+---
+
+## POST `/oauth/token/refresh`
+
+Refresh expired JWT using refresh token.
+
+**Permission:** `PUBLIC`
+
+### Request Body
+```json
+{
+  "refresh_token": "def50200..."
+}
+```
+
+### Response `200`
+```json
+{
+  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+  "refresh_token": "def50200..."
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Invalid or expired refresh token |
+
+---
+
+## GET `/oauth/userinfo`
+
+Get authenticated user info.
+
+**Permission:** `AUTH` — requires valid JWT
+
+### Headers
+```
+Authorization: Bearer <token>
+```
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "550e8400-e29b-41d4-a716-446655440000",
+    "mobile_number": "09123456789",
+    "real_name": "علی احمدی",
+    "roles": ["ROLE_USER"],
+    "status": "active",
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Invalid or missing token |
+
+---
+
+## POST `/oauth/logout`
+
+Invalidate the refresh token (stored in Redis).
+
+**Permission:** `AUTH`
+
+### Request Body
+```json
+{
+  "refresh_token": "def50200..."
+}
+```
+
+| Field | Type | Required |
+|-------|------|----------|
+| `refresh_token` | string | ❌ |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "message": "با موفقیت خارج شدید"
+  }
+}
+```