Referral System Service - Getting Started Guide

The Referral System Service is a powerful tool for managing user referrals, rewards, and profiles in your application. Before you start using the service, you need to create an admin profile.

Step 1: Create an Admin Profile

To create an admin profile, send a POST request to the /profile endpoint. You will need to provide a username and password in the request body.

• Request Method: POST
• Required Parameters:
  • username: Admin username
  • password: Admin password

This will create your admin profile, and you will receive a unique admin ID in the response.

Make sure to save your admin ID. You will need it for making authenticated requests to the service in the future.

Now, you have successfully created an admin profile, and you’re ready to use the Referral System Service to manage your user referrals and rewards. You can proceed to define rewards, generate referral codes, and handle user referrals.

Step 2: Define Reward Configuration

In this step, you’ll define the reward configuration for your referral system. Rewards are what make your referral program enticing for both referrers and referred users.

To define Rewards send a POST request to the /define-rewards endpoint. You will need to provide your admin profile ID, along with the reward details in the request body.

• Request Method: POST
• Required Parameters:
  • id: Admin ID
  • forReferrer: Object with reward details
  • forReferred: Object with reward details

The service will save your reward configuration, and it will be used to allocate rewards to users who participate in the referral program.

Step 3: Generate Referral Codes for Users

In this step, you will generate a unique referral code for each user, allowing them to participate in your referral program.

To generate a referral code for a user, send a POST request to the /generate-referral-code endpoint. You will need to provide the user’s ID and their user-specific ID in the request body.
userID is a unique identifier for your user, something like an Email or Phone number.

• Request Method: POST
• Required Parameters:
  • id: Admin ID
  • userId: User’s ID

The service will generate and save a unique referral code for the specified user. The user can use this code to refer others to your service and earn rewards.

Now, every user in your system has a unique referral code, enabling them to participate in your referral program. Users can share this code with others, and when those referrals take action, rewards will be allocated based on your reward configuration.

Step 4: Implement Submitted Referral Codes

In this step, you will implement the handling of submitted referral codes. When users submit referral codes, the system will verify the codes, allocate rewards, and track the referral process.

To handle submitted referral codes, send a POST request to the /submit-referral-code endpoint. In the request body, provide the user’s ID, their user-specific ID, and the referrer’s code.

• Request Method: POST
• Required Parameters:
  • id: Admin ID
  • userId: User’s ID
  • referrerCode: Referrer’s code

If the referral code is valid, the system will allocate rewards to both the referrer and the referred user, based on the reward configuration defined in Step 2.

The service will track the referral process, marking that the user has used a referral code. This prevents multiple uses of the same code by the same user.

Step 5: Retrieve Allocated Rewards for a User

To retrieve the allocated rewards for a user, send a GET request to the /referral/rewards/:id/:userReferralCode endpoint. Replace :id with your admin ID, and :userReferralCode with the referral code of the user whose rewards you want to check.

• Request Method: GET
• Required Parameters:
  • id: Admin ID

The service will return the rewards allocated to the user with the provided referral code. You can view the list of rewards and their details, including the reward type and allocation time.

The reward details may include the reward type (e.g., for referrer or for referred) and the time of allocation (timestamp). You can check each reward entry for these criteria.

Step 6: Admin Profile and User Management

In this step, you will learn how to manage admin profiles and user accounts. Both editing profiles and user management require basic authentication using the admin ID used to create the profile.

Edit Admin Profile

To edit your admin profile, send a PUT request to the /profile endpoint. Include your admin ID in the request body, and provide the updated username and password

• Request Method: PUT
• Required Parameters:
  • id: Admin ID
  • username: New username
  • password: New password

Edit User Information

To edit user information, send a PUT request to the /user/:userId endpoint, replacing :userId with the user’s specific ID you want to edit. Include your admin ID in the request body, and provide the updates to the user’s

• Request Method: PUT
• Required Parameters:
  • id: Admin ID
  • username: New username
  • password: New password
  • other-user-properties: New values

Delete User

To delete a user account, send a DELETE request to the /user/:userId endpoint, replacing :userId with the user’s specific ID you want to delete. Include your admin ID in the request body.

• Request Method: DELETE
• Required Parameters:
  • id: Admin ID

Authentication:

The following endpoints require admin authentication:

• /define-rewards: Define rewards for users.
• /get-rewards: Get the current rewards.
• /user/:userId: Edit user information.
• /user/:userId: Delete a user.

Admin authentication is performed using HTTP Basic Authentication with the admin’s username and password.

Responses

The API may return the following HTTP response codes to indicate the status of your requests:

• 200 OK: The request was successful, and the response data is included in the body.
• 201 Created: The resource (e.g., user profile, rewards) was successfully created.
• 400 Bad Request: The request is invalid, missing parameters, or contains errors. Check the error message in the response body for details.
• 401 Unauthorized: Authentication failed, or the user does not have access to the requested resource.
• 404 Not Found: The requested resource was not found (e.g., user, rewards, or referral code).
• 500 Internal Server Error: An unexpected server error occurred. Please report this issue to the administrator.

Sample Response (Success)

A successful response (e.g., 200 OK) will typically include the requested data in JSON format in the response body. Here’s an example:

{
  "message": "Operation successful",
  "data": {
    "user": "user123",
    "rewards": [
      {
        "timestamp": "2023-01-01T00:00:00Z",
        "amount": 10
      }
    ]
  }
}

Sample Response (Error)

In case of an error (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found), the response will include an error message in the response body. Here’s an example:

{
  "error": "Invalid user ID"
}

This README provides an overview of the Referral service API.