Öffentliche API v1

Die öffentliche REST-API ist für Server-zu-Server-Verbindungen mit beispielsweise CRM- oder Abrechnungssoftware gedacht.

Basis-URL: https://auto.manisma.com/api/v1

Verwenden Sie nicht direkt die Directus-API und platzieren Sie einen API-Schlüssel niemals in Frontend-JavaScript.

API-Schlüssel erstellen

Öffnen Sie als Admin Verwaltung → API-Schlüssel. Geben Sie dem Schlüssel einen erkennbaren Namen und wählen Sie Scopes:

• read: kennzeichnet einen für das Lesen vorgesehenen Schlüssel;
• write: schreibbare Ressourcen anlegen oder ändern und Planungsendpunkte verwenden.
• plan: einen Planungsvorschlag anfordern.

Wählen Sie für eine normale Lese-/Schreibverbindung beide Scopes. Hinweis: Das aktuelle v1-Backend prüft write explizit für POST/PATCH, lässt jedoch GET für jeden gültigen aktiven Schlüssel zu; read ist derzeit also eine administrative Kennzeichnung und noch keine eigene technische Sperre. Der Rohe Schlüssel beginnt mit msk_, wird einmalig angezeigt und kann nicht wiederhergestellt werden. Erstellen Sie bei Verlust einen neuen Schlüssel und deaktivieren oder entfernen Sie den alten.

Authentifizierung

Verwenden Sie einen dieser Header:

Authorization: Bearer msk_...

X-API-Key: msk_...

Alle Ergebnisse werden serverseitig auf die Organisation des Schlüssels beschränkt. Eine ID eines anderen Mandanten liefert dieselbe 404 wie eine unbekannte ID.

Ressourcen und Methoden

Es gibt in v1 keinen DELETE-Endpunkt.

Listen und Paginierung

GET /clients?limit=50&page=1

• limit: 1 bis 100, Standard 50;
• page: beginnt bei 1.
• search: für Kunden- und Materiallisten, Groß- und Kleinschreibung wird nicht beachtet und Teiltexte werden wörtlich abgeglichen. Ein Prozentzeichen sucht nach einem Prozentzeichen. Kunden werden über Name, E-Mail oder Kundennummer gefunden, Materialien über SKU oder Name.

{
  "data": [],
  "meta": { "total": 0, "page": 1, "limit": 50 }
}

Eine Detail- oder Schreibanwort verwendet { "data": { ... } }.

Kunden

Lesefelder: id, tenant_id, customer_number, name, client_type, email, phone, vat_number, status, created_at, updated_at.

POST /clients erfordert name. Zulässige Schreibfelder sind name, customer_number, client_type, email, phone, vat_number und status. Bei PATCH sind sie alle optional, aber es muss mindestens ein gültiges Feld vorhanden sein. Unbekannte Felder und eine mitgelieferte tenant_id werden ignoriert.

POST /addresses legt eine Adresse für einen Kunden an und erfordert client_id. Der Kunde muss zum selben Mandanten gehören.

curl -X POST 'https://auto.manisma.com/api/v1/clients' \
  -H 'Authorization: Bearer msk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Bakkerij Peeters","client_type":"b2b","email":"info@example.com"}'

Aufträge

Lesefelder umfassen ID, Mandant, Auftragsnummer, Kunden-ID, Titel, Beschreibung, Priorität, Status, erwartete Dauer, Haupttechniker-ID, erforderliche Anzahl Techniker, Planung, Serviceadressen-ID, Aufgabentyp-ID, erforderliche Fähigkeiten und Zeitstempel. Interne und Technikernotizen werden nicht offengelegt.

POST /jobs erfordert title. Zulässige Felder:

job_number, client_id, title, description, priority, status, estimated_duration_minutes, required_technicians, scheduled_date, scheduled_start, scheduled_end, service_address_id, task_type_id, required_skills.

Wenn status fehlt, wird unplanned verwendet. Wenn job_number fehlt, generiert Manisma eine Nummer mit dem eingestellten Mandantenpräfix. Bei PATCH sind job_number, status und assigned_technician_id nicht änderbar.

Fremdschlüssel für Kunde, Serviceadresse und Aufgabentyp müssen zum selben Mandanten gehören.

POST /jobs/:id/assign plant einen Auftrag mit technician_id, scheduled_start und scheduled_end. POST /jobs/:id/unassign entfernt seine Zuweisung und stellt ihn zurück in die ungeplante Warteschlange; der Auftrag wird nicht gelöscht.

Planungsvorschlag

POST /plan liefert einen Planungsvorschlag und ändert nichts: Er legt keine Aufträge an und verschiebt keine. Er benötigt den separaten Scope plan und ist auf 3 Aufrufe pro Organisation in 10 Minuten begrenzt; weitere Aufrufe geben einen eindeutigen 429-Fehler zurück. Er verwendet keine KI von Manisma und verbraucht keine in Ihrem Manisma-Tarif enthaltenen KI-Aktionen, weil Ihr aufrufender Assistent das Denken übernimmt.

Weitere Ressourcen

• assets: bei einem Kunden installierte Geräte; mit POST und PATCH schreibbar.

• task_types: mit POST und PATCH schreibbar.

• materials: mit POST und PATCH schreibbar; Einkaufspreis und Bestand sind lesbar und schreibbar.

• asset_models: schreibgeschützt.

• technicians: Name, E-Mail, Telefon, Aktivstatus und Fähigkeiten. Arbeitszeiten, Adressen und Benutzer-ID sind nicht öffentlich.

Fehler und Limits

Die API ist auf 600 Anfragen pro Minute pro Quell-IP begrenzt. Bauen Sie Retries mit exponentiellem Backoff für 429, 502 und vorübergehende Netzwerkfehler ein. Wiederholen Sie Validierungsfehler nicht ohne Korrektur der Anfrage.