API কী

BI (Power BI, Metabase), স্প্রেডশিট বা নিজস্ব সিস্টেমের সাথে Tenka সংযুক্ত করতে আপনার কোম্পানির API কী তৈরি ও পরিচালনা করুন। প্রতিটি কী REST API-এর মাধ্যমে আপনার ডেটাতে শুধুমাত্র-পঠন অ্যাক্সেস দেয়।

শুধু এর জন্য একটি কী তৈরি করুন। Excel-এ: ডেটা ▸ ডেটা পান ▸ অন্যান্য উৎস থেকে ▸ OData ফিড ▸ ফিডের URL বসান; উন্নত অংশে "Bearer SUA_CHAVE" মানসহ Authorization হেডার যোগ করুন। Excel টেবিলগুলো তালিকাভুক্ত করে (গ্রাহক, চুক্তি, লেনদেন…) এবং নিজে থেকেই পাতাগুলো অনুসরণ করে। Power BI-তে একই পথ (OData ফিড)।

একটি সেলে: =IMPORTDATA("…/api/v1/feed/csv/clientes.csv?api_key=SUA_CHAVE&sep=,&dec=.")। sep=, ও dec=. দিয়ে Sheets সংখ্যাগুলোকে সংখ্যা হিসেবে পড়ে। প্রতিটি রিসোর্সের নিজস্ব CSV আছে (contratos.csv, movimentacoes.csv…)।

তালিকায় প্রতিটি কী-র নাম, প্রিফিক্স, কবে তৈরি ও শেষ ব্যবহার, অবস্থা, MCP পরিসর ও অনিয়মিত পরিচয়ের চিহ্ন। ওপরে প্রতি ব্যক্তি একটি কী-র নিয়ম, পরিচয় পরিবর্তনের প্রস্তুতি ও কী তৈরির প্যানেল — কী আপনার নামে তৈরি হয় ও শুধু একবার খোলা অবস্থায় দেখা যায়: সঙ্গে সঙ্গে কপি করুন।

একটি নাম দিন (যেমন: "Power BI ইন্টিগ্রেশন") এবং কী তৈরি করুন-এ ক্লিক করুন। কী শুধুমাত্র একবার দেখা যায় — এটি কপি করে একটি সিক্রেট ভল্টে সংরক্ষণ করুন। ডাটাবেসে শুধু হ্যাশ থাকে; পরে সাপোর্টও কী পুনরুদ্ধার করতে পারবে না। যদি এটি ফাঁস হয় বা আর প্রয়োজন না হয়, বাতিল করুন ব্যবহার করুন (ইন্টিগ্রেশন তাৎক্ষণিকভাবে বন্ধ হয়ে যায়)।

/api/v1/me — আপনার tenant-এর ডেটা।
/api/v1/clientes — id, কোড, নাম, CPF/CNPJ।
/api/v1/contratos — নম্বর, স্ট্যাটাস, মেয়াদ।
/api/v1/movimentacoes — বিবরণ, মূল্য, মেয়াদপূর্তি, স্ট্যাটাস।
/api/v1/tickets — অনুরোধসমূহ।

"এখনই পরীক্ষা করুন" ব্লক ব্যবহার করুন: কী পেস্ট করুন, রিসোর্স বেছে নিন এবং টেস্ট-এ ক্লিক করুন — Tenka নিজস্ব API কল করে এবং JSON দেখায়। অথবা প্রতিটি এন্ডপয়েন্ট চাক্ষুষভাবে ব্রাউজ ও পরীক্ষা করতে "এক্সপ্লোরার খুলুন (Swagger UI)"-এ ক্লিক করুন (Authorize বোতাম → কী পেস্ট করুন)। স্বয়ংক্রিয় ক্লায়েন্ট তৈরি করতে, OpenAPI স্পেসিফিকেশন (JSON) ডাউনলোড করুন এবং Postman বা কোড জেনারেটরে ইম্পোর্ট করুন।

কোনো কী নিবন্ধিত না থাকলে প্যানেল বলে "তথ্যহীন মিটার" — "বদলানোর জন্য প্রস্তুত" নয়। পার্থক্যটা গুরুত্বপূর্ণ: শূন্য বিদ্যমান কী-এর মধ্যে শূন্য চিহ্নিত কী কিছুই প্রমাণ করে না, আর তাকে অনুমোদন ধরা মিটারের মিথ্যা বলার সবচেয়ে সাধারণ উপায়। পরিমাপ সবকিছু শ্রেণিবদ্ধ করতে না পারলে সেটিও সতর্ক করে, অনুমান দিয়ে হিসাব পূর্ণ না করে।

আপনার কী দিয়ে: GET https://SEU-TENKA/api/v1/analitico ডেটাসেটগুলো (প্ল্যাটফর্মের এবং আপনার কোম্পানি BI-তে যেগুলো তৈরি করেছে) তাদের কলাম ও কী ফিল্টারযোগ্য তা সহ তালিকাভুক্ত করে। একটি ডেটাসেট আনতে: GET /api/v1/analitico/financeiro?formato=csv — Power BI (ডেটা পান ▸ ওয়েব) ও Metabase (CSV/URL উৎস) সরাসরি পড়ে। প্যারামিটার: colunas=a,b · filtros=campo=valor;campo2>valor2;campo3~contem · agrupamento=campo · funcao=SOMA|MEDIA|CONTAGEM|MAIOR|MENOR|MEDIANA। JSON-এ থাকে count, truncado ও regrasDeLinhaAplicadas; CSV আসে BOM-সহ যাতে Excel তা UTF-8-এ খোলে, এবং 1,000 সারি ছাড়ালে শেষ লাইন "# TRUNCADO"।

Tenka-র MCP সার্ভার (/mcp, একই কী দিয়ে) এখন listar_datasets_bi (ক্যাটালগ), metricas_do_dataset_bi (কোনো উৎসে কী মাপা যায়) এবং consultar_dataset_bi (সারিগুলো, বা একটি মাত্রা অনুযায়ী গ্রুপিং, প্রতি উত্তরে সর্বোচ্চ 50 সারি ও মোট ঘোষণাসহ) দেয়। আপনার Tenka-র সঙ্গে যুক্ত AI সহকারী "এ মাসে আমরা প্রতি গ্রাহককে কত বিক্রি করেছি" প্রশ্নের উত্তর দেয় নিয়ন্ত্রিত ডেটাসেট পড়ে — কখনো ডেটাবেস নয়। কী-এর মালিকের সারির নিয়ম ও "মূল্য দেখুন" একইভাবে প্রযোজ্য।

ডেটাসেট কোয়েরিতে ?fonte=snapshot যোগ করুন (/api/v1/analitico/financeiro?fonte=snapshot&formato=csv) যাতে কোম্পানির নির্ধারিত সময়ে রেকর্ড করা স্ন্যাপশট পান, উত্তরে atualizadoEm-সহ — তাৎক্ষণিক এবং অপারেশনাল ডেটাবেসে হাত না দিয়ে, রাতে Power BI হালনাগাদের জন্য আদর্শ। স্ন্যাপশট না থাকলে (নতুন কোম্পানি, বা কী-এর মালিকের সারির নিয়ম আছে যা স্ন্যাপশট ছাঁটে না), API সরাসরি উত্তর দেয় এবং তা `fonte`-তে বলে।

GET /api/v1/analitico/{dataset}?pagina=2&tamanho=200 কোয়েরি করা সেটের (যা "truncado"-তে ঘোষিত 1,000 সারির সীমা মানে) 200 সারির দ্বিতীয় পাতা ফেরত দেয়। উত্তরে থাকে pagina, tamanho, totalNaConsulta ও temMais। প্যারামিটার ছাড়া পুরো সেট সীমা পর্যন্ত আসে, আগের মতো। JSON ও CSV দুটিতেই প্রযোজ্য।

ভাঁজযোগ্য "API কীভাবে ব্যবহার করবেন" বাক্সে আছে নিয়ম (প্রমাণীকরণ, শুধু পড়া, কোম্পানি অনুযায়ী পরিসর, পেজিনেশন ও সীমা), এন্ডপয়েন্ট, পেস্ট করা কী দিয়ে API ডাকার পরীক্ষক এবং Excel, Power BI ও Google Sheets-এর তৈরি ফিড URL।

Com o A2A ligado na plataforma, outro agente de IA descobre o Tenkai em /.well-known/agent.json e pede tarefas em /a2a com a mesma chave de API: cada ferramenta de leitura é uma skill, com as mesmas permissões da chave e do usuário dono dela. Só leitura — escrita continua pelo MCP, em dois passos.

Na Central de Ajuda, em Área do desenvolvedor (/central-ajuda/desenvolvedores). À esquerda fica o guia — começar, autenticação, paginação, erros, limites, idempotência, webhooks e SDK — e a referência de cada operação. Em cada operação estão os parâmetros, os campos da resposta, as mensagens de erro e exemplos para copiar em cURL, JavaScript, Python, Java, C#, PHP e Node.

শুধু বদলানো রোল পড়তে: GET /api/v1/rolos?desde=2026-10-17T00:00:00, হেডার Authorization: Bearer <আপনার কী> সহ; শেষ পাওয়া রোলের তারিখ রেখে দিন এবং পরের desde-তে ব্যবহার করুন। প্রক্রিয়াকারীর কাছে রোল পাঠাতে: POST /api/v1/remessas, হেডার Authorization: Bearer <আপনার কী> ও Idempotency-Key: <প্রতি চালানের জন্য একটি অনন্য কোড> এবং বডি {"idFornecedor": 12, "tipoServico": "TINTURARIA", "rolos": [101, 102]} সহ। একই Idempotency-Key দিয়ে কল আবার করলে একই চালান ফেরত আসে, দ্বিগুণ হয় না। কী-এর লেখার অনুমতি থাকতে হবে এবং এটি শুধু তার প্রোফাইল যে স্ক্রিন দেখে সেগুলোতেই পৌঁছায়।

হেডারে কী পাঠান Authorization: Bearer <key> (অথবা X-API-Key). উদাহরণ:
curl -H "Authorization: Bearer tnk_..." SEU_TENKA/api/v1/clientes?limit=50

কী শুধুমাত্র আপনার কোম্পানির ডেটা দেখতে পায় (tenant বিচ্ছিন্নতা)। এটি শুধুমাত্র-পঠন (GET)। পেজিনেশন ?limit (সর্বোচ্চ 200) এবং ?offset-এর মাধ্যমে। প্রতি কী-তে প্রতি মিনিটে ১২০টি অনুরোধের সীমা (অতিক্রম করলে HTTP 429 ফেরত দেয়)।

সর্বজনীন API-তে প্রতিটি কল একজন ব্যক্তির — কী-এর মালিকের — প্রবেশাধিকার নিয়ে উত্তর দেয়। কী-এর কোনো মালিক না থাকলে, বা মালিক চলে গেলে, প্রয়োগ করার মতো কোনো প্রবেশাধিকার থাকে না, আর প্ল্যাটফর্মের তিনটি সম্ভাব্য অবস্থান: পর্যবেক্ষণ (শুধু রেকর্ড করে), সতর্ক করা (সেবা দেয় এবং একটি হেডার ফেরত দেয় যে একদিন প্রত্যাখ্যান করবে) এবং প্রত্যাখ্যান (403, মূল অংশে কারণ ও সমাধানসহ)। আজ অ্যাকাউন্টটি সতর্ক করা অবস্থায়।

কারণ সময়ের আগে বদলালে যারা অ্যাকাউন্টের ওপর নির্ভর করে তাদের ইন্টিগ্রেশন ভেঙে পড়ে — আর নির্ভরকারীরাই ঠিক তারা যারা নজর রাখছে না। মানদণ্ড কখনো সময়সীমা ছিল না: তা হলো এই স্ক্রিনে আর কোনো চিহ্নিত কী না দেখানো। যতক্ষণ একটিও আছে, প্রস্তুতির প্যানেল বলে কতগুলো, কোনগুলো এবং প্রতিটি নিয়ে কী করতে হবে। শূন্যে পৌঁছালে বলে প্রস্তুত, আর বদলানোটা ঝুঁকিহীন সিদ্ধান্ত হয়ে যায়।

ফিড হলো অন্য ফরম্যাটে v1 API: শুধু পঠনযোগ্য, কী-এর অ্যাকাউন্টে সীমাবদ্ধ, একই রেট-লিমিটসহ। কী বাতিল করলে Excel ও Sheets সঙ্গে সঙ্গে বিচ্ছিন্ন হয়। মুদ্রার কলামগুলো মালিকহীন কী-এর জন্য API-র নিয়ম মানে।

যে পড়ে সে কী-এর মালিক। তার গ্রুপের সারির নিয়ম (প্যানেল ▸ উপাদান ▸ "এই উৎসের জন্য সারির নিয়ম") আপনার যেকোনো ফিল্টারের আগে প্রয়োগ হয়; মূল্যের কলাম কেবল তখনই আসে যখন মালিক মূল্য দেখতে পারে — অনুপস্থিত কলাম হলো মাস্ক, ত্রুটি নয়। প্রতিটি কোয়েরি অডিটে চিহ্ন রাখে (কে, কোন ডেটাসেট, কত সারি)। ডেটাবেসে সরাসরি সংযোগ ইচ্ছা করেই নেই: তা কোম্পানিগুলোর মধ্যকার পৃথকীকরণ ও মূল্যের নিয়ন্ত্রণ ভেঙে দিত।

API কী ট্র্যাশে যায় না: মুছলে (বা প্রত্যাহার বোতামে) কী প্রত্যাহার হয়, সঙ্গে সঙ্গে প্রমাণীকরণ বন্ধ হয়, আর প্রত্যাহার অডিট ট্রেইলে থাকে। কার্ডে শুধু নাম সম্পাদনা হয়; MCP (পড়া) ও লেখার পরিসর বদলায় পরিসর বোতামে — খালি লেখা মানে কোনো লেখা নয়।

সেটিংস › API কী-তে "স্যান্ডবক্স কী তৈরি করুন" বোতাম tnk_sbx_ দিয়ে শুরু হওয়া একটি কী দেয়। এটি শুধু স্যান্ডবক্সের ঠিকানায় কাজ করে: ডেমো ডেটাসহ আলাদা একটি সার্ভার, প্রোডাকশনের একই সংস্করণে, যা প্রতি সপ্তাহে প্রাথমিক অবস্থায় ফেরে — নির্দ্বিধায় পড়া ও লেখা পরীক্ষা করুন। এটি ৯০ দিন এবং দিনে সর্বোচ্চ ১০০০টি কলের জন্য বৈধ; সীমা ছাড়ালে মধ্যরাত পর্যন্ত স্যান্ডবক্স "সীমা পূর্ণ" জানায়। প্রোডাকশন ব্যাখ্যাসহ এটি প্রত্যাখ্যান করে, আর স্যান্ডবক্স প্রোডাকশনের কী প্রত্যাখ্যান করে। তৈরির সময় কী সংরক্ষণ করুন: এটি একবারই দেখানো হয়।

প্ল্যাটফর্ম A2A খুললে এবং অ্যাকাউন্ট সেটিংস › প্যারামিটার › ইন্টিগ্রেশনে চালু করলে, অন্য AI এজেন্ট এই স্ক্রিনের একটি কী দিয়ে Tenkai-কে কাজ দেয়। কী-এর মালিক যা দেখেন সে শুধু তাই দেখে। প্রশ্নের উত্তর সঙ্গে সঙ্গে আসে। বিল পরিশোধের মতো কাজ শুধু প্রস্তাব করা হয়: কাজটি অপেক্ষা করে, ব্যক্তি অনুমতি দেন এবং এজেন্ট একই কাজে নিশ্চিত করে; তার আগে কিছুই সংরক্ষিত হয় না, এবং প্রস্তাব ১৫ মিনিটে শেষ হয়। কাজের অনুমতি দিতে কী-তে সেগুলো চিহ্নিত করুন যা সে প্রস্তাব করতে পারে। প্রতিটি অনুরোধ অডিটে থাকে।

রোল, লট, প্রেরণ, উৎপাদন অর্ডার, টেক শিট ও কাটিং টিকিট চাবি দিয়ে বের হয় শুধু তখন, যখন চাবির মালিকের সেই পর্দায় প্রবেশাধিকার থাকে যেখান থেকে তথ্য আসে (রোল, লটের খোঁজ, বাইরের প্রক্রিয়াকরণ, উৎপাদন অর্ডার, টেক শিট, কাটিং অর্ডার)। প্রেরণ খুলতে বা উৎপাদন লিখতে চাবিকে লেখার অনুমতি দিতে হবে এবং মালিককে পর্দায় যোগ করতে পারতে হবে। যিনি এসব পর্দা চালান তার নামে চাবি তৈরি করুন; প্রবেশাধিকার না থাকলে উত্তর বলে কোন পর্দা বাকি।

Tenant অ্যাডমিনিস্ট্রেটর ("ব্যবহারকারী এবং অ্যাক্সেস গ্রুপ"-এর একই দর্শক)। কী পুরো কোম্পানির জন্য প্রযোজ্য — এগুলোকে পাসওয়ার্ডের মতো বিবেচনা করুন।

এটি এখানে চিহ্নিত অবস্থায় দেখা যায়। আজ কলটি এখনো সেবা পায় এবং হেডারে সতর্কতাসহ ফেরে; বদলানোর পরে 403 পেতে শুরু করবে। এটি সবচেয়ে সাধারণ এবং সবচেয়ে বিপজ্জনক ঘটনা: চলে যাওয়ার মাসখানেক পরেও ইন্টিগ্রেশন চলতে থাকে, এমন কারও প্রবেশাধিকারে যিনি আর প্রতিষ্ঠানে কাজ করেন না। সমাধান হলো প্রতিটি সক্রিয় ব্যক্তির জন্য একটি কী ইস্যু করা এবং পুরনোটি বাতিল করা — মালিক বদলে কী আবার ব্যবহার করা কখনো নয়।

অ্যাড-ইনের জন্য Microsoft Partner Center অ্যাকাউন্ট, স্টোরে প্রকাশ এবং প্রতিটি Office সংস্করণের জন্য রক্ষণাবেক্ষণ লাগে — আর কোনো প্রতিযোগীই তা দিয়ে শুরু করে না। OData ফিড Excel ও Power BI-র নিজস্ব পথ, Mac ও ব্রাউজারে কাজ করে, এবং ইতিমধ্যে থাকা স্প্রেডশিটে যুক্ত হয়।

ফিতাটি জানায় আপনি প্রোডাকশনে নেই: হোমোলোগেশন (যে সার্ভারে দল পরের সংস্করণ যাচাই করে), স্যান্ডবক্স (ইন্টিগ্রেশন পরীক্ষার পরিবেশ, প্রতি সপ্তাহে নতুন ডেমো ডেটাসহ) অথবা ডেভেলপমেন্ট। এই সার্ভারগুলো থেকে কোনো ই-মেইল, WhatsApp, বিলিং, চালান, মোবাইল নোটিশ বা অন্য সিস্টেমে কল আসলে যায় না: সবকিছু অবরুদ্ধ হিসেবে নথিভুক্ত হয়। প্রোডাকশনে ফিতাটি দেখা যায় না।