Publieke API v1

De publieke REST API is bedoeld voor server-naar-serverkoppelingen met bijvoorbeeld CRM- of facturatiesoftware.

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

Gebruik niet rechtstreeks de Directus API en plaats een API-sleutel nooit in frontend-JavaScript.

API-sleutel maken

Open als Admin Beheer → API-sleutels. Geef de sleutel een herkenbare naam en kies scopes:

• read: markeert een sleutel die voor lezen bedoeld is;
• write: schrijfbare resources aanmaken of wijzigen en planningsendpoints gebruiken.
• plan: een planningsvoorstel aanvragen.

Selecteer voor een normale lees/schrijfkoppeling beide scopes. Let op: de huidige v1-backend controleert write expliciet voor POST/PATCH, maar laat GET toe voor iedere geldige actieve sleutel; read is momenteel dus een administratieve aanduiding en nog geen afzonderlijke technische blokkade. De ruwe sleutel begint met msk_, wordt één keer getoond en kan niet worden hersteld. Maak bij verlies een nieuwe sleutel en deactiveer of verwijder de oude.

Authenticatie

Gebruik één van deze headers:

Authorization: Bearer msk_...

X-API-Key: msk_...

Alle resultaten worden server-side beperkt tot de organisatie van de sleutel. Een id van een andere tenant geeft dezelfde 404 als een onbekend id.

Resources en methoden

Er is in v1 geen DELETE-endpoint.

Lijsten en paginering

GET /clients?limit=50&page=1

• limit: 1 tot 100, standaard 50;
• page: begint bij 1.
• search: voor klanten- en materiaallijsten, hoofdletterongevoelig gedeeltelijk zoeken naar letterlijke tekst. Een procentteken zoekt naar een procentteken. Klanten komen overeen op naam, e-mail of klantnummer; materiaal op SKU of naam.

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

Een detail- of schrijfantwoord gebruikt { "data": { ... } }.

Klanten

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

POST /clients vereist name. Toegestane schrijfvelden zijn name, customer_number, client_type, email, phone, vat_number en status. Bij PATCH zijn ze allemaal optioneel, maar er moet minstens één geldig veld aanwezig zijn. Onbekende velden en een aangeleverd tenant_id worden genegeerd.

POST /addresses maakt een adres voor een klant aan en vereist client_id. De klant moet tot dezelfde tenant behoren.

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"}'

Opdrachten

Leesvelden omvatten id, tenant, opdrachtnummer, klant-id, titel, omschrijving, prioriteit, status, verwachte duur, hoofdtechnieker-id, vereist aantal techniekers, planning, serviceadres-id, taaktype-id, vereiste vaardigheden en timestamps. Interne en techniekernotities worden niet blootgesteld.

POST /jobs vereist title. Toegestane velden:

job_number, client_id, title, description, priority, estimated_duration_minutes, required_technicians, service_address_id, task_type_id, required_skills.

Nieuwe opdrachten komen altijd in de wachtrij unplanned. Wanneer job_number ontbreekt, genereert Manisma een nummer met de ingestelde tenantprefix. Gebruik /jobs/:id/assign om een opdracht te plannen. PATCH kan job_number, status en assigned_technician_id niet wijzigen; planningsvelden mogen alleen een reeds toegewezen opdracht hertimen en moeten samen één volledig, geldig tijdvenster met Brusselse datum vormen.

Foreign keys voor klant, serviceadres en taaktype moeten tot dezelfde tenant behoren.

POST /jobs/:id/assign plant een opdracht met technician_id, scheduled_start en scheduled_end. POST /jobs/:id/unassign verwijdert de toewijzing en zet de opdracht terug in de ongeplande wachtrij; de opdracht wordt niet verwijderd.

Planningsvoorstel

POST /plan geeft een planningsvoorstel terug en wijzigt niets: het maakt geen opdracht aan en verplaatst er geen. Het vereist de afzonderlijke scope plan en is beperkt tot 3 oproepen per organisatie per 10 minuten; verdere oproepen geven een duidelijke 429-fout. Het gebruikt geen AI van Manisma en verbruikt geen AI-acties uit je Manisma-abonnement, omdat je aanroepende assistent het denkwerk doet.

Andere resources

• assets: bij een klant geïnstalleerde apparaten; schrijfbaar met POST en PATCH.

• task_types: schrijfbaar met POST en PATCH.

• materials: schrijfbaar met POST en PATCH; aankoopprijs en voorraad zijn leesbaar en schrijfbaar.

• asset_models: alleen-lezen.

• technicians: naam, e-mail, telefoon, actiefstatus en vaardigheden. Werkuren, adressen en gebruikers-id zijn niet publiek.

Fouten en limieten

De API is begrensd op 600 verzoeken per minuut per bron-IP. Bouw retries met exponentiële backoff voor 429, 502 en tijdelijke netwerkfouten. Retry geen validatiefouten zonder het verzoek te corrigeren.