MASCHINENCIRCLEGeprüfte Maschinen
LoginKostenlos registrieren

Service API · Version 1.2.0

Vollständige
API-Dokumentation.

Maschinen, Kunden, Vertrieb, Dokumente, Kommunikation, Rechnungen und Statistiken sicher über eine versionierte Schnittstelle steuern.

OpenAPI 3.1 JSON55 Operationen

1. API-Schlüssel erstellen

Als Administrator unter Dashboard → Einstellungen → API-Schlüssel. Der vollständige Schlüssel wird nur einmal angezeigt.

AUTH

2. Authentifizieren

Bevorzugt per Authorization: Bearer …. Alternativ wird X-API-Key unterstützt.

POST

3. Sicher schreiben

Jede Mutation benötigt einen eindeutigen Idempotency-Key. Wiederholungen liefern dieselbe Antwort.

Schnellstart

Erste Anfrage

curl --request GET \ --url 'https://maschinencircle.net/api/v1/machines?status=active&limit=25' \ --header 'Authorization: Bearer msp_live_IHR_API_SCHLUESSEL' \ --header 'Accept: application/json'

Referenz

Alle Endpunkte

55 Treffer
GET/analytics/customersKunden- und Produktinteressen auflisten

Benötigter Scope: `analytics:pii:read`. Dieser Sensitive-Scope wird weder von analytics:* noch analytics:read impliziert. Aufrufe werden ohne IP, Referrer, User-Agent oder Fingerprint in 30-Minuten-Buckets erfasst.

Operation-ID: listCustomerAnalytics

Parameter

FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.
Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/analytics/customers/{id}Kundeninteressen und betrachtete Produkte abrufen

Benötigter Scope: `analytics:pii:read`. Zeigt je Maschine aggregierte Aufrufe und den letzten Aufruf im Zeitraum.

Operation-ID: getCustomerAnalytics

Parameter

idpathPflicht
Kunden-ID. Better Auth verwendet hierfür eine nichtleere String-ID.
FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/analytics/machinesProdukt-Funnel auflisten

Benötigter Scope: `analytics:read`.

Operation-ID: listMachineAnalytics

Parameter

FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.
Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/analytics/machines/{id}Produktstatistik abrufen

Benötigter Scope: `analytics:read`.

Operation-ID: getMachineAnalytics

Parameter

idpathPflicht
UUID der Ressource.
FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/analytics/overviewGesamtkennzahlen und Zeitreihe abrufen

Benötigter Scope: `analytics:read`. Standardzeitraum 30 Tage, maximal 366 Tage. Umsätze schließen stornierte Rechnungen aus.

Operation-ID: getAnalyticsOverview

Parameter

FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/analytics/sellersVerkäuferstatistiken auflisten

Benötigter Scope: `analytics:read`.

Operation-ID: listSellerAnalytics

Parameter

FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.
Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/analytics/sellers/{id}Verkäuferstatistik abrufen

Benötigter Scope: `analytics:read`.

Operation-ID: getSellerAnalytics

Parameter

idpathPflicht
Mitarbeiter-ID.
FromDatesiehe Schema
Siehe OpenAPI-Schema.
ToDatesiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/contractsVerträge auflisten

Benötigter Scope: `contracts:read`.

Operation-ID: listContracts

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.
customerIdquery
Siehe OpenAPI-Schema.
machineIdquery
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/contracts/{id}Signierten Vertrag abrufen

Benötigter Scope: `contracts:read`. Enthält unveränderliche Verkäufer-/Käufer-/Maschinensnapshots ohne Bankdaten.

Operation-ID: getContract

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/contracts/{id}/documentSigniertes Vertrags-PDF herunterladen

Benötigter Scope: `contracts:read`. Der Server lädt das private Objekt, begrenzt die Größe und verifiziert SHA-256 vor jeder Ausgabe.

Operation-ID: downloadContractDocument

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/customersKunden auflisten

Benötigter Scope: `customers:read`.

Operation-ID: listCustomers

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.
kindquery
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/customers/{id}Kundenakte abrufen

Benötigter Scope: `customers:read`. Enthält Profil, Anschriften, zugehörige Vorgänge und aggregierte Angebots-/Rechnungswerte.

Operation-ID: getCustomer

Parameter

idpathPflicht
Kunden-ID. Better Auth verwendet hierfür eine nichtleere String-ID.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

PATCH/customers/{id}Kundenstammdaten, Status und Anschriften ändern

Benötigter Scope: `customers:write`. Nur ein aktiver verantwortlicher Administrator darf Kunden ändern. Sperren widerruft alle Sitzungen; Aktivieren setzt eine bestätigte E-Mail voraus. Die E-Mail-Verifikation kann nicht umgangen werden.

Operation-ID: updateCustomer

Parameter

idpathPflicht
Kunden-ID. Better Auth verwendet hierfür eine nichtleere String-ID.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

CustomerPatch

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/healthApp- und Datenbankstatus

App- und Datenbankstatus

Operation-ID: getHealth

Mögliche HTTP-Statuscodes

200 · 503

GET/inquiriesVertriebsvorgänge auflisten

Benötigter Scope: `inquiries:read`.

Operation-ID: listInquiries

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.
customerIdquery
Siehe OpenAPI-Schema.
machineIdquery
Siehe OpenAPI-Schema.
assignedToUserIdquery
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/inquiries/{id}Vorgangsakte abrufen

Benötigter Scope: `inquiries:read`. Enthält Kunden-/Maschinenkontext, Notizen, Aufgaben, Angebote und den updatedAt-Concurrency-Token.

Operation-ID: getInquiry

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/inquiries/{id}/assignVorgang einem Verkäufer zuweisen oder Zuweisung lösen

Benötigter Scope: `inquiries:write`. Nur ein aktiver verantwortlicher Administrator darf zuweisen. Zulässig sind ausschließlich aktive Verkäufer. Die Verkäuferbenachrichtigung und optional die serverseitig adressierte Kundenbenachrichtigung werden atomar eingereiht.

Operation-ID: assignInquiry

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InquiryAssign

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/inquiries/{id}/messagesNachrichten eines Vorgangs auflisten

Benötigter Scope: `messages:read`.

Operation-ID: listInquiryMessages

Parameter

idpathPflicht
UUID der Ressource.
Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
MessageDirectionsiehe Schema
Siehe OpenAPI-Schema.
MessageStatussiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/inquiries/{id}/messagesSichere E-Mail an den Vorgangskunden einreihen

Benötigter Scope: `messages:write`. Der Empfänger wird ausschließlich serverseitig aus dem Vorgang ermittelt. Freie to/from/replyTo/cc/html-Felder sind nicht zulässig; gewählt wird nur eine mailboxId. Ein verantwortlicher Verkäufer darf ausschließlich zugewiesene Postfächer verwenden. E-Mail-Datensatz, Outbox-Job und Audit werden atomar gespeichert.

Operation-ID: queueInquiryEmail

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InquiryMessageCreate

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/inquiries/{id}/notesInterne Vorgangsnotiz anlegen

Benötigter Scope: `inquiries:write`. Die verantwortliche Person wird serverseitig aus dem API-Schlüssel bestimmt. Verkäufer können ausschließlich ihnen zugewiesene Vorgänge bearbeiten.

Operation-ID: createInquiryNote

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InquiryNoteCreate

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/inquiries/{id}/offersAngebot erstellen, versionieren oder senden

Benötigter Scope: `offers:write`. Erhält sämtliche Status-, Eigentümer-, Steuer-, Preis- und Concurrency-Prüfungen des Admin-Workflows. Bei send=true wird nur die im Vorgang gespeicherte Kundenadresse verwendet und ein Outbox-Job atomar angelegt.

Operation-ID: createOrSendOffer

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

OfferCreate

Mögliche HTTP-Statuscodes

200 · 201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/inquiries/{id}/statusCRM-Status eines Vorgangs ändern

Benötigter Scope: `inquiries:write`. Erlaubt nur fachlich zulässige Übergänge nach assigned, contacted, qualified oder lost. Für lost ist ein Grund erforderlich. Verkäufer können ausschließlich ihnen zugewiesene Vorgänge ändern.

Operation-ID: changeInquiryStatus

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InquiryStatusChange

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/inquiries/{id}/tasksVorgangsaufgabe anlegen

Benötigter Scope: `inquiries:write`. Zuweisbar nur an aktive Mitarbeiter. Verkäufer können Aufgaben ausschließlich sich selbst und nur in ihren eigenen Vorgängen zuweisen.

Operation-ID: createInquiryTask

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InquiryTaskCreate

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

PATCH/inquiries/{id}/tasks/{taskId}Aufgabe abschließen oder wieder öffnen

Benötigter Scope: `inquiries:write`. Verwendet den Concurrency-Token der Aufgabe. Bei Neuzuweisung stornierte Aufgaben können nicht wieder geöffnet werden.

Operation-ID: updateInquiryTask

Parameter

idpathPflicht
UUID der Ressource.
taskIdpathPflicht
UUID der Vorgangsaufgabe.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InquiryTaskPatch

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/invoicesRechnungen auflisten

Benötigter Scope: `invoices:read`.

Operation-ID: listInvoices

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/invoicesRechnung aus signiertem Vertrag ausstellen und senden

Benötigter Scope: `invoices:write`. Prüft den erwarteten Vertrags-Hash, vergibt die Eigentümer-/Jahres-Sequenz atomar, erzeugt PDF und EN-16931/XRechnung-XML und reiht die Zustellung an die im Vertrag festgeschriebene Kundenadresse ein.

Operation-ID: issueInvoice

Parameter

Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

InvoiceIssue

Mögliche HTTP-Statuscodes

200 · 201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/invoices/{id}Rechnung abrufen

Benötigter Scope: `invoices:read`. Interne Storage-, Idempotency-, Mutation- und Storno-Hashes werden nicht ausgegeben.

Operation-ID: getInvoice

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/invoices/{id}/cancelRechnung stornieren

Benötigter Scope: `invoices:write`. Nur für API-Schlüssel mit aktivem, verantwortlichem Administrator. Rechnungen werden niemals gelöscht; Grund und Audit bleiben erhalten.

Operation-ID: cancelInvoice

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

VoidMutation

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/invoices/{id}/documents/{format}Rechnungs-PDF oder strukturierte XML herunterladen

Benötigter Scope: `invoices:read`. Der Server lädt das private Objekt, begrenzt die Größe und verifiziert SHA-256 vor jeder Ausgabe.

Operation-ID: downloadInvoiceDocument

Parameter

idpathPflicht
UUID der Ressource.
formatpathPflicht
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/invoices/{id}/paymentsZahlungen einer Rechnung auflisten

Benötigter Scope: `payments:read`.

Operation-ID: listInvoicePayments

Parameter

idpathPflicht
UUID der Ressource.
Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/invoices/{id}/paymentsZahlung verbuchen

Benötigter Scope: `payments:write`. Optimistic Concurrency über expectedRowVersion; Überzahlung und Buchung auf stornierte Rechnungen werden abgelehnt.

Operation-ID: recordInvoicePayment

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

PaymentCreate

Mögliche HTTP-Statuscodes

200 · 201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/invoices/{id}/payments/{paymentId}/voidZahlungsbuchung stornieren

Benötigter Scope: `payments:write`. Nur für API-Schlüssel mit aktivem, verantwortlichem Administrator. Die ursprüngliche Buchung bleibt unveränderlich erhalten.

Operation-ID: voidInvoicePayment

Parameter

idpathPflicht
UUID der Ressource.
paymentIdpathPflicht
UUID der Zahlungsbuchung.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

VoidMutation

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/machinesMaschinen auflisten

Benötigter Scope: `machines:read`.

Operation-ID: listMachines

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.
ownerIdquery
Siehe OpenAPI-Schema.
categoryquery
Siehe OpenAPI-Schema.
manufacturerquery
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/machinesMaschine als Entwurf anlegen

Benötigter Scope: `machines:write`. Die Fachänderung, der Audit-Eintrag und das Idempotency-Ergebnis werden atomar gespeichert.

Operation-ID: createMachine

Parameter

Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MachineCreate

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/machines/{id}Maschine mit Medien abrufen

Benötigter Scope: `machines:read`.

Operation-ID: getMachine

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

PATCH/machines/{id}Nicht verkaufte Maschine ändern

Benötigter Scope: `machines:write`. Die Fachänderung, der Audit-Eintrag und das Idempotency-Ergebnis werden atomar gespeichert.

Operation-ID: updateMachine

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MachinePatch

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/machines/{id}/archiveMaschine archivieren

Benötigter Scope: `machines:write`. Die Fachänderung, der Audit-Eintrag und das Idempotency-Ergebnis werden atomar gespeichert.

Operation-ID: archiveMachine

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MachineArchive

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

PATCH/machines/{id}/mediaMedien sortieren, beschreiben und Titelbild festlegen

Benötigter Scope: `media:write`. Ersetzt die vollständige Medienreihenfolge mit Optimistic Concurrency. Jedes Medium muss genau einmal vorkommen und das Titelbild Teil der Liste sein.

Operation-ID: organizeMachineMedia

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MachineMediaOrganize

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/machines/{id}/media-uploadZeitlich begrenzten Direkt-Upload anlegen

Benötigter Scope: `media:write`. Die signierte PUT-URL zeigt nur auf einen privaten, temporären create-only Schlüssel und ist kryptografisch an die angekündigte Größe sowie SHA-256-Prüfsumme gebunden. JSON bleibt auf 1 MiB begrenzt; die Datei selbst wird direkt zum Objektspeicher geladen. Weil die Signatur 15 Minuten gilt, ist diese Operation abweichend nur 10 Minuten idempotent replaybar.

Operation-ID: createMachineMediaUpload

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MediaUpload

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

DELETE/machines/{id}/media/{mediaId}Medienreferenz kontrolliert entfernen

Benötigter Scope: `media:write`. Entfernt im Request nur die Datenbankreferenz. Eine getrennte überwachte Löschqueue bereinigt das private Objekt nach 24 Stunden Schonfrist. Das letzte geprüfte, für Kunden sichtbare Bild aktiver Maschinen kann nicht entfernt werden; ein neues Titelbild wird automatisch bestimmt.

Operation-ID: deleteMachineMedia

Parameter

idpathPflicht
UUID der Ressource.
mediaIdpathPflicht
UUID des Medienobjekts.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MachineMediaDelete

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/machines/{id}/media/{mediaId}/completeDirekt-Upload prüfen und abschließen

Benötigter Scope: `media:write`. Prüft tatsächliche Größe und Dateisignatur, decodiert Bilder, entfernt Metadaten, berechnet SHA-256 und schreibt create-only unter einen content-addressierten finalen Schlüssel. Der zurückgegebene concurrencyToken ist für die nächste Medienänderung zu verwenden.

Operation-ID: completeMachineMediaUpload

Parameter

idpathPflicht
UUID der Ressource.
mediaIdpathPflicht
UUID des Medienobjekts.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MediaUploadComplete

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/machines/{id}/publishGeprüften Entwurf veröffentlichen

Benötigter Scope: `machines:write`. Prüfdatum, Gutachter, bestandene Prüfung und mindestens ein serverseitig verifiziertes, für Kunden sichtbares Bild sind Pflicht.

Operation-ID: publishMachine

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/machines/{id}/statusEntwurfs- oder Aktivstatus ändern

Benötigter Scope: `machines:write`. Der Status sold ist absichtlich ausgeschlossen und wird ausschließlich durch den atomaren Vertragsabschluss gesetzt.

Operation-ID: changeMachineStatus

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MachineStatusChange

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/mailboxesPostfächer und Teamzuordnungen auflisten

Benötigter Scope: `mailboxes:read`.

Operation-ID: listMailboxes

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/mailboxesPostfach anlegen

Benötigter Scope: `mailboxes:write`. Nur API-Schlüssel eines aktiven verantwortlichen Administrators. Absenderdomains müssen zusätzlich beim Provider verifiziert sein.

Operation-ID: createMailbox

Parameter

Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MailboxCreate

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

PATCH/mailboxes/{id}Postfach, Status und Teamzugriffe ändern

Benötigter Scope: `mailboxes:write`. Deaktivierte Postfächer können nicht mehr als Absender verwendet werden. Es wird niemals hart gelöscht.

Operation-ID: updateMailbox

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

MailboxPatch

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/messagesGlobale Kommunikationshistorie auflisten

Benötigter Scope: `messages:read`.

Operation-ID: listMessages

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.
mailboxIdquery
Siehe OpenAPI-Schema.
inquiryIdquery
Siehe OpenAPI-Schema.
customerIdquery
Siehe OpenAPI-Schema.
MessageDirectionsiehe Schema
Siehe OpenAPI-Schema.
MessageStatussiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/offersAngebote auflisten

Benötigter Scope: `offers:read`.

Operation-ID: listOffers

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/offers/{id}Angebot mit Versionen abrufen

Benötigter Scope: `offers:read`. Private Storage-Keys und Eigentümer-Bankdaten werden nicht ausgegeben.

Operation-ID: getOffer

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/offers/{id}/documentAngebots-PDF herunterladen

Benötigter Scope: `offers:read`. Der Server lädt das private Objekt, begrenzt die Größe und verifiziert SHA-256 vor jeder Ausgabe.

Operation-ID: downloadOfferDocument

Parameter

idpathPflicht
UUID der Ressource.
versionquery
Optionale Angebotsversion; Standard ist die aktuelle.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/openapiOpenAPI-3.1-Vertrag abrufen

Öffentliches, cachebares JSON-Dokument. Es enthält keine Secrets oder Laufzeitkonfiguration.

Operation-ID: getOpenApiDocument

Mögliche HTTP-Statuscodes

200

GET/ownersEigentümer auflisten

Benötigter Scope: `owners:read`. Ohne owners:sensitive:read bleiben PII, Anschrift, Steuer- und Bankdaten ausgeblendet. Eine E-Mail-Suche ist nur mit diesem zusätzlichen Scope erlaubt.

Operation-ID: listOwners

Parameter

Pagesiehe Schema
Siehe OpenAPI-Schema.
Limitsiehe Schema
Siehe OpenAPI-Schema.
kindquery
Siehe OpenAPI-Schema.
statusquery
Siehe OpenAPI-Schema.
Searchsiehe Schema
Siehe OpenAPI-Schema.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

POST/ownersEigentümer anlegen

Benötigter Scope: `owners:write`. Die Mutationsantwort ist bewusst PII-arm. Sensitivdaten können anschließend nur mit owners:read und owners:sensitive:read gelesen werden.

Operation-ID: createOwner

Parameter

Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

OwnerCreate

Mögliche HTTP-Statuscodes

201 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

GET/owners/{id}Eigentümer abrufen

Benötigter Scope: `owners:read`. Sensitive Felder werden nur ausgegeben, wenn derselbe Schlüssel zusätzlich owners:sensitive:read besitzt.

Operation-ID: getOwner

Parameter

idpathPflicht
UUID der Ressource.

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503

PATCH/owners/{id}Eigentümer ändern

Benötigter Scope: `owners:write`. Die Fachänderung, der Audit-Eintrag und das Idempotency-Ergebnis werden atomar gespeichert.

Operation-ID: updateOwner

Parameter

idpathPflicht
UUID der Ressource.
Idempotency-KeyheaderPflicht
Je API-Schlüssel eindeutiger Mutationsschlüssel. Identische Wiederholungen liefern bis zu 24 Stunden die verschlüsselt gespeicherte Originalantwort; abweichende Wiederverwendung ergibt 409.

Request-Body

OwnerPatch

Mögliche HTTP-Statuscodes

200 · 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 500 · 503