API পরিচিতি

সিস্টেমের মধ্যে সংযোগের জন্য FreeMaint একটিই API পৃষ্ঠ দেয়: /api/v1/graphql-এ GraphQL। ব্রাউজারে যে REST রুটগুলো দেখেন সেগুলো অ্যাপ্লিকেশনের নিজস্ব API, ব্যবহারকারীর সেশন দিয়ে যাচাই হয় — API কী সেখানে পৌঁছায় না। সংযোগ GraphQL-এর উপর পরিকল্পনা করুন।

REST API

/api/v1/{resource}-এর REST রুটগুলো FreeMaint-এর ওয়েব ও মোবাইল অ্যাপ ডাকে, ব্যবহারকারীর সেশন (JWT) দিয়ে যাচাই করে। API কী (fmk_...) সেগুলো যাচাই করে না — এটি কেবল /api/v1/graphql এবং এনার্জি ইনজেস্ট এন্ডপয়েন্টে গৃহীত হয়। সংযোগের জন্য নিচের GraphQL অংশ পড়ুন।

উদাহরণ (ব্যবহারকারীর সেশন, API কী নয় — fmk_ কী এই রুট যাচাই করবে না): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL API

GraphQL এন্ডপয়েন্ট হলো POST /api/v1/graphql। এটি ইচ্ছাকৃতভাবে পণ্যের একটি অংশ ঢাকে — কাজের নির্দেশনা, সম্পদ, যন্ত্র বন্ধ, যন্ত্রাংশ ও তাদের স্টক চলাচল, মিটার, ক্রয়াদেশ, অবস্থান, সরবরাহকারী, গ্রাহক ও ফ্লোর প্ল্যান — পুরো অ্যাপ্লিকেশন নয়। একটি পর্দা গড়তে যখন একাধিক এন্ডপয়েন্ট ডাকতে হতো, তখন GraphQL ব্যবহার করুন: যেমন একটি টাইল যা কাজের নির্দেশনার সঙ্গে তার সম্পদের বিবরণ, ব্যবহৃত যন্ত্রাংশ ও মোট শ্রমব্যয় দেখায়। স্কিমা যা ছোঁয় না, তা ERP ইন্টিগ্রেশন নির্দেশিকায় তালিকাভুক্ত আছে।

উদাহরণ কোয়েরি: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

প্রমাণীকরণ

দুটি API-ই Authorization হেডারে JWT টোকেন গ্রহণ করে, যা POST /api/v1/auth/login ইস্যু করে এবং 2 ঘণ্টা বৈধ থাকে (রিফ্রেশ টোকেন দিয়ে নবায়নযোগ্য)। সার্ভার-টু-সার্ভার ইন্টিগ্রেশনে বরং একটি API কী ব্যবহার করুন: একজন অ্যাডমিন এটি কোম্পানি সেটিংস > API (/company-settings/api) থেকে তৈরি করেন, আর যাঁর ভূমিকা অনুমতি দেয় তিনি প্রোফাইল > নিরাপত্তা > API কী (/profile/api-keys) থেকে নিজের কী তৈরি করেন; Authorization: Bearer fmk_... পাঠান। একটি কী তার মালিক হিসেবে কাজ করে: এতে মালিকের অনুমতিগুলোই থাকে এবং মালিক যা দেখেন শুধু সেটুকুই দেখে। গুরুত্বপূর্ণ: API কী দিয়ে GraphQL এন্ডপয়েন্ট (POST /api/v1/graphql), এনার্জি ইনজেস্ট এন্ডপয়েন্ট এবং /public-api/{whoami,ping} প্রমাণীকৃত হয় — REST রিসোর্স রুটগুলো হয় না, সেগুলোর জন্য ব্যবহারকারীর JWT লাগে।

টিয়ার অনুযায়ী প্রাপ্যতা

রেট লিমিট

কোটা হলো কোম্পানিপ্রতি একটি দৈনিক কাউন্টার, যা GraphQL ও এনার্জি ইনজেস্ট এন্ডপয়েন্ট ভাগ করে নেয় এবং 00:00 UTC-তে রিসেট হয়। Business দিনে 5,000 কল দেয়, Enterprise 100,000। প্রতিটি রেসপন্সে X-RateLimit-Limit, X-RateLimit-Remaining ও X-RateLimit-Reset থাকে। প্রতি-মিনিট উইন্ডো বা Retry-After হেডার নেই। REST পৃষ্ঠে প্রত্যাখ্যান আসে HTTP 403 হিসেবে; GraphQL-এ HTTP স্ট্যাটাস 200-ই থাকে — GraphQL সবসময় 200 দেয় — আর প্রত্যাখ্যান থাকে errors[0].extensions.code = FORBIDDEN-এ। GraphQL-এ HTTP 403 খুঁজবেন না: errors অ্যারে পড়ুন।

ত্রুটির ফরম্যাট

প্রতিটি ত্রুটির সঙ্গে থাকে একটি HTTP স্ট্যাটাস, যন্ত্রপাঠযোগ্য একটি কোড এবং পাঠযোগ্য একটি বার্তা। 4xx হলো ক্লায়েন্টের ত্রুটি (যাচাই, অনুমতি, পাওয়া যায়নি); 5xx হলো সার্ভারের ত্রুটি, যেগুলি সূচকীয় বিরতিতে পুনরায় চেষ্টা করা উচিত। GraphQL-এ কোডটি থাকে extensions.code-এ, আর যে মানগুলির সঙ্গে মেলানো যায় সেগুলি হলো: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT এবং TOO_MANY_REQUESTS। যাচাই ব্যর্থ হলে বার্তাটি ঠিক কোন ক্ষেত্রগুলি ভুল তা জানিয়ে দেয় — যেমন «quantity must be a number conforming to the specified constraints» — তাই আপনার সিস্টেম কোনটি ভুল পাঠিয়েছে তা অনুমান করতে হয় না। যে অনুসন্ধানে কিছুই মেলেনি সেটি ত্রুটি নয়: part(barcode:) null ফেরত দেয়।

অফিসিয়াল SDK ও টুলিং

বর্তমানে কোনো অফিসিয়াল ক্লায়েন্ট SDK নেই। GraphQL এন্ডপয়েন্টে ইন্ট্রোস্পেকশন চালু আছে, তাই যেকোনো GraphQL ক্লায়েন্ট (Apollo, graphql-codegen, Insomnia, Postman) আপনার API কী দিয়ে POST /api/v1/graphql-এ গিয়ে স্কিমা জেনে নিতে পারে। নির্দিষ্ট কোনো URL-এ স্ট্যাটিক OpenAPI নথি বা SDL ফাইল আমরা এখন প্রকাশ করি না।

Core ও Starter-এ API কী পাওয়া যায় না।