Design of invoice layout with CraftMyPDF

With the CraftMyPDF integration, you can use the following functionality when designing invoice templates for your customers:

• Choose from pre-designed templates or create your own from scratch using the visual editor.
• Customize the layout, colors, and fonts of your invoice templates to match your company’s branding guidelines.
• Easily insert variables in your invoice template, which will be populated with the actual PortaBilling data, such as company name, invoice number, or invoice total.
• Preview your invoice to check how your customers will see it.

• The current integration allows you to generate the “mass-market” one-page invoices, e.g., with subtotals per service, using a predefined set of variables (JSON structure).

  If you wish to add extra data, such as individual CDRs or specific CDR summaries, then you need to define an additional cloud function. This function will extract the data from PortaBilling and send the updated data structure to Add-on Mart, which will then pass it to the external PDF generation service.

• In case your reseller wants to use this external service to create their own invoice templates, they need to have a separate Add-on Mart subscription for the CraftMyPDF module.

To reflect the data such as “Company name,” “Amount due,” or “Due date” in the invoice template, MyCraft PDF uses expressions in the template fields. These expressions are pieces of code that include the invoice variables in JSON format, which are replaced with the actual values in the generated invoice. For example: {{ format(data.invoice.amount_due, “number”, “0,0.00”) }}.

Let’s see what happens when an invoice with an external template is generated:

1. PortaBilling sends the invoice template ID along with the invoice data to the Add-on Mart cloud infrastructure (AMCI).
2. AMCI triggers an API request to the external service via HTTPS and passes the data to the external service.
   If you use a cloud function to retrieve and manipulate additional data from PortaBilling, AMCI first sends a request to the cloud function, and only then passes the received data to the external service.
3. The external service generates a PDF file based on the defined template and returns it to PortaBilling via the Add-on Mart.

The invoice PDF can now be sent to the customer or downloaded from the web interface.

Prerequisites for creating invoice templates via the external service:

1. Sign up for an account with CraftMyPDF and obtain the corresponding API key (service token).
   
2. Subscribe to the CraftMyPDF module via the Add-on Mart Management Portal.
3. Configure the integration:
   • On the Add-on Mart Management Portal, go to the Subscriptions tab, choose the module and click Manage.
   • You will find the login and password in the Instance info section. They should be entered in PortaBilling at step 4.
     These credentials are the same for all Add-on Mart modules.
   • Click Configure to open the module’s Configuration UI and fill in the details:
     • Service token – specify the API key obtained from CraftMyPDF.
     • The service URL – this is the CraftMyPDF’s API endpoint. By default, it is set for Europe (Frankfurt) https://api-de.CraftMyPDF.com. See the Regional-API-endpoints  section in the CraftMyPDF documentation for all available options.
     • The URL for the cloud function – if you use a cloud function to retrieve and manipulate the PortaBilling data, specify the corresponding URL here.
4. In PortaBilling, navigate to Company info > Add-on Mart. If the Login and Password fields are empty (this is the first Add-on Mart module you’re activating), enter your Add-on Mart credentials.
   

Watch the video from CraftMyPDF to explore the steps to create and customize the invoice template.

Download a .zip file with JSON data structure that can be used in your templates.

Here’s a brief overview of the required steps:

1. Log in to CraftMyPDF account and click Manage templates. To create a new template:
   1. Click New PDF template.
      CraftMyPDF also allows you to upload a PDF file with a template designed via another service, e.g., to ensure proper reflection of the brand color scheme. For this, click “New PDF Template from PDF file.”
   2. Specify the template name, select one of the predefined template layouts, and click Create.
      The template name will then be reflected in the PortaBilling web interface as an “external template” name.
2. Click Edit.
3. Open the Data tab. Delete the default JSON data and insert the data from the attached file “JSON data structure.”
4. Click Validate and Format JSON to make sure the data scheme was uploaded correctly.
5. Return to the Designer page. Now you need to change the data expressions so that they contain the new JSON data. To do this, click on any data expression, then click “Insert data expression” and choose from the available JSON data.
6. Click Preview to check how the invoice will appear to customers.

To start using the template created via the external service:

1. Log in to the PortaBilling web interface
2. Navigate to MyCompany > Templates, click Add and fill in the details:
   1. Name – specify the template name that will be used within PortaBilling.
   2. Type – select “Invoice”.
   3. Managed by – select “Administrator only”.
      Resellers can use the external service to create their own invoice templates only if they have a subscription for the corresponding Add-on Mart module. Reseller’s templates can be configured on the reseller portal.
   4. PDF generator – click “External”.
   5. External template – select a template that was previously created via the external service (CraftMyPDF).

   

3. To define the template on the customer class, navigate to Customer class > Finances > Invoicing > Regular invoices > select the invoice template.

You can also use the template for an individual customer.