Invoice as a service

This service generates professional looking PDF invoices, from a simple POST HTTP request with json payload.

Example

Usage

I provide invoice-as-a-service with a full hosted environment for fast and easy setup (endpoint: https://invoice-as-a-service.cleverapps.io).

For improved privacy, you can also deploy the project on your own infrastructure for free.

Output file can be exported to AWS S3 and any compatible storage destination.

Hosted

$ curl "https://invoice-as-a-service.cleverapps.io/api/invoice/generate" \
     -X POST -H "content-type: application/json" \
     -d '{

        "id": "42",
        "currency": "€",
        "lang": "en",
        "date": 1520852472,
        "due_date": 1521457272,
        "paid": false,
        "payment_link": "https://amazon.com/user/invoices/42/pay",
        "decimals": 2,
        "notes": "Lorem ipsum dolor sit amet.",

        "items": [
            {
                "title": "'Growth' plan Bienavous.io",
                "description": "1 year subscription",
                "price": 42,
                "quantity": 1,
                "tax": 20
            }
        ],

        "customer": {
            "summary": "John Doe",
            "address_line_1": "Baxter Building, 42nd street, Madison Avenue",
            "address_line_2": "Manhattan, NY, 11234",
            "address_line_3": "United States",
            "address_line_4": "Earth",
            "phone": "1-888-548-0034",
            "email": "[email protected]"
        },

        "company": {
            "summary": "Bienavous",
            "address_line_1": "123, place de Bretagne",
            "address_line_2": "44000 Nantes",
            "address_line_3": "France",
            "address_line_4": "Earth",
            "phone": "1-888-548-0034",
            "email": "[email protected]",
            "logo": "https://upload.wikimedia.org/wikipedia/commons/7/70/Amazon_logo_plain.svg",
            "other": [
                "EMEA office",
                {
                    "title": "Business hours",
                    "content": "9am - 6pm"
                }
            ]
        },

        "s3": {
            "presigned_url": null
        },

        "ftp": {
        	"host": "127.0.0.1",
        	"username": "ftpuser",
        	"password": "superSecretPassword",
        	"path" : "/var/html/share/"
        }

     }'

Self hosted

$ php artisan serve

$ curl "http://localhost:8000/api/invoice/generate" \
     -X POST -H "content-type: application/json" \
     -d '{ ... }'

Properties

Property	Type	Required	Description	Example
id	string	yes	Your invoice reference	"42"
currency	string	yes	Your billing currency	"€"
lang	string	yes	Only english supported for now	"en"
tax	float	yes	Tax percentage	20
date	integer	yes	Timestamp of invoice creation date	1520852472
due_date	integer	yes	Timestamp of invoice due date	1521457272
paid	boolean	no	Adding a "paid" logo (default: false)	false
payment_link	string	no	Payment link	"https://amazon.com/user/invoices/42/pay"
decimals	integer	no	Number decimals for prices (default: 2)	2
notes	string	no	Terms, conditions or anything you have to write in order to edit a valid invoice.	"Lorem ipsum dolor sit amet."
items	array	yes	List of items	[ Item(...), Item(...) ]
customer	object	yes	Customer infos	Customer(...)
company	object	yes	Company infos	Company(...)
s3	object	false	AWS S3 invoice upload	S3Upload(...)
FTP	object	false	FTP invoice upload	FTPUpload(...)

Item:

Property	Type	Required	Description	Example
title	string	yes	Product or service name	"'Growth' plan Bienavous.io"
description	string	no	Product or service description	"1 year subscription"
price	float	yes	Product or service price	42
quantity	float	no	Product or service quantity (default: 1)	1
tax	float	no	Tax rate (default: 0)	1

Customer:

Property	Type	Required	Description	Example
summary	string	yes	Organisation or customer name	"John Doe"
address_line_1	string	yes	Customer address, line 1	"Baxter Building, 42nd street, Madison Avenue"
address_line_2	string	no	Customer address, line 2	"Manhattan, NY, 11234"
address_line_3	string	no	Customer address, line 3	"United States"
address_line_4	string	no	Customer address, line 4	"Earth"
phone	string	no	Customer phone number	"1-888-548-0034"
email	string	no	Customer email address	"[email protected]"
other	array of mixed string and Other()	no	Customer additional infos	[ String, Other(), ... ]

Company:

Property	Type	Required	Description	Example
summary	string	yes	Your organisation name	"Bienavous"
address_line_1	string	yes	Customer address, line 1	"123, place de Bretagne"
address_line_2	string	no	Customer address, line 2	"44000 Nantes"
address_line_3	string	no	Customer address, line 3	"France"
address_line_4	string	no	Customer address, line 4	"Earth"
phone	string	no	Customer phone number	"1-888-548-0034"
email	string	no	Customer email address	"[email protected]"
logo	string	no	URL of your company logo	"https://acme.corp/logo.png"
siret (deprecated)	string	no	French company identification number	"539 138 107 00021"
other	array of mixed string and Other()	no	Company additional infos	[ String, Other(), ... ]

customer.other[].* and company.other[].*

customer.other and company.other fields are arrays of mixed type: simple string or the following object:

Property	Type	Required	Description	Example
title	string	true	Field name	"Twitter handle"
content	string	true	Field value	"@foobar"

S3 upload

Property	Type	Required	Description	Example
presigned_url	string	false	Presigned AWS S3 upload url	"https://my-bucket.s3.eu-central-1.amazonaws.com/[email protected]?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=xxxx&X-Amz-Date=xxxx&X-Amz-Expires=xxxx&X-Amz-Signature=xxxx&X-Amz-SignedHeaders=host"

FTP upload

Property	Type	Required	Description	Example
host	string	true	The host, IP Address of the server	"ftp.example.com"
username	string	true	The ftp username to connect	"john"
password	string	true	The ftp password of the user you are trying to connect	"test1234"
port	integer	false	The port used to connect, default is 21.	21
ssl	boolean	false	If the connection supports SSL mention that here, default is false.	true
passive	boolean	false	If it should use a passive connection, default is true.	true
path	string	true	The full path on the server where you want the invoice to be uploaded.	"/home/john/share"

Notes

The provided logo (optional) must be accessible from the invoice-as-a-service API !

Contribute

Fuck yeah!

Clone + pull-request.

I usually reply in hours or days ;)

Magic happens here:

template: `resources/views/invoices/default.blade.php``
controller + input validation: app/Http/Controllers/InvoiceController.php
pdf build: app/Helpers/PDF.php
invoice storage: app/Helpers/Storage.php

[AWS S3] - Generate presigned upload url:

$ aws configure
$ node ./scripts/presign-upload-url.js <region> <my-bucket> invoices/[email protected]

aptimyze / invoice-as-a-service Goto Github PK