npm package: @invoicekit/datev-export
Description: Generate DATEV-compatible CSV export files (EXTF) from TypeScript
Author: Daniel Rocha
Latest version: 0.1.0

# @invoicekit/datev-export

Generate DATEV EXTF export files for German accounting software. Supports Buchungsstapel (posting batches) and Debitoren/Kreditoren (master data) exports.

## Installation

```bash
npm install @invoicekit/datev-export
```

## Quick Start

### Buchungsstapel (Posting Batch)

```ts
import { generateBuchungsstapel } from "@invoicekit/datev-export";

const result = generateBuchungsstapel(
  [
    {
      umsatz: 119.0,
      sollHaben: "S",
      konto: 1200,
      gegenKonto: 8400,
      belegDatum: new Date(2024, 0, 15),
      buchungstext: "Rechnung 2024-001",
      belegfeld1: "RE-2024-001",
    },
  ],
  {
    beraternummer: 1234567,
    mandantennummer: 1,
    wirtschaftsjahrBeginn: new Date(2024, 0, 1),
    sachkontenlaenge: 4,
    datumVon: new Date(2024, 0, 1),
    datumBis: new Date(2024, 11, 31),
    kontenrahmen: "SKR03",
  },
);
```

### Debitoren (Debtor Master Data)

```ts
import { generateDebitoren } from "@invoicekit/datev-export";

const result = generateDebitoren(
  [
    {
      konto: 10000,
      name1: "Musterfirma GmbH",
      strasse: "Musterstraße 1",
      plz: "12345",
      ort: "Berlin",
      land: "DE",
      ustIdNr: "DE123456789",
    },
  ],
  {
    beraternummer: 1234567,
    mandantennummer: 1,
    wirtschaftsjahrBeginn: new Date(2024, 0, 1),
    sachkontenlaenge: 4,
    datumVon: new Date(2024, 0, 1),
    datumBis: new Date(2024, 11, 31),
  },
);
```

### Kreditoren (Creditor Master Data)

```ts
import { generateKreditoren } from "@invoicekit/datev-export";

const result = generateKreditoren(
  [
    {
      konto: 70000,
      name1: "Lieferant AG",
      strasse: "Lieferweg 42",
      plz: "54321",
      ort: "Hamburg",
      land: "DE",
      zahlungsbedingung: 30,
    },
  ],
  {
    beraternummer: 1234567,
    mandantennummer: 1,
    wirtschaftsjahrBeginn: new Date(2024, 0, 1),
    sachkontenlaenge: 4,
    datumVon: new Date(2024, 0, 1),
    datumBis: new Date(2024, 11, 31),
  },
);
```

## API Reference

### `generateBuchungsstapel(buchungen, options)`

Generates a DATEV EXTF Buchungsstapel file (data category 21).

**Parameters:**

- `buchungen: Buchung[]` - Array of posting records
  - `umsatz` (number, required) - Amount (positive)
  - `sollHaben` ("S" | "H", required) - Debit/credit indicator
  - `konto` (number, required) - Account number
  - `gegenKonto` (number, required) - Contra account number
  - `belegDatum` (Date, required) - Document date
  - `belegfeld1` (string, optional) - Document reference field 1
  - `belegfeld2` (string, optional) - Document reference field 2
  - `buchungstext` (string, optional, max 60 chars) - Posting text
  - `skonto` (number, optional) - Cash discount amount
  - `kostenstelle1` (string, optional) - Cost center 1
  - `kostenstelle2` (string, optional) - Cost center 2
  - `beleglink` (string, optional) - Document link

- `options: BuchungsstapelOptions`
  - `beraternummer` (number, 1001-9999999) - Tax advisor number
  - `mandantennummer` (number, 1-99999) - Client number
  - `wirtschaftsjahrBeginn` (Date) - Fiscal year start
  - `sachkontenlaenge` (number, 4-8) - G/L account length
  - `datumVon` (Date) - Period start
  - `datumBis` (Date) - Period end
  - `bezeichnung` (string, optional, max 30 chars) - Description
  - `kontenrahmen` ("SKR03" | "SKR04", optional) - Chart of accounts
  - `festschreibung` (boolean, optional) - Lock flag

**Returns:** `string` - Complete EXTF file content with `\r\n` line endings.

### `generateDebitoren(stammdaten, options)`

Generates a DATEV EXTF Debitoren/Kreditoren file (data category 16) for debtor accounts.

### `generateKreditoren(stammdaten, options)`

Generates a DATEV EXTF Debitoren/Kreditoren file (data category 16) for creditor accounts.

**Parameters (both functions):**

- `stammdaten: DebitKreditStammdaten[]` - Array of master data records
  - `konto` (number, required) - Account number (debtors typically 10000-69999, creditors 70000-99999)
  - `name1` (string, required) - Company name or last name
  - `name2` (string, optional) - Additional name / first name
  - `kurzbezeichnung` (string, optional) - Short name
  - `strasse` (string, optional) - Street address
  - `plz` (string, optional) - Postal code
  - `ort` (string, optional) - City
  - `land` (string, optional) - Country code (e.g., "DE")
  - `telefon` (string, optional) - Phone number
  - `email` (string, optional) - Email address
  - `ustIdNr` (string, optional) - VAT ID
  - `steuernummer` (string, optional) - Tax number
  - `zahlungsbedingung` (number, optional) - Payment terms

- `options: StammdatenOptions` - Same fields as `BuchungsstapelOptions` except no `festschreibung`.

**Returns:** `string` - Complete EXTF file content with `\r\n` line endings.

### `generateHeader(options)`

Low-level function to generate EXTF header lines (metadata + column headers).

### `validateBuchungsstapelOptions(options)`

Validates `BuchungsstapelOptions`. Throws on invalid input.

### `validateBuchung(buchung)`

Validates a `Buchung` record. Throws on invalid input.

### `encodeWindows1252(input)`

Encodes a JavaScript string to a `Uint8Array` in Windows-1252 encoding.

### `decodeWindows1252(input)`

Decodes a `Uint8Array` from Windows-1252 encoding to a JavaScript string.

## Kontenrahmen (Chart of Accounts)

DATEV supports two standard charts of accounts:

- **SKR03** - Process-oriented chart of accounts (Prozessgliederungsprinzip)
- **SKR04** - Function-oriented chart of accounts (Abschlussgliederungsprinzip)

The `sachkontenlaenge` parameter (4-8) determines the length of G/L account numbers:

```ts
// SKR03 with 4-digit accounts
{ sachkontenlaenge: 4, kontenrahmen: "SKR03" }

// SKR04 with 5-digit accounts
{ sachkontenlaenge: 5, kontenrahmen: "SKR04" }
```

## Encoding Notes

DATEV expects Windows-1252 encoded files. This package generates UTF-8 strings by default. Use `encodeWindows1252()` when writing files for DATEV import:

```ts
import { generateBuchungsstapel, encodeWindows1252 } from "@invoicekit/datev-export";
import { writeFileSync } from "fs";

const csv = generateBuchungsstapel(buchungen, options);
writeFileSync("EXTF_Buchungsstapel.csv", encodeWindows1252(csv));
```

German umlauts (ae, oe, ue, ss) and special characters are fully supported through the Windows-1252 encoding lookup table.

## References

- [DATEV Format Documentation (German)](https://developer.datev.de/datev/platform/de/dtvf)
- DATEV EXTF Format Specification v7.0