Mutații GraphQL (scriere)

Începând cu planul Business, endpointul GraphQL oferă 12 mutații de scriere: creare, actualizare și ștergere pentru comenzi de lucru, active și piese, plus adjustStock pentru mișcările de stoc. Mutațiile trec prin aceleași servicii folosite de aplicația însăși, așa că jurnalul de audit, notificările și generarea automată a referințelor (WO-XX, ASS-XX, PART-XX) se comportă identic. A unsprezecea, addMeterReading, înregistrează citiri de contor (ore de funcționare, contoare de piese) — vezi mai jos. A douăsprezecea, setPurchaseOrderErpReference, scrie pe o comandă de achiziție numărul de document din ERP-ul dvs. (doar cu o cheie cu acces FULL) și nu declanșează niciun webhook, astfel că ERP-ul dvs. nu își primește niciodată înapoi propria scriere.

Mutații disponibile

• createWorkOrder(input) → WorkOrder
• updateWorkOrder(id, input) → WorkOrder
• deleteWorkOrder(id) → DeleteResult
• createAsset(input) → Asset
• updateAsset(id, input) → Asset
• deleteAsset(id, force?) → DeleteResult
• createPart(input) → Part
• updatePart(id, input) → Part
• deletePart(id, force?) → DeleteResult
• adjustStock(id, quantity, reason?, vendorId?, documentNumber?) → Part
• addMeterReading(meterId, value?, incrementValue?, date?, notes?, confirmRegression?) → MeterReading
• setPurchaseOrderErpReference(id, erpReference?) → PurchaseOrder

Forma de intrare

Fiecare mutație are un InputType cu numai câmpuri sigure - companyId, sequenceNumber, reference și createdById sunt completate pe partea serverului. Transmiteți doar titlu, descriere, stare, prioritate, assetId, locationId etc. Inputurile de piesă acceptă și barcode, maxStockLevel, locationId și vendorId, iar quantity/minQuantity/maxStockLevel acceptă zecimale (ex. 0.5). Câmpurile enumerate sunt verificate: priority trebuie să fie LOW, MEDIUM, HIGH, CRITICAL; status-ul unei comenzi de lucru OPEN, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, VALIDATED, CANCELLED, CLOSED; status-ul unui activ OPERATIONAL, DEGRADED, DOWN, MAINTENANCE, STANDBY, RETIRED. Orice altă valoare este respinsă cu BAD_REQUEST. Intrările pentru piese acceptă și customReference — codul dumneavoastră pentru piesă (de exemplu cel din ERP), cu care part(barcode:) se potrivește apoi. Unicitatea nu este impusă: rămâne în sarcina dumneavoastră.

Exemplu: creați o comandă de lucru

Crearea unei comenzi de lucru: mutation($i: WorkOrderCreateInput!) { createWorkOrder(input: $i) { id title reference status createdAt } } cu variabilele {"i": {"title": "Pump #3 leak", "priority": "HIGH"}}

Ajustarea stocului

Pentru a modifica cantitatea unei piese, folosiți adjustStock cu o diferență cu semn — negativă pentru consum, pozitivă pentru recepție. Mutația actualizează cantitatea și scrie un rând de audit StockMovement într-o singură tranzacție atomică și nu lasă niciodată stocul să scadă sub zero. Pentru o piesă al cărei stoc este urmărit pe locație, transmiteți locationId: mișcarea se aplică acelei locații, iar fără el apelul este refuzat: errors[0].extensions.code este BAD_REQUEST, iar extensions.reason este LOCATION_STOCK_REQUIRES_LOCATION. updatePart(quantity) setează în schimb o valoare absolută: este refuzată pe o piesă urmărită pe locație din același motiv, iar în rest înregistrează diferența ca mișcare ADJUSTMENT. Puteți consemna și proveniența mărfii: vendorId și documentNumber (numărul facturii sau al avizului de însoțire al furnizorului, maximum 64 de caractere) se salvează pe mișcarea însăși, astfel încât istoricul arată cine a livrat-o și în baza cărui document. Ambele sunt opționale — un consum obișnuit nu trimite niciunul. Furnizorul trebuie să aparțină companiei dvs.

Înregistrarea citirilor de contor

addMeterReading înregistrează o citire pe un contor — ore de funcționare, contor de piese, odometru, indicator — pentru ca un sistem extern (SCADA, gateway PLC, ERP) să alimenteze mentenanța preventivă pe contor fără ca cineva să mai tasteze cifra. Aflați mai întâi id-ul contorului: query { meters(assetId: 7) { id reference name unit type lastReadingValue lastReadingDate } } Apoi trimiteți FIE value (totalul absolut afișat de contor), FIE incrementValue (de exemplu orele de funcționare de la ultima citire, pe care serverul le adaugă la citirea anterioară) — exact unul dintre ele: mutation { addMeterReading(meterId: 12, value: 1250.5, date: "2026-09-25T06:00:00Z") { id value date isAnomaly } } date este opțională (ISO 8601, implicit acum) și poate fi în trecut, niciodată în viitor. La contoarele RUNTIME și COUNTER, o valoare mai mică decât citirea anterioară este refuzată cu BAD_REQUEST — după o resetare sau o înlocuire a contorului, retrimiteți-o cu confirmRegression: true. Citirea trece prin același serviciu ca ecranul de contoare din aplicație: dacă este cea mai recentă, declanșatoarele și mentenanța preventivă pe contor pornesc exact ca pentru o citire introdusă de un tehnician. Această mutație necesită o cheie cu acces FULL.

Atribuire

Fiecare mutație rulează ca proprietarul cheii — persoana în numele căreia acționează cheia — cu permisiunile sale, vizibilitatea sa asupra datelor și numele său în jurnalul de audit. O cheie nu aprobă niciodată un pas al fluxului de lucru, chiar dacă proprietarul ei ar putea.

Reîncercare în siguranță (Idempotency-Key)

O expirare a timpului de rețea nu vă spune dacă o mutație a fost executată. Trimiteți un antet Idempotency-Key (între 8 și 64 de litere, cifre sau cratime — merge un UUID) la fiecare cerere care scrie și trimiteți ACEEAȘI cheie când o reîncercați. Timp de 7 zile, o reîncercare cu aceeași cheie returnează rezultatul salvat al primului apel (răspunsul conține "Idempotent-Replayed: true") în loc să execute din nou mutația: nicio a doua comandă de lucru, nicio mișcare de stoc dublată.

• O cheie pentru fiecare scriere. Într-o cerere cu mai multe mutații cu alias, fiecare mutație este înregistrată separat sub acea cheie. Valorile trimise nu sunt comparate: aceeași cheie cu alte valori returnează rezultatul primului apel.
• Un apel eșuat nu păstrează nimic: reîncercarea lui cu aceeași cheie îl execută din nou.
• IDEMPOTENCY_KEY_REUSED — sub această cheie, același nume (câmp sau alias) a executat deja o altă mutație sau un alt apelant a folosit cheia: folosiți o cheie nouă pentru o scriere nouă.
• IDEMPOTENCY_IN_PROGRESS — primul apel este încă în curs: așteptați câteva secunde și reîncercați.

Erori comune

• GRAPHQL_VALIDATION_FAILED — forma datelor de intrare nu se potrivește (de exemplu lipsește un title obligatoriu)
• BAD_REQUEST — validarea unei valori a eșuat (de exemplu un title de peste 500 de caractere)
• FORBIDDEN — planul tău este sub Business
• NOT_FOUND — id-ul nu există sau aparține altei companii
• FORBIDDEN — nivelul de acces al cheii este insuficient (de exemplu o cheie READ care apelează o mutation)