Accounts

Introduction

This page outlines the API routes for account management in the Toolstation E-Com system. It covers operations such as fetching account details, managing customers, retrieving orders, and setting customer-specific limits in the Toolstation Ecom API.

List of Routes for Accounts

1. /accounts/_ping
2. /accounts/{accountId}
3. /accounts/{accountId}/customers
4. /accounts/{accountId}/customers/{accountId}/spend-stats
5. /accounts/{accountId}/customers/{accountId}
6. /accounts/{accountId}/orders
7. /accounts/{accountId}/customer-limit/{accountId}
8. /accounts/{accountId}/customer-limit/{accountId}
9. /accounts/{accountId}/customer-limits

GET: accounts/_ping

• Method: GET
• Controller: PingController
• Description: Endpoint to check if the Accounts is valid and running successfully. This is a common endpoint for health checks or status pings.

GET: accounts/{accountId}

• Controller: AccountController
• Method: GET
• Request: Request
• Parameters:
  • accountId - Identifies the account.
• Description: Endpoint for getting details of an account.

The get function is responsible for retrieving an account by its ID and returning it as a response. It first calls the getAccountById method on the accountService object to retrieve the account data. Then, it checks if the user has permission to view the account using the authorize method. Finally, it creates a new AccountResource instance and returns it as the response.

public function get(Request $request, $accountId)
{
    // Function implementation goes here
}       

GET: accounts/{accountId}/customers

• Controller: AccountController
• Method: GET
• Request: GetAccountCustomersRequest
• Parameters:
  • accountId - Identifies the account.
• Description: Endpoint for getting details of customers associated with an account.

The getCustomers function is a controller method that retrieves a collection of customers associated with a given account. It performs various checks and retrieves the necessary data using the $accountService object. It also handles authorization and sorting of the customers based on the provided request parameters.

public function getCustomers(GetAccountCustomersRequest $request, $accountId)
{
    // Function implementation goes here
}       

POST: accounts/{accountId}/customers

• Controller: AccountController
• Method: POST
• Request: CreateChildAccountRequest
• Service: AccountCustomerLimitService
• Description: Endpoint for adding a new customer to an account.

The addCustomer function adds a new customer to an account, associates an existing customer with a trade credit account, updates employee limits, handles exceptions, and returns appropriate responses based on the outcome of the operations.

public function addCustomer(CreateChildAccountRequest $request, AccountCustomerLimitService $limitService)
{
    // Function implementation goes here
}       

GET: accounts/{accountId}/customers/{customerId}/spend-stats

• Controller: AccountController
• Method: GET
• Request: Request
• Service: AccountCustomerLimitService
• Parameters:
  • accountId - Identifies the account.
  • customerId - Identifies the customer.
• Description: Endpoint for adding a new customer to an account.

The addCustomer function getCustomerSpendStats that takes in a request object, account ID, customer ID, and an instance of AccountCustomerLimitService. It first checks if the user is authenticated and not a guest; if not, it returns a 403 Forbidden response. It then retrieves the account and customer based on the provided IDs and checks if the customer is associated with the account if not, it returns a 403 response. Next, it verifies if the user has the view permission on the account or if the user is the actual customer. If either condition is met, it returns spend statistics for the employee. Otherwise, it returns a 403 response.

public function getCustomerSpendStats(Request $request, $accountId, $customerId, AccountCustomerLimitService $service)
{
    // Function implementation goes here
}       

DELETE: accounts/{accountId}/customers/{customerId}

• Controller: AccountController
• Method: DELETE
• Request: Request
• Parameters:
  • accountId - Identifies the account.
  • customerId - Identifies the customer.
• Description: Endpoint for removing a customer from an account.

The removeCustomer function that removes a customer from an account. It first retrieves the account and customer by their IDs, and then checks whether the customer belongs to the account and is not an admin. If the customer is valid, it removes the customer from the account using the accountService object. If the customer is not valid, it returns an error response. The code also logs informational messages indicating the success or failure of the operation.

public function removeCustomer(Request $request, $accountId, $customerId)
{
    // Function implementation goes here
}       

GET: accounts/{accountId}/orders

• Controller: AccountController
• Method: GET
• Request: Request
• Parameters:
  • accountId - Identifies the account.
• Description: Endpoint for orders associated with an account.

The getOrdersForAccount function that allows users to retrieve orders for a specific account. It performs authorization checks to ensure that the user has the necessary permissions to view the orders and filters the orders based on the user's ID if they do not have the view permission on the account.

public function getOrdersForAccount(Request $request, $accountId)
{
    // Function implementation goes here
}       

POST: accounts/{accountId}/customer-limit/{customerId}

• Controller: AccountController
• Method: POST
• Request: Request
• Parameters:
  • customerId - Identifies the customer.
  • accountId - Identifies the account.
• Description: Endpoint for setting customer credit limit.

The setCustomerLimit function updates the credit limit and spend amount for a customer associated with an account, authorizes the user to update the account, checks if the customer exists and is not an admin, deletes the credit limit attributes if the credit limit is empty, sets the employee credit limit and spend amount if the credit limit is not empty, logs the successful update, and returns a successful response.

public function setCustomerLimit(Request $request, $accountId, $customerId)
{
    // Function implementation goes here
}       

DELETE: accounts/{accountId}/customer-limit/{customerId}

• Controller: AccountController
• Method: DELETE
• Request: Request
• Parameters:
  • customerId - Identifies the customer.
  • accountId - Identifies the account.
• Description: Endpoint for removing customer credit limit.

The setCustomerLimit function removes a customer's credit limit and balance from an account. It first fetches the account and authorizes the user to update it. Then, it checks if the customer exists and is not an admin. If the customer does not exist or is an admin, it returns an error response. If the customer exists, it deletes the credit limit and balance associated with the customer and logs the successful update. Finally, it returns an empty response with a 204 No Content status code.

public function removeCustomerLimit(Request $request, $accountId, $customerId)
{
    // Function implementation goes here
}       

PATCH: accounts/{accountId}/customer-limits

• Controller: AccountController
• Method: PATCH
• Request: UpdateCustomerLimitsRequest
• Service: AccountCustomerLimitService
• Description: Endpoint for updating customer limits.

The updateCustomerLimits function updates the employee limits for a list of customers in an account. It does this by calling the updateEmployeeLimits method of the AccountCustomerLimitService instance for each customer, passing in the account, customer, and limit data. The function returns an empty response after updating all the limits.

public function updateCustomerLimits(UpdateCustomerLimitsRequest $request, AccountCustomerLimitService $service)
{
    // Function implementation goes here
}