API-Dokumentation

Schnellstart

1. In BauManager Pro unter Einstellungen → API-Zugang einen Schlüssel anlegen (nur Administratoren). 2. Den Schlüssel bei jeder Anfrage mitsenden. 3. Fertig — alle Daten sind JSON in UTF-8.

curl https://baumanager.pro/api/v1/ich \
  -H "Authorization: Bearer bmp_IHR_SCHLUESSEL"

Basis-Adresse: https://baumanager.pro/api/v1

Authentifizierung

Jede Anfrage braucht einen API-Schlüssel im Kopf Authorization: Bearer <Schlüssel> (alternativ X-API-Key: <Schlüssel>). Schlüssel beginnen mit bmp_ und werden nur einmal beim Anlegen angezeigt.

Ein Schlüssel gilt nur für den eigenen Betrieb und handelt mit Administratorrechten. Er wird ungültig, wenn er widerrufen wird oder abläuft, wenn sein Ersteller kein aktiver Administrator mehr ist oder der Tarif keinen API-Zugang mehr enthält.

Anfragen und Antworten

Anfragen mit Inhalt (POST, PATCH) senden JSON mit Content-Type: application/json (höchstens 1 MB). Feldnamen sind deutsch, wie in der App. Datumsangaben im Format JJJJ-MM-TT, Zeitpunkte nach ISO 8601 mit Zeitzone, Beträge als Zahl mit Dezimalpunkt (netto, Euro).

Einzelner Datensatz

{ "data": { "id": 42, "nummer": "P-2026-0007", "name": "EFH Müller", … } }

Liste mit Seiten

{
  "data": [ { … }, { … } ],
  "meta": { "seite": 1, "pro_seite": 25, "gesamt": 137, "seiten": 6 }
}

Parameter für alle Listen: seite (ab 1) und pro_seite (1–100, Standard 25). Sortierung: neueste zuerst. Für die Synchronisation geaendert_seit nutzen und den Zeitpunkt der letzten Abfrage speichern.

PATCH ändert nur die übergebenen Felder (PUT wird gleich behandelt). Unbekannte Felder werden nicht still ignoriert, sondern als Fehler gemeldet.

Endpunkte

Kunden

Filter für GET /api/v1/kunden

Felder

Beispiel: anlegen

curl -X POST https://baumanager.pro/api/v1/kunden \
  -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{ "typ": "firma", "firmenname": "Müller Immobilien GmbH", "email": "info@mueller-immobilien.de",
        "strasse": "Hauptstraße 5", "plz": "50667", "ort": "Köln", "ust_id": "DE123456789" }'

→ 201 Created, Location: /api/v1/kunden/57
{ "data": { "id": 57, "kundennummer": "K-00057", "typ": "firma", … } }

Projekte

Filter für GET /api/v1/projekte

Felder

Beispiel: anlegen

curl -X POST https://baumanager.pro/api/v1/projekte \
  -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{ "name": "EFH Müller – Bad", "kunde_id": 57, "typ": "sanierung", "status": "beauftragt",
        "strasse": "Lindenweg 3", "plz": "50858", "ort": "Köln", "start_datum": "2026-11-02", "budget": 18500 }'

Angebote

Filter für GET /api/v1/angebote

Felder

Beispiel: anlegen

curl -X POST https://baumanager.pro/api/v1/angebote \
  -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{ "kunde_id": 57, "projekt_id": 12, "titel": "Badsanierung",
        "positionen": [
          { "typ": "titel", "bezeichnung": "Fliesenarbeiten" },
          { "bezeichnung": "Wandfliesen verlegen\nInkl. Kleber und Fugenmaterial", "menge": 24.5, "einheit": "m²", "einzelpreis": 48, "kostenart": "lohn" },
          { "produkt_id": 311, "menge": 3 } ] }'

→ 201 Created — Entwurf mit Nummer, Summen und Positionen

Rechnungen

Filter für GET /api/v1/rechnungen

Felder

Beispiel: anlegen

curl -X POST https://baumanager.pro/api/v1/rechnungen \
  -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-auftrag-10293" \
  -d '{ "kunde_id": 57, "leistungsdatum": "2026-10-15", "zahlungsziel_tage": 14,
        "positionen": [ { "bezeichnung": "Wartung Gasheizung", "menge": 1, "einzelpreis": 189, "kostenart": "lohn" } ] }'

curl https://baumanager.pro/api/v1/rechnungen/845/pdf -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" -o Rechnung.pdf
curl https://baumanager.pro/api/v1/rechnungen/845/xrechnung -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" -o XRechnung.xml

Positionen

Angebote und Rechnungen enthalten positionen — eine Liste in der gewünschten Reihenfolge (höchstens 500, mindestens eine vom Typ position). Mit produkt_id werden Bezeichnung, Einheit und Verkaufspreis aus dem Produktkatalog übernommen, sofern nicht angegeben; es gelten dieselben Regeln wie in der App (nur Artikel des Verkaufskatalogs). Steht in bezeichnung ein Zeilenumbruch, wird ab der zweiten Zeile ein Langtext. Für Artikel mit Maßen kann parameter (Objekt, z. B. {"breite": 1.2}) mitgegeben werden.

Über die API angelegte Angebote und Rechnungen sind Entwürfe: Nummer, MwSt.-Regeln (§ 13b, § 19 UStG), Tariflimits und Summen wie in der App. Prüfen, Versenden und Stornieren erfolgen in BauManager Pro — so bleibt jede versendete Rechnung GoBD-konform unverändert.

Fehler

Fehler haben einen HTTP-Status und einen stabilen code für Programme; message ist für Menschen (deutsch). Bei ungültigen Eingaben stehen alle Probleme auf einmal in felder.

{
  "error": {
    "code": "validierung",
    "message": "Eingaben ungültig.",
    "felder": { "email": "Keine gültige E-Mail-Adresse.", "positionen[0].menge": "Erlaubt: 0.001 bis 9999999.999." }
  }
}

Limits und Idempotenz

Je Betrieb gilt ein Stundenlimit für alle Schlüssel zusammen (im Tarif Enterprise: 1.000 Anfragen pro Stunde). Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Zeit). Bei Überschreitung folgt 429 mit Retry-After in Sekunden.

Doppelte Belege vermeiden

Senden Sie bei POST den Kopf Idempotency-Key (8–100 Zeichen, z. B. Ihre Auftragsnummer). Wird die Anfrage nach einem Verbindungsabbruch mit demselben Schlüssel wiederholt, liefert die API innerhalb von 24 Stunden die ursprüngliche Antwort (Kopf Idempotent-Replayed: true) — es entsteht keine zweite Rechnung.

curl -X POST https://baumanager.pro/api/v1/rechnungen \
  -H "Authorization: Bearer bmp_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-auftrag-10293" \
  -d '{ "kunde_id": 15, "positionen": [ { "bezeichnung": "Wartung Heizung", "menge": 1, "einzelpreis": 189 } ] }'

Versionen

Die Version steht in der Adresse (/api/v1) und im Kopf X-API-Version. Neue Felder und Endpunkte können ohne neue Version hinzukommen — Programme sollten unbekannte Felder in Antworten ignorieren. Inkompatible Änderungen erscheinen nur unter einer neuen Version.