Archiving Invoice PDF on FTP

Archiving Invoice PDF on FTP

Back   Posted on 18 april 2020
Reading time 3 minutes

Who is it for?

ITF (Invoice To FTP) is a plugin integrated in Billing Extension that is capable of downloading PDF files generated by WHMCS (Proforma, Invoice and Credit Notes) for archiving on a remote FTP server. This process is performed automatically on a daily basis after all scheduled cron tasks of WHMCS have completed.

ITF is particularly useful for companies that use DMS (Document Management System) to process invoices as PDF files to extract data such as invoice numbers, customer names, amounts and link them to accounting workflow and accouting softwares. On a smaller scale, ITF can also be used to make things easier for small and medium-sized companies to organize, achive and transmit invoices to accountants.

Directory Structure

Folder structure and conventions for naming files are especially needed when collaborating with others or when a DMS is in use. To this purpose ITF provides maximum flexibility allowing to create fully customizable paths and file names. You won't be restricted to how WHMCS names PDF files, anything can be freely changed.

We borrowed the concept of Auto-Insert Tags to let you design your folder structure and file names quickly. An Auto-InserT Tag looks like this {COUNTRY} and acts as a placeholder that in this case is replaced by customer's country. Here is the complete list of the available tags. If you need additional tags open a feature request:

  • {YEAR} Format yyyy (2020, 2021...)
  • {MONTH} Format mm (10, 11...)
  • {DAY} Format gg (09, 10...)
  • {NUMBER} Invoice number (tblinvoices.invoicenum)
  • {ID} Invoice ID (tblinvoices.id)
  • {TYPE} Document type (Proforma, Invoice, CreditNote)
  • {USERID} User ID
  • {COUNTRY} User country ISO 3166-1 alpha-2 (IT, US, DE...)
  • {CURRENCY} User currency (EUR, USD, AUD...)

There are a few things to consider:

  • You can pick any tag and use them in any order
  • The same tag can be used multiple times
  • Use slash / as directory separator and .pdf as extension otherwise the module throws an error
  • You can also freely type any character but / \ : * ? " < > | are replaced with -
  • Take a look the the examples provided below

{YEAR}/{MONTH}/{CURRENCY}/{COUNTRY}-{NUMBER}.pdf

Results:

  • 2020/04/USD/US-Invoice 120.pdf
  • 2020/04/USD/US-Invoice 121.pdf
  • 2020/04/EUR/IT-Invoice 122.pdf
  • 2020/04/EUR/FR-Invoice 123.pdf

{YEAR}/{MONTH}/{TYPE}/{CURRENCY}-{COUNTRY}-{NUMBER}.pdf

Results:

  • 2020/04/Invoice/USD-US-Invoice 120.pdf
  • 2020/04/Invoice/USD-US-Invoice 121.pdf
  • 2020/04/CreditNote/EUR-IT-Credit Note 122.pdf
  • 2020/04/Proforma/EUR-FR-Proforma 8204.pdf

{YEAR}/{MONTH}/ABC-{YEAR}-{MONTH}-{ID}.pdf

Results:

  • 2020/04/ABC-2020-04-8100.pdf
  • 2020/04/ABC-2020-04-8101.pdf
  • 2020/04/ABC-2020-04-8102.pdf
  • 2020/04/ABC-2020-04-8103.pdf

Start Date

ITF archives PDF files from WHMCS based on document date (tblinvoices.date). Typically this value corresponds to generation date for proforma and issuing date for invoices and credit notes. Simply put, this setting lets you define a starting date. For example if you set it to current date, ITF archives PDF issued from now on. Now let's focus for a moment on the following info box.

At the top right corner there's a small label that reports the last time ITF has been invoked to archive PDF files. You can use it to determine if an error occurred. Keep in mind that Billing Extension also adds a notification to the Warning System. You can force ITF to retransmit documents issued in previous days by simply changing this settings. Let us give you a real case scenario.

Let's suppose you started to archive PDF on 01/01/2020. On 30/01/2020 you realise that the cron didn't run on 28/01/2020. Simply change Start Date from 01/01/2020 to 28/01/2020. This forces ITF to retransmit all PDF issued from 28/01/2020 to current date with next cron exectution.

It's important to underline that some WHMCS are configured to update proforma date to the date the proforma turned into an invoice. Let's suppose a proforma is generated on the 1st of April and paid on 18th. The cron performed on 2nd of April archives the proforma while the one performed on 19th archives the invoice.

Another important thing to remember is that ITF overrides any file that already exists on the FTP therefore be careful when you change Directory Structure on production systems.

Document Type

This setting lets you choose what type of PDF you want to archive and organize on FTP. For example usually companies don't want to store proforma since they're not true invoices therefore just go for invoices and credit notes.