What is the Open Invoice Format

An open-source, JSON-based schema for invoices. This project is designed to offer a simple and reliable alternative to complex standards like ZUGFeRD and XRechnung. Built on JSON schema, it ensures easy validation and parsing across all programming languages.
Have a look at the Open Invoice Format GitHub Repository

Table of Contents

1. Schema Details
   • How to use inside a PDF
2. Getting Started
   • How to set specific Schema version
   • Parsing JSON
     • OIF JSON to Obj
     • Obj to OIF JSON
   • Handling OIF PDFs
     • How to extract the OIF JSON from a PDF
     • How to add the OIF JSON to a PDF
3. More Integration Libraries
4. Contributing
5. Questions or Feedback?

Schema details

How to use inside a PDF:

To use the open invoice format like ZugFeRD inside a PDF. Your JSON should be attached as inbridge-oif.json to the PDF. By using one of our integration libraries you can work with OIF as easy as pie!

For the full schema, check out the OIF GitHub Repository

Getting Started

The library loads based on your input the schema out of the OIF GitHub Repository to validate it.

How to set specific Schema version

You can set a specific version of the schema by passing the version as a string. Autocomplete for the versions is available. Additionally, you can use latest as version, to get the latest schema from main Branch of the OIF GitHub Repository.

import {SchemaProvider} from "./schema-provider";

(async () => {
    try {
        await SchemaProvider.setVersion('latest');
    } catch (e) {
        console.error(e);
    }
})()

Parsing JSON

OIF JSON to Obj

import {SchemaProvider} from "./schema-provider";

const oifJson = /* your OIF JSON String */;

(async () => {
    try {
        const obj = await SchemaProvicer.parse<T>(oifJson);

        console.log(obj);
    } catch (e) {
        console.error(e);
    }
})()

You can pass T for example as DefaultInvoice to predefine the output type for auto complete. Or if you need then dont.

Obj to OIF JSON

import {SchemaProvider} from "./schema-provider";

const oifJson = /* your OIF JSON String */;

(async () => {
    try {
        const obj = await SchemaProvicer.stringify(oifJson);

        console.log(obj);
    } catch (e) {
        console.error(e);
    }
})()

Handling OIF PDFs

To handle PDFs containing the OIF JSON we use pdf-lib.

How to extract the OIF JSON from a PDF:

import {getOIFFromPdf} from "@inbridgeio/oif/pdf-manipulator";
import {readFileSync} from "fs";
import {join} from "path";

const file = readFileSync(join(__dirname, '..', 'test-files','oif.pdf'));


(async () => {
    console.log(await getOIFFromPdf(file));
})()

As file, you can use a Buffer or a UInt8Array. Here the variable file is a Buffer. It will return the parsed Invoice Obj or throw an InvalidOIFException if the JSON is invalid.

How to add the OIF JSON to a PDF:

If you generated a PDF out of your invoice, you can easily add the JSON and if its valid it will get added to the PDF. Otherwise it throws an InvalidOIFException.

import {addOIFToPdf} from "@inbridgeio/oif/pdf-manipulator";
import {writeFileSync} from "fs";

const invoiceObj = /* your OIF Object */;

(async () => {
    try {
        const pdf = await addOIFToPdf(invoiceObj);

        // Do something with the pdf
        writeFileSync('invoice.pdf', pdf);
    } catch (e) {
        console.error(e);
    }
})()

More Integration Libraries:

@inbridgeio/oif-ts: Work with OIF in TypeScript and JavaScript
Java: coming soon
PHP: coming soon
Python: coming soon

Contribute your own

Contributing

We welcome contributions! Feel free to submit pull requests or open issues for feature requests or bugs.
How to contribute on GitHub

License

This project is licensed under the MIT License. See the LICENSE file for details.

Questions or Feedback?

Create an issue or reach out via GitHub Discussions.