OIF Integration

This library is the TypeScript integration of the Open Invoice Format (OIF) schema.
Create PDFs in OIF Format with ease and parse/validate JSON back and forth.

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.

First, install the package via npm:

npm install @inbridge/oif-ts

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.