مفاتيح API

أنشئ وأدر مفاتيح API الخاصة بشركتك لدمج Tenka مع أدوات BI (Power BI، Metabase)، أو جداول البيانات أو الأنظمة الخاصة بك. يمنح كل مفتاح وصولاً للقراءة فقط إلى بياناتك عبر واجهة REST API.

أنشئ مفتاحًا لهذا الغرض فقط. في Excel: البيانات ▸ الحصول على البيانات ▸ من مصادر أخرى ▸ موجز OData ▸ الصق رابط الموجز؛ وفي "خيارات متقدمة" أضف الترويسة Authorization بالقيمة "Bearer SUA_CHAVE". يسرد 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") وانقر على إنشاء مفتاح. يظهر المفتاح مرة واحدة فقط — انسخه واحفظه في خزنة أسرار. لا يُحفظ في قاعدة البيانات سوى التجزئة (hash)؛ ولا يمكن حتى للدعم الفني استرجاع المفتاح لاحقًا. إذا تسرّب أو لم تعد بحاجة إليه، استخدم إلغاء (يتوقف التكامل فورًا).

/api/v1/me — بيانات الـ tenant الخاص بك.
/api/v1/clientes — المعرف، الرمز، الاسم، 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/رابط) مباشرة. المعاملات: 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، مع سطر أخير "# TRUNCADO" عندما يتجاوز 1,000 سطر.

أصبح خادم MCP الخاص بـ Tenka (/mcp، بالمفتاح نفسه) يقدّم listar_datasets_bi (الكتالوج)، وmetricas_do_dataset_bi (ما يمكن قياسه في مصدر)، وconsultar_dataset_bi (السطور، أو التجميع حسب بُعد واحد، حتى 50 سطرًا لكل إجابة مع ذكر الإجمالي). المساعد الذكي المتصل بـ Tenka الخاص بك يجيب عن "كم بعنا لكل عميل هذا الشهر" بقراءة مجموعة البيانات المحكومة — لا قاعدة البيانات أبدًا. وتسري قواعد الصفوف و"عرض القيم" لمالك المفتاح بالطريقة نفسها.

أضف ?fonte=snapshot إلى استعلام مجموعة البيانات (/api/v1/analitico/financeiro?fonte=snapshot&formato=csv) لتتلقى اللقطة المسجّلة في الوقت المضبوط للشركة، مع atualizadoEm في الاستجابة — فورية ودون المساس بقاعدة البيانات التشغيلية، ومثالية لتحديث Power BI ليلًا. عندما لا توجد لقطة (شركة جديدة، أو لدى مالك المفتاح قاعدة صفوف لا تقتطعها اللقطة)، تجيب الواجهة مباشرة وتذكر ذلك في `fonte`.

GET /api/v1/analitico/{dataset}?pagina=2&tamanho=200 يعيد الصفحة الثانية من 200 سطر من المجموعة المستعلَم عنها (التي تحترم سقف 1,000 سطر، المذكور في "truncado"). تحمل الاستجابة pagina وtamanho وtotalNaConsulta وtemMais. بدون المعاملات تأتي المجموعة كاملة حتى السقف كما في السابق. يسري ذلك على JSON وCSV.

يجمع الإطار القابل للطي "كيفية استخدام الـ API" القواعد (المصادقة والقراءة فقط والنطاق حسب الشركة والترقيم والحد) ونقاط النهاية والمختبِر الذي يستدعي الـ API بالمفتاح الملصق وعناوين الموجز الجاهزة لـ Excel وPower BI وGoogle Sheets.

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 <المفتاح> (أو X-API-Key). مثال:
curl -H "Authorization: Bearer tnk_..." SEU_TENKA/api/v1/clientes?limit=50

المفتاح لا يرى سوى بيانات شركتك (العزل حسب الـ tenant). وهو للقراءة فقط (GET). التصفح عبر ?limit (بحد أقصى 200) و?offset. الحد هو 120 طلبًا في الدقيقة لكل مفتاح (يُعيد HTTP 429 عند التجاوز).

كل استدعاء لواجهة API العامة يُجاب بصلاحيات شخص واحد — مالك المفتاح. عندما لا يكون للمفتاح مالك، أو يكون المالك قد غادر، لا توجد صلاحيات تُطبَّق، وللمنصة ثلاثة مواقف ممكنة: المراقبة (تسجّل فقط)، والتنبيه (تخدم وتعيد ترويسة تقول إنها سترفض يومًا ما)، والرفض (403، مع السبب والحل في المتن). الحساب اليوم في وضع التنبيه.

لأن التحويل قبل الأوان يُسقط تكامل من يعتمد على الحساب — ومن يعتمد عليه هو بالضبط من لا ينظر. المعيار لم يكن مهلة قط: بل أن لا تعرض هذه الشاشة أي مفتاح معلَّم. ما دام هناك واحد، تقول لوحة الجاهزية كم عددها وأيها وماذا تفعل بكل منها. وعندما تصل إلى الصفر تقول إنها جاهزة، ويصبح التحويل قرارًا بلا مخاطرة.

الموجز هو واجهة API v1 بصيغة أخرى: للقراءة فقط، ومحصور في حساب المفتاح، وبحد المعدل نفسه. إلغاء المفتاح يقطع Excel وSheets فورًا. الأعمدة المالية تتبع قاعدة الواجهة للمفاتيح بلا مالك.

من يقرأ هو مالك المفتاح. تُطبَّق قواعد الصفوف لمجموعته (اللوحات ▸ المكوّن ▸ "قواعد الصفوف لهذا المصدر") قبل أي تصفية منك؛ ولا تخرج أعمدة القيم إلا إذا كان المالك يستطيع رؤية القيم — فالعمود الناقص هو القناع لا خطأ. كل استعلام يترك أثرًا في سجل التدقيق (من، وأي مجموعة بيانات، وكم سطرًا). الاتصال المباشر بقاعدة البيانات غير موجود عن قصد: فهو سيخرق العزل بين الشركات وحوكمة القيم.

لا يذهب مفتاح API إلى سلة المحذوفات: الحذف (أو زر الإلغاء) يلغي المفتاح فيتوقف عن المصادقة فورًا، ويبقى الإلغاء في سجل التدقيق. في البطاقة يُحرَّر الاسم فقط؛ ويتغير نطاق MCP (القراءة) والكتابة عبر زر النطاق — الكتابة الفارغة تعني لا كتابة.

في الإعدادات › مفاتيح API، يُصدر زر "إنشاء مفتاح بيئة التجربة" مفتاحًا يبدأ بـ tnk_sbx_. لا يعمل إلا على عنوان بيئة التجربة: خادم منفصل ببيانات تجريبية، بالإصدار نفسه للإنتاج، يعود إلى حالته الأولى كل أسبوع — اختبر القراءة والكتابة بحرية. صالح 90 يومًا وحتى 1000 طلب يوميًا؛ عند تجاوز الحد تردّ بيئة التجربة "تم بلوغ الحد" حتى منتصف الليل. يرفضه الإنتاج مع التوضيح، وترفض بيئة التجربة مفتاح الإنتاج. احفظ المفتاح عند إنشائه: يظهر مرة واحدة فقط.

عندما تفتح المنصة A2A ويفعّله الحساب في الإعدادات › المعاملات › التكاملات، يستخدم وكيل ذكاء اصطناعي آخر مفتاحًا من هذه الشاشة ليطلب مهام من Tenkai. لا يرى إلا ما يراه صاحب المفتاح. الاستعلامات تعود فورًا. أما الإجراءات، مثل تسوية فاتورة، فتُقترح فقط: تنتظر المهمة، ويأذن الشخص، ويؤكد الوكيل في المهمة نفسها؛ وقبل ذلك لا يُحفظ شيء، وتنتهي صلاحية الاقتراح بعد 15 دقيقة. للسماح بالإجراءات، حدّد في المفتاح ما يمكنه اقتراحه. كل طلب يُسجَّل في التدقيق.

لا تخرج اللفائف والدفعات والإرساليات وأوامر الإنتاج والبطاقات الفنية وقسائم القص عبر المفتاح إلا إذا كان لمالكه وصول إلى الشاشة التي يأتي منها الدليل (اللفائف، تتبع الدفعة، التصنيع الخارجي، أوامر الإنتاج، البطاقة الفنية، أمر القص). لفتح إرسالية أو تسجيل إنتاج يجب أن يكون المفتاح للكتابة وأن يستطيع المالك الإضافة في الشاشة. أنشئ المفتاح باسم من يشغّل هذه الشاشات؛ وبدون وصول يذكر الرد الشاشة الناقصة.

مسؤول الـ tenant (نفس جمهور "المستخدمون ومجموعات الوصول"). المفاتيح صالحة للشركة بأكملها — تعامل معها كأنها كلمة مرور.

يظهر معلَّمًا هنا. اليوم لا يزال الاستدعاء يُخدم ويعود بتنبيه في الترويسة؛ وبعد التحويل سيبدأ في تلقي 403. إنها الحالة الأكثر شيوعًا والأخطر: يظل التكامل يعمل لأشهر بعد المغادرة، بصلاحيات شخص لم يعد يعمل في الشركة. الحل هو إصدار مفتاح لكل شخص نشط وإلغاء القديم — ولا تُعِد استخدام المفتاح بنقل المالك أبدًا.

تتطلب الوظيفة الإضافية حسابًا في Microsoft Partner Center ونشرًا في المتجر وصيانة لكل إصدار من Office — ولا يبدأ أي من المنافسين بها. موجز OData هو المسار الأصلي لـ Excel وPower BI، ويعمل على Mac وفي المتصفح، ويدخل في جدول بيانات موجود بالفعل.

يخبرك الشريط بأنك لست في الإنتاج: بيئة الاختبار (الخادم الذي يراجع فيه الفريق الإصدار القادم)، أو بيئة التجربة (بيئة اختبار التكامل، ببيانات تجريبية يُعاد إنشاؤها كل أسبوع)، أو التطوير. على هذه الخوادم لا يُرسَل فعليًا أي بريد أو رسالة WhatsApp أو تحصيل أو فاتورة أو إشعار هاتف أو طلب إلى نظام آخر: يُسجَّل كل ذلك كمحظور. في الإنتاج لا يظهر الشريط.