API密钥

生成并管理贵公司的API密钥，用于将Tenka与BI工具（Power BI、Metabase）、电子表格或自有系统集成。每个密钥都通过REST API为您的数据提供只读访问权限。

专门为此生成一个密钥。在 Excel 中：数据 ▸ 获取数据 ▸ 自其他源 ▸ OData 源 ▸ 粘贴源 URL；在“高级”中添加 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集成"）并点击生成密钥。密钥仅显示一次——请复制并保存到密钥保管库中。数据库中只保存哈希值；之后即使是技术支持也无法恢复密钥。如果密钥泄露或不再需要，请使用撤销（集成会立即停止）。

/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（获取数据 ▸ Web）和 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 返回所查询数据集的第二页，每页 200 行（该数据集遵守 1,000 行上限，并在“truncado”中声明）。响应中包含 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进行分页。每个密钥限制每分钟120次请求（超出则返回HTTP 429）。

对公共 API 的每一次调用，都以“一个人”——密钥所有者——的权限作答。当密钥没有所有者，或所有者已离职时，就没有可适用的权限，平台有三种可能的姿态：观察（仅记录）、警告（照常响应，并返回一个表示将来会拒绝的响应头）和拒绝（403，响应体中附原因和修复方法）。目前该账户处于“警告”状态。

因为过早切换会让依赖该账户的集成中断——而依赖它的人恰恰是没在盯着的人。判断标准从来不是某个期限：而是这个页面上不再出现任何被标记的密钥。只要还有一个，就绪面板就会显示有多少个、是哪些、每个该怎么处理。降到零时，它会显示已就绪，切换就成了没有风险的决定。

数据源就是另一种格式的 v1 API：只读、限定在密钥所属账户范围内，并受同样的调用频率限制。撤销密钥会立即切断 Excel 和 Sheets。金额列遵循 API 对无所有者密钥的规则。

读取者是密钥所有者。其所在组的行规则（面板 ▸ 组件 ▸ “此数据源的行规则”）会在您的任何筛选之前生效；金额列只有在所有者可查看金额时才会输出——缺少的列是遮蔽，而不是错误。每次查询都会在审计中留下记录（谁、哪个数据集、多少行）。刻意不提供直连数据库：那会打破公司之间的隔离和金额管控。

API 密钥不会进入回收站：删除（或“吊销”按钮）会吊销密钥，立即停止认证，吊销记录保留在审计轨迹中。详情中只能编辑名称；MCP（读取）和写入范围通过“范围”按钮修改 — 写入为空即不允许任何写入。

在 设置 › API 密钥 中，"生成沙箱密钥"按钮会签发以 tnk_sbx_ 开头的密钥。它只能在沙箱地址使用：一台独立的服务器，使用演示数据，与生产环境版本相同，每周恢复到初始状态 — 可以放心测试读取和写入。有效期 90 天，每天最多 1,000 次调用；超过上限后，沙箱在午夜前返回"已达上限"。生产环境会拒绝它并给出说明，沙箱也会拒绝生产环境的密钥。生成时请保存密钥：它只显示一次。

平台开放 A2A 且账户在 设置 › 参数 › 集成 中开启后，其他 AI 代理使用本页的密钥向 Tenkai 下达任务。它只能看到密钥所有者能看到的内容。查询立即返回。像核销账单这样的操作只会被提议：任务等待，本人授权后代理在同一任务中确认；在此之前不会保存任何内容，提议 15 分钟后失效。要允许操作，请在密钥上勾选它可以提议的操作。每个请求都记入审计。

只有当密钥所有者能访问数据来源界面（布卷、批次追溯、外协加工、生产单、工艺单、裁剪单）时，布卷、批次、外发单、生产单、工艺单和裁剪票才会通过密钥输出。要新建外发或录入产量，密钥必须可写，且所有者能在该界面新增。请以操作这些界面的人员名义生成密钥；没有权限时，响应会说明缺少哪个界面。

Tenant管理员（与"用户和访问组"的对象相同）。密钥适用于整个公司——请像对待密码一样对待它们。

它会在这里被标记出来。目前调用仍会被响应，并在响应头中附带警告；切换之后，就会开始收到 403。这是最常见也最危险的情况：人走了几个月，集成仍在以一个已不在公司工作的人的权限运行。修复办法是为每个“在职”人员各签发一个密钥，并撤销旧的——绝不要通过转移所有者来继续使用旧密钥。

加载项需要 Microsoft Partner Center 账户、应用商店发布以及针对每个 Office 版本的维护——而且没有哪个竞品是从加载项做起的。OData 数据源是 Excel 和 Power BI 的原生途径，在 Mac 和浏览器中都能用，还能接入已有的表格。

横条提示您不在生产环境：验收环境（团队检查下一版本的服务器）、沙箱（集成测试环境，演示数据每周重建）或开发环境。这些服务器不会真正发出任何电子邮件、WhatsApp、收款、发票、手机通知或对其他系统的调用：一切都记录为已拦截。在生产环境中不会出现横条。