Import Buchungen API

Import Entries (Importierte Buchungen) sind Banktransaktionen, die aus CAMT-Dateien importiert wurden und noch nicht als endgültige Buchungen erfasst wurden. Sie dienen als Zwischenschritt, um Banktransaktionen zu kategorisieren und anschliessend in Buchungen umzuwandeln.

Import Entry-Objekt

json

{
  "id": 4521,
  "company_id": 123,
  "user_id": 456,
  "bank_account_id": 847,
  "other_account_id": 923,
  "tax_rate_id": 12,
  "entry_id": null,
  "invoice_id": null,
  "date": "2024-01-15",
  "type": "expense",
  "sum": 150.00,
  "description": "Büromaterial Migros",
  "og_description": "MIGROS BASEL ZAHLUNG",
  "reference": "RF123456789",
  "ignore": false,
  "created_at": "2024-01-16T08:30:00.000000Z",
  "updated_at": "2024-01-16T10:15:00.000000Z",
  "date_formatted": "15.01.2024",
  "sum_formatted": "150.00",
  "is_ready": true,
  "similarExists": false
}

Attribute

Feld	Typ	Beschreibung
`id`	integer	Eindeutige ID des Import-Eintrags
`company_id`	integer	ID der zugehörigen Firma
`user_id`	integer	ID des Benutzers, der den Import durchgeführt hat
`bank_account_id`	integer	ID des Bankkontos
`other_account_id`	integer\|null	ID des Gegenkontos (Aufwand/Ertrag)
`tax_rate_id`	integer\|null	ID des MwSt-Satzes
`entry_id`	integer\|null	ID der erstellten Buchung (nach Verarbeitung)
`invoice_id`	integer\|null	ID der verknüpften Rechnung (bei Zahlungseingängen)
`date`	date	Datum der Transaktion
`type`	string	Typ (`income` oder `expense`)
`sum`	decimal	Betrag der Transaktion
`description`	string\|null	Bearbeitete Beschreibung
`og_description`	string\|null	Originalbeschreibung aus dem Bankauszug
`reference`	string\|null	Referenznummer (z.B. QR-Referenz)
`ignore`	boolean	Als ignoriert markiert
`is_ready`	boolean	Bereit zur Verarbeitung (Gegenkonto zugewiesen oder ignoriert)
`similarExists`	boolean	Gibt an, ob eine ähnliche Buchung bereits existiert
`date_formatted`	string	Formatiertes Datum
`sum_formatted`	string	Formatierter Betrag

Type-Werte

Wert	Beschreibung
`income`	Einnahme (Gutschrift auf Bankkonto)
`expense`	Ausgabe (Belastung auf Bankkonto)

Status-Logik

Ein Import-Eintrag ist bereit zur Verarbeitung (is_ready: true) wenn:

Ein Gegenkonto (other_account_id) zugewiesen wurde, ODER
Der Eintrag als ignoriert (ignore: true) markiert wurde

Endpoints

Alle Import-Einträge auflisten

http

GET /companies/{company_id}/entries/import

Ruft eine Liste aller nicht verarbeiteten Import-Einträge ab.

Parameter

Parameter	Typ	Standard	Beschreibung
`status`	string	-	Filtern nach Status
`search`	string	-	Volltextsuche in Beschreibung, Referenz, Betrag, Datum
`limit`	integer\|string	-	Einträge pro Seite (oder `all` für alle)
`offset`	integer	0	Offset für Paginierung

Filter-Optionen für Status

Wert	Beschreibung
`ready`	Bereit zur Verarbeitung (Gegenkonto zugewiesen oder ignoriert)
`notReady`	Noch nicht kategorisiert
`deleted`	Als ignoriert markiert
`notDeleted`	Nicht ignoriert

Response

json

{
  "data": [
    {
      "id": 4521,
      "date": "2024-01-15",
      "type": "expense",
      "sum": 150.00,
      "description": "Büromaterial Migros",
      "is_ready": true,
      "similarExists": false,
      "bank_account": {
        "id": 847,
        "name": "Bankkonto CHF",
        "number": "1020"
      },
      "other_account": {
        "id": 923,
        "name": "Büromaterial",
        "number": "6500"
      },
      "tax_rate": null,
      "invoice": null,
      "file": null
    }
  ],
  "current_count": 1,
  "total_count": 45,
  "open_count": 12,
  "ready_count": 33
}

Beispiel

bash

curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/entries/import"

# Mit Filtern
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/entries/import?status=notReady&search=migros"

Import-Eintrag aktualisieren

http

PUT /companies/{company_id}/entries/import/{import_entry_id}

Aktualisiert einen Import-Eintrag (z.B. Gegenkonto zuweisen).

Request Body

json

{
  "other_account_id": 923,
  "tax_rate_id": 12,
  "description": "Büromaterial Migros",
  "ignore": false
}

Aktualisierbare Felder

Feld	Typ	Beschreibung
`other_account_id`	integer	Gegenkonto-ID
`bank_account_id`	integer	Bankkonto-ID
`expense_account_id`	integer	Aufwandskonto-ID (nur bei `type: expense`)
`income_account_id`	integer	Ertragskonto-ID (nur bei `type: income`)
`tax_rate_id`	integer\|null	MwSt-Satz-ID
`vat_income`	string\|null	MwSt-Code für Einnahmen
`vat_expense`	string\|null	MwSt-Code für Ausgaben
`description`	string	Beschreibung
`tags`	array	Array von Tag-Objekten (mit `id` oder `new: true` und `name`, `color`)
`invoice_id`	integer\|null	Verknüpfte Rechnung
`ignore`	boolean	Als ignoriert markieren

Response

http

HTTP/1.1 200 OK

Beispiel

bash

curl -X PUT \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"other_account_id": 923, "tax_rate_id": 12}' \
     "https://app.milkee.ch/api/v2/companies/123/entries/import/4521"

Import-Eintrag zurücksetzen

http

PUT /companies/{company_id}/entries/import/{import_entry_id}/reset

Setzt einen Import-Eintrag auf den Originalzustand zurück (entfernt Gegenkonto, MwSt und setzt Originalbeschreibung).

Response

http

HTTP/1.1 200 OK

Mehrere Import-Einträge aktualisieren

http

PUT /companies/{company_id}/entries/import/multiple

Aktualisiert mehrere Import-Einträge gleichzeitig mit denselben Werten.

Request Body

json

{
  "ids": [4521, 4522, 4523],
  "other_account_id": 923,
  "tax_rate_id": 12
}

Response

http

HTTP/1.1 200 OK

Import-Einträge löschen

http

DELETE /companies/{company_id}/entries/import

Löscht Import-Einträge.

Request Body

json

{
  "ids": [4521, 4522, 4523]
}

Oder alle löschen:

json

{
  "ids": "all"
}

Response

http

HTTP/1.1 200 OK

json

{
  "success": true
}

Import-Einträge verarbeiten (Buchungen erstellen)

http

POST /companies/{company_id}/entries/import

Verarbeitet alle bereiten Import-Einträge und erstellt daraus Buchungen.

Voraussetzung

Nur Import-Einträge mit is_ready: true werden verarbeitet.

Response

json

{
  "created": 25,
  "ignored": 8,
  "errors": []
}

CAMT-Datei hochladen

http

POST /companies/{company_id}/entries/import/camt-upload

Importiert Banktransaktionen aus einer CAMT-Datei (XML) oder ZIP-Archiv.

Request Body (multipart/form-data)

Feld	Typ	Beschreibung
`file`	file	CAMT-XML oder ZIP-Datei
`bank_account_id`	integer	(Optional) Bankkonto-ID

Unterstützte Formate

CAMT.053 (Kontoauszug)
CAMT.054 (Sammelbuchung-Details)
ZIP-Archive mit mehreren CAMT-Dateien

Response

http

HTTP/1.1 200 OK

json

true

Beispiel

bash

curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -F "file=@kontoauszug.xml" \
     -F "bank_account_id=847" \
     "https://app.milkee.ch/api/v2/companies/123/entries/import/camt-upload"

Beleg-Verwaltung

Beleg hochladen

http

POST /companies/{company_id}/entries/import/{import_entry_id}/file

Lädt einen Beleg (Quittung, Rechnung) für einen Import-Eintrag hoch.

Request Body (multipart/form-data)

Feld	Typ	Beschreibung
`file`	file	Beleg-Datei (max. 6MB)

Response

json

{
  "success": true,
  "file": {
    "id": 789,
    "name": "quittung.pdf",
    "size": 125000
  }
}

Beleg löschen

http

DELETE /companies/{company_id}/entries/import/{import_entry_id}/file

Löscht den Beleg eines Import-Eintrags.

Response

json

{
  "success": true
}

Beleg-URL abrufen

http

GET /companies/{company_id}/entries/import/{import_entry_id}/file/url

Gibt eine signierte URL zum Anzeigen des Belegs zurück.

Response

json

{
  "url": "https://storage.example.com/files/abc123?signature=xyz",
  "expires_at": "2024-01-16T12:00:00Z"
}

Fehlerbehandlung

400 Bad Request

json

{
  "message": "Keine Buchungen ausgewählt"
}

404 Not Found

json

{
  "message": "Not found."
}

json

{
  "message": "Kein Beleg vorhanden."
}

422 Validation Error

json

{
  "message": "Datei darf nicht grösser als 6MB sein."
}

Best Practices

Typischer Import-Workflow

javascript

// 1. CAMT-Datei hochladen
await api.post(`/companies/${companyId}/entries/import/camt-upload`, {
  file: camtFile,
  bank_account_id: bankAccountId
});

// 2. Import-Einträge abrufen
const entries = await api.get(`/companies/${companyId}/entries/import`, {
  params: { status: 'notReady' }
});

// 3. Gegenkonten zuweisen
for (const entry of entries.data) {
  await api.put(`/companies/${companyId}/entries/import/${entry.id}`, {
    other_account_id: determineAccount(entry),
    tax_rate_id: determineTaxRate(entry)
  });
}

// 4. Buchungen erstellen
const result = await api.post(`/companies/${companyId}/entries/import`);
console.log(`${result.created} Buchungen erstellt`);

Automatische Kategorisierung

Import-Einträge werden automatisch mit Import-Regeln abgeglichen. Wenn eine Regel passt, werden Gegenkonto, MwSt-Satz und Beschreibung automatisch gesetzt.

javascript

// Prüfen ob Eintrag bereits kategorisiert wurde
if (entry.is_ready) {
  console.log('Eintrag ist bereit zur Verarbeitung');
} else {
  console.log('Gegenkonto muss noch zugewiesen werden');
}

Zahlungseingänge mit Rechnungen verknüpfen

Bei Zahlungseingängen mit QR-Referenz wird automatisch die passende Rechnung gesucht:

javascript

// Rechnung wurde automatisch verknüpft
if (entry.invoice_id) {
  console.log(`Zahlung für Rechnung #${entry.invoice.number}`);
}

Mehrere Einträge gleichzeitig aktualisieren

javascript

// Alle ausgewählten Einträge demselben Konto zuweisen
await api.put(`/companies/${companyId}/entries/import/multiple`, {
  ids: [4521, 4522, 4523],
  other_account_id: 923,
  tax_rate_id: 12
});

Nächste Schritte

Entries API - Buchungen verwalten
Accounts API - Konten verwalten
Import Rules - Automatische Kategorisierung einrichten

Import Buchungen API ​

Import Entry-Objekt ​

Attribute ​

Type-Werte ​

Status-Logik ​

Endpoints ​

Alle Import-Einträge auflisten ​

Parameter ​

Filter-Optionen für Status ​

Response ​

Beispiel ​

Import-Eintrag aktualisieren ​

Request Body ​

Aktualisierbare Felder ​

Response ​

Beispiel ​

Import-Eintrag zurücksetzen ​

Response ​

Mehrere Import-Einträge aktualisieren ​

Request Body ​

Response ​

Import-Einträge löschen ​

Request Body ​

Response ​

Import-Einträge verarbeiten (Buchungen erstellen) ​

Response ​

CAMT-Datei hochladen ​

Request Body (multipart/form-data) ​

Unterstützte Formate ​

Response ​

Beispiel ​

Beleg-Verwaltung ​

Beleg hochladen ​

Request Body (multipart/form-data) ​

Response ​

Beleg löschen ​

Response ​

Beleg-URL abrufen ​

Response ​

Fehlerbehandlung ​

400 Bad Request ​

404 Not Found ​

422 Validation Error ​

Best Practices ​

Typischer Import-Workflow ​

Automatische Kategorisierung ​

Zahlungseingänge mit Rechnungen verknüpfen ​

Mehrere Einträge gleichzeitig aktualisieren ​

Nächste Schritte ​

Import Buchungen API

Import Entry-Objekt

Attribute

Type-Werte

Status-Logik

Endpoints

Alle Import-Einträge auflisten

Parameter

Filter-Optionen für Status

Response

Beispiel

Import-Eintrag aktualisieren

Request Body

Aktualisierbare Felder

Response

Beispiel

Import-Eintrag zurücksetzen

Response

Mehrere Import-Einträge aktualisieren

Request Body

Response

Import-Einträge löschen

Request Body

Response

Import-Einträge verarbeiten (Buchungen erstellen)

Response

CAMT-Datei hochladen

Request Body (multipart/form-data)

Unterstützte Formate

Response

Beispiel

Beleg-Verwaltung

Beleg hochladen

Request Body (multipart/form-data)

Response

Beleg löschen

Response

Beleg-URL abrufen

Response

Fehlerbehandlung

400 Bad Request

404 Not Found

422 Validation Error

Best Practices

Typischer Import-Workflow

Automatische Kategorisierung

Zahlungseingänge mit Rechnungen verknüpfen

Mehrere Einträge gleichzeitig aktualisieren

Nächste Schritte