An awesome starter template to create your Salla Apps today!
Explore our blogs »
Report Bug ·
Request Feature . </Salla Developers>
Table of Contents
This is a starter App includes a Laravel application equipped with the required auth processes and webhooks/actions that help you to create your Salla App which works with the Salla APIs. Your App later can be published to the Salla App Store and be available for installation to any of Salla Merchants Stores.
What can you use this starter App for?
- Create a Salla App from scratch, e.g. chatbot app or shipping service app, or any amazing app from your idea.
- Modify/Customize any of your previous Apps in order to take the advantages given by this starter App.
The starter App comes with an easy 1-command step that does the complete setup for your starter App. To be ready, you will need some prerequisites which will be listed hereafter.
-
Create a Partner account at Salla Partner Portal
-
Create your App in Salla Partner Portal
From your App dashboard at Salla Partner Portal, you will be able to get your App's Client ID, Client Secret Key and Webhook Secret Key which you will use later duraing the setup process.
-
For Laravel compatibility:
PHP >= 7.4, Composer package manager and MySql Database -
Install ngrok:
npm install ngrok -g -
Other requirments:
Nodejs and npm
That is all!
The installation process is straightforward as you will see in the below steps.
-
In your MySql Database: create a database with any name for example
laravel. -
In your command line: run the following
create-projectcomposer command to create your Laravel starter App project.
composer create-project salla/laravel-starter-kit {your-awesome-app}The above create-project will take you through a step-by-step process in which you'll enter your App's Client ID, Client Secret Key, and Webhook Secret Key, which you can get from your App dashboard in the Partners Panel, as well as your database name, which is set to laravel by default.
The step will ask you to select the authorization mode for your App, which can be Easy or Custom mode. In case you selected the Custom mode for your App authorization, you will need to enter the same callback Url you already entered in your App dashboard at the Salla Partner Portal
- In your command line: Run
php artisan serve.remotecommand
Now you can open your browser to view your App at Remote App Url in the output URLs.. 🎉
- Login to the Laravel App with the demo account: Email:
awesome@salla.dev, Password:in ksa - Click the button to request the Access Token.
- The Laravel App will redirect you to Merchant Auth Page.
- Login using a Merchant Account (or the demo store of your app).
- Give access to your App.
If you are using Easy mode. the access token will push to the action (
StoreAuthorize) via webhookIf you are using Custom mode. the browser will redirect you again to the
callback() page.
| URL | Description |
|---|---|
| Local App Url | The local link for your App. |
| Remote App Url | The online link to your App. It will be always synced with the local Url |
| Webhook Url | The Url link that connects your App with any action that may happen at the Merchant store, e.g. \ncreate new product. |
| OAuth Callback Url | The App entry page where the access token is generated; Note that this Url is available only for the Custom mode auth. |
While creating your App in the Salla Partners Portal, you will see that Salla provids two methods for the OAuth protocol, which are the Easy Mode and the Custom Mode.
During the setup process, the default OAuth protocol will be set to the
Easy Mode, which can be configured from the file.env. All of the setup's values/keys are stored in the.envfile as we can see in the below image.
This mode is the default mode for the authorization, which means that the access token is generated automatically at Salla's side back to you.
You may refer to the class StoreAuthorize which is defined inside app\Actions\App\StoreAuthorize.php to get more details on how to receive and manage the access token
A callback Url is the Url that is triggered when the App has been granted authorization. This should be a valid Url to which the merchant's browser is redirected. In this mode, you will need to set a custom callback url from the App dashboard at the Salla Partner Portal. This callback url will redirect the merchants who are interested in using your app into your App entry page where the access token is generated.
You may refere to file app/Http/Controllers/OAuthController.php which contains the callback() function. This function is responsible for generating the access token
The custom url will redirect the merchant to the Store Dashboard in order to access the Store where he needs your App to be installed.
This project comes with a simple singleton authorization service to help you with managing the access and refresh tokens
// set the current user or any user you want to use his access tokens
app('salla.auth')->forUser(auth()->user());
// Get the get the store details
/** Salla\OAuth2\Client\Provider\SallaUser::class **/
app('salla.auth')->getResourceOwner();
// Made an API request using the current access token of the user
app('salla.auth')->request('GET', 'https://api.salla.dev/admin/v2/products')['data'];
// Request a new access token
app('salla.auth')->getNewAccessToken();
// Save the access token
auth()->user()->token()->create([
'merchant' => 'id',
'access_token' => 'access token',
'expires_in' => 'expires in sec',
'refresh_token' => 'refresh token'
]);Access tokens expire after one week. Once expired, you will have to refresh a user’s access token. you can easily request a new access token via the current refresh token for any user like this
try {
// set the current user
// or any user you want to refresh his access token
app('salla.auth')
->forUser(auth()->user())
->getNewAccessToken();
// by default the function `getNewAccessToken` will get a new access token
// and save the new access token to the same user you are set it in the `forUser` function
} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $exception) {
// in case the token access token & refresh token is expired
// you should redirect the user again to Salla authorization service to get a new token
// return redirect()->route('oauth.redirect');
}Webhooks simplify the communication between your App and Salla APIs. In this way, you will be notified whenever your app receives payload/data from the Salla APIs. These webhooks are triggered along with many actions such as an order or product being created, a customer logs in, a coupon is applied, and much more.
Salla already defined a list of the webhooks/actions that are triggered automatically. The predefined webhooks/actions can be found in the folder app/Actions.
| ** Action Name ** | ** Description ** |
|---|---|
| order.created | This indicates a singular order has been created |
| order.updated | Details, data and/or content of a specific order have been refreshed updated |
| order.status.updated | Whenever there is an order status update, this is triggered |
| order.cancelled | This happens when an order is cancelled |
| order.refunded | The refund action to refund the whole order is triggered. |
| order.deleted | This indicates an order has been deleted |
| order.products.updated | Order products is updated |
| order.payment.updated | A payment method has been updated |
| order.coupon.updated | This is triggered whenever a Coupon is updated |
| order.total.price.updated | A total price of an order has been updated |
| order.shipment.creating | This indicates a new shipment is being created |
| order.shipment.created | This indicates a new shipment has been created |
| order.shipment.cancelled | This indicates a an order shipment has been cancelled |
| order.shipment.return.creating | This is triggered when a returned order shipment is being created |
| order.shipment.return.created | This is triggered when a returned order shipment has been created |
| order.shipment.return.cancelled | This is triggered when a returned order shipment has been cancelled |
| order.shipping.address.updated | Occurs when an Order shipping address is updated |
| ** Action Name ** | ** Description ** |
|---|---|
| product.created | A new product is created. Payload of the new product are to accompanying the product |
| product.updated | Add/Modify details of a product |
| product.deleted | Delete a product along with all its variants and images |
| product.available | Flags a product as stock available |
| product.quantity.low | Shows warnings whenever a stock is of low quantity |
| ** Action Name ** | ** Description ** |
|---|---|
| customer.created | Create a new customer record |
| customer.updated | Update details for a customer |
| customer.login | Triggered whenever a customer log in |
| customer.otp.request | One-Time Password request for a customer |
| ** Action Name ** | ** Description ** |
|---|---|
| category.created | Creates a new category for products to be put under |
| category.updated | Add new or reform existing category details |
| ** Action Name ** | ** Description ** |
|---|---|
| brand.created | Creates a new Brand. |
| brand.updated | Triggered when Information about a sepcific Brand is updated/refurbished/streamlined |
| brand.deleted | An existing brand is then deleted and removed from a store |
| ** Action Name ** | ** Description ** |
|---|---|
| store.branch.created | Creates a new store. |
| store.branch.updated | Updates an existing branch |
| store.branch.setDefault | Sets for default a specific branch |
| store.branch.activated | Activates a disabled branch |
| store.branch.deleted | Deletes a branch |
| storetax.created | Creats a new Store Tax |
| ** Action Name ** | ** Description ** |
|---|---|
| coupon.applied | Creates a discount code in the form of a coupon |
| review.added | A product review has been added |
| abandoned.cart | Outputs a list of abandoned carts |
| specialoffer.created | Creates a new special offer |
| specialoffer.updated | Updates a special offer |
The setup file can be found in app/Console/Commands/Setup.php.
php artisan setupThe predefined Webhooks, events/actions, can be found in folder app/Actions.
You may define your own new webhook/action the way fits your App's requirments.
php artisan make:webhook.event {event-name}Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
If you discover any security-related issues, please email security@salla.sa instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.