# basic-usage: undefined
URL: /docs/basic-usage
Source: https://github.com/jslno/node-zugferd/blob/main/docs/content/docs/basic-usage.mdx

undefined

***

title: Basic Usage
description: Getting started with node-zugferd
priority: 0.8
-------------

<Steps>
  <Step>
    ## Install the Package

    Let's start by adding node-zugferd to your project:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install node-zugferd
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add node-zugferd
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add node-zugferd
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add node-zugferd
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <GithubInfo owner="jslno" repo="node-zugferd" />
  </Step>

  <Step>
    ## Create a new Instance

    Create a file named `invoicer.ts` in preferably one of those locations:

    * Project root
    * `lib/` folder
    * `utils/` folder

    In this file, import node-zugferd and create your instance. Make sure to export the instance.

    ```ts title="invoicer.ts"
    import { zugferd } from "node-zugferd";

    export const invoicer = zugferd({
      //...
    });
    ```
  </Step>

  <Step>
    ### Select a Profile

    node-zugferd requires a profile to generate the invoice. You can easily configure node-zugferd to use these built-in profiles:

    <Callout type="warn">Documents containing only information of the first two profiles (MINIMUM and
    BASIC WL) are not considered to be invoices according to German fiscal law ([→
    GoBD](https://www.bundesfinanzministerium.de/Content/DE/Downloads/BMF_Schreiben/Weitere_Steuerthemen/Abgabenordnung/2019-11-28-GoBD.html));
    they may therefore not be used as electronic invoices in Germany. They will
    not be considered as invoices in France anymore once the einvoicing B2B
    mandate CTC reform has been fully deployed (2028). **It is then highly
    recommended to target the [BASIC](/docs/profiles/basic) profile at minimum.**</Callout>

    * [MINIMUM](/docs/profiles/minimum)
    * [BASIC WL](/docs/profiles/basic-wl)
    * [BASIC](/docs/profiles/basic)
    * [EN16931 (COMFORT)](/docs/profiles/en16931)
    * [EXTENDED](/docs/profiles/extended)

    <Callout type="info">By default this package only provides support for the CII-Syntax</Callout>
    <Callout type="tip">You can also define your own Profiles.</Callout>

    ```ts title="invoicer.ts"
    import { zugferd } from "node-zugferd"; // [!code highlight]
    import { BASIC } from "node-zugferd/profile/basic"; // [!code highlight]

    export const invoicer = zugferd({
      profile: BASIC, // [!code highlight]
    });
    ```
  </Step>

  <Step>
    ## Your first invoice

    Once the necessary setup is complete, it's time to create your first invoice. This involves defining the invoice data and embedding it into a PDF to ensure it meets electronic invoicing standards.
  </Step>

  <Step>
    #### Define the data

    Invoices contain essential details like transaction information, participant details, and line items. This data will be structured in a way that allows it to be processed electronically and integrated seamlessly into business workflows.

    ```ts
    import { invoicer } from "./your/path/invoicer";

    const data: typeof invoicer.$Infer.Schema = {
      //...
    };

    const invoice = invoicer.create(data); // [!code highlight]
    ```
  </Step>

  <Step>
    #### Save the document

    After creating the invoice, it needs to be saved in a format that meets the necessary standards for distribution and compliance. This ensures the document is both human-readable and machine-readable, allowing for automated processing within business workflows.

    <Tabs items={["PDF/A-3b", "XML"]}>
      <Tab value="PDF/A-3b">
        The most common practice for saving invoices is embedding them in a PDF/A document. This format retains the visual appearance of the invoice while also embedding the structured data. PDF/A ensures that the invoice can be archived and retrieved in a standardized, legally-compliant manner.

        <Callout type="warn">The data in your pdf must exactly match the provided data!</Callout>

        ```ts
        const pdf = fs.readFileSync("./your/invoice.pdf");

        const pdfA = await invoice.embedInPdf(pdf, {
          metadata: {
            title: "New Invoice",
          },
        });
        ```

        PDF/A is the preferred format for ZUGFeRD invoices, as it complies with the necessary legal standards for document archiving and submission.
      </Tab>

      <Tab value="XML">
        Alternatively, you can generate the invoice as an XML file. However, it's important to note that just the XML does not meet the full ZUGFeRD standard. Without embedding the data into a PDF/A file, the invoice is incomplete for compliance and automated processing in most cases.

        <Callout type="warn">While generating the XML alone may be suitable in some situations, embedding
        it in PDF/A is the recommended and compliant method for ZUGFeRD invoices.</Callout>

        ```ts
        const xml = await invoice.toXML();
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## 🎉 That's it \[#thats-it]

    {"\n"}

    That's it! You've successfully set up node-zugferd, generated your first
    invoice, and learned how to save it as a PDF/A-3b file or XML. You can now
    automate the generation of invoices with structured data in the format that
    fits your needs.
  </Step>
</Steps>