Introduction

We understand the reluctance of certain businesses or individuals to store business-critical invoicing data in the cloud. With the self-hosting capability of InvoicingAPI, you're able to utilize our powerful invoice creation engine within your infrastructre. The only communication with our servers during the lifetime of your self-hosted container is at startup to verify your API key is valid. Thereafter, you can call your API within your application environment to receive InvoicingAPI's beautifully formatted invoices.

Note that the self-hosted version consists of just an API that you can call to generate invoices. The dashboard app where you can see your invoice and payment history is only available on the web app for now. Read on to learn how to configure the self-hosted version.

Getting Started

First you'll need to create a text file to store all environmental variables to be loaded into the container. Name it config.txt and copy the contents from below.

InvoicingAPIKey=__YOUR_INVOICINGAPI_API_KEY__
StripeSecretKey=__YOUR_STRIPE_SECRET_KEY__
StripeWebhookEndpointSecret=__YOUR_STRIPE_WEBHOOK_ENDPOINT_SECRET_KEY__
EmailFrom=__SENDER_EMAIL__
EmailTo=__RECIPIENT_EMAIL__
EmailName=__RECIPIENT_NAME__
EmailHost=__SMTP_SERVER_HOST__
EmailPort=__SMTP_SERVER_PORT__
EmailUser=__SMTP_SERVER_USER__
EmailPassword=__SMTP_SERVER_PASSWORD__
AddressName=__COMPANY_NAME__
AddressEmail=__COMPANY_EMAIL__
AdddressCountry=__COMPANY_COUNTRY__
AddressCity=__COMPANY_CITY__
AddressLine1=__COMPANY_ADDRESS_LINE_1
AddressLine2=__COMPANY_ADDRESS_LINE_2
AddressTelephone=__COMPANY_TELEPHONE__
AddressWebsite=__COMPANY_WEBSITE__
AddressVATNo=__COMPANY_VAT_NUMBER__
TaxType=__TAX_TYPE__
TaxPercentage=__TAX_PERCENTAGE__
TaxDisplayInline=__TAX_DISPLAY_INLINE
TaxUnitPriceIncludesTax=__TAX_UNIT_PRICE_INCLUSIVE__

• InvoicingAPIKey (string) - this is your API key available on your profile page. Only accounts that have purchased the Self Hosted plan will have a valid API key.
• StripeSecretKey (string) - this is your Stripe Secret key available on your Stripe account. This is required for the Payment Links feature to be activated. If not provided, invoices will not include links. See below for how to find it.
• StripeWebhookEndpointSecret (string) - this is your Stripe Webhook Secret key available on your Stripe account after you add a webhook endpoint. This is required for being notified once a payment was made by your customer from an invoice. See below for how to find it.
• EmailFrom (string) - The email address to be used to send notification emails when a payment was made. If left empty, no notification email will be sent.
• EmailTo (string) - The email recipient of notification emails when a payment is made from an invoice. If left empty, no notification email will be sent.
• EmailName (string) - The name to be used on notification emails when a payment is made from an invoice. If left empty, no notification email will be sent.
• EmailHost (string) - The SMTP host. If left empty, no notification email will be sent.
• EmailPort (int) - The SMTP port. If left empty, no notification email will be sent.
• EmailUser (string) - The SMTP username. If left empty, no notification email will be sent.
• EmailPassword (string) - The SMTP password. If left empty, no notification email will be sent.
• AddressName (string) - The default issuer address name. This value will be overriden if an address name is included in the request body.
• AddressEmail (string) - The default issuer email address. This value will be overriden if an email address is included in the request body.
• AddressCountry (string) - The default issuer address country. This value will be overriden if an address country is included in the request body.
• AddressCity (string) - The default issuer address city. This value will be overriden if an address city is included in the request body.
• AddressLine1 (string) - The default issuer address line 1. This value will be overriden if an address line 1 is included in the request body.
• AddressLine2 (string) - The default issuer address line 2. This value will be overriden if an address line 2 is included in the request body.
• AddressTelephone (string) - The default issuer address telephone. This value will be overriden if an address telephone is included in the request body.
• AddressWebsite (string) - The default issuer website. This value will be overriden if a website is included in the request body.
• AddressVATNo (string) - The default issuer VAT Number. This value will be overriden if a VAT Number is included in the request body.
• TaxType (string) - The default tax type to apply to invoices. This value will be overriden if a tax type is included in the request body.
• TaxPercentage (double) - The default tax percentage to apply to invoices. This value will be overriden if a tax percentage is included in the request body.
• TaxDisplayInline (bool) - Whether to display tax fields inline per unit on invoices. This value will be overriden if display inline is included in the request body.
• TaxUnitPriceIncludesTax (bool) - Whether unit prices are tax inclusive. This value will be overriden if unit prices includes tax is included in the request body.

You can find your Stripe Secret key in your Stripe account on the developers page. Once logged in, click on the Developers link near the top right.

Look for the section "Integration Status" and you should see your Secret key. Click the eye icon to see your key and paste it into the config file.

To get your Stripe Webhook Secret key for listening to invoice payment events you'll need to setup a webhook in Stripe. On the Developers page, click the Webhooks tab.

Click on the Add an endpoint button.

On the wenhook configuration page you will need to add your endpoint URL. This is the URL where you are hosting the container, with "/StripeWebook" as the suffix (e.g. https://www.myazurewebapp/StripeWebhook). If you're hosting the container locally, you'll need to use a tunneling service to provide you with a public facing URL which is tunneled to your local environment.

Select the latest API version from the drop down list.

Press the "Select events" button, tick the "checkout.session.completed" event, and click "Add events".

Finally click to add the endpoint. You'll be taken to the webhook page where you can reveal your Stripe Webhook Signing Secret. Press to reveal it and paste it into the config file.

If you'd like to receive email notification from InvoicingAPI when your customer has made a payment, populate all the Email properties in the config file. You should be able to access the SMTP credentials from your email provider. You'll receive an email similar to below with each payment.

Using the API

Now that you've configured your config file, you can pull the image from dockerhub and run it. To pull the latest image, run the following command. You can see all available images on DockerHub.

docker pull invoicingapi/invoicingapi-api:latest

After pulling the invoicingapi-api image, change directory to the same location as the config file and execute the following command to run the image.

docker run --rm --env-file config.txt --name invoicingapi -p 6000:80 invoicingapi/invoicingapi-api

This command will import all the environmental variables from your config file into the container, and expose the API on port 6000.

After running the command, you can check the docker logs to see if your InvoicingAPI Key has passed the validation check. If it has, you should see "InvoicingAPI API key is valid." in the log. Otherwise you will likely see something along the lines of "The license server returned an error", and the container will have ended.

With your container now running, you can send requests to create invoices. Refer to our developer documentation for details on how to structure your API calls. The self-hosted version of InvoicingAPI behaves similarily to the hosted version, with the only difference being the source of your company logo and signature which are accessed from online hosted urls. We recommend you use .png images for your logo and signature.

Below is a sample cURL request to the self-hosted version, assuming it is running locally (localhost) on port 6000.

curl -X POST "http://localhost:6000/invoice/createinvoice" \
    -H "Content-Type: application/json" \
    -d '{
        "template": "business1",
        "logoUrl": "https://www.my_url/logo.png",
        "signatureUrl": "https://www.my_url/signature.png",
        "color": "black",
        "documentType": "a4",
        "fontSize": 11,
        "invoiceNumber": "2024-44",
        "issueDate": "2024-01-11T09:18:54.092Z",
        "dueDate": "2024-05-11T09:18:54.092Z",
        "recipientAddress":{
            "name": "John Doe",
            "email": "johndoe@gmail.com",
            "addressLine1": "John Keneddy Str",
            "telephone": "(034)-543-43354"
        },
        "lineItems":[
            {
                "description": "App consulting services",
                "quantity": 1,
                "unitPrice": 950
            }
        ],
        "currency": "usd",
        "notes": "Payment Information\nIBAN Number: 43249423423489234",
        "IsPaid": false
    }' \
    -o output.pdf