Electronic Invoicing is spreading around the world and is quickly becoming mandatory in many countries. Billing Extension already integrates Italian E-Invoicing and soon also Slovenian one. Even though we would like to integrate all countries, this is prohibitive.
E-Invoicing differs enormously from country to country due to regulations and technological aspects. Let us put it into perspective. It took 4 months to complete the integration with Italy. We simply cannot repeat the same process tens of times. It would take years.
Instead of leaving non-Italian and non-Slovenian customers alone dealing with electronic invoicing, we came up with the idea of including a plugin in Billing Extension that provides all data you might need to integrate WHMCS E-Invoicing of any country.
We understand that the idea of having to complete the integration on your own doesn't sound good but at least you have something to start with. From our experience a big part of the job is preparing, validating and retrieving data from WHMCS and this plugin already gives you everything.
We underline that even if you don't need to comply to E-Invoicing regulations, this plugin can also be used for different purposes. For example you could use it to integrate WHMCS with your accounting software or intranet.
Begin by visiting Plugin section (Addons > Billing Extension > Settings and click "plus" icon) and activate WebService.
Once done go back to Settings and expand the newly added section. Here you find WebService configuration that at the moment 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 then hit save.
We prepared a PHP script with comments that explains how to interact with WebService (Download). It uses the same approach of WHMCS for External API requests via curl() library. Responses are in json format. A bit of PHP knowledge is required.
The autentication process is very simple and requires just two parameters.
|$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 equal to the one you have in Addons > Billing Extension > Settings > WebService > Token||Required|
At the time of writing, this is the only supported action that can be used to retrieve billing details from WHMCS based on different criteria. We'll probably add more actions upon receiving feedback.
|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|
|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||State||State, region, province|
|ClientData||Country||Two-letter ISO country code (eg. IT, DE, ES)|
|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|
|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|
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.
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.
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.
|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|