easyinvoice

v3.0.47

Published

9 months ago

Easily create beautiful PDF invoices.

Downloads

16,271

0High
0Medium
0Low

dveldhoen

invoice quote estimate bill pdf generator

Important

Please note that this package is a wrapper for an API, so it's logic runs on external servers.
Your data is secure and will not be shared with third parties.
We try to keep the API up and running at all times, but we cannot guarantee 100% uptime. Please build in a retry mechanism in case the API is down for maintenance.
Make sure to upgrade your package to either >2.4.0 or >3.0.25 for apiKey support.

Installation

Using npm:

$ npm install easyinvoice

Using yarn:

$ yarn add easyinvoice

Using PNPM:

$ pnpm install easyinvoice

CDN

Using unkpg CDN:


<script src="https://unpkg.com/easyinvoice/dist/easyinvoice.min.js"></script>

Using jsDelivr CDN:


<script src="https://cdn.jsdelivr.net/npm/easyinvoice/dist/easyinvoice.min.js"></script>

Platform support

| Platform | Repository | Supported | Link | |-----------------|------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | PHP | Composer | Yes! | | | Javascript | NPM | Yes! | | | Python | PIP | Yes! | |

Step-by-step guide

Read our step-by-step guide on Medium. Click here! And gives us a clap if it helped you! 😉

Demo

JS Fiddle: Plain Javascript JS Fiddle: Vue JS Fiddle: React JS Fiddle: Angular

Sample

JSON Configs used for above samples:

[View JSON] First Sample
[View JSON] Second Sample

Plans

| Plan | Rate | Price | Link | |-------------|-----------------------|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Free | 25 invoices / 15 days | $0 | Not required to register | | Paid | Unlimited | - 30 day free trial- 1st month $1.99- $17.99 per month*Prices include VAT | |

To use paid

Register through:
- Web: https://app.budgetinvoice.com/register
- iOS: https://apple.co/3ySZ5JY
- Android: https://play.google.com/store/apps/details?id=nl.dashweb.factuursimpel
Create an API key through the app: settings -> API keys
Make sure to upgrade your package to either >2.4.0 or >3.0.25 for apiKey support.
Use the API Key as shown in the complete example below. Add the apiKey property to the data object.

Note: The GUI is not (yet) fully translated to English, though the path to getting an apiKey should mostly be in English. Also this will allow you to use the in app purchase mechanism to pay for the subscription.

Development mode

When using the free version, you can set the mode to 'development' to make sure you are not running into rate limits while testing this package or developing your invoices. The free version is limited to 25 invoices per 15 days. When your invoice looks good, you can switch to 'production' mode to create your production invoices. Production mode is activated by either not setting the mode or setting the mode to 'production'.

Direct REST API access

In case you don't want to use NPM, but you want to call our invoice creation api directly.

# HTTPS POST 
https://api.budgetinvoice.com/v2/free/invoices

# POST Data
Format: JSON
Structure: {
  "data": { # Parent parameter must be 'data'
    "mode": "development", # Production or development, defaults to production
    "products": [
      {
        "quantity": 2,
        "description": "Test product",
        "taxRate": 6,
        "price": 33.87
      }
    ],
  }
} 

# Optionally add your paid apiKey to the header 
Header: "Authorization": "Bearer 123abc" # Please register to receive a production apiKey: https://app.budgetinvoice.com/register

Import

CommonJS

var easyinvoice = require('easyinvoice');

ES6 =<

import easyinvoice from 'easyinvoice';

Getting Started - Basic Example

NodeJS

// Import the library into your project
var easyinvoice = require('easyinvoice');

// Create your invoice! Easy!
var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    products: [
        {
            quantity: 2,
            description: "Test product",
            taxRate: 6,
            price: 33.87
        }
    ]
};

easyinvoice.createInvoice(data, function (result) {
    // The response will contain a base64 encoded PDF file
    console.log('PDF base64 string: ', result.pdf);

    // Now this result can be used to save, download or render your invoice
    // Please review the documentation below on how to do this
});

Web


<html>
<head>
    // Import the library into your project
    <script src="https://unpkg.com/easyinvoice/dist/easyinvoice.min.js"></script>
</head>
<body>
<script>
    // Create your invoice! Easy!
    var data = {
        apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
        mode: "development", // Production or development, defaults to production
        products: [
            {
                quantity: 2,
                description: "Test product",
                taxRate: 6,
                price: 33.87
            }
        ]
    };

    easyinvoice.createInvoice(data, function (result) {
        // The response will contain a base64 encoded PDF file
        console.log('PDF base64 string: ', result.pdf);

        // Now this result can be used to save, download or render your invoice
        // Please review the documentation below on how to do this
    });
</script>
</body>
</html>

High volume: asynchronous invoice creation

Our API is able to handle high volumes of requests. If you need to create a lot of invoices fast, make sure to create them asynchronously. This will allow you to create multiple invoices at the same time.

Note: using async/await for this example

// Import the library into your project
var easyinvoice = require('easyinvoice');

// Create a promises array to store all your promises
const promises = [];

// Use a loop to prepare all your invoices for async creation
for (let i = 0; i < 25; i++) {
    // Add your invoice data to the promise array
    promises[i] = easyinvoice.createInvoice({
        apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
        mode: "development", // Production or development, defaults to production
    });
}

// Create all your invoices at the same time
const invoices = await Promise.all(promises);

Complete Example (NodeJS)

//Import the library into your project
var easyinvoice = require('easyinvoice');

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production   
    images: {
        // The logo on top of your invoice
        logo: "https://public.budgetinvoice.com/img/logo_en_original.png",
        // The invoice background
        background: "https://public.budgetinvoice.com/img/watermark-draft.jpg"
    },
    // Your own data
    sender: {
        company: "Sample Corp",
        address: "Sample Street 123",
        zip: "1234 AB",
        city: "Sampletown",
        country: "Samplecountry"
        // custom1: "custom value 1",
        // custom2: "custom value 2",
        // custom3: "custom value 3"
    },
    // Your recipient
    client: {
        company: "Client Corp",
        address: "Clientstreet 456",
        zip: "4567 CD",
        city: "Clientcity",
        country: "Clientcountry"
        // custom1: "custom value 1",
        // custom2: "custom value 2",
        // custom3: "custom value 3"
    },
    information: {
        // Invoice number
        number: "2021.0001",
        // Invoice data
        date: "12-12-2021",
        // Invoice due date
        dueDate: "31-12-2021"
    },
    // The products you would like to see on your invoice
    // Total values are being calculated automatically
    products: [
        {
            quantity: 2,
            description: "Product 1",
            taxRate: 6,
            price: 33.87
        },
        {
            quantity: 4.1,
            description: "Product 2",
            taxRate: 6,
            price: 12.34
        },
        {
            quantity: 4.5678,
            description: "Product 3",
            taxRate: 21,
            price: 6324.453456
        }
    ],
    // The message you would like to display on the bottom of your invoice
    bottomNotice: "Kindly pay your invoice within 15 days.",
    // Settings to customize your invoice
    settings: {
        currency: "USD", // See documentation 'Locales and Currency' for more info. Leave empty for no currency.
        // locale: "nl-NL", // Defaults to en-US, used for number formatting (See documentation 'Locales and Currency')        
        // marginTop: 25, // Defaults to '25'
        // marginRight: 25, // Defaults to '25'
        // marginLeft: 25, // Defaults to '25'
        // marginBottom: 25, // Defaults to '25'
        // format: "A4", // Defaults to A4, options: A3, A4, A5, Legal, Letter, Tabloid
        // height: "1000px", // allowed units: mm, cm, in, px
        // width: "500px", // allowed units: mm, cm, in, px
        // orientation: "landscape" // portrait or landscape, defaults to portrait
    },
    // Translate your invoice to your preferred language
    translate: {
        // invoice: "FACTUUR",  // Default to 'INVOICE'
        // number: "Nummer", // Defaults to 'Number'
        // date: "Datum", // Default to 'Date'
        // dueDate: "Verloopdatum", // Defaults to 'Due Date'
        // subtotal: "Subtotaal", // Defaults to 'Subtotal'
        // products: "Producten", // Defaults to 'Products'
        // quantity: "Aantal", // Default to 'Quantity'
        // price: "Prijs", // Defaults to 'Price'
        // productTotal: "Totaal", // Defaults to 'Total'
        // total: "Totaal", // Defaults to 'Total'
        // taxNotation: "btw" // Defaults to 'vat'
    },

    // Customize enables you to provide your own templates
    // Please review the documentation for instructions and examples
    // "customize": {
    //      "template": fs.readFileSync('template.html', 'base64') // Must be base64 encoded html 
    // }
};

//Create your invoice! Easy!
easyinvoice.createInvoice(data, function (result) {
    //The response will contain a base64 encoded PDF file
    console.log('PDF base64 string: ', result.pdf);
});

Return values

| Key | Value | Data Type | |--------------------------------------------|------------------------------------------------------------|---------------| | result.pdf | The PDF file as base64 string | String | | result.calculations.products | Array of objects reflecting the products used in creation | Array | | result.calculations.products[key].subtotal | Rounded price without tax per product | Number | | result.calculations.products[key].tax | Rounded tax per product | Number | | result.calculations.products[key].total | Rounded price including tax per product | Number | | result.calculations.tax | Object containing total calculated tax per unique tax rate | Array | | result.calculations.tax[rate] | Total tax for all products with same tax rate | Number | | result.calculations.subtotal | Rounded price without tax for all products | Number | | result.calculations.total | Rounded price with tax for all products | Number |

Error handling

Callback

var easyinvoice = require('easyinvoice');

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};

easyinvoice.createInvoice(data, function (invoice) {
    console.log(invoice);
}).catch((error) => {
    // Handle the error
    console.log(error);
});

Async/await

var easyinvoice = require('easyinvoice');

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};

try {
    const invoice = await easyinvoice.createInvoice(data);
    console.log(invoice);
} catch (error) {
    // Handle the error
    console.log(error);
}

Locales and Currency

Used for number formatting and the currency symbol:

//E.g. for Germany, prices would look like 123.456,78 €
const data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    settings: {
        locale: 'de-DE',
        currency: 'EUR'
    }
};

//E.g. for US, prices would look like $123,456.78
const data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    settings: {
        locale: 'en-US',
        currency: 'USD'
    }
};

Formatting and symbols are applied through the ECMAScript Internationalization API

Click here for a list of locale codes Click here for a list of currency codes

Disclaimer: Not all locales and currency codes found in the above lists might be supported by the ECMAScript Internationalization API.

Logo and Background

The logo and background inputs accept either a URL or a base64 encoded file.

Supported file types:

Logo: image
Background: image, pdf

URL

const data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    images: {
        logo: "https://public.budgetinvoice.com/img/logo_en_original.png",
        background: "https://public.budgetinvoice.com/img/watermark_draft.jpg",
    }
};

Base64

const data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    //Note: Sample base64 string
    //Please use the link below to convert your image to base64
    images: {
        logo: "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
        background: "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
    }
};

Local File (NodeJS only)

//Import fs to be able to read from the local file system
var fs = require("fs");

//Use the code below to read your local file as a base64 string
const data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    images: {
        logo: fs.readFileSync('logo.png', 'base64'),
        background: fs.readFileSync('images/background.png', 'base64')
    }
};

Click here for an online tool to convert an image to base64

Async/await support

// Import the library into your project
var easyinvoice = require('easyinvoice');

// Create your invoice! Easy!
var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};
const result = await easyinvoice.createInvoice(data);

// The response will contain a base64 encoded PDF file
console.log('PDF base64 string: ', result.pdf);

To store the file locally (NodeJS)

var fs = require('fs');

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};
const result = await easyinvoice.createInvoice(data);
await fs.writeFileSync("invoice.pdf", result.pdf, 'base64');

Print your invoice (browser only)

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};
const result = await easyinvoice.createInvoice(data);
easyinvoice.print(result.pdf);

Download your invoice (browser only)

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};
const result = await easyinvoice.createInvoice(data);
easyinvoice.download('myInvoice.pdf', result.pdf);
//	you can download like this as well:
//	easyinvoice.download();
//	easyinvoice.download('myInvoice.pdf');

Render(view) your invoice (browser only)

html

<!-- Only include when rendering is required -->
<script src="https://unpkg.com/[email protected]/build/pdf.min.js"></script>
<script src="https://unpkg.com/[email protected]/build/pdf.worker.min.js"></script>

<!-- Include pdfjs version 2.3.200 for Internet Explorer compatibility, no worker required -->
<!-- <script src="https://unpkg.com/[email protected]/build/pdf.min.js"></script> -->

<!-- The pdf will be rendered within this div -->
<div id="pdf"></div>

css (optional)

#pdf {
    text-align: center;
}

#pdf canvas {
    border: 1px solid black;
    width: 95%;
}

var data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
};
const elementId = 'pdf';
const result = await easyinvoice.createInvoice(data);
await easyinvoice.render(elementId, result.pdf);

Template customization

Download our default template ( invoice-v2) here to have an example which you can customize.

Supported file types:

Base64
URL (soon)

// You are able to provide your own html template
var html = '<p>Hello world! This is invoice number %number%</p>';

const data = {
    apiKey: "free", // Please register to receive a production apiKey: https://app.budgetinvoice.com/register
    mode: "development", // Production or development, defaults to production
    customize: {
        // btoa === base64 encode
        template: btoa(html) // Your template must be base64 encoded
    },
    information: {
        number: '2022.0001'
    }
};

// This will return a pdf with the following content
// Hello world! This is invoice number 2022.0001

Variable placeholders

The following placeholders can be put into your template. They will be replaced by their corresponding value upon creation.


<products>
    <!-- Product row html -->
</products>

Don't leave out the product tags or your custom product row won't be iterable by the template parser and you will end up with a single product row. Customize the html as you wish.

Within:
<products></products>

%description%

Within:
<products></products>

%quantity%

Within:
<products></products>

%price%

Within:
<products></products>

%row-total%


<tax>
    <!-- Tax row html -->
</tax>

Don't leave out the tax tags or your custom tax row won't be iterable by the template parser and you will end up with a single tax row. Customize the html as you wish.

Within:
<tax></tax>

%tax-notation%

Within:
<tax></tax>

%tax-rate%

Within:
<tax></tax>

%tax%