> For the complete documentation index, see [llms.txt](https://twenty-ninex2.gitbook.io/ngx-bill/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://twenty-ninex2.gitbook.io/ngx-bill/master.md). # Quick start ### NGX.BILL SaaS - Accounting & billing software | | | | ------------------ | ------------------------------ | | **Version:** 1.3.9 | **Created**: 11 November, 2021 | | **Author**: 29x2 | **Updated**: 21 November, 2021 | Thank you for trusting us to launch or manage your business with NGX.BILL SaaS and we hope that this can help to boost your activities. 🀞 If you have any questions that are beyond the scope of this help file, Please feel free via email or discord: {% embed url="" %} ### Project structure Unzip the zip file you have downloaded. The project is located in the **/ngx-bill** folder ``` ngx-bill/ | |– startup-kit-angular/ | |– .vscode # Contains visual studio code editor configurations | |– e2e # end to end tests | |– src | | |– app # Contains all the angular components of the web app | | |– assets # Contains images, css, scss and javascript files | | |– environments # Contains the environment variable files: dev & prod | |– .editorconfig | |– .gitignore | |– angular.json | |– browserslist | |– karma.conf.js | |– package-lock.json | |– package.json # Contains project informations & dependencies definition | |– tsconfig.app.json | |– tsconfig.json | |– tsconfig.spec.json | |– tslint.json | |– startupi-kit-api/ | |– .vscode # Contains visual studio code editor configurations | |– Common # Contains common cs files | |– Controllers # Contains all the api controllers | |– Migrations # Contains entity framework migrations | |– Models # Contains all the models | |– Properties | |– Services | |– .gitignore | |– Program.cs | |– Startup.cs | |– appsettings.Development.json | |– appsettings.json # Contains connection string & other variables | |– libwkhtmltox.dll | |– libwkhtmltox.dylib | |– libwkhtmltox.so | |– startup-kit-api.csproj | |– startup-kit-api.csproj.user | |– web.config |– documentation link & resources ``` ### Installation In this documentation we will consider that you are using [smarterasp.net](https://www.smarterasp.net/) because for us it is the easiest way to host your web app but you can use any other hosting company. The installation requires a little technical background. Do not hesitate to contact us if you encounter any difficulties. ***We offer installation services starting at $49. Do not hesitate to contact us if you need us to take care of this task:*** [***https://discord.gg/kA4adFJWrz***](https://discord.gg/kA4adFJWrz) #### **Minimum server requirements** Make sure that the server of your hosting company has the following technology installed: * .NET Core 3.1 * MSSQL (Microsoft SQL Server) Go to smarterasp.net or your web hosting companies and create your account. *If you choose smarterasp.net free plan, you need to activate it on the dashboard by providing the requested information before doing anything.* Access the control panel of your web hosting or smarterasp.net via this icon below ![](/files/DIULfNxGdCM8Gm6kjLIh) #### Create the database Once on the dashboard of your control panel create a SQL Server database. On smarterasp.net click on database then MSSQL to create a new database ![](/files/bSQScjMkQRom6svYTi2V) Once created get the connection string to use for database connection. In smarterasp click on the icon bellow ![](/files/c8Pqi4ECX0oqwjqzIpF6) Replace connection string provided in ngx-bill/startup-kit-api/appsettings.json ``` "ConnectionStrings": { "LocalConnectionString": "Data Source=(localdb)\\MSSQLLocalDB;Initial Catalog=ngx-bill-01;Integrated Security=True;", } ``` Download & install dotnet core 3.1 in your local machine: [Download .net core 3.1](https://dotnet.microsoft.com/download/dotnet/3.1) Search and open a command prompt ![](/files/XwPTDZurH8wuX60FYyUZ) Navigate to ngx-bill//startup-kit-api using the command below where \ corresponds to the location where you copied the project folder. ``` cd c://ngx-bill/startup-kit-api ``` Use the command below to generate tables and default data inside the database ``` dotnet ef database update ``` #### Upload the api to server In your command prompt access the api folder ``` cd c://ngx-bill/startup-kit-api ``` Run the command below to create the deployment package ``` dotnet publish --configuration Release ``` A folder "bin" will be created at this path : **ngx-bill\startup-kit-api\bin\\** and the deployment package will be at **: ngx-bill\startup-kit-api\bin\Release\netcoreapp3.1\publish\\** Use an FTP File transfert client or download WinSCP to connect to the server: Try to find in your control panel your FTP connection information. For smaterasp.net you will find these information in the left side ![](/files/qcw8lLXZ4Bob25h7ayiO) Upload the content of your api **ngx-bill\startup-kit-api\bin\Release\netcoreapp3.1\publish** to the server ![](/files/Ut39NEE3OB8uhwg42zbY) #### Upload the client to the server You can publish the client content on a different server but here for practical reasons we will do it on the same server Download and install in your local machine the latest node.js: [Link](https://nodejs.org/en/download/)\ After nodejs installation, run the command below to install angular cli locally in your machine ``` npm install -g @angular/cli ``` Navigate to the angular root project **ngx-bill/startup-kit-angular** via your prompt command ``` cd c://ngx-bill/startup-kit-angular ``` Run the command below to install the project dependencies and package. ``` npm install ``` In ngx-bill/startup-kit-angular/src/environments/environment.prod.ts replace the value of apiHost with what will be your domain url ``` apiHost: 'http://yourdomain.com/api', ``` In the same path **ngx-bill/startup-kit-angular**, run the command below to generate the release ``` npm run prod ``` This will generate the release at this path: **ngx-bill\startup-kit-angular\dist\startup-kit-angular\browser**. Connect again to the server via FTP connection and upload the content of this folder inside the wwwroot folder of your api on the server. That's all. Use the url provided to test your site then connect your domain name. I*f you have a technical background and want to have a quick guide to host your application on lunix then follow this tutorial:* [*https://dev.to/maxwelladn/deploying-net-core-angular-and-sql-server-to-ubuntu-2a6h*](https://dev.to/maxwelladn/deploying-net-core-angular-and-sql-server-to-ubuntu-2a6h) ### Technologies * The API & database * The api is built in .net core 3.1 (c#) and use entity framework core 3.1 to connect with the database * The database type is SQL Server * Stripe SDK for stripe API calls * PayPal SDK for PayPal API call * JWT Authentication for API security * The client side is built with angular 12 and lot of others technologies * Angular 12 * A customizable angular UI kit: Nebular - * Bootstrap 4.6: * Stripe SDK * PayPal SDK * JsPDF for invoice PDF building: * ngx-translate that help to translate the web application: ### ### SuperAdmin (application owner) 🦾 After you host the application you can access it with the login details provided in the documentation & resources file. For security reasons it is important to change this information in profile section. Also try to remember it because these login have the role super admin as the owner and gives access to the application setting.You can also add other super admin accounts for security otherwise in case of forget you will be forced to create new super admin account directly in the database. ### ### Activate your license We are mooving to codecanyon. However if you have purchased your license on this platform you have to send a request to activate your license key before using it otherwise you can use your license directly in the application We are sorry for the inconvenience. We are still working on the automatic activation system of your license from codecanyon within the application In the meantime After the purchase you received by email a link containing the source code and the license key {% embed url="" %} The project is open source and contains no third party or tracker so you can safely modify and use it. The activation key just unlocks certain features depending on your license. After sending filling the form, please wait for ours response and then copy the license. Go to Console => Activate license Paste the license the key in the field and save. ### Stripe Stripe integrates main features of your application. Its configuration is mandatory in order to make the software work perfectly. By setting up your stripe account you will allow your users to automatically connect their own stripe account via the application and receive credit card payments from their customers. You will also be able to receive payments from your users' subscriptions. * Go to [https://dashboard.stripe.com/](https://dashboard.stripe.com) and make sure to login to your account or create new one * Click on \*\*developers \*\*in the right top menu section * Then click on **API keys** in the left menu * Switch from test to live at the top of the menu then copy your p**ublishable key** and **secret key** * As super admin and the owner of the application you have access to the super admin console. Go to your web application and click on \*\*Console \*\*in the sidebar then \*\*Stripe & PayPal \*\* * Enter your **publishable key** and \*\*secret key \*\*then save * Return to your **Stripe dashboard** and click on \*\*Webhooks \*\*in the left menu in the \*\*developer \*\*section * You have to create 3 differents endpoint * Click on \*\*Add endpoint \*\*to create **first webhook** * Replace your api (dotnet project) domain using the following url: * Description is optional * Click on **+ Select events and add these 3 events:** * **invoice.payment\_failed;** **invoice.paid; checkout.session.completed** * Review all filled informations and save * Click on \*\*Reveal \*\*the \*\*Signing secret \*\*. * Go to super admin console then \*\*Stripe & PayPal \*\* * Copy and paste the signature secret into the field corresponding to the example url used above. * Save the changes * Create **second webhook** * Replace your api (dotnet project) domain using the following url: * Description is optional * Click on **+ Select events and add 1 events:** * **checkout.session.completed** * Review all filled informations and save * Click on \*\*Reveal \*\*the \*\*Signing secret \*\*. * Go to super admin console then \*\*Stripe & PayPal \*\* * Copy and paste the signature secret into the field corresponding to the example url used above. * Save the changes * Create the \*\*third webhook \*\* * Replace your api (dotnet project) domain using the following url: * Description is optional * `Click on checkbox`` `**`Listen to event on Connected account`** * Click on \*\*+ Select events \*\*and add **18 events:** * **transfer.updated; payout.updated; charge.refund.updated; charge.updated; transfer.paid; payment\_intent.succeeded; payout.paid; invoice.paid; order.payment\_succeeded; invoice.payment\_succeeded; charge.succeeded; charge.refunded; charge.captured; application\_fee.created; application\_fee.refunded; application\_fee.refund.updated; checkout.session.async\_payment\_succeeded; checkout.session.completed** * Review all filled informations and save * Click on \*\*Reveal \*\*the \*\*Signing secret \*\*. * Go to super admin console then \*\*Stripe & PayPal \*\* * Copy and paste the signature secret into the field corresponding to the example url used above. * Save the changes * After all the Stripe configuration, if you can, do some payment tests ### PayPal PayPal also integrates main features of your application. Its configuration is mandatory in order to make the software work perfectly. You can also allow your users to automatically connect their own PayPal account via the application and receive payments from their customers. You will also be able to receive payments from your users' subscriptions. * To get access to PayPal partner APIs go to this page and submit your information. * PayPal should respond in two or three days on average by email for a positive or negative response. In the meantime continue to configure the application and check your email regularly to be able to test in case of a position response. * If you receve a negative call PayPal or submit to them and ticket. * Go to PayPal developer dashboard [https://developer.paypal.com/](https://developer.paypal.com) and Make sure you switch to **Live Mode** * Click on **create app** for subscriptions module * Give a name to your app and click on the radio button "**Merchant** **– Accept payments as a merchant (seller)**" * Provide your own information and save * Click on the newly app created and make sure that also \*\*Transaction Search \*\*is checked and save * Go to the bottom of the app page and **create a new webhook** * Provide the webhook url: [https://yourdomain.com/api/subscriptions/paypal/webhook](https://3949-2a01-e0a-523-f8e0-c41f-42f6-9e7a-8e53.ngrok.io/api/subscriptions/paypal/webhook) * Select these events and save: **Billing subscription payment failed; Payment sale completed** * Copy your Client Id and Secret key. * Go to your web application and click on \*\*Console \*\*in the sidebar then \*\*Stripe & PayPal \*\* * Paste the Client Id in PayPal Client Id field and secret key in PayPal Secret field. Save the information * Return to the PayPal dashboard * Create a new app again and click on the radio button "**Platform** **– Move payments to sellers as a platform (marketplace, crowdfunding, or e-commerce platform)**" * Provide your information and save * Click on your newly created application and check that this field is checked: \*\*Intent => business \*\*and save * Copy your Client Id and Secret key. * Go to your web application and click on \*\*Console \*\*in the sidebar then **Stripe & PayPal** * Paste the Client Id in PayPal Partner Client Id field and secret key in PayPal Partner Secret field. Save the information ### Google login We strongly recommend you to setup Google login because it sometimes convinces the most hesitant to register with a few clicks on your platform with their google account if they have one * Go to * Login with your google account or create a new one * Create a **new project** for your software * In the sidebar menu click on \*\*API & Services \*\*then **OAuth consent screen** * Select the **User Type** as **External** and click **Create** * Fill out and save your app details, while making sure that you select **userinfo.email** & **userinfo.profile** scopes. * Complete all the steps * Click on **credentials** on the left menu * Click on **+Create credentials** then on **OAuth Client ID.** * Select web application for "**application type**" * For **Authorized JavaScript origins** URIs field, enter your domain url like this: * For **Authorized redirect URIs**: * After saving copy the **Client ID** and **Client Secret**. * As super admin and the owner of the application you have access to the super admin console. Go to your web application and click on \*\*console **in the sidebar then G**oogle login \*\* * Fill the copied keys and save * Click on the toggle button to enable Google login ### Facebook login We also strongly recommend to setup in Facebook login because it sometimes convinces the most hesitant to register with a few clicks on your platform with their Facebook account * Go to [https://developers.facebook.com/](https://developers.facebook.com) and clicks on **My Apps** * **Create new app** for your web application * Enter details about the software and submit * In the left sidebar menu, click on \*\*Settings \*\*then **Basic** * Fill out details about you and your web application and submit * Click on F**acebook Login** in the sidebar menu the select **Web** with \*\*www \*\*icon for the platform * In the next step enter your web app domain and click on next * For the following steps click on next to skip * Click on **Settings under Facebook Login** * **In Allowed Domains for the JavaScript SDK** section enter your domain () and **save changes** * Copy your **App ID** in the header * As super admin and the owner of the application you have access to the super admin console. Go to your web application and click on \*\*console \*\*in the sidebar then \*\*Facebook login \*\* * Enter your App ID and save * Click on the toggle button to enable Facebook login * Test your setup * If everything is working perfectly, go back to the dashboard of your application in Facebook and switch from \*\*development \*\*to live in \*\*the \*\*top header toolbar. ### ### Translate You can change the translation or add a new one. Below we will explain in detail how to change the translation or add a new one as you wish. There is no limit to add a new language as long as the language exists and is understood by someone 😁 Several files contain the translated elements. To modify the translation, modify the values of the corresponding elements in these files If you add a new language you have to create content to it for each file mentioned below. In each case we will consider that you want to add German for example to help you add a new language ***Files and variables name must be ISO 639-1 Code (2 letter)*** Ex: en.json ; fr.json; export const en...; export const fr...; English: ngx-bill\startup-kit-angular\src\assets\i18n\en.json ``` { "general": { "home":"Home", "products":"Products", "invoicing":"Invoicing", "createSendInvoice":"Create & send invoices to yours customer", ... } ``` French: ngx-bill\startup-kit-angular\src\assets\i18n\fr.json ``` { "general": { "home" : "Accueil", "products" : "Produits", "invoicing" : "Facturation", "createSendInvoice" : "CrΓ©er et envoyer des factures Γ  vos clients", ``` For new language create a new file a this path: ngx-bill\startup-kit-angular\src\assets\i18n\\ Ex: Create de.json at ngx-bill\startup-kit-angular\src\assets\i18n\\ ``` { "general": { "home" : "Heimat", "products" : "Produits", "invoicing" : "Fakturierung", ... } ``` You will also need to modify the files containing the menus. ***Only the "title" variable should be modified for each language "en" ,"fr", "other"*** ngx-bill\startup-kit-angular\src\assets\translate\\**company-setting-menu.ts** ``` import { NbMenuItem } from '@nebular/theme'; export const en: NbMenuItem[] = [ //Company settings { title: 'Company settings', group: true }, { title: 'Company profile', icon: 'clipboard-outline', link:'/dashboard/setting-list/company' }, ... ] export const fr: NbMenuItem[] = [ //Company settings { title: 'ParamΓ¨tre entreprise', group: true }, { title: 'Profil entreprise', icon: 'clipboard-outline', link:'/dashboard/setting-list/company' }, ... ] //To add new language ==> new export const de: NbMenuItem[] = [ //Company settings { title: 'Parameter des Unternehmens', group: true }, { title: 'Profil des Unternehmens', icon: 'clipboard-outline', link:'/dashboard/setting-list/company' }, ... ] export const COMPANY_SETTINGS_MENUS = { en, fr, ... de, ==> new } ``` **Do the same as company-setting-menu.ts in all the rest of these files below** ngx-bill\startup-kit-angular\src\assets\translate\console-menu.ts ngx-bill\startup-kit-angular\src\assets\translate\profile-context.ts ngx-bill\startup-kit-angular\src\assets\translate\report-menu.ts ngx-bill\startup-kit-angular\src\assets\translate\sidebar-menu.ts ngx-bill\startup-kit-angular\src\assets\translate\super-admin-menu.ts If you have added a new language, make it available using this file: ngx-bill\startup-kit-angular\src\assets\translate\language.ts ``` export const LANGUAGE: any[] = [ {value:"en", name:"English"}, {value:"fr", name:"French"}, {value:"de", name:"German"}, ==> new ]; ``` ### Cookies consent banner To add a cookies consent banner to the home page, create an account on our platform Create a new campaign with the domain name of your web application ![](/files/aKYl2Cty8a1Wc9xM1lXT) Connect to the server and inside the wwwroot folder find the index.html file and copy the pixel at the end of the head tag ``` ... ``` Create a new notification ![](/files/FWfbExUgwgMkyGnwDkfu) Choose the cookie notification banner and configure it to be displayed from the landing page and one per user visit browser ![](/files/ZwgYcBAHegy1THXIXd0I) Activate the notification and go to your website to test the notification ### Hosting companies Here is a small overview of windows hosting companies for your project. If you are just starting out, and you don't have any knowledge of VPS hosting, we recommend choosing Windows hosting. | **Windows hosting companies** | **Links** | | ----------------------------- | --------------------------------------------------------- | | Smarter ASP | [https://www.smarterasp.net/](https://www.smarterasp.net) | | GoDaddy Windows hosting | | | Contabo windows vps | | | Hostgator windows hosting | | | 1&1 ionos | | Cloud hosting companies that will make your job easier. Need a helping hand? Use our referral link to get $100 of free credit to get started. 🦾 {% embed url="" %} | | | | -------------------------------------- | ------------------------------------------------------- | | \*\*VPS & Cloud hosting companies \*\* | Link | | Digital ocean | | | Microsoft Azure | | | Google Cloud | [https://cloud.google.com/](https://cloud.google.com) | | CloudWays | [https://www.cloudways.com/](https://www.cloudways.com) | | Vultr | [https://www.vultr.com/](https://www.vultr.com) | ### Support Do not hesitate to contact us if you have any questions or if you need support {% embed url="" %} {% embed url="" %} ***