⚝
One Hat Cyber Team
⚝
Your IP:
216.73.216.81
Server IP:
178.33.27.10
Server:
Linux cpanel.dev-unit.com 3.10.0-1160.119.1.el7.x86_64 #1 SMP Tue Jun 4 14:43:51 UTC 2024 x86_64
Server Software:
Apache/2.4.62 (Unix) OpenSSL/1.0.2k-fips
PHP Version:
8.2.25
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
home
/
id
/
ecommerce.dev-unit.com
/
View File Name :
API_DOCUMENTATION.md
# B2C E-Commerce API Documentation ## Base URL ``` Production: https://your-domain.com/api/v1 Development: http://localhost/api/v1 ``` ## Authentication All protected endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer {your_token} ``` --- ## Endpoints ### 1. Health Check Check if the API is running. **Request** ``` GET /api/health ``` **Headers** ``` None required ``` **Response (200 OK)** ```json { "status": "ok", "message": "API is running", "timestamp": "2024-02-16T12:00:00.000000Z" } ``` --- ### 2. Register User Create a new user account. An email verification token will be sent to the registered email. **Request** ``` POST /api/v1/auth/register ``` **Headers** ``` Content-Type: application/json Accept: application/json ``` **Body** ```json { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "password": "password123", "password_confirmation": "password123", "g-recaptcha-response": "optional_recaptcha_token" } ``` **Response (201 Created)** ```json { "success": true, "message": "Registration successful. Please verify your email to login.", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": "+1234567890", "photo": null, "is_verified": false, "addresses": { "shipping": { "address1": null, "address2": null, "city": null, "country": null, "zip": null, "company": null, "state_id": null }, "billing": { "address1": null, "address2": null, "city": null, "country": null, "zip": null, "company": null } }, "created_at": "2024-02-16T12:00:00.000000Z", "updated_at": "2024-02-16T12:00:00.000000Z" }, "token": "1|abc123xyz...", "token_type": "Bearer" } } ``` **Error Responses** | Code | Error | |------|-------| | 422 | Validation failed | | 422 | reCAPTCHA verification failed (if enabled) | | 500 | Internal server error | **Example Error (422)** ```json { "success": false, "message": "The given data was invalid.", "errors": { "email": ["The email has already been taken."], "password": ["The password confirmation does not match."] } } ``` --- ### 3. Login User Authenticate with email and password. Returns a Bearer token for subsequent requests. **Request** ``` POST /api/v1/auth/login ``` **Headers** ``` Content-Type: application/json Accept: application/json ``` **Body** ```json { "email": "john.doe@example.com", "password": "password123", "g-recaptcha-response": "optional_recaptcha_token" } ``` **Response (200 OK)** ```json { "success": true, "message": "Login successful.", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": "+1234567890", "photo": "https://your-domain.com/assets/images/user.jpg", "is_verified": true, "addresses": { "shipping": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp", "state_id": 1 }, "billing": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp" } }, "created_at": "2024-01-01T10:00:00.000000Z", "updated_at": "2024-02-15T15:30:00.000000Z" }, "token": "1|abc123xyz...", "token_type": "Bearer" } } ``` **Error Responses** | Code | Error | |------|-------| | 401 | Invalid credentials | | 403 | Email not verified | | 422 | Validation failed | | 422 | reCAPTCHA verification failed (if enabled) | **Example Error (401)** ```json { "success": false, "message": "Invalid credentials.", "errors": { "email": ["The provided credentials are incorrect."] } } ``` **Example Error (403)** ```json { "success": false, "message": "Email not verified. Please verify your email to login.", "errors": { "email": ["Email verification required."] } } ``` --- ### 4. Get Current User Get the authenticated user's profile information. **Request** ``` GET /api/v1/auth/me ``` **Headers** ``` Content-Type: application/json Accept: application/json Authorization: Bearer {your_token} ``` **Response (200 OK)** ```json { "success": true, "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": "+1234567890", "photo": "https://your-domain.com/assets/images/user.jpg", "is_verified": true, "addresses": { "shipping": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp", "state_id": 1 }, "billing": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp" } }, "created_at": "2024-01-01T10:00:00.000000Z", "updated_at": "2024-02-15T15:30:00.000000Z" } } } ``` **Error Responses** | Code | Error | |------|-------| | 401 | Unauthenticated (invalid or expired token) | **Example Error (401)** ```json { "success": false, "message": "Unauthenticated." } ``` --- ### 5. Refresh Token Generate a new access token (invalidates the current token). **Request** ``` POST /api/v1/auth/refresh ``` **Headers** ``` Content-Type: application/json Accept: application/json Authorization: Bearer {your_token} ``` **Response (200 OK)** ```json { "success": true, "message": "Token refreshed successfully.", "data": { "token": "2|xyz456abc...", "token_type": "Bearer" } } ``` **Error Responses** | Code | Error | |------|-------| | 401 | Unauthenticated | --- ### 6. Logout Invalidate the current authentication token. **Request** ``` POST /api/v1/auth/logout ``` **Headers** ``` Content-Type: application/json Accept: application/json Authorization: Bearer {your_token} ``` **Response (200 OK)** ```json { "success": true, "message": "Logged out successfully." } ``` **Error Responses** | Code | Error | |------|-------| | 401 | Unauthenticated | --- ### 7. Forgot Password Request a password reset link to be sent to the user's email. **Request** ``` POST /api/v1/auth/forgot-password ``` **Headers** ``` Content-Type: application/json Accept: application/json ``` **Body** ```json { "email": "john.doe@example.com" } ``` **Response (200 OK)** ```json { "success": true, "message": "Password reset link has been sent to your email." } ``` **Error Responses** | Code | Error | |------|-------| | 404 | No account found with this email | | 422 | Validation failed | | 500 | Failed to send email | **Example Error (404)** ```json { "success": false, "message": "No account found with this email address.", "errors": { "email": ["User not found."] } } ``` --- ### 8. Reset Password Reset the user's password using a reset token sent via email. **Request** ``` POST /api/v1/auth/reset-password/{token} ``` **URL Parameters** | Parameter | Type | Required | Description | |-----------|-------|-----------|-------------| | token | string | Yes | Password reset token received via email | **Headers** ``` Content-Type: application/json Accept: application/json ``` **Body** ```json { "password": "newpassword123", "password_confirmation": "newpassword123" } ``` **Response (200 OK)** ```json { "success": true, "message": "Password has been reset successfully." } ``` **Error Responses** | Code | Error | |------|-------| | 400 | Invalid or expired reset token | | 422 | Validation failed | **Example Error (400)** ```json { "success": false, "message": "Invalid or expired reset token.", "errors": { "token": ["Invalid reset token."] } } ``` --- ### 9. Verify Email Verify the user's email address using the verification token. **Request** ``` GET /api/v1/auth/verify/{token} ``` **URL Parameters** | Parameter | Type | Required | Description | |-----------|-------|-----------|-------------| | token | string | Yes | Email verification token | **Headers** ``` Accept: application/json ``` **Response (200 OK)** ```json { "success": true, "message": "Email verified successfully. You can now login.", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": "+1234567890", "photo": null, "is_verified": true, "addresses": { "shipping": { "address1": null, "address2": null, "city": null, "country": null, "zip": null, "company": null, "state_id": null }, "billing": { "address1": null, "address2": null, "city": null, "country": null, "zip": null, "company": null } }, "created_at": "2024-02-16T12:00:00.000000Z", "updated_at": "2024-02-16T12:00:00.000000Z" } } } ``` **Error Responses** | Code | Error | |------|-------| | 400 | Invalid verification token | **Example Error (400)** ```json { "success": false, "message": "Invalid verification token." } ``` --- ### 10. Resend Verification Email Resend the email verification link to the user. **Request** ``` POST /api/v1/auth/resend-verification ``` **Headers** ``` Content-Type: application/json Accept: application/json ``` **Body** ```json { "email": "john.doe@example.com" } ``` **Response (200 OK)** ```json { "success": true, "message": "Verification email has been resent." } ``` **Error Responses** | Code | Error | |------|-------| | 400 | Email already verified | | 404 | No account found with this email | | 422 | Validation failed | | 500 | Failed to send email | **Example Error (404)** ```json { "success": false, "message": "No account found with this email address." } ``` **Example Error (400)** ```json { "success": false, "message": "Email is already verified." } ``` --- ### 11. Get User Profile Get the authenticated user's profile with complete details including address information and state. **Request** ``` GET /api/v1/user ``` **Headers** ``` Content-Type: application/json Accept: application/json Authorization: Bearer {your_token} ``` **Response (200 OK)** ```json { "success": true, "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": "+1234567890", "photo": "https://your-domain.com/storage/avatars/user_1.jpg", "is_verified": true, "addresses": { "shipping": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp", "state_id": 1 }, "billing": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp" } }, "created_at": "2024-01-01T10:00:00.000000Z", "updated_at": "2024-02-16T15:30:00.000000Z" } } } ``` **Error Responses** | Code | Error | |------|-------| | 401 | Unauthenticated (invalid or expired token) | **Example Error (401)** ```json { "success": false, "message": "Unauthenticated." } ``` --- ### 12. Update User Profile Update the authenticated user's profile information. Supports updating name, phone, and avatar via file upload or URL. **Request** ``` POST /api/v1/update-profile ``` **Headers** ``` Content-Type: multipart/form-data (for file upload) Content-Type: application/json (for URL upload or text fields only) Accept: application/json Authorization: Bearer {your_token} ``` **Body (JSON)** ```json { "first_name": "John", "last_name": "Smith", "phone": "+1987654321", "avatar_url": "https://example.com/images/new-avatar.jpg" } ``` **Body (Form Data - for file upload)** ``` first_name: John last_name: Smith phone: +1987654321 avatar: [file] ``` **Body Fields** | Field | Type | Required | Description | |-------|------|----------|-------------| | first_name | string | No | User's first name | | last_name | string | No | User's last name | | phone | string | No | User's phone number | | avatar | file | No | Profile image file (jpeg, jpg, png, gif, max 2MB) | | avatar_url | string | No | Profile image URL (used if no file uploaded) | **Response (200 OK)** ```json { "success": true, "message": "Profile updated successfully.", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "email": "john.doe@example.com", "phone": "+1987654321", "photo": "https://your-domain.com/storage/avatars/user_1.jpg", "is_verified": true, "addresses": { "shipping": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp", "state_id": 1 }, "billing": { "address1": "123 Main St", "address2": "Apt 4B", "city": "New York", "country": "USA", "zip": "10001", "company": "Acme Corp" } }, "created_at": "2024-01-01T10:00:00.000000Z", "updated_at": "2024-02-16T16:45:00.000000Z" } } } ``` **Error Responses** | Code | Error | |------|-------| | 401 | Unauthenticated | | 422 | Validation failed | **Example Error (422)** ```json { "success": false, "message": "The given data was invalid.", "errors": { "first_name": ["First name must not exceed 255 characters."], "phone": ["Phone number is required."], "avatar": ["Avatar must be a file of type: jpeg, jpg, png, gif."] } } ``` --- ## HTTP Status Codes | Code | Description | |------|-------------| | 200 | OK - Request successful | | 201 | Created - Resource created successfully | | 400 | Bad Request - Invalid request data | | 401 | Unauthorized - Authentication required or invalid | | 403 | Forbidden - Access denied (e.g., email not verified) | | 404 | Not Found - Resource not found | | 422 | Unprocessable Entity - Validation errors | | 500 | Internal Server Error - Server error occurred | --- ## Common Error Response Format ```json { "success": false, "message": "Error description", "errors": { "field_name": ["Specific error message"] } } ``` --- ## Common Success Response Format ```json { "success": true, "message": "Success message", "data": { // Response data (optional) } } ``` --- ## Testing with Postman ### Import Collection To use these endpoints in Postman: 1. Create a new collection named "B2C E-Commerce API" 2. Set the base URL as a variable: `{{baseUrl}}` - Value: `http://localhost/api/v1` (development) - Value: `https://your-domain.com/api/v1` (production) 3. Add the endpoints from this documentation 4. For authenticated requests, add an Authorization header with type "Bearer Token" 5. Save the token from login response to use in subsequent requests ### Example Postman Setup **Environment Variables:** ``` baseUrl = http://localhost/api/v1 token = {{login_response.token}} ``` **Pre-request Script (for authenticated endpoints):** ```javascript if (!pm.environment.get("token")) { console.log("No token found. Please login first."); } ``` **Test Script (for login endpoint):** ```javascript if (pm.response.code === 200) { var jsonData = pm.response.json(); if (jsonData.success && jsonData.data.token) { pm.environment.set("token", jsonData.data.token); } } ``` --- ## Notes 1. **Token Expiration**: By default, Sanctum tokens do not expire unless configured otherwise. The `refresh` endpoint can be used to generate new tokens. 2. **Email Verification**: Users cannot login until their email is verified. The `email_token` field in the `users` table must be `null` for verification. 3. **Password Reset**: Reset tokens are MD5 hashes that can be used once. After a successful reset, the token is cleared. 4. **reCAPTCHA**: The system supports Google reCAPTCHA. If enabled in settings, the `g-recaptcha-response` field is required. 5. **CORS**: Ensure CORS is properly configured for frontend requests. 6. **File Uploads**: For endpoints requiring file uploads (e.g., profile photo), use `multipart/form-data` content type.