APIキー

BI（Power BI、Metabase）、スプレッドシート、または独自システムとTenkaを連携させるために、自社のAPIキーを生成・管理します。各キーは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 の範囲、ID 不備のマークが表示されます。上部には「1人1キー」のルール、ID 切り替えの準備状況、キー生成パネルがあります — キーはあなたの名義で作成され、平文で表示されるのは一度だけなので、すぐにコピーしてください。

名前を付けて（例：「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やコードジェネレーターにインポートしてください。

キーが1つも登録されていなければ、パネルは「準備完了」ではなく「データのない計器」と表示します。この違いは重要です。存在するキーがゼロのうち印付きがゼロでも何も証明しておらず、それを承認とみなすのは計器が嘘をつく最もよくあるパターンです。測定ですべてを分類できない場合も、推測で数を埋めるのではなく、その旨を警告します。

キーを使って：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 は Excel が UTF-8 で開けるよう BOM 付きで、1,000 行を超えた場合は最終行に「# TRUNCADO」が付きます。

Tenka の MCP サーバー（/mcp、同じキー）では、listar_datasets_bi（カタログ）、metricas_do_dataset_bi（ソースで何を測れるか）、consultar_dataset_bi（行、または1つのディメンションでのグループ化、総数を明示して1回の回答につき最大 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 行ずつの 2 ページ目を返します。応答には 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.

変更された反物だけを読む：ヘッダー Authorization: Bearer <あなたのキー> を付けて GET /api/v1/rolos?desde=2026-10-17T00:00:00。最後に受け取った反物の日時を保存し、次の desde に使います。加工先へ反物を送る：ヘッダー Authorization: Bearer <あなたのキー> と Idempotency-Key: <送り状ごとの一意のコード>、本文 {"idFornecedor": 12, "tipoServico": "TINTURARIA", "rolos": [101, 102]} で POST /api/v1/remessas。同じ 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で行います。キーごとに1分間に120リクエストの上限があります（超えるとHTTP 429を返します）。

公開 API への呼び出しはすべて、「1人」の人物 — キーの所有者 — のアクセス権で応答します。キーに所有者がいない、あるいは所有者が退職している場合は適用すべきアクセス権がなく、プラットフォームには3つの姿勢があり得ます。「観察」（記録だけ）、「警告」（応答し、いずれ拒否するというヘッダーを返す）、「拒否」（403、本文に理由と対処法）。現在、このアカウントは「警告」です。

早すぎる切り替えは、このアカウントに頼っている人の連携を止めてしまうからです — しかも頼っているのは、まさに見ていない人たちです。基準が期限だったことは一度もありません。この画面に印の付いたキーが1つもなくなることが基準です。1つでも残っている間は、準備状況パネルが、何個あるか、どれか、それぞれどうすべきかを示します。ゼロになれば準備完了と表示され、切り替えはリスクのない判断になります。

フィードは別形式の v1 API です。読み取り専用で、キーのアカウントに限定され、同じレート制限が適用されます。キーを取り消すと、Excel と Sheets は即座に遮断されます。金額の列は、所有者のいないキーに関する API のルールに従います。

読み取るのはキーの所有者です。所有者のグループの行ルール（ダッシュボード ▸ コンポーネント ▸「このソースの行ルール」）が、あなたのどのフィルタよりも先に適用されます。金額の列は所有者が金額を見られる場合にだけ出力され — 欠けている列はエラーではなくマスクです。すべてのクエリは監査（誰が、どのデータセットを、何行）に記録されます。データベースへの直接接続は意図的に用意していません。会社間の分離と金額のガバナンスを破ってしまうからです。

API キーはごみ箱に入りません。削除（または失効ボタン）でキーは失効し、すぐに認証できなくなり、失効は監査証跡に残ります。詳細画面で編集できるのは名前だけです。MCP（読み取り）と書き込みの範囲は「範囲」ボタンで変更します — 書き込みが空なら書き込みは一切できません。

設定 › APIキー の「サンドボックスキーを発行」ボタンで、tnk_sbx_ で始まるキーが発行されます。使えるのはサンドボックスのアドレスだけです：デモデータを持つ別サーバーで、本番と同じバージョン、毎週初期状態に戻ります — 読み取りも書き込みも自由にテストできます。有効期間は90日、1日最大1,000回の呼び出しで、上限を超えると深夜0時まで「上限に達しました」と応答します。本番では理由とともに拒否され、サンドボックスでは本番キーが拒否されます。キーは発行時に保存してください：表示は一度だけです。

プラットフォームが A2A を開き、アカウントが 設定 › パラメーター › 連携 で有効にすると、別の AI エージェントがこの画面のキーを使って Tenkai にタスクを依頼します。エージェントはキーの所有者が見られるものだけを見ます。照会はすぐに返ります。請求の消込などの操作は提案だけされ、タスクは待機し、本人が承認してエージェントが同じタスクで確定します。それまでは何も保存されず、提案は 15 分で失効します。操作を許可するには、キーに提案できる操作を設定します。すべての依頼は監査に記録されます。

ロール、ロット、外注出荷、製造指図、仕様書、裁断票は、キーの持ち主がデータ元の画面（ロール、ロット追跡、外注加工、製造指図、仕様書、裁断指図）にアクセスできる場合だけキーで出力されます。外注出荷や生産実績の登録には、書き込み可能なキーで、持ち主がその画面で追加できる必要があります。これらの画面を使う人の名前でキーを作成してください。アクセスがない場合、応答で不足している画面が示されます。

tenant管理者（「ユーザーとアクセスグループ」と同じ対象者）。キーは会社全体に適用されます — パスワードと同様に扱ってください。

ここに印付きで表示されます。今は呼び出しにまだ応答し、ヘッダーに警告を付けて返しますが、切り替え後は 403 を受け取るようになります。最もよくあり、最も危険なケースです。退職から何か月もたっても、もう社内で働いていない人のアクセス権で連携が動き続けるのです。対処は、「在籍中の」人ごとにキーを発行し、古いキーを取り消すことです — 所有者を移してキーを使い回すことは決してしないでください。

アドインには Microsoft Partner Center のアカウント、ストアでの公開、Office のバージョンごとの保守が必要で — しかもどの競合もそこから始めてはいません。OData フィードは Excel と Power BI のネイティブな手段で、Mac でもブラウザでも動き、既存のスプレッドシートに組み込めます。

帯は本番ではないことを示します：検証環境（チームが次のバージョンを確認するサーバー）、サンドボックス（連携テスト用の環境で、デモデータを毎週作り直し）、または開発環境です。これらのサーバーからはメール、WhatsApp、請求、請求書、スマートフォン通知、他システムへの呼び出しが実際に送られることはなく、すべてブロックとして記録されます。本番では帯は表示されません。