Let us build an invoice in our own app, and with one button finalise it
and mail it to the customer through the accounting.
Sales invoices are a fine example of work that belongs in two systems at once. Building up an invoice is business work: which lines, which rate, which customer. Sending and booking it is accounting work, and that belongs in the accounting, not in an app of your own.
For a cafe we built it like this: a draft in their own app, and one button that finalises it, books it and mails it through Nmbrs Accounting. It is built and one real invoice has been sent with it, as a test. The client stays anonymous and there are no amounts, prices or margins here.
This is what we learned from it. The quirks of the API itself are in the Nmbrs Accounting API.
One button, three things
The operation you offer sales invoices with does more than book. You pass a few switches per invoice, and those decide everything:
Process, yes or no. With that off, the invoice lands in the accounting as a draft and nothing is booked. Handy for checking once whether your document is built up correctly.
Mail to the customer, yes or no. With that on, the accounting sends the invoice to the contact's mail address itself.
And that is the first lesson. We had already built our own mail function, with its own sender and its own text. After three days it came out again. The accounting sends from the address the customer knows, records that a mail went out and files the invoice with the contact. Rebuilding all of that gains you nothing except two places where something can go wrong.
Your own layout may come along, but not always
What we did want to keep is the layout. The invoice the customer receives should be the company's, not a bookkeeping package's default.
That is possible: you send your own PDF along and the accounting stores and sends that instead of its own version. In our case there is a limit of a few megabytes per document, which is ample for an invoice.
There is one rule in here that you meet once and then never forget: your own PDF may only come along if you actually process the invoice. Send a draft with a document and the accounting refuses the entire invoice, with a message that processing has to be on if you supply a document.
That has consequences for your test setup. So a test invoice you do not want to book goes without a PDF. In our app the generator then leaves the document elements out, and the check beforehand rejects an unprocessed invoice that has a PDF. That way the combination cannot go out by accident.
Not a new item for every line
Every invoice line needs an item in the accounting, with a description, a price without VAT, a percentage and a ledger account. The temptation is to offer an item per line with that line's text in it.
Do not. The item list in the accounting then grows with every invoice, and after a year that list is useless to the person who actually works with it.
We work with a fixed item per line type. Five types was enough: turnover at the high rate, turnover at the low rate, other turnover, a contribution from a supplier, and packaging or deposit. Every type has its own ledger account and its own VAT indication, derived from the way the bookkeeper always did it. The text the customer sees on the invoice sits in the description of the line, not in the item.
Note that the package's VAT indication is not the same as the percentage. There is a list of types of its own, including exempt and zero rate next to high and low. Fill in only the percentage and the entry can end up in the wrong category.
The contact: do not create it again
The biggest fear with this integration was a duplicate contact. An accounting with the same customer in it twice is months of mess.
What happened with the first real invoice: we sent the contact along with name, address and our own customer code. The accounting matched that on name to the existing contact, put our code on that contact and ticked it as a customer. No second contact appeared.
That is pleasant behaviour, but it also means the name you send is decisive. So send the name as it stands in the accounting, not the name as somebody typed it into your app.
Numbers, and what you do not invent yourself
Two things we deliberately leave to the accounting:
The payment term. We send no due date. That comes from the accounting's settings, and then there is one place where it gets changed.
The sequence number. For the next number we look at the highest number already in the accounting. That costs a call, but it stops two series from running alongside each other.
The second one turned out to be more work than expected, because an existing administration holds numbers with typos. A year that is wrong, a dash in an odd place. Our reader handles those tolerantly and ignores a sequence number so high that it cannot be a number. Otherwise one typo sends your numbering hundreds of steps forward.
What the answer tells you
One invoice goes out per call, and the answer says per invoice whether it succeeded, whether it was booked and whether the mail went out. Those three are not the same thing and we store them separately.
For a draft the accounting does not return your own reference. Do not count on it in your processing.
Common mistakes
Sending the mail yourself. The accounting mails from the address the customer knows and records it. One sender beats two.
Offering a draft with your own PDF. That refuses the whole invoice. Draft without document, final with document.
Creating a new item per invoice line. Use a fixed item per line type and put the text in the line.
Filling in only the VAT percentage. Fill in the package's VAT indication too, or the category will be wrong.
Keeping your own number series. Read the highest number from the accounting, and read it tolerantly.
What an integration on this package can do is on connecting Nmbrs. If you want to send invoices from your own app, have a look at custom software.