This service generates professional looking PDF invoices, from a simple POST HTTP request with json payload.
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.
$ 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/"
}
}'
$ php artisan serve
$ curl "http://localhost:8000/api/invoice/generate" \
-X POST -H "content-type: application/json" \
-d '{ ... }'
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(...) |
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 |
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" |
string | no | Customer email address | "[email protected]" | |
other | array of mixed string and Other() | no | Customer additional infos | [ String, Other(), ... ] |
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" |
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
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" |
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" |
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" |
The provided logo (optional) must be accessible from the invoice-as-a-service
API !
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]