Schnellstart
In wenigen Schritten zur ersten Batch-Verarbeitung
Voraussetzungen
Sie benötigen einen aktiven SteuerMappePro-Account und API-Zugangsdaten (Client ID & Secret). Diese erhalten Sie von Ihrem SteuerMappePro Administrator.
1
API-Zugangsdaten erhalten
Kontaktieren Sie Ihren SteuerMappePro Administrator, um API-Zugangsdaten für Ihr Projekt zu erhalten. Sie erhalten:
- Client ID - Eindeutige Projekt-Kennung
- Client Secret - Geheimer Schlüssel (nur einmal sichtbar!)
- Scopes - Berechtigungen (z.B. batches:write, batches:read)
Sicherheitshinweis
Das Client Secret wird nur einmal bei der Erstellung angezeigt. Speichern Sie es sicher (z.B. in einem Password Manager oder Secret Management System).
2
Access Token anfordern
Authentifizieren Sie sich mit OAuth2 Client Credentials Flow:
cURL
curl -X POST https://api.steuermappe-pro.de/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "proj_datev_2024_abc123",
"client_secret": "secret_xyz789",
"scope": "batches:write batches:read results:read"
}'TypeScript / Node.js
const response = await fetch('https://api.steuermappe-pro.de/v1/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'client_credentials',
client_id: 'proj_datev_2024_abc123',
client_secret: 'secret_xyz789',
scope: 'batches:write batches:read results:read'
})
});
const { access_token } = await response.json();
console.log('Access Token:', access_token);Antwort:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "batches:write batches:read results:read",
"project": {
"id": "prj_123",
"name": "DATEV Integration 2024",
"organization_id": "org_abc",
"partner_code": "ABC123"
}
}Der Access Token ist 1 Stunde gültig. Fordern Sie bei Bedarf einen neuen Token an (Token Refresh wird aktuell nicht unterstützt).
3
Batch erstellen
Erstellen Sie Ihre erste Batch-Verarbeitung:
cURL
curl -X POST https://api.steuermappe-pro.de/v1/batches \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"batch_name": "Steuererklärung 2024 - Q4",
"mandant": {
"first_name": "Klaus",
"last_name": "Müller",
"tax_id": "12345678901"
},
"documents": [
{
"filename": "rechnung_001.pdf",
"source": {
"type": "url",
"url": "https://files.partner.example/presigned/rechnung_001.pdf",
"expires_at": "2025-10-28T10:15:00Z",
"sha256": "b6f2..."
}
}
],
"processing": {
"phases": ["conversion", "analysis"],
"language": "de"
},
"webhook_url": "https://ihre-app.de/webhooks/steuermappe"
}'TypeScript / Node.js
const response = await fetch('https://api.steuermappe-pro.de/v1/batches', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
batch_name: 'Steuererklärung 2024 - Q4',
mandant: {
first_name: 'Klaus',
last_name: 'Müller',
tax_id: '12345678901'
},
documents: [
{
filename: 'rechnung_001.pdf',
source: {
type: 'url',
url: 'https://files.partner.example/presigned/rechnung_001.pdf',
expires_at: '2025-10-28T10:15:00Z',
sha256: 'b6f2...'
}
}
],
processing: {
phases: ['conversion', 'analysis'],
language: 'de'
},
webhook_url: 'https://ihre-app.de/webhooks/steuermappe'
})
});
const batch = await response.json();
console.log('Batch erstellt:', batch.batch_id);Antwort (202 Accepted):
{
"batch_id": "b_abc123",
"project_id": "prj_123",
"organization_id": "org_abc",
"mandant": {
"id": "m_456",
"name": "Klaus Müller"
},
"status": "queued",
"storage": { "provider": "managed", "base_path": "/<org>/<year>/<mandant>/Batch_<date>_b_abc123" },
"partner_code": {
"code": "ABC123",
"discount_percent": 15.00,
"snapshot_id": "pcs_789"
},
"estimated_cost": {
"total_eur": "8.50"
},
"created_at": "2025-10-06T10:00:00Z"
}4
Status abfragen
Überwachen Sie den Fortschritt Ihrer Batch-Verarbeitung:
cURL
curl -X GET https://api.steuermappe-pro.de/v1/batches/b_abc123/progress \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"TypeScript / Node.js
const response = await fetch(
'https://api.steuermappe-pro.de/v1/batches/b_abc123/progress',
{
headers: { 'Authorization': `Bearer ${accessToken}` }
}
);
const progress = await response.json();
console.log(`Fortschritt: ${progress.current_phase.overall_progress}%`);Antwort:
{
"batch_id": "b_abc123",
"status": "processing",
"current_phase": {
"phase": "ANALYSIS",
"phase_progress": 65,
"overall_progress": 82,
"micro_step": "processing_invoices",
"estimated_time_remaining_seconds": 45
},
"file_progress": {
"current_file": "rechnung_007.pdf",
"current_index": 7,
"total_files": 12
}
}5
Ergebnis herunterladen
Nach Abschluss der Verarbeitung können Sie das Ergebnis abrufen:
cURL
curl -X GET https://api.steuermappe-pro.de/v1/batches/b_abc123/result \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"TypeScript / Node.js
const response = await fetch(
'https://api.steuermappe-pro.de/v1/batches/b_abc123/result',
{
headers: { 'Authorization': `Bearer ${accessToken}` }
}
);
const result = await response.json();
console.log('Download URL:', result.result.download_url);
// Datei herunterladen
const fileResponse = await fetch(result.result.download_url);
const blob = await fileResponse.blob();
// Speichern oder verarbeiten...Antwort:
{
"batch_id": "b_abc123",
"status": "completed",
"result": {
"download_url": "https://files.partner.example/presigned/result.zip",
"expires_at": "2025-10-28T10:15:00Z",
"file_size_bytes": 5242880,
"sha256": "a3b5..."
},
"usage": {
"pages_processed": 38,
"documents_processed": 12,
"total_duration_seconds": 245
},
"billing": {
"total_cost_eur": "8.50"
}
}Nächste Schritte
Benötigen Sie Hilfe?
Unser Support-Team steht Ihnen bei Fragen zur Verfügung: api@steuermappe-pro.de