API ডকুমেন্টেশন

Shifton কাজসমূহ আপনাকে প্ল্যাটফর্মের কাজ স্বয়ংক্রিয় করার এবং খোলা API-র মাধ্যমে বাইরের সেবার সঙ্গে সেটি যুক্ত করার সুযোগ দেয়। API-র মাধ্যমে সব মূল সত্তা পাওয়া যায় — কাজ, ক্লায়েন্ট, কর্মচারী, চেকলিস্ট, ইনভেন্টরি, সেবা অঞ্চল, আর্থিক নথিপত্র এবং রিপোর্ট, — তাই Shifton-কে আপনার HR, বেতন হিসাবের ও বিশ্লেষণের সিস্টেমের পাশাপাশি কোম্পানির অভ্যন্তরীণ সেবার সঙ্গেও যুক্ত করা যায়।

API ডকুমেন্টেশন

ডকুমেন্টেশন দুটি সংস্করণে প্রকাশ করা হয়েছে:

• 🚀 নতুন ডকুমেন্টেশন — হালনাগাদ করা কাঠামো ও সাম্প্রতিক মেথডসহ নির্দেশিকার বর্তমান সংস্করণ: 👉 https://api2.shifton.com/openapi/
• 📄 পুরাতন ডকুমেন্টেশন — আগের সংস্করণ (আগের ইন্টিগ্রেশনগুলোর জন্য এটি এখনো সমর্থিত): 👉 https://api2.shifton.com/docs/

দুটি সংস্করণই অ্যাপ্লিকেশন থেকেই খোলা যায় — Developer বিভাগের সংক্ষিপ্ত বিবরণ ট্যাবে “নতুন ডকুমেন্টেশন” ও “পুরাতন ডকুমেন্টেশন” বোতাম দিয়ে।

ডকুমেন্টেশন দুটি ভাষায় পাওয়া যায়। নতুন ডকুমেন্টেশনের পৃষ্ঠার ডান দিকের উপরের কোণে EN / RU সুইচ আছে — বেছে নেওয়া ভাষাটি মনে রাখা হয়।

API কী কীভাবে পাবেন

API কী অ্যাপ্লিকেশনেই তৈরি করা হয়:

• Developer বিভাগটি খুলুন।
• API কী (“API কী”) ট্যাবে যান।
• “API কী তৈরি করুন” ক্লিক করুন।

কী তৈরি করার সময় কী কী পূরণ করতে হবে

API কী তৈরি করুন সাইড প্যানেলটি খুলে যাবে, যেখানে থাকবে এই ঘরগুলো:

• শিরোনাম — কী-র নাম, ঘরটি বাধ্যতামূলক। কোন কাজে লাগছে সেই অনুযায়ী নাম দিন, যাতে পরে বোঝা যায় কোনটি বন্ধ করতে হবে: “1С-এ ডাউনলোড”, “বিশ্লেষণের জন্য রিপোর্ট”।
• মেয়াদ শেষ হবে — যে তারিখের পরে কী-টি আর কাজ করবে না। ঘরটি খালি রাখলে মেয়াদের কোনো সীমা থাকে না।
• অ্যাক্সেস — কী-টির অধিকারের পরিসর:
• Full access (act as me) — কী-টি আপনার নামে এবং আপনার অধিকার নিয়ে কাজ করে।
• সীমিত অনুমতি — অনুমতির একটি সীমিত সেট, যা আপনি নিজেই বেছে নেন।

কী তৈরি করতে যোগ করুন ক্লিক করুন, আর প্যানেলটি বন্ধ করতে বাতিল করুন ক্লিক করুন।

📷 *কী তৈরির প্যানেলের স্ক্রিন — প্রোডে তোলা হবে*

কী নির্দিষ্ট একটি কোম্পানির জন্য তৈরি হয় এবং কেবল সেই কোম্পানির ডেটা নিয়েই কাজ করে। কী যেকোনো সময় বাতিল করা যায় — বাতিল সঙ্গে সঙ্গেই কার্যকর হয়, আর সেই কী দিয়ে পরের সব অনুরোধ 401 ত্রুটি ফিরিয়ে দেবে।

গুরুত্বপূর্ণ: তৈরি করা কী কেবল একবারই দেখানো হয়। সঙ্গে সঙ্গে সেটি কপি করে নিরাপদ জায়গায় রাখুন — দ্বিতীয়বার এটি পাওয়া যায় না। কী হারিয়ে গেলে নতুন একটি তৈরি করুন এবং পুরোনোটি বাতিল করুন।

অনুমোদন

API-তে সব অনুরোধ হেডারে কী দিয়ে সই করা হয়:

Authorization: Bearer {your_API_key}

API-র মূল ঠিকানা:

https://api2.shifton.com/work/1.0.0

কার্যকর কী ছাড়া অনুরোধ করলে 401 এবং {"message":"Unauthenticated."} বডি ফিরে আসে।

প্রথম অনুরোধ

উদাহরণস্বরূপ, কোম্পানির কর্মচারীদের তালিকা পেতে ({companyId}-এর জায়গায় নিজের কোম্পানির ID বসান):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

curl দিয়ে একই কাজ:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

কোম্পানির ID অ্যাপ্লিকেশনের অ্যাড্রেস বারেই দেখা যায়: app.shifton.com/c/8397/... — /c/-এর পরের সংখ্যাটি।

API-র মাধ্যমে কী কী পাওয়া যায়

নির্দেশিকাটিতে 360-এর বেশি মেথড রয়েছে। বাইরে গিয়ে সেবা দেওয়ার মূল বিভাগগুলো:

• কাজসমূহ — /companies/{companyId}/tasks: তৈরি করা, বদলানো, স্ট্যাটাস, কাজের ফাইল।
• করণীয় তালিকা (To Do) — /companies/{companyId}/todo।
• ক্লায়েন্টরা — /companies/{companyId}/clients, পাশাপাশি ক্লায়েন্টের ঠিকানা ও কাস্টম ঘরগুলো।
• চেকলিস্ট — /companies/{companyId}/checklists।
• সেবা অঞ্চল — /companies/{companyId}/tasks/service-areas।
• দক্ষতা — /companies/{companyId}/skills।
• কর্মচারীরা — /companies/{companyId}/employees: যোগ করা, সম্পাদনা করা, চাকরি থেকে অব্যাহতি ও পুনর্বহাল।
• ইনভেন্টরি — জিনিসপত্র, শ্রেণি, সেট এবং গুদামের মজুত।
• আর্থিক নথিপত্র — খরচের হিসাব, কাজের অর্ডার, বিল, রসিদ, নথির কাউন্টার এবং লোগো।
• রিপোর্ট — কাজ ও হাজিরার ডেটা ডাউনলোড করা।

এ ছাড়া সময়সূচি ও শিফট, ছুটি ও ছুটির অনুরোধ, হাজিরা, বিলিং ও SMS বিলিং, বিজ্ঞপ্তি এবং মডিউলও পাওয়া যায়।

ওয়েবহুক

API-তে বারবার অনুরোধ পাঠানোর বদলে ঘটনাগুলো ঘটার মুহূর্তেই পেতে চাইলে ওয়েবহুক ব্যবহার করুন — Developer বিভাগের Webhooks ট্যাব। দরকারি ঘটনা ঘটলে Shifton নিজেই আপনার ঠিকানায় অনুরোধ পাঠাবে; সমর্থিত ঘটনার তালিকা আলাদা একটি মেথড ফিরিয়ে দেয়।

ত্রুটির কোড

Shifton-এর API সাধারণ HTTP স্টেটাস কোড ব্যবহার করে:

• 200 — অনুরোধ সফলভাবে সম্পন্ন হয়েছে।
• 201 — অবজেক্ট সফলভাবে তৈরি হয়েছে।
• 400 — অনুরোধের প্যারামিটার ভুল।
• 401 — অনুমোদনের ত্রুটি: কী পাঠানো হয়নি, কার্যকর নয় বা বাতিল করা হয়েছে।
• 403 — প্রবেশাধিকার নিষিদ্ধ।
• 404 — রিসোর্স পাওয়া যায়নি (বেশির ভাগ ক্ষেত্রে মেথডের ঠিকানায় বানানের ভুল)।
• 500 — সার্ভারের ত্রুটি।

ব্যবহারের পরামর্শ

• নতুন ইন্টিগ্রেশনের জন্য নতুন ডকুমেন্টেশন ব্যবহার করুন — পুরোনোটি কেবল আগে থেকে চলা ইন্টিগ্রেশনের জন্য রাখা হয়েছে।
• অনুরোধ পরীক্ষা করার জন্য Postman বা curl সুবিধাজনক — এগুলোতে এক লাইন কোড না লিখেই উত্তর দেখা যায়।
• কী-টি কোডে খোলা অবস্থায় রাখবেন না এবং তৃতীয় পক্ষকে দেবেন না: কী কোম্পানির ডেটায় প্রবেশাধিকার দেয়।
• অনুরোধের হারের সীমা (rate limits) মেনে চলুন — সীমা ছাড়িয়ে গেলে API-তে প্রবেশাধিকার সাময়িকভাবে বন্ধ হয়ে যেতে পারে।

প্রায়শই জিজ্ঞাসিত প্রশ্ন

প্রশ্ন: API কী কোথায় পাব? উত্তর: অ্যাপ্লিকেশনে: Developer বিভাগ → API কী ট্যাব → “API কী তৈরি করুন” বোতাম। কী বর্তমান কোম্পানির জন্য দেওয়া হয়।

প্রশ্ন: আমি উইন্ডোটি বন্ধ করে দিয়েছি, কী কপি করিনি। এটি কোথায় দেখব? উত্তর: কোথাও নয় — কী কেবল একবারই দেখানো হয় এবং দ্বিতীয়বার দেওয়া হয় না। নতুন একটি কী তৈরি করুন এবং পুরোনোটি বাতিল করুন।

প্রশ্ন: কী ভুল হাতে পড়লে সেটি কীভাবে বাতিল করব? উত্তর: API কী ট্যাবে সেটি মুছে ফেলুন। বাতিল সঙ্গে সঙ্গেই কার্যকর হয়: সেই কী দিয়ে সব অনুরোধ তখনই 401 ফিরিয়ে দিতে শুরু করবে।

প্রশ্ন: “Full access” ও “Restricted permissions”-এর মধ্যে পার্থক্য কী? উত্তর: Full access (act as me) কী-টিকে আপনার নিজের সব অধিকারই দিয়ে দেয়। সীমিত অনুমতি দিয়ে কী-টিকে কেবল বেছে নেওয়া অনুমতিগুলোই দেওয়া যায় — যে ইন্টিগ্রেশনের কেবল কিছু ডেটা দরকার, তার জন্য এটি বেশি নিরাপদ।

প্রশ্ন: কী-র মেয়াদ কি সীমিত করা যায়? উত্তর: হ্যাঁ, তৈরি করার সময় মেয়াদ শেষ হবে ঘরটি আছে। এটি পূরণ না করলে কী-র মেয়াদ অসীম হবে।

প্রশ্ন: একটি কী কি কয়েকটি কোম্পানির জন্য কাজ করে? উত্তর: না। কী যে কোম্পানিতে তৈরি হয়েছে, সেটির সঙ্গেই বাঁধা থাকে এবং কেবল সেই কোম্পানির ডেটা নিয়েই কাজ করে। অন্য কোম্পানির জন্য আলাদা কী তৈরি করুন।

প্রশ্ন: API-র মূল ঠিকানা কী? উত্তর: https://api2.shifton.com/work/1.0.0। এর পরে মেথডের পথ বসে, উদাহরণস্বরূপ /companies/{companyId}/tasks।

প্রশ্ন: অনুরোধের জন্য কোম্পানির ID কোথায় পাব? উত্তর: এটি অ্যাপ্লিকেশনের অ্যাড্রেস বারে /c/-এর ঠিক পরেই থাকে — উদাহরণস্বরূপ, app.shifton.com/c/8397/tasks-এ কোম্পানির শনাক্তকারী হলো 8397।

প্রশ্ন: ডকুমেন্টেশনের কোন সংস্করণটি ব্যবহার করব? উত্তর: নতুন ইন্টিগ্রেশনের জন্য — নতুনটি (api2.shifton.com/openapi)। পুরোনোটি (api2.shifton.com/docs) আগের ইন্টিগ্রেশনগুলোর জন্য সমর্থিত।

প্রশ্ন: রুশ ভাষায় ডকুমেন্টেশন আছে কি? উত্তর: হ্যাঁ। নতুন ডকুমেন্টেশনের পৃষ্ঠায় ডান দিকের উপরের কোণে EN / RU সুইচ আছে।

প্রশ্ন: API-র অনুরোধ কী দিয়ে পরীক্ষা করব? উত্তর: সবচেয়ে সুবিধাজনক Postman বা curl — এগুলো দিয়ে কোড না লিখেই অনুরোধ পাঠানো ও উত্তর দেখা যায়।

প্রশ্ন: কী কপি করেছি, তবু 401 আসছে কেন? উত্তর: দেখে নিন, কী-টি Authorization হেডারে তার আগে Bearer শব্দসহ পাঠানো হচ্ছে কি না, কী-টি বাতিল হয়নি এবং তার মেয়াদ শেষ হয়নি কি না।

প্রশ্ন: 404 আসছে কেন? উত্তর: বেশির ভাগ ক্ষেত্রে ঠিকানা এলোমেলো হয়ে যায়: মূল অংশটি হতে হবে https://api2.shifton.com/work/1.0.0, আর মেথডের পথে থাকতে হবে সঠিক {companyId}।

প্রশ্ন: API-র মাধ্যমে কী কী স্বয়ংক্রিয় করা যায়? উত্তর: কাজ তৈরি ও বদলানো, ক্লায়েন্ট ও তাঁদের ঠিকানা নিয়ে কাজ, চেকলিস্ট, সেবা অঞ্চল, দক্ষতা, কর্মচারী, ইনভেন্টরি, আর্থিক নথিপত্র ও রিপোর্ট ডাউনলোড, পাশাপাশি সময়সূচি, শিফট ও ছুটি।

প্রশ্ন: API-তে বারবার না জিজ্ঞেস করে Shifton থেকে ঘটনা পাওয়া যায় কি? উত্তর: হ্যাঁ, এর জন্য ওয়েবহুক আছে — Developer বিভাগের Webhooks ট্যাব।

প্রশ্ন: পাসওয়ার্ড পরিবর্তন কি ইন্টিগ্রেশনের কাজে প্রভাব ফেলে? উত্তর: না। ইন্টিগ্রেশনগুলো অ্যাকাউন্টের পাসওয়ার্ড দিয়ে নয়, API কী দিয়ে কাজ করে।