Integratie-API

Met de CUTL Integratie-API kunt u onderdelen programmatisch prijzen: stuur een DXF- of STEP-bestand vanuit uw eigen software en lees de geometrie en een volledige prijs terug, berekend door dezelfde engine die de app gebruikt. Het live aanbod is vandaag bewust klein, één geauthenticeerd paar calculatie-endpoints, terwijl een bredere project-API in ontwerp is (zie de vooruitblik aan het eind van deze pagina).

Authenticatie

Elk verzoek bevat uw integratietoken in een header:

X-Auth-Token: <token>

• Elk account heeft één integratietoken. Genereer het in de app op het tabblad Integratie van uw accountinstellingen (dezelfde actie is beschikbaar als PUT /v2/security/user/key).
• Een nieuw token genereren maakt het vorige onmiddellijk ongeldig. Elke integratie die het oude token nog gebruikt, loopt vanaf dat moment vast met 401, dus wissel bewust en werk alle afnemers direct na het opnieuw genereren bij.
• Het token geeft volledige toegang tot het account en verloopt niet van zichzelf.

Afrekenen met coins

Er is geen gratis sandbox: de API werkt tegen productie en elke berekening haalt echte coins van het saldo van uw team, tegen dezelfde tarieven als in de app (ongeveer 100 coins per onderdeelberekening). Is het saldo te laag, dan wordt het verzoek vooraf geweigerd in plaats van uitgevoerd en in rekening gebracht. Plan integratietests met beleid, houd uw saldo in de gaten in het facturatiegedeelte van de app, en zie Coins & facturatie voor tarieven en bijvullen.

Berekening van één DXF- of STEP-bestand

Dit is het live paar endpoints. Stuur één tekening als base64 en vraag het resultaat daarna op via het id. Alleen DXF en STEP worden geaccepteerd (PDF wordt hier geweigerd; upload een PDF-tekening in de app, die de snijcontouren interactief extraheert). Prijzen worden alleen teruggegeven wanneer zowel materialId als cuttingModeId zijn meegegeven; geometrie wordt altijd teruggegeven.

# Versturen, geeft 202 terug
DXF_B64=$(base64 -i part.dxf | tr -d '\n')
curl -sS -X POST "$BASE/v2/integration/calculations" \
  -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -d "{\"fileName\":\"part.dxf\",\"fileBase64\":\"$DXF_B64\",\"materialId\":\"7e1...\",\"cuttingModeId\":\"4a8...\",\"count\":1}"
# → 202 { "id": "<calcId>", "status": "PENDING", "created": "..." }

# Opvragen, geeft 200 terug
curl -sS "$BASE/v2/integration/calculations/<calcId>" -H "X-Auth-Token: $TOKEN"
# → { "id": "...", "status": "PENDING|COMPLETED|FAILED",
#     "result": { "fileType", "sizeXMm", "sizeYMm", "areaSqM", "cutLengthMm", "contourCount",
#                 "weightKg", "volumeM3", "svgUrl", "thumbnailUrl", "contours": [],
#                 "materialPrice", "cuttingPrice", "incuttingPrice", "markupPercent",
#                 "singlePrice", "totalPrice", "clientSinglePrice", "clientTotalPrice" },
#     "failureReason": "..." }
# incuttingPrice zijn de doorsteekkosten; fileType geeft DXF of STEP aan

Zodra status op COMPLETED staat, zijn de geometrievelden gevuld; de prijs- en gewichtsvelden verschijnen alleen wanneer een materiaal en een snijmodus zijn meegegeven. Een mislukte verwerking meldt FAILED met een failureReason; een ontbrekend of verouderd token geeft 401.

Het veld fileBase64 accepteert zowel een DXF- als een STEP-payload: CUTL bepaalt het formaat aan de hand van de bestandsinhoud.

Vooruitblik: de volledige project-API

De geplande project-API volgt de projectschermen in de app:

• Projecten, onderdelen, snelle berekeningen en nesten als REST-resources onder een geversioneerd basispad, met tekeningen die als base64 (DXF of STEP) worden geüpload en resultaten met dezelfde cijfers die de panelen in de app tonen (prijzen exclusief marge en klantprijzen, snijtijden, geometrie, coëfficiënten).
• CRUD op woordenboeken voor materialen, apparatuur, snijmodi en klanten, zodat integraties referentiedata kunnen beheren in plaats van die te dupliceren.
• Asynchroon overal waar rekenwerk plaatsvindt: het versturen van een onderdeel of een nestingtaak geeft 202 terug met een taak-id, en resultaten komen binnen via een webhook (HMAC-ondertekend, minstens één keer afgeleverd, met herhaalpogingen) of door op te vragen.
• Conventies op de roadmap: RFC 7807-fouten in problem+json, idempotency-keys op muterende calls, paginering op lijst-endpoints, rate limits per token en een expliciet uitfaseringsbeleid voor hoofdversies.
• Beheer van meerdere tokens (overzicht, intrekken, audit per token) ter vervanging van het huidige enkele token dat opnieuw wordt gegenereerd.

Bekijk vervolgens Coins & facturatie om te begrijpen wat elke berekening kost en hoe u uw saldo op peil houdt.