WHMCS Accounting Software Electronic Invoice Integration
Introduction
Electronic Invoicing is spreading around the world and is quickly becoming mandatory in many countries. Billing Extension brings Italian and Slovene E-Invoicing integration with WHMCS but can also help with other countries.
Before we dig deeper into the topic, keep in mind that electronic invoicing works differently in every country. For instance there's no way one can use Italian e-invoicing in any country other than Italy. Platforms are not interchangeable.
We would like to integrate all platforms with WHMCS but there are huge differences in regulations not counting technological aspects. Let us put it into perspective.
Integrating Italian e-invoice took us 4 months work and keeping it functional is a process that never stops. It would be prohibitive for us to go through the same thing for tens of different platforms but there's a good news.
There is a common thread through every implementation of electronic invoicing. In one way or another, they all rely on the same information and billing concepts like credit note, VIES, invoice shapshot, billing error detection, monthly invoicing etc.
Instead of leaving you with no option other than creating your own implementation from scratch, we came up with the idea of including in our module a plugin that provides you with all information you need to integrate any e-invoce platform.
We understand that the idea of completing the integration on your own is daunting. Not to mention you still need to hire a developer but you just need to take care of the final step. Allow us to explain you what we mean.
When it comes to integrating e-invoice platforms, the most challenging part is collecting information from WHMCS. We are not simply referring to things like customers' details and VAT numbers.
There are other things that require WHMCS to understand billing concepts that it is not aware of. For example intra/extra EU, the correct use of credit, MOSS, VIES, the difference between invoice, proforma and credit note and so on.
That's where Billing Extension combined with this plugin comes to help. It gives you everything you need to get billing data out of WHMCS and feed your accounting software or e-invoice system.
With this solution you don't need to hire a WHMCS developer. They are as rare as hen's teeth nowadays. All you need is a "general purpose" developer capable of using this information to get the result you expect.
Be it generating XML or CSV files (electronic invoices) and transmit them via FTP or HTTP to Revenue Agency, accounting software or an intermediary platform.
As you see, Billing Extension already gives you everything you need. You just need to complete the final step. In the following chapters we are going to explain you how to use this feature.
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 | ||
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)