155 lines
4.2 KiB
Markdown
155 lines
4.2 KiB
Markdown
# Member Lookup API Documentation
|
|
|
|
## Overview
|
|
This API endpoint allows secure lookup of member information using encrypted member IDs. It's designed to be used with an Expo Android app that scans QR codes containing encrypted member IDs.
|
|
|
|
## Endpoint
|
|
```
|
|
GET /api/member-lookup?encryptedId={encrypted_member_id}
|
|
```
|
|
|
|
## Security
|
|
- Member IDs are encrypted using AES-256-CBC encryption
|
|
- QR codes contain encrypted member IDs, not plain text IDs
|
|
- The API validates and decrypts the member ID before database lookup
|
|
|
|
## Request Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| encryptedId | string | Yes | The encrypted member ID obtained from QR code |
|
|
|
|
## Response Format
|
|
|
|
### Success Response (200)
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Member information retrieved successfully",
|
|
"data": {
|
|
"name": "John Doe",
|
|
"gender": "m",
|
|
"planDelay": 1,
|
|
"planStart": "Mon, 01 Jan 2024 00:00:00 GMT",
|
|
"planStatus": "active",
|
|
"planExpAt": "Thu, 01 Feb 2024 00:00:00 GMT"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error Responses
|
|
|
|
#### Missing Parameter (400)
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Missing encrypted member ID"
|
|
}
|
|
```
|
|
|
|
#### Invalid Encryption (400)
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Invalid encrypted member ID"
|
|
}
|
|
```
|
|
|
|
#### Member Not Found (404)
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Member not found"
|
|
}
|
|
```
|
|
|
|
#### Server Error (500)
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Server error"
|
|
}
|
|
```
|
|
|
|
## Response Data Fields
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| name | string | Full name (firstName + lastName) |
|
|
| gender | string | Gender ("m" for male, "f" for female) |
|
|
| planDelay | number | Plan duration in months |
|
|
| planStart | string | Plan start date (UTC string) |
|
|
| planStatus | string | "active" or "expired" |
|
|
| planExpAt | string | Plan expiration date (UTC string) |
|
|
|
|
## Usage with Android App
|
|
|
|
### 1. QR Code Scanning
|
|
- Scan the QR code from the member details popup
|
|
- Extract the encrypted member ID from the QR code data
|
|
|
|
### 2. API Call
|
|
```javascript
|
|
// Example using fetch in React Native/Expo
|
|
const lookupMember = async (encryptedId) => {
|
|
try {
|
|
const response = await fetch(
|
|
`https://your-domain.com/api/member-lookup?encryptedId=${encodeURIComponent(encryptedId)}`
|
|
);
|
|
const data = await response.json();
|
|
|
|
if (data.success) {
|
|
// Display member information in card view
|
|
return data.data;
|
|
} else {
|
|
// Handle error
|
|
console.error('API Error:', data.message);
|
|
}
|
|
} catch (error) {
|
|
console.error('Network Error:', error);
|
|
}
|
|
};
|
|
```
|
|
|
|
### 3. Display in Card View
|
|
Use the returned data to populate your Android card view with:
|
|
- Member name
|
|
- Gender
|
|
- Plan information (duration, start date, expiration)
|
|
- Plan status (active/expired with appropriate styling)
|
|
|
|
## Security Considerations
|
|
|
|
1. **Encryption Key**: Ensure the `ENCRYPTION_KEY` environment variable is set to a secure 32-character string in production
|
|
2. **HTTPS**: Always use HTTPS in production to protect data in transit
|
|
3. **Rate Limiting**: Consider implementing rate limiting to prevent abuse
|
|
4. **Authentication**: For additional security, consider adding API authentication
|
|
|
|
## Environment Variables
|
|
|
|
```env
|
|
ENCRYPTION_KEY=your-32-character-secret-key-here!
|
|
```
|
|
|
|
## Files Modified/Created
|
|
|
|
1. **Created**: `src/utils/encryption.ts` - Encryption/decryption utilities
|
|
2. **Created**: `src/app/api/member-lookup/route.ts` - API endpoint
|
|
3. **Modified**: `src/components/dashboard/members/parts/detailsPopUp.tsx` - QR code generation with encryption
|
|
4. **Modified**: `src/messages/en.json` - English translations
|
|
5. **Modified**: `src/messages/ar.json` - Arabic translations
|
|
|
|
## Testing
|
|
|
|
1. Start the development server: `npm run dev`
|
|
2. Open a member details popup to generate a QR code
|
|
3. The QR code now contains an encrypted member ID
|
|
4. Test the API endpoint with the encrypted ID
|
|
|
|
## Example QR Code Flow
|
|
|
|
1. **Web App**: Generates QR code with encrypted member ID
|
|
2. **Android App**: Scans QR code and extracts encrypted ID
|
|
3. **Android App**: Calls `/api/member-lookup?encryptedId=...`
|
|
4. **API**: Decrypts ID, looks up member, returns information
|
|
5. **Android App**: Displays member information in card view |