API'ye Genel Bakış

FreeMaint, sistemler arası entegrasyon için tek bir API yüzeyi sunar: /api/v1/graphql adresindeki GraphQL. Tarayıcıda gördüğünüz REST yolları uygulamanın kendi API'sidir ve kullanıcı oturumuyla doğrulanır — bir API anahtarı bunlara erişemez. Entegrasyonunuzu GraphQL üzerine kurun.

REST API

/api/v1/{resource} altındaki REST yolları, FreeMaint web ve mobil uygulamalarının çağırdığı yollardır ve kullanıcı oturumuyla (JWT) doğrulanır. Bir API anahtarı (fmk_...) bunları doğrulaMAZ — yalnızca /api/v1/graphql ve enerji veri alma uç noktasında kabul edilir. Entegrasyon için aşağıdaki GraphQL bölümünü okuyun.

Örnek (kullanıcı oturumu, API anahtarı DEĞİL — fmk_ anahtarı bu yolu doğrulamaz): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL API

GraphQL uç noktası POST /api/v1/graphql'dir. Ürünün bilinçli olarak seçilmiş bir alt kümesini kapsar — iş emirleri, varlıklar, makine duruşları, yedek parçalar ve bunların stok hareketleri, sayaçlar, satın alma siparişleri, konumlar, tedarikçiler, müşteriler ve kat planları — uygulamanın tamamını değil. Tek bir ekranı oluşturmak için aksi hâlde birkaç uç noktayı çağırmanız gerekecekse GraphQL kullanın: örneğin bir iş emrini varlık ayrıntıları, kullanılan parçalar ve toplam işçilik maliyetiyle gösteren bir kart. Şemanın ulaşamadıklarını ERP entegrasyon kılavuzu sıralar.

Örnek sorgu: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Kimlik doğrulama

Her iki API de Authorization başlığında JWT taşıyıcı token kabul eder; token POST /api/v1/auth/login tarafından verilir ve 2 saat geçerlidir (yenileme token'ı ile yenilenir). Sunucudan sunucuya entegrasyonlarda bunun yerine API anahtarı kullanın: bir yönetici bunu Şirket Ayarları > API (/company-settings/api) altında oluşturur, rolü izin veren bir kişi de kendi anahtarlarını Profil > Güvenlik > API anahtarları (/profile/api-keys) altında oluşturur; Authorization: Bearer fmk_... gönderin. Bir anahtar sahibi olarak davranır: onun izinlerine sahiptir ve yalnızca onun gördüğünü görür. ÖNEMLİ: Bir API anahtarı GraphQL uç noktasını (POST /api/v1/graphql), enerji veri alma uç noktasını ve /public-api/{whoami,ping} adreslerini doğrular — REST kaynak yollarını doğrulamaz; onlar kullanıcı JWT'si ister.

Katman bazında kullanılabilirlik

Hız sınırları

Kota, şirket başına GÜNLÜK bir sayaçtır; GraphQL ile enerji veri alım uç noktası arasında paylaşılır ve 00:00 UTC'de sıfırlanır. Business günde 5.000, Enterprise 100.000 çağrıya izin verir. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset taşır. Dakikalık pencere ve Retry-After başlığı yoktur. REST yüzeylerinde ret bir HTTP 403'tür; GraphQL'de HTTP durumu 200 kalır — GraphQL her zaman 200 döner — ve ret errors[0].extensions.code = FORBIDDEN içindedir. GraphQL'de HTTP 403 durumunu yoklamayın: errors dizisini okuyun.

Hata biçimi

Her hata bir HTTP durumu, makine tarafından okunabilir bir kod ve okunabilir bir mesaj taşır. 4xx istemci hatalarıdır (doğrulama, yetki, bulunamadı); 5xx sunucu hatalarıdır ve üstel bekleme ile yeniden denenmelidir. GraphQL'de kod extensions.code içindedir ve eşleştirebileceğiniz değerler şunlardır: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT ve TOO_MANY_REQUESTS. Doğrulama başarısız olduğunda mesaj hatalı alanları tam olarak adlandırır — örneğin "quantity must be a number conforming to the specified constraints" — böylece sisteminizin hangisini yanlış gönderdiğini asla tahmin etmek zorunda kalmazsınız. Hiçbir şeyle eşleşmeyen bir arama hata değildir: part(barcode:) null döndürür.

Resmi SDK'lar ve araçlar

Şu anda resmî bir istemci SDK'sı yok. GraphQL uç noktasında introspection açık olduğundan, herhangi bir GraphQL istemcisi (Apollo, graphql-codegen, Insomnia, Postman) API anahtarınızla POST /api/v1/graphql adresine giderek şemayı keşfedebilir. Şu an sabit bir URL'de statik OpenAPI belgesi veya SDL dosyası yayımlamıyoruz.

API anahtarları Core ve Starter planlarında bulunmaz.