@codefusion-cc/commerce-invoices

Invoicing programs for a CodeFusion shop: Fakturownia, wFirma and inFakt. The shop builds an order's invoice with invoiceDraft, and the program creates it, finds it again on a retry and gives its PDF. The programs send invoices to KSeF themselves.

npm install @codefusion-cc/commerce-invoices

Entry points

A shop imports only the program it uses, so its Worker bundles no other program's code (the rule for every commerce kind: ROADMAP.md, Commerce).

| Entry | Holds | | --- | --- | | @codefusion-cc/commerce-invoices | The program contract (InvoiceProvider, InvoiceResult, IssuedInvoice), the helpers for a program's answers (apiError, jsonOf, pdfOf), and everything of ./browser. No program. | | …/browser | The invoice draft (invoiceDraft, productLines, invoiceNote), the settings every program has (invoiceFields, shouldIssue, vatRate, privateInvoiceNeedsAddress), INVOICE_GROUP and invoicingDef, for the panel's page, the storefront and shared code. | | …/fakturownia, …/infakt, …/wfirma | The program (fakturownia, infakt, wfirma), the request bodies it sends, and its definition. | | …/fakturownia/browser, …/infakt/browser, …/wfirma/browser | The program's panel definition alone (fakturowniaDef, infaktDef, wfirmaDef), without its code. | | …/testing | A fake of all three programs. |

// The Worker: the program the shop offers, from its own entry.
import { fakturownia } from '@codefusion-cc/commerce-invoices/fakturownia'

// The panel's page and shared code: the settings, the draft and the definition, without the program's code.
import { INVOICE_GROUP, privateInvoiceNeedsAddress, shouldIssue } from '@codefusion-cc/commerce-invoices/browser'
import { fakturowniaDef } from '@codefusion-cc/commerce-invoices/fakturownia/browser'

Issuing an invoice

import { zonedDate } from '@codefusion-cc/commerce/browser'
import { invoiceDraft } from '@codefusion-cc/commerce-invoices'

const draft = invoiceDraft(
  { number, company, nip, name, street, postcode, city, email, payment: 'transfer', paid: true, items, extraLines, shipping, saleDate, paidDate },
  config, // the program's settings: when to issue, a customer without NIP, the VAT rate
  { today: zonedDate(Date.now(), 'Europe/Warsaw') }, // the shop's date: after midnight UTC Poland is a day ahead
) // null: a customer without NIP, and the program issues them nothing
if (draft) {
  // ctx: the invoicing plugin's context (@codefusion-cc/commerce) as it is
  let result = await provider.create(ctx, draft) // inFakt: { pending } until its task is done (provider.status)
}

• The draft adds up to what the customer paid. A discount that does not divide to the grosz puts the last unit on a line of its own.
• Extra lines. A shop adds its own lines (a deposit) through extraLines and its own panel fields by appending them to a definition's fields.
• Dates. saleDate is the day of the sale when it is not the issue day: the delivery, or the payment when it came first (VAT act art. 106e(1)(6)). paidDate is the day the money came, for a paid order invoiced later. Both default to today; a day not of the calendar throws.
• One invoice per order. A retry never makes a second one: Fakturownia refuses a second oid, wFirma is found by id_external, and inFakt by its task and its note, among up to 2,000 newest invoices.
• One correction per invoice. Fakturownia's correction carries its own oid (korekta/<invoice id>): a retry after a lost answer takes the correction made, and never makes a second one. A correction made by a version before this one has no such oid, so check Fakturownia before retrying one of those.
• Text wFirma's XML cannot carry (control characters pasted with a name) is left out rather than failing the request.
• Copy is Polish. That covers the definitions and the errors the owner sees. These programs serve Polish shops.

A new program

A program is an entry of this package: src/<program>/index.ts (the InvoiceProvider, built on the root's contract) and src/<program>/browser.ts (its definition, made with invoicingDef, which adds the settings every program has), both listed in exports. It becomes a package of its own (@codefusion-cc/commerce-invoices-<program>, depending on this one for the contract) only when it needs a heavy dependency, is maintained by someone else, or needs its own release pace.

Testing

fakeInvoicingApi() from @codefusion-cc/commerce-invoices/testing is a fetch that plays the three programs, one entry for all of them (tests never reach a Worker's bundle).

• It keeps the invoices it creates, and refuses Fakturownia's oid twice where the request asks for it to be unique.
• It runs inFakt's tasks: the first look finds a task still running.
• It serves PDFs, including Fakturownia's public ones.
• It refuses the key wrong.

So a shop's tests can issue, retry and download without the programs.