ak-easyinvoice

v3.0.2-4.1

Published

a year ago

Easily create beautiful pdf invoices. forked from dveldhoen/easyinvoice

Downloads

0High
0Medium
0Low

abdullah.kurnaz

invoice quote estimate bill pdf generator

Platform support

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

Sample

JSON Configs used for above samples:

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

Demo

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

Step-by-step guide

Read our step-by-step guide on Medium. Click here!

Installing

Using npm:

$ npm install easyinvoice --save

Using yarn:

$ yarn add 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>

Import

CommonJS

var easyinvoice = require('easyinvoice');

ES6 =<

import easyinvoice from 'easyinvoice';

Direct REST API access

# HTTPS POST 
https://api.easyinvoice.cloud/v2/free/invoices

# POST Data
Format: JSON
Structure: {"data":{"products":[]}} # Parent object must be 'data'

Getting Started - Basic Example

NodeJS

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

// Create your invoice! Easy!
var data = {};
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 = {};
    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>

Complete Example (NodeJS)

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

var data = {
    // 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 
    },
    "images": {
        // The logo on top of your invoice
        "logo": "https://public.easyinvoice.cloud/img/logo_en_original.png",
        // The invoice background
        "background": "https://public.easyinvoice.cloud/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
        "due-date": "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",
            "tax-rate": 6,
            "price": 33.87
        },
        {
            "quantity": 4.1,
            "description": "Product 2",
            "tax-rate": 6,
            "price": 12.34
        },
        {
            "quantity": 4.5678,
            "description": "Product 3",
            "tax-rate": 21,
            "price": 6324.453456
        }
    ],
    // The message you would like to display on the bottom of your invoice
    "bottom-notice": "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')        
        // "margin-top": 25, // Defaults to '25'
        // "margin-right": 25, // Defaults to '25'
        // "margin-left": 25, // Defaults to '25'
        // "margin-bottom": 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'
        // "due-date": "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'
        // "product-total": "Totaal", // Defaults to 'Total'
        // "total": "Totaal", // Defaults to 'Total'
        // "vat": "btw" // Defaults to 'vat'
    },
};

//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 |

Locales and Currency

Used for number formatting and the currency symbol:

//E.g. for Germany, prices would look like 123.456,78 €
const data = {settings: {locale: 'de-DE', currency: 'EUR'}};

//E.g. for US, prices would look like $123,456.78
const data = {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 = {
    images: {
        logo: "https://public.easyinvoice.cloud/img/logo_en_original.png",
        background: "https://public.easyinvoice.cloud/img/watermark_draft.jpg",
    }
};

Base64

const data = {
    //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 = {
    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 = {};
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 = {};
const result = await easyinvoice.createInvoice(data);
await fs.writeFileSync("invoice.pdf", result.pdf, 'base64');

Print your invoice (browser only)

Using callback

var data = {};
easyinvoice.createInvoice(data, function (result) {
    easyinvoice.print(result.pdf);
});

Using async/await

var data = {};
const result = await easyinvoice.createInvoice(data);
easyinvoice.print(result.pdf);

Download your invoice (browser only)

Using callback

var data = {};
easyinvoice.createInvoice(data, function (result) {
    easyinvoice.download('myInvoice.pdf', result.pdf);
    //	you can download like this as well:
    //	easyinvoice.download();
    //	easyinvoice.download('myInvoice.pdf');   
});

Using async/await

var data = {};
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/pdfjs-dist/build/pdf.min.js"></script>
<script src="https://unpkg.com/pdfjs-dist/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%;
}

js: Using Callback

var data = {};
var elementId = 'pdf';
easyinvoice.createInvoice(data, function (result) {
    easyinvoice.render(elementId, result.pdf, function () {
        console.log('Invoice rendered!');
    });
});

js: Using async/await

var data = {};
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 = {
    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%