GraphQL mutasyonları (yazma)

Business planından itibaren GraphQL uç noktası 12 yazma mutation'ı sunar: İş emirleri, Varlıklar ve Yedek parçalar üzerinde oluşturma, güncelleme ve silme, ayrıca stok hareketleri için adjustStock. Mutation'lar uygulamanın kendi kullandığı servislerden geçer; böylece denetim kaydı, bildirimler ve referans otomatik üretimi (WO-XX, ASS-XX, PART-XX) aynı şekilde çalışır. On birincisi olan addMeterReading, sayaç okumalarını (çalışma saati, adet sayacı) kaydeder — aşağıya bakın. On ikincisi olan setPurchaseOrderErpReference, ERP'nizin belge numarasını bir satın alma siparişine yazar (yalnızca FULL erişimli anahtarla) ve hiçbir webhook tetiklemez; böylece ERP'niz kendi yazdığını asla geri almaz.

Mevcut mutasyonlar

• 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

Giriş şekli

Her mutasyonun yalnızca güvenli alanlara sahip bir InputType'ı vardır; companyId, sequenceNumber, reference ve createdById sunucu tarafında doldurulur. Yalnızca title, description, status, priority, assetId, locationId vb. alanları iletirsiniz. Parça girdileri ayrıca barcode, maxStockLevel, locationId ve vendorId kabul eder; quantity/minQuantity/maxStockLevel ondalık değer alabilir (örn. 0.5). Sabit değerli alanlar doğrulanır: priority şunlardan biri olmalıdır: LOW, MEDIUM, HIGH, CRITICAL; bir iş emrinin status değeri OPEN, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, VALIDATED, CANCELLED, CLOSED; bir varlığın status değeri OPERATIONAL, DEGRADED, DOWN, MAINTENANCE, STANDBY, RETIRED. Başka her değer BAD_REQUEST ile reddedilir. Parça girdileri ayrıca customReference kabul eder — parçaya kendi verdiğiniz kod (örneğin ERP kodunuz); part(barcode:) sonrasında bununla eşleşir. Benzersizliği dayatılmaz: bunu siz güvence altına alırsınız.

Örnek: iş emri oluşturma

Bir iş emri oluşturma: mutation($i: WorkOrderCreateInput!) { createWorkOrder(input: $i) { id title reference status createdAt } } şu değişkenlerle {"i": {"title": "Pump #3 leak", "priority": "HIGH"}}

Stok ayarlama

Bir parçanın miktarını değiştirmek için işaretli bir farkla adjustStock kullanın — tüketmek için negatif, teslim almak için pozitif. Miktarı günceller ve tek bir atomik işlemde bir StockMovement denetim satırı yazar; stoğun asla sıfırın altına düşmesine izin vermez. Stoğu konuma göre izlenen bir parça için locationId verin: hareket o konuma uygulanır; locationId olmadan çağrı reddedilir ve errors[0].extensions.code BAD_REQUEST, extensions.reason ise LOCATION_STOCK_REQUIRES_LOCATION olur. updatePart(quantity) ise mutlak bir değer belirler: konuma göre izlenen bir parçada aynı nedenle reddedilir, diğer durumlarda farkı bir ADJUSTMENT hareketi olarak kaydeder. Malın nereden geldiğini de kaydedebilirsiniz: vendorId ve documentNumber (tedarikçinin fatura veya irsaliye numarası, en fazla 64 karakter) hareketin kendisinde saklanır; böylece geçmiş, malı kimin verdiğini ve hangi belgeyle verdiğini gösterir. İkisi de isteğe bağlıdır — sıradan bir tüketim hiçbirini göndermez. Tedarikçi şirketinize ait olmalıdır.

Sayaç okumalarını kaydetme

addMeterReading bir sayaca okuma kaydeder — çalışma saati, adet sayacı, kilometre sayacı, gösterge — böylece harici bir sistem (SCADA, PLC ağ geçidi, ERP) kimse rakamı elle girmeden sayaç tabanlı önleyici bakımı besler. Önce sayacın id'sini bulun: query { meters(assetId: 7) { id reference name unit type lastReadingValue lastReadingDate } } Ardından YA value (sayacın gösterdiği mutlak toplam) YA DA incrementValue (örneğin son okumadan bu yana çalışılan saatler; sunucu bunu önceki okumaya ekler) gönderin — ikisinden tam olarak biri: mutation { addMeterReading(meterId: 12, value: 1250.5, date: "2026-09-25T06:00:00Z") { id value date isAnomaly } } date isteğe bağlıdır (ISO 8601, varsayılan şimdi) ve geçmişte olabilir, asla gelecekte olamaz. RUNTIME ve COUNTER sayaçlarında önceki okumadan düşük bir değer BAD_REQUEST ile reddedilir; sayaç sıfırlandıktan veya değiştirildikten sonra confirmRegression: true ile yeniden gönderin. Okuma, uygulamadaki sayaç ekranıyla aynı servisten geçer: en son okuma ise sayaç tetikleyicileri ve sayaç tabanlı önleyici bakım, bir teknisyenin girdiği okumadakiyle tamamen aynı şekilde çalışır. Bu mutation FULL erişimli bir anahtar gerektirir.

İlişkilendirme

Her mutasyon, anahtarın sahibi olarak — yani anahtarın adına davrandığı kişi olarak — onun izinleri, onun veri görünürlüğü ve denetim günlüğünde onun adıyla çalışır. Sahibi onaylayabilecek olsa bile bir anahtar hiçbir zaman bir iş akışı adımını onaylamaz.

Güvenle yeniden deneme (Idempotency-Key)

Bir ağ zaman aşımı, mutasyonun çalışıp çalışmadığını söylemez. Yazma yapan her isteğe bir Idempotency-Key başlığı (8 ile 64 arasında harf, rakam veya tire — bir UUID olur) ekleyin ve yeniden denerken AYNI anahtarı gönderin. 7 gün boyunca aynı anahtarla yapılan yeniden deneme, mutasyonu tekrar çalıştırmak yerine ilk çağrının kayıtlı sonucunu döndürür (yanıtta "Idempotent-Replayed: true" bulunur): ikinci bir iş emri yok, iki kez işlenen stok hareketi yok.

• Her yazma için bir anahtar. Takma adlı birden çok mutasyon içeren bir istekte her mutasyon bu anahtar altında ayrı kaydedilir. Gönderilen değerler karşılaştırılmaz: aynı anahtar farklı değerlerle ilk çağrının sonucunu döndürür.
• Başarısız bir çağrı hiçbir şey saklamaz: aynı anahtarla yeniden denemek onu tekrar çalıştırır.
• IDEMPOTENCY_KEY_REUSED — bu anahtarla aynı ad (alan veya takma ad) zaten başka bir mutasyon çalıştırdı ya da anahtarı başka bir çağıran kullandı: yeni bir yazma için yeni bir anahtar kullanın.
• IDEMPOTENCY_IN_PROGRESS — ilk çağrı hâlâ sürüyor: birkaç saniye bekleyip yeniden deneyin.

Yaygın hatalar

• GRAPHQL_VALIDATION_FAILED — girdi yapısı uyuşmuyor (örneğin zorunlu title eksik)
• BAD_REQUEST — değer doğrulaması başarısız (örneğin 500 karakterden uzun bir title)
• FORBIDDEN — planınız Business'ın altında
• NOT_FOUND — id mevcut değil ya da başka bir şirkete ait
• FORBIDDEN — anahtarın erişim düzeyi yetersiz (örneğin READ anahtarıyla mutation çağırmak)