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, status, estimated_duration_minutes, required_technicians, scheduled_date, scheduled_start, scheduled_end, service_address_id, task_type_id, required_skills.

Wanneer status ontbreekt, wordt unplanned gebruikt. Wanneer job_number ontbreekt, genereert Manisma een nummer met de ingestelde tenantprefix. Bij PATCH zijn job_number, status en assigned_technician_id niet wijzigbaar.

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.