Build for Web and Backend 💪

If this package helped you out please star us on Github!
Much appreciated!

Important

Please upgrade from v2.x to v3.x for important security updates. The update should be relatively effortless for most users. Note that support for Internet Explorer has been dropped from v3.x.

[//]: # (## EASY products) [//]: # () [//]: # (| Package | Description | Link |) [//]: # (|----------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|) [//]: # (| Easy PDF | Easy PDF Creator |

|) [//]: # (| Easy Invoice | Easy Invoice Creator |

|) ## Platform support |Platform | Repository |Supported | Link | |---|---|---|---| | PHP | Composer |Yes! |

| | Javascript | NPM | Yes! |

| | Python | PIP | Yes! |

| [//]: # (| Java | Maven | In progress... | |) [comment]: <> (## Features) [comment]: <> (- [x] Create invoices) [comment]: <> (- [ ] List, get, update, delete invoices (api ready / npm in progress)) [comment]: <> (- [ ] Create, list, get, update, delete clients (api ready / npm in progress)) [comment]: <> (- [ ] More soon...)
## Sample

### JSON Configs used for above samples: - [View JSON] First Sample - [View JSON] Second Sample ## Demo [JS Fiddle: Plain Javascript](https://jsfiddle.net/easyinvoice/rjtsxhp3/)
[JS Fiddle: Vue](https://jsfiddle.net/easyinvoice/gpb1osav/)
[JS Fiddle: React](https://jsfiddle.net/easyinvoice/qfs8dk0p/)
[JS Fiddle: Angular](https://jsfiddle.net/easyinvoice/pmt3bs9q/) ## Step-by-step guide Read our step-by-step guide on Medium. Click here! ## Installing Using npm: ```bash $ npm install easyinvoice --save ``` Using yarn: ```bash $ yarn add easyinvoice ``` ## CDN Using unkpg CDN: ```html ``` Using jsDelivr CDN: ```html ``` ## Import CommonJS ```js var easyinvoice = require('easyinvoice'); ``` ES6 =< ```js import easyinvoice from 'easyinvoice'; ``` ## Direct REST API access ```shell # 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 ```js // 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 // Import the library into your project ``` ## Complete Example (NodeJS) ```js //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: ```js //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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) [Click here for a list of locale codes](https://datahub.io/core/language-codes/r/3.html)
[Click here for a list of currency codes](https://www.iban.com/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 ```js const data = { images: { logo: "https://public.easyinvoice.cloud/img/logo_en_original.png", background: "https://public.easyinvoice.cloud/img/watermark_draft.jpg", } }; ``` ### Base64 ```js 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) ```js //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](https://base64.guru/converter/encode/image) ## Async/await support ```js // 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) ```js 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 ```js var data = {}; easyinvoice.createInvoice(data, function (result) { easyinvoice.print(result.pdf); }); ``` Using async/await ```js var data = {}; const result = await easyinvoice.createInvoice(data); easyinvoice.print(result.pdf); ``` ## Download your invoice (browser only) Using callback ```js 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 ```js 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 ```html

``` css (optional) ```css #pdf { text-align: center; } #pdf canvas { border: 1px solid black; width: 95%; } ``` js: Using Callback ```js var data = {}; var elementId = 'pdf'; easyinvoice.createInvoice(data, function (result) { easyinvoice.render(elementId, result.pdf, function () { console.log('Invoice rendered!'); }); }); ``` js: Using async/await ```js 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) ```js // You are able to provide your own html template var html = '

Hello world! This is invoice number %number%

'; 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.

Placeholder	Will be replaced by
%document-title%	translate.invoice
%logo%	images.logo
%company-from%	sender.company
%address-from%	sender.address
%zip-from%	sender.zip
%city-from%	sender.city
%country-from%	sender.country
%sender-custom-1%	sender.custom1
%sender-custom-2%	sender.custom2
%sender-custom-3%	sender.custom3
%company-to%	client.company
%address-to%	client.address
%zip-to%	client.zip
%city-to%	client.city
%country-to%	client.country
%client-custom-1%	client.custom1
%client-custom-2%	client.custom2
%client-custom-3%	client.custom3
%number-title%	translate.number
%number%	settings.number
%date-title%	translate.date
%date%	settings.date
%due-date-title%	translate.due-date
%due-date%	settings.due-date
%products-header-products%	translate.products
%products-header-quantity%	translate.quantity
%products-header-price%	translate.price
%products-header-total%	translate.product-total
A custom product row must be enclosed in products tags like: ```html ``` 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.	products
```html Within: ``` %description%	products[].description
```html Within: ``` %quantity%	products[].quantity
```html Within: ``` %price%	products[].price
```html Within: ``` %row-total%	products[].quantity * products[].price (rounded)
%subtotal-title%	translate.subtotal
%subtotal%	Auto inserted: Calculated total price excluding tax
A custom tax row must be enclosed in tax tags like: ```html ``` 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.	tax
```html Within: ``` %tax-notation%	translate.vat
```html Within: ``` %tax-rate%	Auto inserted: Distinct tax rate used in products
```html Within: ``` %tax%	Auto inserted: Calculated total tax for rate
%total%	Auto inserted: Calculated total price including tax