Gambaran Keseluruhan API

FreeMaint menyediakan satu permukaan API untuk integrasi antara sistem: GraphQL di /api/v1/graphql. Laluan REST yang anda lihat dalam pelayar ialah API aplikasi itu sendiri dan disahkan dengan sesi pengguna — kunci API tidak sampai kepadanya. Rancang integrasi anda di atas GraphQL.

API REST

Laluan REST di bawah /api/v1/{resource} ialah yang dipanggil oleh aplikasi web dan mudah alih FreeMaint, disahkan dengan sesi pengguna (JWT). Kunci API (fmk_...) TIDAK mengesahkannya — ia hanya diterima di /api/v1/graphql dan endpoint pengambilan tenaga. Untuk integrasi, baca bahagian GraphQL di bawah.

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

API GraphQL

Titik akhir GraphQL ialah POST /api/v1/graphql. Ia merangkumi subset produk yang dipilih secara sedar — perintah kerja, aset, pemberhentian mesin, alat ganti berserta pergerakan stoknya, meter, pesanan belian, lokasi, pembekal, pelanggan dan pelan lantai — bukan keseluruhan aplikasi. Gunakan GraphQL apabila anda terpaksa memanggil beberapa titik akhir untuk membina satu skrin: contohnya kad yang memaparkan perintah kerja berserta butiran asetnya, alat ganti yang digunakan dan jumlah kos buruh. Panduan integrasi ERP menyenaraikan apa yang tidak dicapai oleh skema ini.

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

Pengesahan

Kedua-dua API menerima token JWT dalam pengepala Authorization, dikeluarkan oleh POST /api/v1/auth/login dan sah selama 2 jam (diperbaharui dengan token penyegaran). Untuk integrasi pelayan ke pelayan, gunakan kunci API sebaliknya: pentadbir menciptanya di Tetapan Syarikat > API (/company-settings/api), dan orang yang peranannya membenarkan mencipta kunci mereka sendiri di Profil > Keselamatan > Kunci API (/profile/api-keys); hantar Authorization: Bearer fmk_... . Sesebuah kunci bertindak sebagai pemiliknya: ia mempunyai kebenaran pemiliknya dan hanya melihat apa yang dilihat oleh pemiliknya. PENTING: kunci API mengesahkan titik akhir GraphQL (POST /api/v1/graphql), titik akhir pengambilan tenaga dan /public-api/{whoami,ping} — ia TIDAK mengesahkan laluan sumber REST, yang memerlukan JWT pengguna.

Ketersediaan mengikut peringkat

Had kadar

Kuota ialah pembilang HARIAN bagi setiap syarikat, dikongsi antara GraphQL dan titik akhir pengambilan data tenaga, dan ditetapkan semula pada 00:00 UTC. Business membenarkan 5,000 panggilan sehari, Enterprise 100,000. Setiap respons membawa X-RateLimit-Limit, X-RateLimit-Remaining dan X-RateLimit-Reset. Tiada tetingkap per minit dan tiada pengepala Retry-After. Pada permukaan REST penolakannya ialah HTTP 403; pada GraphQL status HTTP kekal 200 — GraphQL sentiasa menjawab 200 — dan penolakan berada dalam errors[0].extensions.code = FORBIDDEN. Jangan tinjau status HTTP 403 pada GraphQL: baca tatasusunan errors.

Format ralat

Setiap ralat membawa status HTTP, kod yang boleh dibaca mesin, dan mesej yang boleh dibaca manusia. 4xx ialah ralat klien (pengesahan, kebenaran, tidak dijumpai); 5xx ialah ralat pelayan dan patut dicuba semula dengan jeda eksponen. Dalam GraphQL kodnya berada dalam extensions.code, dan nilai yang boleh anda padankan ialah: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT dan TOO_MANY_REQUESTS. Apabila pengesahan gagal, mesej itu menamakan dengan tepat medan yang salah — contohnya "quantity must be a number conforming to the specified constraints" — jadi anda tidak perlu meneka medan mana yang dihantar salah oleh sistem anda. Carian yang memang tidak sepadan dengan apa-apa bukanlah ralat: part(barcode:) memulangkan null.

SDK rasmi dan perkakasan

Buat masa ini tiada SDK pelanggan rasmi. Titik akhir GraphQL mempunyai introspection yang dihidupkan, jadi mana-mana pelanggan GraphQL (Apollo, graphql-codegen, Insomnia, Postman) boleh menemui skema dengan menuju ke POST /api/v1/graphql menggunakan kunci API anda. Kami tidak menerbitkan dokumen OpenAPI statik atau fail SDL pada URL tetap buat masa ini.

Kunci API tidak tersedia pada pelan Core atau Starter.