HERO

Geschäftsüberblick in EINEM Aufruf: offene Posten (Summe + Liste), Termine der nächsten 7 Tage, offene und zugewiesene Aufträge. Ideal als Einstieg ('was ist heute los?'). stichtag optional 'YYYY-MM-DD' (Default: heute).

Universalsuche über Kontakte, Projekte, Dokumente und Aufträge in EINEM Request. Erster Griff, wenn nur ein Name, eine Nummer oder ein Stichwort bekannt ist.

Projektakte: Stufe, Kunde, Adresse, Dokumente und Dateien. Akzeptiert Projektnummer ('PRJ-153') oder project_match_id.

Kontakte suchen oder auflisten (Name, Firma, E-Mail, Telefon, Adresse).

Ein Kontakt mit allen Adressen und seinen Projekten.

Dokumente eines Projekts (Angebote, Rechnungen, …) mit Status und Wert. only_active=true blendet gelöschte aus.

Artikelstamm mit Preisen. Liefert product_id (String!), Nummer, Name, EK (base_price), VK (list_price) und den Lagerbestand, falls der Artikel Lagermaterial ist.

Lagerbestand eines Artikels, gelesen über den Artikel. product_id ist ein String (HERO nutzt hier keine Zahl) — aus list_articles übernehmen.

Field-Service-Aufträge (Wartung, Reparatur, Notdienst). status akzeptiert offen/zugewiesen/erledigt (verifiziert) oder einen status_code als Zahl; andere Namen werden gegen die tatsächlichen Statuswerte des Mandanten aufgelöst.

Checklisten eines Auftrags inklusive der vor Ort in der Mobile-App ausgefüllten Antworten (Feld 'data').

Termine im Zeitraum. start/end als ISO MIT Offset ('2026-07-20T00:00:00+02:00'); ohne Offset antwortet HERO mit einem Serverfehler.

Erfasste Arbeitszeiten eines Projekts (Datum, Dauer, Kommentar, Mitarbeiter). start/end als 'YYYY-MM-DD'. Dauer steht in duration_in_seconds.

Debitoren-Offene-Posten: wer schuldet was und hängt wie weit hinterher. Restbetrag wird aus Rechnungswert minus erfassten Zahlungen gerechnet.

Zahlungsstatus einer Rechnung: offen oder bezahlt, Restbetrag, Fälligkeit und die erfassten Zahlungen. Das ist der Rücklesepfad für record_payment.

Eingangsbelege inklusive Zahlungsstand. offen = Wert minus paid_sum. Hinweis: Belege lassen sich über die HERO-API nur lesen, nicht anlegen.

Vorsignierter, zeitbegrenzter PDF-Link eines Dokuments — der Empfänger braucht keinen Token. Existiert kein PDF, ist das Dokument noch Entwurf oder im Publishing (~5–8 s).

Vorsignierter, zeitbegrenzter Link für eine beliebige Datei per uuid.

Kontakt mit Adresse anlegen. Wird über die Stammdaten dedupliziert — ein bereits vorhandener Kontakt wird zurückgegeben statt doppelt angelegt. Liefert id UND address_id; die address_id braucht create_project zwingend.

Projekt auf einen Kunden anlegen. Startet immer auf der ersten Stufe — eine beim Anlegen mitgegebene Stufe ignoriert HERO. Projekte sind bei HERO NICHT löschbar.

Angebot über den Document-Builder anlegen. Der Empfänger wird frisch aus HERO gelesen. ⚠ Ein veröffentlichtes Angebot verschiebt das Projekt automatisch auf die Stufe 'Angebot verschickt'. Höchstens EIN Titel: ab zwei Titeln zeigt HEROs PDF je Titel 0,00 €.

Rechnung mit exakt den Positionen des Angebots — centgenau, inklusive Referenz auf das Angebot. Positionen werden aus dem veröffentlichten Angebotsentwurf übernommen, nicht neu getippt.

Beliebiges Dokument anlegen: rechnung, angebot, gutschrift, auftragsbestaetigung, lieferschein, allgemein, rechnung_13b — oder jeder Dokumenttyp-Name dieses Mandanten. Abschlags- und Schlussrechnungen sind 'rechnung' mit passenden (auch negativen) Positionen.

Stundenzettel als PDF aus den bereits erfassten Zeiten eines Projekts. Baut ein Dokument vom Typ 'allgemein' mit je einer Position pro Zeiteintrag (Menge = Stunden). date_from/date_to als 'YYYY-MM-DD'.

Field-Service-Auftrag (Wartung, Reparatur, Notdienst) anlegen. job_type ist eine geschlossene Liste — HERO speichert jeden anderen Wert still als 'unknown', deshalb wird hier vorher geprüft. start/end als ISO MIT Offset. Aufträge sind nicht löschbar.

Checkliste an einen Auftrag ODER ein Projekt hängen (genau eins von beiden). Die Punkte sind die Struktur — abgehakt wird in der Mobile-App, nicht über die API. Eine falsche Form leert HERO beim Anlegen still, deshalb wird das Ergebnis zurückgelesen und geprüft.

Artikel in den Stamm aufnehmen. Setzt sales_prices UND default_sales_price — ohne die kalkuliert HERO jedes Angebot mit dem EINKAUFSpreis, und Angebote gehen zum Selbstkostenpreis raus. Das ist die teuerste Falle der HERO-API und hier eingebaut.

Termin am Projekt anlegen. start/end als ISO MIT Offset — ohne Offset antwortet HERO mit einem Serverfehler. category ist der Name einer Terminkategorie dieses Mandanten.

Aufgabe an ein Projekt hängen. HERO hat kein create_task — update_task ohne id legt an (Upsert). due als ISO mit Offset.

Arbeitszeit auf ein Projekt buchen. Wie bei Aufgaben legt update_ ohne id an. start/end als ISO MIT Offset. Die Dauer rechnet HERO selbst (duration_in_seconds).

Logbucheintrag / Kommentar am Projekt. Erscheint als 'Kommentar von <Nutzer>'.

Zahlung auf eine Rechnung erfassen und anschließend zurücklesen, damit klar ist, ob sie wirklich verbucht wurde. date als 'YYYY-MM-DD'.

Externen Lead über die Lead API einliefern. Erzeugt Kunde UND Projekt. ⚠ Nicht idempotent: der Kunde wird dedupliziert, das Projekt NICHT — zweimal aufrufen heißt zwei Projekte, und Projekte sind bei HERO nicht löschbar.

Datei nach HERO hochladen und optional an ein Projekt hängen. Inhalt entweder als url (wird geladen) oder als content_base64. Liefert die file_upload_uuid, die alle Datei-Konsumenten von HERO brauchen. ⚠ HERO kennt nur einen Upload-Weg (die Lead API), der dabei zwangsläufig ein Eingangs-Projekt anlegt; dieses Projekt ist nicht löschbar.

Ein fremdes PDF als eigenständiges Dokument an ein Projekt hängen (nicht über den Document-Builder erzeugt, sondern hochgeladen). Inhalt als url oder content_base64.