The HTTPS method uses a RESTful API with JWT (JSON Web Token) bearer authentication with TLS 1.2 or higher encryption. All data is transmitted using encryption through Microsoft Azure's secure infrastructure. This method is ideal for organisations that have development resources to create API integrations.

Uploading data to FISCAL: HTTPS upload setup

Your script must send data to our server using an HTTPS POST request - the same secure standard used by web browsers for file uploads. You'll need one separate request for each file type (Transactions, Suppliers, Employees) and each FISCAL unit (if applicable).

Your script will need to cover the following requirements:

• Build the correct URL for the POST request
• Add the required headers
• Provide the body containing the CSV data
• Handle the response after making the request

If you choose to use an integration platform that requires certificates to be manually provided, you will also need to consider Managing Certificates (advanced - usually not necessary). 

Build the URL

Format your URL as follows:

https://api-<your-region>.apfnxg.com/customers/<your-customer-shortname>/units/<your-unit-shortname>/Uploads/upload/<your-file-type>/<your-file-name>

Required components:

• Region: Choose uksouth, euwest, or uswest
• Customer Shortname: Provided by FISCAL (lowercase letters and digits only)
• Unit Shortname: Your unit identifier (same as customer shortname if you have only one unit)
• File Type: Must be APT (for transaction data), Suppliers (for supplier data), or Employees (for employee data)
• File Name: Description that appears in FISCAL. Avoid spaces/special characters, include timestamp, must end with file extension e.g. .csv, .xlsx, or .txt

Add required headers

• Content-Type Header:
  • Use text/csv for transactions, employees, and suppliers data

• Authorization Header:
  • Format: Bearer <your-token>
    • Generate the token within your FISCAL site: Customer Settings (cog icon) > Organisation Settings > Access Tokens
  • Choose token validity period and click "Go"
  • Treat the token like a password - keep it secure and don't share it. FISCAL do not store a copy of the password.

Provide the body

Include your extracted data in CSV, XLSX or TXT format as the request body. You can either:

• Extract data to a file first, then upload the file
• Send data directly from your ERP via HTTPS

Handle the response

The response will either be an HTTP error status, in the event that there was a problem, or a JSON object with various named properties, which indicates a successful upload. Note that a success status indicates receipt of the data, not that the analysis is complete.

An HTTP response always includes a numeric status code, and the following values may be returned for automated uploads in FISCAL:

• 201 Created - This indicates a successful upload; any other code means the upload attempt was unsuccessful.
• 400 Bad request - The file type specified in the URL was not one of the allowed values. You will need to correct this in your script.
• 415 Unsupported media type - The media type specified in the Content-Type header was not one of the allowed values, so review the value you passed for that header.
• 401 Unauthorized - This means that the Authorization header was missing or invalid in some way. Check that your token is being passed in its original form, prefixed with Bearer, with no other characters missing or added (even in "plain text" editors, it's possible to have invisible control characters).
• 500 Internal Server Error - This would indicate an unexpected temporary problem in our services. If so, you can retry the request later, or contact our support team.

5. Managing Certificates (advanced)

Certificates and TLS
Most HTTPS clients, including Powershell and CURL, get their configuration from the operating system. If you're using such a client, you can skip this section.

But some types of scripting technology may require you to take responsibility for managing certificates. This adds some extra complexity to your integration. You should definitely consider choosing a self-managing alternative to avoid this problem.

If you decide to go ahead with an HTTPS client that requires manual configuration, you will need to obtain the certificates used by FISCAL to cover all its services, including the site you are reading now. You can click on the padlock icon in your browser's address bar to see how the connection is being encrypted. The exact method depends on the type of browser, but there will be a way to view the details of all the certificates involved, and to export them to files with the extension .cer, .crt, or .pem.

You will also need to take note of when the certificates expire, and arrange to repeat this process whenever they do.

TLS Versions
From time to time, the current version of TLS used across the software service industry is found to contain security flaws and has to be replaced by a new version. Currently the minimum acceptable version is 1.2, and your HTTPS client will need to be capable of that version to connect to FISCAL servers.

Some old clients require configuration to make them use the required version. For example, PowerShell scripts running in older versions of PowerShell may need the line:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Further Information
The HTTPS method uses a RESTful API with JWT (JSON Web Token) bearer authentication with TLS 1.2 or higher encryption. All data is transmitted using encryption through Microsoft Azure's secure infrastructure. A list of supported cipher suites can be found here: https://developers.cloudflare.com/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites/

HTTPS uses TLS for two purposes:

• To encrypt all communication between the client and the server in both directions, and
• To allow the client to be sure that they are communicating with the correct server.

The second problem, checking the identity of the server, is the more difficult of the two, and ultimately involves trusting a central body called a Certificate Authority (CA). Any public service exposed over HTTPS must possess a certificate that has ultimately been digitally signed by a CA. If a client trusts that CA, they can trust the service is genuine.

Certificates can form a chain; typically a service like FISCAL buys its certificate from an intermediate vendor such as Cloudflare. The certificate is digitally signed using the vendor's certificate, which they originally obtained from a CA. That middle certificate is signed using the CA's root certificate. So there is a chain of three certificates that can be verified back to the root, for example:

• DigiCert Baltimore Root
  • CloudFlare Inc ECC CA-2
    • apfnxg.com

The DigiCert CA is just assumed to be trustworthy, so their certificate is self-signed (issued to and by the same entity).

This means that any client using HTTPS needs to have a store of root certificates that identify each currently trusted CA. This allows the client to validate any certificate chain as long as the chain ends with one of the trusted CAs. The store must be kept up to date, as new CAs are occasionally established, and also sometimes a CA's own root certificate will expire, so they have to issue a new one.

The most widely used HTTPS clients use the operating system's central store of root certificates. As long as the OS is regularly updated, such clients have no problem connecting to any properly protected HTTPS service.

The problem is that some less widely-used HTTPS clients do not have a way of using a pre-existing root certificate store. They have to be configured and updated manually.