Customer API

The Customer API provides REST endpoints for customer authentication, profile management, and order access. This API uses token-based authentication via Laravel Sanctum and supports ability-based access control to differentiate between active and guest customers.

For customer authentication on the frontend web interface, see Customer Authentication. For customer account management in the admin panel, see Customer Administration.

Purpose and Scope

The Customer API enables external applications and single-page applications (SPAs) to integrate with the GP247/Shop customer system. It provides authenticated access to customer data, order history, and profile information through standard REST endpoints.

The API implements:

• Token-based authentication with configurable expiration
• Ability-based access control using Laravel Sanctum scopes
• Customer profile retrieval
• Order listing and detail access
• Secure logout with token revocation

Sources: src/Routes/Api/auth.php1-41 src/Api/Front/MemberAuthController.php1-142

API Architecture and Request Flow

Diagram: Customer API Request Flow and Component Relationships

This diagram shows how API requests flow through the routing layer, authentication middleware, controller logic, and data access layers before returning JSON responses.

Sources: src/Routes/Api/auth.php4-40 src/Api/Front/MemberAuthController.php13-141

Route Configuration and Namespace Resolution

The API routes are defined with dynamic namespace resolution to support both package-level and application-level controller overrides.

Diagram: Route Registration and Namespace Resolution Logic

The system checks for application-level controller overrides before falling back to package controllers, enabling customization without modifying core files.

Sources: src/Routes/Api/auth.php13-17 src/Routes/Api/auth.php19-37

API Endpoints

Public Endpoints

Method	Path	Description	Request Body	Response
POST	/login	Authenticate customer and generate access token	email, password, remember_me (optional)	Token object with expiration

Sources: src/Routes/Api/auth.php19 src/Api/Front/MemberAuthController.php27-69

Protected Endpoints

All protected endpoints require the Authorization: Bearer {token} header.

Method	Path	Description	Abilities Required	Response
GET	/logout	Revoke current access token	User or User Guest	Success message
GET	/info	Get current customer profile	User or User Guest	Customer object
GET	/member/order/list	List customer orders with pagination	User or User Guest	Paginated order list
GET	/member/order/detail/{id}	Get single order details	User or User Guest	Order object

Sources: src/Routes/Api/auth.php21-38 src/Api/Front/MemberAuthController.php87-140

Authentication Flow and Token Management

Diagram: Authentication Flow with Token Creation and Ability Assignment

The authentication process validates credentials, determines customer status, assigns appropriate abilities, and sets token expiration based on the remember_me flag.

Sources: src/Api/Front/MemberAuthController.php27-69

Token Abilities and Scopes

The system uses two distinct ability scopes configured in the application config:

• api_scope_user: Full access scope for active customers (status = 1)
• api_scope_user_guest: Limited access scope for inactive/guest customers (status = 0)

Token abilities are assigned during login based on the customer's status field in the shop_customer table:

src/Api/Front/MemberAuthController.php45-49

The middleware checks these abilities on each protected request:

src/Routes/Api/auth.php22-25

Sources: src/Api/Front/MemberAuthController.php45-51 src/Routes/Api/auth.php8-11 src/Routes/Api/auth.php22-25

Token Expiration Configuration

Token expiration is controlled by two configuration values:

Config Key	Purpose	Applied When
gp247-config.api.auth.api_remmember	Extended expiration in days	remember_me is true
gp247-config.api.auth.api_token_expire_default	Default expiration in days	remember_me is false or absent

The expiration timestamp is calculated using Carbon:

src/Api/Front/MemberAuthController.php54-59

Sources: src/Api/Front/MemberAuthController.php54-59

Login Endpoint

Request Format

Validation Rules

Field	Rule	Description
email	required, string, email	Valid email address
password	required, string	Customer password
remember_me	boolean	Optional flag for extended token expiration

src/Api/Front/MemberAuthController.php29-33

Success Response

Error Response

Returns HTTP 401 when credentials are invalid:

src/Api/Front/MemberAuthController.php37-40

Sources: src/Api/Front/MemberAuthController.php27-69

Logout Endpoint

Revokes the current access token, preventing further use.

Request Format

Implementation

The logout method deletes the current access token from the database:

src/Api/Front/MemberAuthController.php87-94

Success Response

Sources: src/Api/Front/MemberAuthController.php87-94

Customer Info Endpoint

Returns the authenticated customer's profile data.

Request Format

Implementation

The method returns the authenticated user object directly:

src/Api/Front/MemberAuthController.php96-99

Response Format

Returns the complete ShopCustomer model attributes including:

Sources: src/Api/Front/MemberAuthController.php96-99

Order Endpoints

Order List

Retrieves paginated list of customer orders with details and totals.

Request Format

Implementation

src/Api/Front/MemberAuthController.php106-122

The query includes:

• with('details'): Eager loads order line items from shop_order_detail table
• with('orderTotal'): Eager loads financial breakdown from shop_order_total table
• where('customer_id', $customer->id): Filters orders by authenticated customer
• orderBy('created_at', 'desc'): Returns newest orders first
• jsonPaginate(): Applies pagination with JSON-friendly response format

Response Format

Sources: src/Api/Front/MemberAuthController.php106-122

Order Detail

Retrieves a single order with full details and totals.

Request Format

Implementation

src/Api/Front/MemberAuthController.php124-140

The query ensures customers can only access their own orders by filtering on both customer_id and the requested order id.

Response Format

Returns the complete order object with nested relationships:

Sources: src/Api/Front/MemberAuthController.php124-140

Guard Configuration

The API uses a dedicated customer guard for authentication:

src/Api/Front/MemberAuthController.php101-104

This guard is referenced in the middleware configuration:

src/Routes/Api/auth.php23

The customer-api guard must be configured in the application's config/auth.php to use Laravel Sanctum with the ShopCustomer model as the provider.

Sources: src/Api/Front/MemberAuthController.php101-104 src/Routes/Api/auth.php23

Controller Inheritance and Traits

The MemberAuthController extends RootFrontController from the GP247/Front package and uses the AuthTrait:

src/Api/Front/MemberAuthController.php13-15

AuthTrait Integration

The trait provides shared authentication logic including:

• mappingValidator(): Maps validation rules for customer data
• validator(): Validates input data using mapped rules

src/Api/Front/MemberAuthController.php75-79

This validation method is available for use in the controller but is not currently called by the existing API methods. It provides a hook for custom validation logic if needed.

Sources: src/Api/Front/MemberAuthController.php13-15 src/Api/Front/MemberAuthController.php75-79

Error Response Format

All API endpoints follow a consistent error response structure:

Authentication Errors (HTTP 401)

or

Success Response (HTTP 200)

The error field is an integer flag:

• 0: Success
• 1: Error condition

Sources: src/Api/Front/MemberAuthController.php37-40 src/Api/Front/MemberAuthController.php118-121 src/Api/Front/MemberAuthController.php136-139

Integration with Other Systems

Diagram: Customer API Integration with Core Systems

The Customer API integrates with the Customer System for authentication and profile data, the Order System for order retrieval, the Configuration System for API settings, and the Authentication System for shared validation logic.

Sources: src/Api/Front/MemberAuthController.php1-142 src/Routes/Api/auth.php1-41