API Endpoints Guide

Relevant source files

The following files were used as context for generating this wiki page:

• routes/api.php
• app/Services/TemplateService.php
• resources/views/dashboard/templates.blade.php
• resources/views/dashboard/messages.blade.php
• resources/views/dashboard/whatsapp-account.blade.php
• resources/views/dashboard/pos/categories.blade.php
• routes/web.php

The QashierWise backend exposes a RESTful API to handle user authentication, WhatsApp Business Platform integration, and Point of Sale (POS) functionalities. The API is the primary interface for the frontend dashboard, enabling a decoupled architecture.

Most API endpoints are protected and require authentication via Laravel Sanctum. Clients must include a Bearer token in the Authorization header for all protected requests. The API is versioned and organized into logical route groups, primarily under the /api prefix.

API Architecture

The API routes are defined in routes/api.php. The structure separates public routes, protected routes, and webhooks. Protected routes are grouped under the auth:sanctum middleware.

The following diagram illustrates the high-level structure of the API routes.

*Sources: [routes/api.php:27-181](https://github.com/adityabintang/qashierwise-be/blob/HEAD/routes/api.php#L27-L181)*

Authentication

Authentication is handled via Laravel Sanctum. Public endpoints are available for user registration and login, which returns a bearer token for subsequent authenticated requests.

The diagram below shows the sequence for a user logging in and receiving an authentication token.

*Sources: [routes/api.php:28](https://github.com/adityabintang/qashierwise-be/blob/HEAD/routes/api.php#L28), [resources/views/dashboard/templates.blade.php:1406-1408](https://github.com/adityabintang/qashierwise-be/blob/HEAD/resources/views/dashboard/templates.blade.php#L1406-L1408)*

Auth Endpoints

Method	URI	Controller Action	Description
POST	/api/register	register	Creates a new user account.
POST	/api/login	login	Authenticates a user and returns a token.
POST	/api/logout	logout	Revokes the current user's token.
GET	/api/me, /api/user	me	Retrieves the authenticated user's data.

Sources: routes/api.php:27-28, 43-45

Webhooks

The API exposes public webhook endpoints to receive real-time data from external services. These routes are not protected by auth:sanctum to allow access from services like WhatsApp and Polar.sh.

Method	URI	Controller Action	Description
GET	/api/whatsapp/webhook	verify	Handles the WhatsApp webhook verification challenge.
POST	/api/whatsapp/webhook	handle	Receives incoming messages and status updates.
POST	/api/webhooks/polar	handle	Receives subscription events from Polar.sh.

Sources: routes/api.php:31-35

WhatsApp Business API (/api/whatsapp)

This is the largest and most critical part of the API, handling all interactions with the WhatsApp Business Platform.

Account Management & Embedded Signup

The application uses the WhatsApp Embedded Signup flow to connect a user's WhatsApp Business Account (WABA). This involves a frontend flow using the Facebook SDK and a backend callback to exchange an authorization code for a permanent user access token.

The flow is as follows:

1. Frontend fetches configuration (/api/whatsapp/embedded-signup/config).
2. Frontend uses the Facebook SDK to launch the signup popup.
3. User completes the flow in the popup.
4. Facebook sends an authorization code to the backend callback (/api/whatsapp/embedded-signup/callback).
5. The backend exchanges the code for a user access token and saves the WABA details.

Method	URI	Controller Action	Description
GET	/api/whatsapp/embedded-signup/config	getConfig	Provides the necessary app_id and config_id for the FB SDK.
POST	/api/whatsapp/embedded-signup/callback	handleCallback	Handles the callback from Facebook after the user completes the signup.
GET	/api/whatsapp/account	getAccountStatus	Retrieves the status of the connected WhatsApp account.
DELETE	/api/whatsapp/account	disconnect	Disconnects the user's WhatsApp account from the application.

Sources: routes/api.php:71-76, resources/views/dashboard/whatsapp-account.blade.php:340-398

Message Templates

Message templates are a core feature, allowing users to create, manage, and send pre-approved messages. The API provides full CRUD functionality for templates.

The creation of a template involves frontend validation and a backend service that constructs the payload for the WhatsApp Graph API.

*Sources: [routes/api.php:117](https://github.com/adityabintang/qashierwise-be/blob/HEAD/routes/api.php#L117), [app/Services/TemplateService.php:329-421](https://github.com/adityabintang/qashierwise-be/blob/HEAD/app/Services/TemplateService.php#L329-L421), [resources/views/dashboard/templates.blade.php:1115-1175](https://github.com/adityabintang/qashierwise-be/blob/HEAD/resources/views/dashboard/templates.blade.php#L1115-L1175)*

Template Validation

The TemplateService enforces several validation rules before submitting a template to Meta for approval:

• Name: Must contain only lowercase letters, numbers, and underscores. (/^[a-z0-9_]+$/)
• Body: Required and cannot exceed 1024 characters.
• Footer: Optional, but cannot exceed 60 characters if provided.
• Buttons: A template can have up to 10 QUICK_REPLY buttons OR up to 2 Call-to-Action (URL, PHONE_NUMBER) buttons, but not a mix of both types.

Sources: app/Services/TemplateService.php:50-57, 91-98, 102-113, 123-157

Template Endpoints

Method	URI	Controller Action	Description
GET	/api/whatsapp/templates	getTemplates	Retrieves all message templates for the user's account. Can use ?refresh=true to sync from Meta.
POST	/api/whatsapp/templates	createTemplate	Creates a new message template.
PUT	/api/whatsapp/templates/{id}	updateTemplate	Updates an existing message template.
DELETE	/api/whatsapp/templates/{name}	deleteTemplate	Deletes a message template by its name.
GET	/api/whatsapp/templates/{name}	getTemplateByName	Retrieves a single template by its name.

Sources: routes/api.php:116-120, resources/views/dashboard/templates.blade.php:913-919, 1115-1175, 1480-1499

Sending Messages

The API provides dedicated endpoints for sending various types of WhatsApp messages.

Method	URI	Controller Action	Description
POST	/api/whatsapp/send/text	sendTextMessage	Sends a plain text message.
POST	/api/whatsapp/send/template	sendTemplateMessage	Sends a pre-approved template message.
POST	/api/whatsapp/send/image	sendImageMessage	Sends an image message with an optional caption.
POST	/api/whatsapp/send/video	sendVideoMessage	Sends a video message with an optional caption.
POST	/api/whatsapp/send/document	sendDocumentMessage	Sends a document with an optional caption.
POST	/api/whatsapp/send/audio	sendAudioMessage	Sends an audio message.
POST	/api/whatsapp/send/location	sendLocationMessage	Sends a location message.
POST	/api/whatsapp/send/button	sendButtonMessage	Sends an interactive message with buttons.
POST	/api/whatsapp/send/list	sendListMessage	Sends an interactive message with a list.

Sources: routes/api.php:78-90, resources/views/dashboard/messages.blade.php

Point of Sale (POS) API (/api/pos)

This route group contains endpoints for managing the Point of Sale system, including products, categories, orders, and reports.

POS Resource Endpoints

The API uses Laravel's apiResource routing for standard CRUD operations on POS entities like products and categories. This automatically generates a set of RESTful endpoints.

Method	URI	Action	Description
GET	/api/pos/categories	index	Get a list of all categories.
POST	/api/pos/categories	store	Create a new category.
GET	/api/pos/categories/{id}	show	Get a single category by ID.
PUT/PATCH	/api/pos/categories/{id}	update	Update an existing category.
DELETE	/api/pos/categories/{id}	destroy	Delete a category.

Note: The table above shows the endpoints for /categories. A similar set of endpoints exists for /products.

Sources: routes/api.php:148, 151, resources/views/dashboard/pos/categories.blade.php:164-192, 209-228

Other POS Endpoints

The POS API also includes more specific endpoints for actions like:

• Managing items within an order (/api/pos/orders/{order}/items).
• Completing or canceling orders.
• Generating sales reports (/api/pos/reports/*).
• Searching and filtering transactions.

Sources: routes/api.php:154-181