Ikhtisar API

FreeMaint menyediakan satu permukaan API untuk integrasi antarsistem: GraphQL di /api/v1/graphql. Rute REST yang Anda lihat di peramban adalah API aplikasi itu sendiri dan diautentikasi dengan sesi pengguna — kunci API tidak menjangkaunya. Rancang integrasi Anda di atas GraphQL.

REST API

Rute REST di /api/v1/{resource} adalah yang dipanggil aplikasi web dan seluler FreeMaint, diautentikasi dengan sesi pengguna (JWT). Kunci API (fmk_...) TIDAK mengautentikasinya — kunci hanya diterima di /api/v1/graphql dan endpoint ingest energi. Untuk integrasi, baca bagian GraphQL di bawah.

Contoh (sesi pengguna, BUKAN kunci API — kunci fmk_ tidak akan mengautentikasi rute ini): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL API

Endpoint GraphQL adalah POST /api/v1/graphql. Cakupannya sengaja dibatasi pada sebagian produk — perintah kerja, aset, penghentian mesin, suku cadang beserta pergerakan stoknya, meter, pesanan pembelian, lokasi, pemasok, pelanggan, dan denah lantai — bukan seluruh aplikasi. Gunakan GraphQL bila tanpa itu Anda harus memanggil beberapa endpoint untuk menyusun satu layar: misalnya kartu yang menampilkan perintah kerja beserta detail asetnya, suku cadang terpakai, dan total biaya tenaga kerja. Panduan integrasi ERP memuat apa saja yang tidak dijangkau skema ini.

Contoh kueri: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Autentikasi

Kedua API menerima token JWT di header Authorization, diterbitkan oleh POST /api/v1/auth/login dan berlaku 2 jam (diperbarui dengan refresh token). Untuk integrasi server-ke-server, gunakan kunci API: admin membuatnya di Pengaturan Perusahaan > API (/company-settings/api), dan orang yang perannya mengizinkan membuat kuncinya sendiri di Profil > Keamanan > Kunci API (/profile/api-keys); kirim Authorization: Bearer fmk_... . Sebuah kunci bertindak sebagai pemiliknya: kunci memiliki izin pemiliknya dan hanya melihat apa yang dilihat pemiliknya. PENTING: kunci API mengautentikasi endpoint GraphQL (POST /api/v1/graphql), endpoint ingest energi, dan /public-api/{whoami,ping} — TIDAK mengautentikasi rute sumber daya REST, yang memerlukan JWT pengguna.

Ketersediaan paket

Batas laju

Kuota adalah penghitung HARIAN per perusahaan, dipakai bersama oleh GraphQL dan endpoint pengambilan data energi, dan disetel ulang pada 00:00 UTC. Business mengizinkan 5.000 panggilan per hari, Enterprise 100.000. Setiap respons membawa X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Tidak ada jendela per menit maupun header Retry-After. Pada permukaan REST penolakannya adalah HTTP 403; pada GraphQL status HTTP tetap 200 — GraphQL selalu menjawab 200 — dan penolakan ada di errors[0].extensions.code = FORBIDDEN. Jangan memantau status HTTP 403 di GraphQL: baca array errors.

Format kesalahan

Setiap galat membawa status HTTP, kode yang dapat dibaca mesin, dan pesan yang dapat dibaca manusia. 4xx adalah galat klien (validasi, izin, tidak ditemukan); 5xx adalah galat server dan sebaiknya dicoba ulang dengan jeda eksponensial. Pada GraphQL kodenya ada di extensions.code, dan nilai yang dapat Anda cocokkan adalah: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT, dan TOO_MANY_REQUESTS. Ketika validasi gagal, pesannya menyebutkan persis bidang mana yang salah — misalnya "quantity must be a number conforming to the specified constraints" — sehingga Anda tidak perlu menebak bidang mana yang dikirim keliru oleh sistem Anda. Pencarian yang memang tidak cocok dengan apa pun bukanlah galat: part(barcode:) mengembalikan null.

SDK resmi dan tooling

Saat ini belum ada SDK klien resmi. Endpoint GraphQL mengaktifkan introspection, jadi klien GraphQL apa pun (Apollo, graphql-codegen, Insomnia, Postman) dapat menemukan skema dengan mengarah ke POST /api/v1/graphql memakai kunci API Anda. Untuk saat ini kami tidak menerbitkan dokumen OpenAPI statis maupun berkas SDL di URL tetap.

Kunci API tidak tersedia pada paket Core maupun Starter.