WHMCS Accounting Software Electronic Invoice Integration

Back   Posted on 15 june 2019 / Updated on 18 june 2021
Reading time 5 minutes

Introduction

Electronic Invoicing is spreading around the world and is quickly becoming mandatory in many countries. Billing Extension integrates Italian and Slovene E-Invoicing with WHMCS but can also give a precious help with other countries.

We would like to integrate all countries but e-invoice differs enormously from country to country due to diffrent regulations and technological aspects. Let us put it into perspective. Integrating Italian e-invoice took us 4 months work. Keeping it functional is a process that never stops.

It is prohibitive for us to go through the same thing for tens of different countries. The good news is that there is a common thread through most of electronic invoicing implementations.

In one way or another, the all need to meet the same requirements ranging from billing data to concepts like credit note, VIES, invoice shapshot, billing error detection, monthly invoicing etc.

Instead of leaving non-Italian and non-Slovenian customers alone dealing with electronic invoicing, we came up with the idea of including in our module a plugin that provides all data you need to integrate WHMCS with any electronicing invoicing platform.

We understand that the idea of completing the integration on your own is daunting but you just need to take care of the final step. From our experience a big part of the job is:preparing, validating and retrieving data from WHMCS.

  • Preparing, validating and retreiving billing data from WHMCS
  • Implementing billing concepts that WHMCS is not aware of

Billing Extension combined with this plugin already gives you everything you need. Not to mention that this can also be used to integrate WHMCS with your accounting software. Keep reading to learn more.

Getting Started

Begin by visiting Addons > Billing Extension > Settings and click "plus" icon to activate WebService.

Once done, go back to Settings and expand the newly added section. Here you find WebService configuration. At the moment of writing this, it only has one parameter named Token.

This randomly generated string is used to establish a secure connection for transmissions of data. Press the orange button to generate the token and save.

We prepared this PHP script with comments to show you how easily you can interact with our web service. We used the same principle WHMCS External API. In essence send a curl() request and receive the response in json array.

Authentication

Authentication requires two parameters. At some point we were also thinking of using OAuth 2.0 but it was a bit overkill.

Parameter Description Required
$URL URL to the root of WHMCS that can be found on Setup > General Settings > General > WHMCS SystemURL. Trailing slash "/" is required. Required
$Token It must be the same of Addons > Billing Extension > Settings > WebService > Token Required

API Get

Use this command to retrieve from WHMCS billing details enriched and validated by Billing Extension. Multiple filters are available.

Request Parameters
Parameter Description Required
action “Get“ Required
start The starting date for the returned results. Supports YYYY-MM-DD dates, integers (5 returns last 5 days) and keywords (yesterday, month to date, last year etc.). Leave empty to get all invoices Optional
end If “start“ has been specified in date format, “end“ can be used to select invoices between a range of dates (eg. start 2019-06-01 end 2019-06-15). The only supported format is YYYY-MM-DD Optional
invoicenum Select the invoice with this specific Invoice Number. If in use, “start“ and “end“ values are ignored. Can't be used together with “invoiceid“ Optional
invoiceid Select the invoice with this specific Invoice ID. Must be an integer. If in use, “start“ and “end“ values are ignored. Can't be used together with “invoicenum“ Optional
doctype “Invoice“ and “CreditNote“ return invoices and credit notes respectively. If empty, both types are returned Optional
Response Parameters
Node Parameter Description
ClientData UserID User ID (tblclients.id)
ClientData ClientData Firstname (eg. “Jack“)
ClientData Lastname Lastname (eg. “Black“)
ClientData ClientName Firstname and lastname separated by space (eg. “Jack Black“)
ClientData CompanyName Company name
ClientData Email Email
ClientData Address1 Address 1
ClientData Address2 Address 2
ClientData City City
ClientData State State, region, province
ClientData PostCode Post code
ClientData Country Two-letter ISO country code (eg. IT, DE, ES)
ClientData PhoneNumber Phone number
ClientData Currency Currency ID of selected customer
ClientData TaxExempt “1“ is tax exempt. “0“ is not tax exempt
ClientData\CustomFields id Client custom field ID (tblcustomfields.id)
ClientData\CustomFields fieldname Client custom field name (eg. VAT Number)
ClientData\CustomFields value Client custom field value
ClientData\Europe MemberState Two-letter ISO country code (eg. IT, DE, ES)
ClientData\Europe Region Mostly “Europe“ but can also be equal to “South-America“, “Africa“ etc. for outermost regions and overseas territories of European Union
ClientData\Europe MonetaryUnion true/false (eg. Italy “true“, Denmark “false“)
ClientData\Europe VIES true/false. If “true“ the selected customer is an Intra-EU company registered on VIES
ClientData\Europe MOSS true/false
DocData Type “Invoice“ or “CreditNote“
DocData ID Document ID (tblinvoices.id)
DocData Num Document Number (eg. 2019-150)
DocData Status Invoice status (“Paid“, “Draft“, “Unpaid“ etc.)
DocData Date Date in YYYY-MM-DD format
DocData DueDate Due date in YYYY-MM-DD format
DocData DatePaid Date/time when invoice has been paid in YYYY-MM-DD hh:mm:ss format
DocData Subtotal Subtotal. 2 decimal places. Dot as the decimal separator
DocData Credit Credit. 2 decimal places. Dot as the decimal separator
DocData Tax Level 1 Tax. 2 decimal places. Dot as the decimal separator
DocData Tax2 Level 2 Tax. 2 decimal places. Dot as the decimal separator
DocData TaxRate Level 1 Tax Rate. 2 decimal places. Dot as the decimal separator
DocData TaxRate2 Level 2 Tax Rate. 2 decimal places. Dot as the decimal separator
DocData PaymentMethod Payment gateway (eg. paypal)
DocData\Items ID Invoice item ID (tblinvoiceitems.id)
DocData\Items Type “Setup“, “Hosting“, “Domain“, “Upgrade“, “Item“, “Addon“, “PromoHosting“, “DomainGraceFee“, “LateFee“ etc.
DocData\Items RelID ID of the related product/service, domain, addon, billing item etc.
DocData\Items Description Description (eg. Renew Domain example.com)
DocData\Items Amount Invoice line amount. 2 decimal places. Dot as the decimal separator
DocData\Items Taxed true/false

It is worth noting that ClientData values come from Invoice Snapshots therefore they're safe to use of billing purposes. Moreover such values are trimmed to remove whitespace from both ends of strings.

Errors

We made our WebService user-friendly. In practical terms when there's something wrong in your API request, WebService provides clear details about the error directly in the json response. Such errors are not cryptic but give a full description about what went wrong.

Date Keywords

When it comes to dates, the WebService supports special keywords that help you filtering records by predefined intervals listed in the table below. Monday is considered the first day of the week and the provided descriptions assume that current date is Saturday 2019-06-15.

Keyword Description
Today Select 2019-06-15
Yesterday Select 2019-06-14
Last 7 days Select from 2019-06-08 to 2019-06-15
Last week Select from 2019-06-10 to 2019-06-16
Week to date Select from 2019-06-10 to 2019-06-15
Month to date Select from 2019-06-01 to 2019-06-15
Previous month Select from 2019-05-01 to 2019-05-31
Year to date Select from 2019-01-01 to 2019-05-15
Last year Select from 2018-01-01 to 2018-12-31
All Select all records

 

Comments (0)

Speak Your Mind Cancel Reply