Integratie-API

Met de CUTL Integratie-API werkt uw eigen software rechtstreeks met CUTL: stuur een DXF-, STEP- of PDF-tekening in en lees de geometrie en een volledige prijs terug, lees uw projecten met hun geoffreerde prijzen, haal het nestresultaat van een project op met plaatafbeeldingen en DXF-bestanden voor de machine, en controleer uw coinsaldo. Prijzen komen uit dezelfde engine die de app gebruikt. Projecten schrijven, webhooks en meerdere tokens zijn nog in ontwerp (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 of met GET /v2/integration/balance, en zie Coins & facturatie voor tarieven en bijvullen.

Wat live is

Antwoorden komen standaard als JSON; stuur Accept: application/xml mee als uw systeem de voorkeur geeft aan XML.

API-referentie

Alle beschikbare endpoints met hun parameters en het volledige antwoordschema. Klik op Authorize en plak uw integratietoken om de alleen-lezen verzoeken (GET) op uw eigen account uit te proberen. Een berekening indienen laat u aan uw eigen code over, omdat elke berekening coins kost.

De onderstaande secties leggen uit hoe de endpoints zich in de praktijk gedragen.

Eén tekening berekenen

Stuur één tekening als base64 en vraag het resultaat daarna op via het id. CUTL bepaalt het bestandstype aan de hand van de inhoud, niet van de bestandsnaam. DXF- en STEP-bestanden mogen maximaal 2 MB zijn, PDF-tekeningen maximaal 20 MB. Prijzen worden alleen teruggegeven wanneer zowel materialId als cuttingModeId zijn meegegeven; geometrie wordt altijd teruggegeven. Het optionele veld units (bijvoorbeeld MILLIMETERS of INCHES) vertelt CUTL in welke eenheid de tekening werkelijk is, wat een tekening corrigeert waarvan de eenheid verkeerd is herkend.

# 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...\",\"units\":\"MILLIMETERS\"}"

# Opvragen, geeft 200 terug
curl -sS "$BASE/v2/integration/calculations/<calcId>" -H "X-Auth-Token: $TOKEN"

Zodra status op COMPLETED staat, zijn de geometrievelden gevuld; de prijs- en gewichtsvelden verschijnen alleen wanneer een materiaal en een snijmodus zijn meegegeven. validationResult bevat de controles en waarschuwingen van de parser (bijvoorbeeld overlappende of niet-gesloten contouren). Een mislukte verwerking meldt FAILED met een failureReason en een errorCode zoals ERROR_READ_DXF, STEP_ASSEMBLY of INSUFFICIENT_BALANCE; een ontbrekend of verouderd token geeft 401.

PDF-tekeningen

Een PDF wordt niet in één keer geprijsd. CUTL haalt de snijcontouren eruit als kandidaat-onderdelen, en de voltooide opvraging geeft die terug in pdfCandidates. Elke kandidaat heeft een dxfUrl (een DXF met de snijcontour), de page waar hij vandaan komt, een waarde confidence en de herkende scale, waarbij needsScaleConfirm is gezet wanneer de werkelijke maat niet is bevestigd. Meerdere kandidaten kunnen verschillende aanzichten van hetzelfde fysieke onderdeel zijn, dus controleer de kandidaten met een lage betrouwbaarheid. Om een kandidaat te prijzen downloadt u zijn DXF en stuurt u die in als nieuwe berekening met uw materiaal, snijmodus en eenheden.

Uw saldo controleren

curl -sS "$BASE/v2/integration/balance" -H "X-Auth-Token: $TOKEN"

balance is het besteedbare totaal, bonuscoins inbegrepen, en is het getal dat CUTL controleert voordat het werk accepteert. Het kan onder nul zakken, omdat sommige bewerkingen na een controle vooraf per item afrekenen. bonusBalance is het deel van het totaal dat uit bonuscoins bestaat, die als eerste worden besteed. Zakt het saldo door een afschrijving onder lowBalanceThreshold, dan krijgen de beheerders van het team één e-mail; er stopt niets met werken op dat niveau.

Het saldo lezen voordat u een batch instuurt, is de eenvoudige manier om te voorkomen dat werk wordt geweigerd wegens te weinig coins (402 met foutcode C00034).

Projecten lezen

# Projecten oplijsten, nieuwste eerst, standaard 10 per pagina
curl -sS "$BASE/v2/integration/projects?updatedFrom=2026-09-01&page=0&size=20" -H "X-Auth-Token: $TOKEN"

# Eén project volledig
curl -sS "$BASE/v2/integration/projects/<projectId>" -H "X-Auth-Token: $TOKEN"

De lijst accepteert optionele datumfilters (createdFrom, createdTo, updatedFrom, updatedTo) plus page en size. Zonder filters krijgt u de projecten van het team, de laatst bijgewerkte eerst. Een datumvenster mag hoogstens één maand beslaan; een langer venster wordt geweigerd met 400. Elke regel bevat het id, de name en de code van het project, de klant en de organisatie, en de prijzen: price en clientPrice (het totaal dat de klant geoffreerd krijgt, na opslag), met de btw-bedragen ernaast.

Een afzonderlijk project voegt de details achter de offerte toe:

• projectParts: elk onderdeel met zijn count, materiaal, snijmodus, bewerkingen, afmetingen, snijlengte, snijtijd en prijzen (vóór opslag en voor de klant), plus een base64-miniatuur in image.
• materialSummary: één regel per materiaal met het gesneden oppervlak en de totalen.
• nestingSheets: één regel per fysieke geneste plaat, zoals in de offerte doorgerekend (materiaal, plaatformaat, gewicht, kosten en benutting).
• Offertegegevens zoals currency, validUntil, paymentTerm en deliveryCost.

Het nestresultaat van een project ophalen

curl -sS "$BASE/v2/integration/projects/<projectId>/nesting?format=CYPCUT" -H "X-Auth-Token: $TOKEN"

Dit leest het nestresultaat achter de offerte van een project; er wordt geen nieuwe nesting uitgevoerd. Kies de DXF-variant met format: STANDARD_DXF (de standaard), CYPCUT of RDWORKS. De eerste aanroep start de DXF-export en het renderen van de afbeeldingen en antwoordt met PENDING; blijf opvragen tot de status READY is. PARTIAL betekent dat sommige materialen klaar zijn en andere mislukt, en FAILED betekent dat alle materialen zijn mislukt.

Er is één regel in nests per materiaal. Platen met een identieke indeling worden samengevoegd tot één regel met een count, dus twintig identieke platen komen terug als één regel met count 20. partId komt overeen met het id van het onderdeel uit het project-endpoint, zodat u de twee kunt koppelen.

Een bestandslink vernieuwen

Sommige antwoorden bevatten opgeslagen bestands-URL's. Om een nieuwe ondertekende link voor zo'n URL te krijgen, stuurt u die naar POST /v2/integration/data-assets/signed-url met als body {"url": "<stored url>"}. Het antwoord geeft de ondertekende url en het tijdstip expiresAt. U kunt alleen bestanden ondertekenen die bij uw eigen team horen.

Vooruitblik: schrijven, webhooks en meer

Lezen is vandaag al live (zie hierboven). De geplande uitbreidingen gaan over schrijven en automatisering:

• Projecten, onderdelen, snelle berekeningen en nestingtaken aanmaken en wijzigen via de API, met tekeningen die als base64 worden geüpload en resultaten met dezelfde cijfers die de panelen in de app tonen.
• CRUD op woordenboeken voor materialen, apparatuur, snijmodi en klanten, zodat integraties referentiedata kunnen beheren in plaats van die te dupliceren.
• Webhooks: resultaten die naar uw systeem worden gepusht (HMAC-ondertekend, minstens één keer afgeleverd, met herhaalpogingen) in plaats van opvragen.
• Conventies op de roadmap: RFC 7807-fouten in problem+json, idempotency-keys op muterende calls, 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.