Invoicing

Invoice templates

Invoice templates are the XHTML documents with embedded macros that are converted into the XSL Formatting Objects document using the ~ssp/etc/xsl/xhtml2fo.xsl, the slightly modified version of the style sheet from  http://antennahouse.com/. The resulting XSL FO document is finally converted into the PDF file using Apache FOP. Starting from 5.0 Sippy version wkhtmltopdf is used as PDF converter.


The invoice templates are stored in the database, table invoice_templates. The templates with the i_invoice_template field values in the range from 1 to 1000 are system templates, which is additionally indicated by the invoice_templates.is_system = True.


Invoice templates for accounts

An invoice template is a mandatory attribute of a Service Plan (billing_plans.i_invoice_template). It has a system default value (see below). Accounts in turn also have optional attribute for an invoice template (accounts.i_invoice_template) which can override the setting from the Service Plan. The accounts also have setting to enable generation of invoices which are sent via e-mail to the address specified in the contacts of the account, this is a field accounts.invoicing_enabled.


On the Sippy web page the account can get the invoicing enabled by checking the Invoicing Enabled in his settings (the owner of that account, after logging in as the customer can change it.)

The particular Invoice template can be chosen from Invoice Template list after enabling the invoicing.

The same could be done using the bulk upload feature for multiple account as well.


Currently assigned system templates

  • 1 - The default invoice template for accounts

Creating a custom invoice template



It is recommended to avoid changing the Default invoice template in order not to brake invoicing mechanism overall. By using the following strategy you'll always keep one Default working invoice template and will be able adjust a custom one on your own.

  1. Log into your switch and open the page which contains a list of all invoice templates. Starting from 5.2 version of Sippy the page is available under Customers - Invoicing - Invoice Templates menu, in earlier versions it is hidden, so you need to type "invoice_templates.php" manually in your browser's address line. The full link looks as https://11.22.33.44/c1/invoice_templates.php (where 11.22.33.44 is the address or domain name of your switch).
  2. By default, only one template is available called "Default...". Open it and copy the HTML content of the Default invoice template into a clipboard or a notepad, or press Add Based on Existing button on Invoice Templates page (starting from 5.2)

  3. Next, go back to the invoice_templates.php page and click "Add New Invoice Template".

  4. Open HTML editor again.

  5. Paste the HTML content which you copied at step #2.

  6. Save the template. Now you have a full copy of the Default working invoice template which you can customize on your own.


Available macros list

Starting from 5.0 version of Sippy the list of available macros are accessible from invoice editor:



Macros that contain the attributes of an account:

  • ${I_INVOICE} - Unique invoice identifier
  • ${I_ACCOUNT} - Unique account identifier
  • ${USERNAME} - Account name
  • ${SALUTATION} - Salutation from account preferences. Mr./Mrs.
  • ${FIRST_NAME} - First name from account preferences
  • ${LAST_NAME} - Last name from account preferences
  • ${CURRENCY} - Account base currency
  • ${STREET_ADDR} - Street address from account preferences
  • ${POSTAL_CODE} - Postal code from account preferences
  • ${CITY} - City from account preferences
  • ${COMPANY_NAME} - Company Name from account preferences. (starting from 5.1)
  • ${COUNTRY} - Country from account preferences
  • ${STATE} - Province/State from account preferences. (starting from 5.3)


Macros containing the current invoice information are:


${TOTAL_CHARGES} - Total sum of all minute plans and charges from the Service Plan

${PAYMENTS_AMOUNT} - Amount of payments for the current billing period

${FORWARD_AMOUNT} - Unpaid amount from the previous period

${LAST_BILL_AMOUNT} - Amount due from the previous invoice

${AMOUNT_DUE} - Amount account owes at the end of the billing period. Will contain non-zero values only if the account's balance is below zero.

${TARIFF_CALLS_PRICE} - Total sum of the calls exceeding the service plan minutes.

${TARIFF_CALLS_DURATION} - Total billed duration of the calls exceeding the service plan minutes. Format of duration is [hh:]mm:ss.(starting from 5.1)

${PLAN_CALLS_DURATION} - Total billed duration of the calls within the service plan minutes. Format of duration is [hh:]mm:ss.(starting from 5.1)

${ALL_CALLS_DURATION} - Total billed duration of all calls. Format of duration is [hh:]mm:ss.(starting from 5.1)

${ADDITIONAL_CHARGES} - Charges that were applied in the current billing period in addition to the ${TOTAL_CHARGES}

${BILL_DATE} - Date at the moment of an invoice creation

${LAST_BILL_DATE} - Date at which the previous invoice was issued

${TOTAL_DID_CALLS_CHARGES} - Total sum of DID calls charges to the account. (starting from 5.0)


Tables:

  • ${TABLE:service_plan_charges} - Contains all fields from the service_charges database table.
  • ${TABLE:service_plan_minutes} - Contains all fields from the service_plans database table.
  • ${TABLE:charges} - Contains all charges applied to the account for the billing period. A table that could include service charges, minute plan fees, DID monthly fee and DID setup fee (starting from 5.0). Available fields within the table:
  • charge_time - date and time of the charge
  • date - date only part of the charge_time
  • amount - positive number of the charge applied
  • currency - currency
  • name - name of the charge
  • description - description of the charge
  • _num - Sequential number of the record
  • ${TABLE:cdrs} - Contains all fields from the cdrs table plus the following additional fields that should be placed inside the TABLE macros:
    • _num - Sequential number of the record
    • date - Date part of the connect_time field
    • time - Time part of the connect_time field

           Examples of the macro within ${TABLE:cdrs}:

  • ${TD:cld_in} - cld_in field
  • ${TD:cost} - cost field
  • ${TD:duration;fmt=duration} - The 'duration' format displays value in the format [hh:]mm:ss. Starting from 4.5
  • ${TD:country} - country from Destinations resolved based on prefix. Starting from 5.3
  • ${TD:description} - Description from Destinations resolved based on prefix. Starting from 5.3

The cdrs table accepts two optional parameters:

  • max_rows - Maximum number of CDRs to display in invoice, default is 100
  • show_zero_cdrs - Display zero duration CDRs in invoice, default is false

Examples:

  • ${TABLE:cdrs;max_rows=0} - fetch unlimited number of CDRs
  • ${TABLE:cdrs;show_zero_cdrs=true;max_rows=10000} - display zero duration cdrs in the invoice, max 10000 records


Macro substitutions

Invoice template can contain macros. The macros can be of two types - common and context specific.

  • Common macros

  • Macros to create tables

To represent a table data there are a macros ${TABLE}, ${TD} and ${TABLE_END} which are designed to be used as shown in the example:

 

<table>
<tr>
<th>Call</th>
<th>Date</th>
<th>Time</th>
<th>Number Called</th>
</tr><tr>
<td>${TABLE:cdrs}</td>
</tr><tr>
<td>${TD:_num}</td>
<td>${TD:date}</td>
<td>${TD:time}</td>
<td>${TD:cld_in}</td>
</tr><tr>
<td>${TABLE_END}</td>
</tr>
</table> 

All rows between the macros ${TABLE} and ${TABLE_END} are repeated as many times as many rows has to be displayed, and the HTML table rows containing these macros are always skipped and never included in the final document.

EVAL macro

With this macro you are allowed to make arbitrary arithmetical calculations and place them on the page in a desired format. The general form for the macro is:

${EVAL:<expression>[;<format>]}


Examples:

Round the result to second digit after the dot:

${EVAL: ( ${TOTAL_CHARGES} ) ; %.02f }

Perform the division with 3 and round to the second digit after the dot:

${EVAL: ( ${LAST_BILL_AMOUNT} / 3.0 ) ; %.02f }

Some arithmetic operation:

${EVAL: ( ${TD:_num} + 15 ) / 2 }


To edit invoice template use web applications using direct links:

/invoice_templates.php
/images.php


List of supported formats for the images:

JPG, JPEG, PNG, GIF(static)


List of supported fonts:

Sans Serif

Monospace

Serif


Custom CSS

Starting from our Sippy 5.0 version Our users can now add their own custom CSS to their own invoice template.  The Invoice Template will have a field specifically for CSS so you can brand your invoices as needed.  The style sheet just needs to be copied into the field below.  A very simple example is provided below and the sample out put is shown.


** 



To help you make use of this feature here is the sample Invoice template updated to include a basic style sheet and the resulting invoice template.

body {
  background-color: #ffffff;
}

h2 {
  colour: orange;
  background-color: #ff9900;
  border: 1px solid #544f4f;
}

p, em {
  colour: orange;
  background-color: #ff9900;
  border: 1px solid #544f4f;
}

p, li {
  text-decoration: underline;
}


Example of the final output:


Test(validate) Invoice template

Starting from 5.2 version it's possible to generate test invoice based on modified invoice template to see the expected result prior to the billing pass.

XMLAPI call is used for that purpose, see documentation:

https://support.sippysoft.com/solution/articles/3000080953-xml-rpc-api-testinvoice