Ключи 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 (Получить данные ▸ Веб) и 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, и с последней строкой «# TRUNCADO», если строк больше 1000.

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. Если снимка нет (новая компания, или у владельца ключа есть правило строк, которое снимок не учитывает), API отвечает в реальном времени и сообщает об этом в `fonte`.

GET /api/v1/analitico/{dataset}?pagina=2&tamanho=200 возвращает вторую страницу по 200 строк запрошенного набора (который соблюдает потолок в 1000 строк, указанный в «truncado»). Ответ содержит pagina, tamanho, totalNaConsulta и temMais. Без параметров, как и раньше, приходит весь набор до потолка. Работает для JSON и CSV.

Сворачиваемый блок «Как пользоваться API» собирает правила (аутентификация, только чтение, область по компании, пагинация и лимит), эндпоинты, тестер, который вызывает сам API со вставленным ключом, и готовые URL фида для 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 для ключей без владельца.

Читает владелец ключа. Правила строк его группы («Панели ▸ компонент ▸ Правила строк для этого источника») применяются раньше любого вашего фильтра; денежные столбцы выводятся, только если владелец может видеть суммы, — отсутствующий столбец означает маску, а не ошибку. Каждый запрос оставляет след в «Аудите» (кто, какой набор, сколько строк). Прямого подключения к базе намеренно нет: оно нарушило бы изоляцию между компаниями и контроль над суммами.

Ключ API не попадает в корзину: удаление (или кнопка «Отозвать») отзывает ключ, он сразу перестаёт аутентифицировать, а отзыв остаётся в журнале аудита. В карточке меняется только название; область MCP (чтение) и записи меняется кнопкой «Область» — пустая запись означает никакой записи.

В Настройки › Ключи API кнопка «Создать ключ песочницы» выдаёт ключ, начинающийся с tnk_sbx_. Он работает только по адресу песочницы: это отдельный сервер с демо-данными, той же версии, что и продакшн, который каждую неделю возвращается в исходное состояние — проверяйте чтение и запись без опасений. Ключ действует 90 дней и до 1 000 вызовов в день; сверх лимита песочница отвечает «лимит достигнут» до полуночи. Продакшн отклоняет его с объяснением, а песочница отклоняет ключ продакшна. Сохраните ключ при создании: он показывается один раз.

Когда платформа открывает A2A, а аккаунт включает его в Настройки › Параметры › Интеграции, другой ИИ-агент использует ключ с этого экрана, чтобы ставить задачи Tenkai. Он видит только то, что видит владелец ключа. Запросы возвращаются сразу. Действия, например погашение счёта, только предлагаются: задача ждёт, человек разрешает, и агент подтверждает в той же задаче; до этого ничего не записывается, а предложение истекает через 15 минут. Чтобы разрешить действия, отметьте в ключе те, которые он может предлагать. Каждый запрос попадает в Аудит.

Рулоны, партии, отправки, производственные заказы, техкарты и талоны выдаются по ключу, только если у его владельца есть доступ к экрану, откуда эти данные (Рулоны, Прослеживание партии, Давальческая переработка, Производственные заказы, Техкарта, Заказ на раскрой). Чтобы открыть отправку или внести выработку, ключ должен разрешать запись, а владелец — иметь право добавлять на экране. Создавайте ключ на имя того, кто работает с этими экранами; без доступа ответ укажет, какого экрана не хватает.

Администратор tenant (та же аудитория, что и «Пользователи и группы доступа»). Ключи действуют для всей компании — относитесь к ним как к паролю.

Он отображается здесь с пометкой. Сейчас вызов ещё обслуживается и возвращается с предупреждением в заголовке; после переключения начнёт получать 403. Это самый частый и самый опасный случай: интеграция продолжает работать спустя месяцы после ухода, с доступом человека, который больше не работает в компании. Исправление — выпустить по ключу на каждого АКТИВНОГО человека и отозвать старый, никогда не переиспользовать ключ, передавая владельца.

Надстройка требует учётной записи Microsoft Partner Center, публикации в магазине и поддержки для каждой версии Office — и ни один из конкурентов с неё не начинает. Канал OData — родной путь для Excel и Power BI, работает на Mac и в браузере и встраивается в уже существующую таблицу.

Полоса сообщает, что вы не в продакшне: ТЕСТОВАЯ СРЕДА (сервер, где команда проверяет следующую версию), ПЕСОЧНИЦА (среда для проверки интеграций с демо-данными, пересоздаваемыми каждую неделю) или РАЗРАБОТКА. С этих серверов не уходят по-настоящему ни e-mail, ни WhatsApp, ни списания, ни счета, ни уведомления на телефон, ни вызовы других систем: всё записывается как заблокированное. В продакшне полосы нет.