Integration Guide

Technische Dokumentation

Alles was Sie brauchen, um die MintFolder AI API in Ihr System zu integrieren

🚀 Quick Start 01

🔑 Authentifizierung 02

📤 Archivierung 03

📊 Statistiken 04

📋 Nutzungsprotokolle 05

💎 Pläne & Preise 06

⚠️ Fehlerbehandlung 07

💡 Code-Beispiele 08

🛡️ Rate Limits 09

🔧 Dashboard API 10

📦 SDKs & Support 11

Quick Start

In drei Schritten zur ersten API-Anfrage. Registrieren, Key erstellen, Dokument archivieren.

Unternehmen registrieren

Erstellen Sie Ihr B2B-Konto über die Registrierungs-API.

cURL

curl -X POST https://api.mintfolder.ai/api/b2b/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme GmbH",
    "email": "[email protected]",
    "password": "StrongPassword123!", // pragma: allowlist secret
    "contact_name": "Max Müller",
    "accepted_terms": true,
    "accepted_privacy": true,
    "accepted_ai_processing": true
  }'

Parameter	Typ	Beschreibung
name REQUIRED	String	Unternehmensname
email REQUIRED	String	E-Mail-Adresse des Administrators
password REQUIRED	String	Passwort (mindestens 8 Zeichen, Groß- und Kleinbuchstaben, Zahl)
contact_name OPTIONAL	String	Name des Ansprechpartners
accepted_terms REQUIRED	Boolean	Zustimmung zu den AGB. Muss JSON `true` sein.
accepted_privacy REQUIRED	Boolean	Zustimmung zur Datenschutzerklärung. Muss JSON `true` sein.
accepted_ai_processing REQUIRED	Boolean	Zustimmung zur KI-Verarbeitung. Muss JSON `true` sein.

API-Key erstellen

Generieren Sie einen API-Key im Dashboard. Der Schlüssel wird nur einmal im Klartext angezeigt — speichern Sie ihn sicher.

cURL

curl -X POST https://api.mintfolder.ai/api/b2b/keys \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key", "environment": "live"}'

Parameter	Typ	Beschreibung
name OPTIONAL	String	Bezeichnung des Schlüssels. Standard: `Default`
environment OPTIONAL	String	Umgebung. Werte: `live`, `test`. Standard: `production`

⚠️

Der Raw-Key (sk_live_...) wird nur bei der Erstellung einmalig zurückgegeben. Kopieren und sicher speichern!

Erstes Dokument archivieren

Senden Sie eine Datei an den Archive-Endpoint und erhalten Sie strukturierte Metadaten zurück.

cURL

curl -X POST https://api.mintfolder.ai/v1/archive \
  -H "Authorization: Bearer sk_live_abc123..." \
  -F "[email protected]" \
  -F "language=de"

Authentifizierung

Jeder API-Request muss einen gültigen API-Key im Authorization-Header enthalten.

HTTP Header

Authorization: Bearer sk_live_...

cURL

curl -X POST https://api.mintfolder.ai/v1/archive \
  -H "Authorization: Bearer sk_live_abc123..." \
  -F "[email protected]"

🔑

Ihr API-Key ist privat. Teilen Sie ihn niemals öffentlich. Bei Verdacht auf Kompromittierung können Sie im Dashboard einen neuen Key generieren.

⚠️

Senden Sie den API-Key niemals im Query-String (?key=...). Verwenden Sie immer den Authorization Header.

Dokument archivieren

Senden Sie eine Datei an den Archive-Endpoint. Die AI analysiert das Dokument, erkennt Metadaten und gibt einen strukturierten Smart Name zurück.

POST /v1/archive

Parameter	Typ	Beschreibung
file REQUIRED	File	Datei zum Archivieren. Max. 100 MB. Formate: PDF, DOCX, XLSX, JPG, PNG, TIFF, ZIP, XML
language OPTIONAL	String	Sprache der Analyse. Standard: `en`. Werte: `ar`, `de`, `en`
category_hint OPTIONAL	String	Hinweis für die Kategorie-Erkennung, z.B. `"finance"` oder `"medical"`

200 OK — Success Response

{
  "smart_name": "2026-03-07_Amazon_Rechnung_Mueller.pdf",
  "display_name": "2026-03-07_Amazon_Rechnung_Mueller.pdf",
  "storage_name": "2026-03-07_Amazon_Rechnung_Mueller.pdf",
  "canonical_name": "amazon_rechnung_mueller",
  "category": "FI",
  "category_label": "Finance",
  "confidence": 0.97,
  "tags": ["finance", "de"],
  "folder_path": "Finance/2026/03",
  "final_path": "Finance/2026/03/2026-03-07_Amazon_Rechnung_Mueller.pdf",
  "fallback_used": "",
  "validation_errors": [],
  "decision_reason": "AI classified as Finance with high confidence",
  "audit_trail": {
    "model": "gemini-2.0-flash",
    "attempts": 1
  },
  "metadata": {
    "sender": "Amazon EU S.à r.l.",
    "recipient": "Max Müller",
    "date": "2026-03-07",
    "language_detected": "de",
    "kuerzel": "FI"
  },
  "financial": {
    "betrag_brutto": "49.99",
    "betrag_netto": "42.01",
    "waehrung": "EUR",
    "rechnungsnummer": "RE-2026-0042",
    "faelligkeitsdatum": "2026-03-21",
    "ust_id_sender": "LU26375245",
    "iban": null,
    "payment_status": null,
    "tax_breakdown": []
  },
  "gobd": {
    "belegnummer_seed": "FI-20260307-001",
    "aufbewahrungsfrist_jahre": 10,
    "requires_manual_review": false
  },
  "processing_time_ms": 2340,
  "usage": {
    "files_used": 13,
    "files_per_month": 500,
    "overage": 0
  },
  "request_id": "req_a1b2c3d4e5f6"
}

📊

confidence zeigt die Sicherheit der AI-Erkennung (0.0–1.0). Werte über 0.85 gelten als zuverlässig. Werte unter 0.60 deuten auf mehrdeutige Dokumente hin.

🤖

KI-Transparenz: Alle Klassifikationsfelder dieser API (category, suggested_name, confidence, summary) sind KI-generiert. Die Verarbeitung nutzt eine Fallback-Kette aus Gemini (Google), Claude (Anthropic) und GPT-4o (OpenAI) sowie Ollama (lokal auf unseren Servern). Welcher Anbieter ein Dokument tatsächlich verarbeitet hat, wird pro Archiveintrag im Feld ai_provider protokolliert und ist im Rahmen einer Auskunft nach Art. 15 DSGVO abrufbar. Ergebnisse sind stets durch den Nutzer prüfbar und korrigierbar. Drittlandtransfers an die US-Anbieter erfolgen — soweit der Empfänger zertifiziert ist — auf Grundlage des EU-U.S. Data Privacy Framework, ergänzend gelten Standardvertragsklauseln (SCCs); Details in der Datenschutzerklärung. Hinweis: Wer KI-Ausgaben dieser API in eigene Produkte einbettet oder Endnutzern bereitstellt, kann eigenen Transparenzpflichten nach Art. 50 KI-VO unterliegen.

POST /v1/bulk-upload

Bis zu 100 Dokumente gleichzeitig für die Batch-KI-Klassifizierung hochladen. Erfordert Starter-Plan oder höher. Rate-Limit: 5 Anfragen/Minute. Max. 20 MB pro Datei.

Parameter	Typ	Beschreibung
files REQUIRED	File[]	Bis zu 100 Dateien als `multipart/form-data`. Max. 20 MB pro Datei.
language OPTIONAL	String	Sprache der Analyse. Werte: `ar`, `de`, `en`. Standard: `de`

🔑

Authentifizierung: Bearer API-Key erforderlich (Authorization: Bearer sk_live_...).

200 OK — Response

{
  "batch_id": "batch_a1b2c3d4e5f6",
  "file_count": 3,
  "poll_url": "/v1/bulk-upload/batch_a1b2c3d4e5f6/status"
}

GET /v1/bulk-upload/{batch_id}/status

Status eines Batch-Jobs abfragen, der mit POST /v1/bulk-upload gestartet wurde.

Parameter	Typ	Beschreibung
batch_id REQUIRED	String	Batch-ID aus der Antwort von `POST /v1/bulk-upload` (URL-Pfadparameter)

🔑

Authentifizierung: Bearer API-Key erforderlich (Authorization: Bearer sk_live_...).

200 OK — Response

{
  "batch_id": "batch_a1b2c3d4e5f6",
  "status": "completed",
  "total": 3,
  "done": 3,
  "failed": 0,
  "results": [...]
}

Nutzungsstatistiken

Rufen Sie detaillierte Statistiken über Ihre API-Nutzung ab — inklusive Dateivolumen, Rate-Limits und Unternehmensinfos.

GET /v1/stats?days=30

Parameter	Typ	Beschreibung
days OPTIONAL	Integer	Zeitraum in Tagen. Standard: `30`. Bereich: `1–365`

200 OK — Success Response

{
  "company": {
    "name": "Acme GmbH",
    "plan": "business",
    "is_active": true,
    "files_used": 847,
    "files_per_month": 2000,
    "billing_cycle_start": "2026-03-01T00:00:00"
  },
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 2000
  },
  "period_days": 30,
  "stats": {
    "total_requests": 847,
    "successful": 831,
    "failed": 16,
    "avg_processing_ms": 2340,
    "by_endpoint": [
      {"endpoint": "/v1/archive", "cnt": 812},
      {"endpoint": "/v1/stats", "cnt": 35}
    ],
    "by_day": [
      {"day": "2026-03-14", "cnt": 42},
      {"day": "2026-03-15", "cnt": 38}
    ]
  },
  "request_id": "req_a1b2c3d4e5f6"
}

📅

Verwenden Sie den days-Parameter, um den Zeitraum einzuschränken. days=7 liefert z.B. nur die Statistiken der letzten Woche.

Nutzungsprotokolle

Detaillierte Protokolle jeder API-Anfrage — ideal für Debugging, Auditing und Nachverfolgung.

GET /v1/usage?limit=50

Parameter	Typ	Beschreibung
limit OPTIONAL	Integer	Anzahl der Einträge. Standard: `50`. Bereich: `1–500`

200 OK — Success Response

{
  "logs": [
    {
      "endpoint": "/v1/archive",
      "method": "POST",
      "status_code": 200,
      "file_name": "invoice.pdf",
      "category": "Finance",
      "processing_ms": 2340,
      "error_message": null,
      "created_at": "2026-03-15T14:30:00"
    },
    {
      "endpoint": "/v1/archive",
      "method": "POST",
      "status_code": 400,
      "file_name": "broken.exe",
      "category": null,
      "processing_ms": 12,
      "error_message": "Unsupported file type: exe",
      "created_at": "2026-03-15T14:25:00"
    }
  ],
  "count": 2,
  "request_id": "req_f6e5d4c3b2a1"
}

🔍

Nutzen Sie die Nutzungsprotokolle für Debugging: Jeder Eintrag enthält endpoint, processing_ms und status_code für die Nachverfolgung. Die request_id wird auf oberster Ebene der Antwort zurückgegeben.

Pläne & Preise

Verfügbare Tarife für die MintFolder AI API. Dieser Endpoint ist öffentlich und erfordert keine Authentifizierung.

GET /v1/plans

Trial

Free

20 files/mo
10 RPM
14 Tage

Starter

€69/mo

500 files/mo
60 RPM
E-Mail-Support

Business ⭐

€149/mo

2,000 files/mo
120 RPM
E-Mail-Support

Enterprise

€349/mo

10,000 files/mo
300 RPM
E-Mail-Support

Enterprise

Custom

Unlimited files
1,000 RPM
E-Mail-Support

200 OK — Response

{
  "plans": [
    {
      "id": "trial",
      "name": "Trial",
      "price_eur": 0,
      "files_per_month": 20,
      "requests_per_minute": 10,
      "requests_per_hour": 60,
      "overage_eur": 0
    },
    {
      "id": "starter",
      "name": "Starter",
      "price_eur": 69,
      "files_per_month": 500,
      "requests_per_minute": 60,
      "requests_per_hour": 600,
      "overage_eur": 0.25
    },
    {
      "id": "business",
      "name": "Business",
      "price_eur": 149,
      "files_per_month": 2000,
      "requests_per_minute": 120,
      "requests_per_hour": 2000,
      "overage_eur": 0.15
    },
    {
      "id": "scale",
      "name": "Enterprise",
      "price_eur": 349,
      "files_per_month": 10000,
      "requests_per_minute": 300,
      "requests_per_hour": 6000,
      "overage_eur": 0.08
    },
    {
      "id": "enterprise",
      "name": "Enterprise",
      "price_eur": "Custom",
      "files_per_month": "Unlimited",
      "requests_per_minute": 1000,
      "requests_per_hour": 20000,
      "overage_eur": "Custom"
    }
  ]
}

💎

Der Trial-Plan läuft nach 14 Tagen automatisch ab. Upgraden Sie rechtzeitig auf einen kostenpflichtigen Plan, um Unterbrechungen zu vermeiden.

Fehlerbehandlung

Die API verwendet RFC 7807 Problem Details Format für alle Fehlerantworten.

RFC 7807 — Error Response

{
  "type": "https://mintfolder.ai/docs/errors/invalid-file-type",
  "title": "Invalid File Type",
  "status": 400,
  "detail": "The uploaded file type 'exe' is not supported.",
  "instance": "/v1/archive",
  "request_id": "req_a1b2c3d4",
  "allowed_types": ["pdf","docx","xlsx","jpg","png","tiff","zip"],
  "hint": "Upload a supported file format"
}

200 Erfolgreich verarbeitet
400 Ungültige Anfrage — fehlende oder ungültige Datei
401 Fehlender oder ungültiger API-Key
402 Kontingent erschöpft — Plan upgraden
403 Abonnement inaktiv
429 Rate-Limit überschritten
500 Interner Serverfehler

⚠️

Bei 429-Fehlern enthält die Antwort einen Retry-After Header mit der Wartezeit in Sekunden.

Code-Beispiele

Fertige Snippets für die gängigsten Programmiersprachen.

cURL

curl -X POST https://api.mintfolder.ai/v1/archive \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "language=de"

Python

import requests

url = "https://api.mintfolder.ai/v1/archive"
headers = {"Authorization": "Bearer sk_live_YOUR_KEY"}

with open("invoice.pdf", "rb") as f:
    resp = requests.post(
        url, headers=headers,
        files={"file": ("invoice.pdf", f, "application/pdf")},
        data={"language": "de"}
    )

result = resp.json()
print(result["smart_name"])
# → "2026-03-07_Amazon_Rechnung_Mueller.pdf"

Node.js

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('invoice.pdf'));
form.append('language', 'de');

const { data } = await axios.post(
  'https://api.mintfolder.ai/v1/archive',
  form,
  { headers: {
    ...form.getHeaders(),
    'Authorization': 'Bearer sk_live_YOUR_KEY'
  }}
);

console.log(data.smart_name);
// → "2026-03-07_Amazon_Rechnung_Mueller.pdf"

PHP

<?php
$ch = curl_init('https://api.mintfolder.ai/v1/archive');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer sk_live_YOUR_KEY'
  ],
  CURLOPT_POSTFIELDS     => [
    'file'     => new CURLFile('invoice.pdf'),
    'language' => 'de'
  ]
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $result['smart_name'];
// → "2026-03-07_Amazon_Rechnung_Mueller.pdf"

using var client = new HttpClient();
client.DefaultRequestHeaders.Add(
  "Authorization", "Bearer sk_live_YOUR_KEY");

using var form = new MultipartFormDataContent();
var fileContent = new ByteArrayContent(
  File.ReadAllBytes("invoice.pdf"));
form.Add(fileContent, "file", "invoice.pdf");
form.Add(new StringContent("de"), "language");

var resp = await client.PostAsync(
  "https://api.mintfolder.ai/v1/archive", form);
var json = await resp.Content.ReadAsStringAsync();
Console.WriteLine(json);

💡

Brauchen Sie Hilfe bei der Integration? [email protected]

Rate Limits

Übersicht der Anfragelimits pro Plan.

Rate Limit Headers

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 47
X-RateLimit-Limit-Hour: 600
X-RateLimit-Remaining-Hour: 553
X-RateLimit-Reset: 1741334460

Plan	Req/Min	Req/Std	Dateien/Monat	Überschreitung
Trial	10	60	20	—
Starter	60	600	500	€0.25
Business	120	2,000	2,000	€0.15
Enterprise	300	6,000	10,000	€0.08
Enterprise	1,000	20,000	Unbegrenzt	Individuell

⚠️

Bei Überschreitung erhalten Sie 429 Too Many Requests. Implementieren Sie exponentielles Backoff und beachten Sie den Retry-After Header.

Dashboard API

Endpoints für die Verwaltung Ihres Unternehmenskontos über das Dashboard.

Authentifizierung

POST/api/b2b/registerUnternehmen registrieren

POST/api/b2b/verify-emailE-Mail verifizieren

POST/api/b2b/resend-codeCode erneut senden

POST/api/b2b/loginAnmelden

POST/api/b2b/forgot-passwordPasswort vergessen

POST/api/b2b/reset-passwordPasswort zurücksetzen

Profilverwaltung

GET/api/b2b/meProfil abrufen

PUT/api/b2b/meProfil aktualisieren

POST/api/b2b/change-passwordPasswort ändern

API-Schlüssel

GET/api/b2b/keysAlle Schlüssel auflisten

POST/api/b2b/keysNeuen Schlüssel erstellen

DELETE/api/b2b/keys/{id}Schlüssel widerrufen

Abrechnung

GET/api/b2b/statsNutzungsstatistiken

GET/api/b2b/logsRequest-Logs

POST/api/b2b/stripe/checkoutCheckout starten

POST/api/b2b/stripe/portalBilling-Portal öffnen

🔧

Dashboard-Endpoints verwenden Bearer ct_... Token (nicht API-Key). Dieses Token erhalten Sie nach dem Login.

SDKs & Support

Ressourcen und Kontaktmöglichkeiten für Ihre Integration.

Support	[email protected]
Base URL	`https://api.mintfolder.ai`
Dashboard	https://b2b.mintfolder.ai
API Version	`v1`

📦

Unser Team antwortet innerhalb von 24 Stunden. Für Enterprise-Kunden bieten wir dedizierten Support und Onboarding.