Chaves de API

Gere e gerencie as chaves de API da sua empresa para integrar o Tenka com BI (Power BI, Metabase), planilhas ou sistemas próprios. Cada chave dá acesso somente-leitura aos seus dados via API REST.

Gere uma chave só para isso. No Excel: Dados ▸ Obter dados ▸ De outras fontes ▸ Feed OData ▸ cole a URL do feed; em Avançado, acrescente o cabeçalho Authorization com valor "Bearer SUA_CHAVE". O Excel lista as tabelas (Clientes, Contratos, Movimentações…) e segue as páginas sozinho. No Power BI é o mesmo caminho (OData feed).

Numa célula: =IMPORTDATA("…/api/v1/feed/csv/clientes.csv?api_key=SUA_CHAVE&sep=,&dec=."). O sep=, e o dec=. fazem o Sheets ler os números como números. Cada recurso tem o seu CSV (contratos.csv, movimentacoes.csv…).

A lista traz cada chave com o nome, o prefixo, quando foi criada e usada pela última vez, a situação, o escopo do MCP e a marca de identidade irregular. No topo ficam as regras de uma chave por pessoa, a prontidão para a virada da identidade e o painel Gerar chave — a chave nasce no seu nome e aparece em claro uma única vez: copie na hora.

Dê um nome (ex.: "Integração Power BI") e clique Gerar chave. A chave aparece uma única vez — copie e guarde num cofre de segredos. No banco fica só o hash; nem o suporte recupera a chave depois. Se vazar ou não precisar mais, use Revogar (a integração para na hora).

/api/v1/me — dados do seu tenant.
/api/v1/clientes — id, código, nome, CPF/CNPJ.
/api/v1/contratos — número, status, vigência.
/api/v1/movimentacoes — descrição, valor, vencimento, status.
/api/v1/tickets — demandas.

Use o bloco "Testar agora": cole a chave, escolha o recurso e clique Testar — o Tenka chama a própria API e mostra o JSON. Ou clique "Abrir explorador (Swagger UI)" para navegar e testar cada endpoint visualmente (botão Authorize → cole a chave). Para gerar cliente automático, baixe a especificação OpenAPI (JSON) e importe no Postman ou num gerador de código.

Se não houver nenhuma chave cadastrada, o painel diz MEDIDOR SEM DADO — e não "pronto para virar". A diferença importa: zero chaves marcadas em zero chaves existentes não prova nada, e tratar isso como aprovação é o jeito mais comum de um medidor mentir. Se a medição não conseguir classificar tudo, ele também avisa, em vez de completar a conta com um palpite.

Com a sua chave: GET https://SEU-TENKA/api/v1/analitico lista os datasets (os da plataforma e os que a sua empresa criou no BI), com as colunas e o que é filtrável. Para trazer um dataset: GET /api/v1/analitico/financeiro?formato=csv — o Power BI (Obter dados ▸ Web) e o Metabase (fonte CSV/URL) leem direto. Parâmetros: colunas=a,b · filtros=campo=valor;campo2>valor2;campo3~contem · agrupamento=campo · funcao=SOMA|MEDIA|CONTAGEM|MAIOR|MENOR|MEDIANA. O JSON traz count, truncado e regrasDeLinhaAplicadas; o CSV vem com BOM para o Excel abrir em UTF-8 e uma última linha "# TRUNCADO" quando passou de 1.000 linhas.

O servidor MCP do Tenka (/mcp, com a mesma chave) passou a oferecer listar_datasets_bi (o catálogo), metricas_do_dataset_bi (o que dá para medir numa fonte) e consultar_dataset_bi (as linhas, ou o agrupamento por uma dimensão, até 50 linhas por resposta com o total declarado). Um Claude ou Copilot ligado ao seu Tenka responde "quanto vendemos por cliente este mês" lendo o dataset governado — nunca o banco. As regras de linha e o Ver Valores do dono da chave valem igual.

Acrescente ?fonte=snapshot à consulta do dataset (/api/v1/analitico/financeiro?fonte=snapshot&formato=csv) para receber o retrato gravado na hora configurada da empresa, com atualizadoEm na resposta — instantâneo e sem tocar o banco operacional, ideal para o Power BI atualizar de madrugada. Quando não há retrato (empresa nova, ou o dono da chave tem regra de linha, que o retrato não recorta), a API responde ao vivo e diz isso em `fonte`.

GET /api/v1/analitico/{dataset}?pagina=2&tamanho=200 devolve a segunda página de 200 linhas do conjunto consultado (que respeita o teto de 1.000 linhas, declarado em "truncado"). A resposta traz pagina, tamanho, totalNaConsulta e temMais. Sem os parâmetros, vem o conjunto inteiro até o teto, como antes. Vale para JSON e CSV.

O quadro recolhível "Como usar a API" reúne as regras (autenticação, somente leitura, escopo por empresa, paginação e limite), os endpoints, o testador que chama a própria API com a chave colada e as URLs prontas do feed para Excel, Power BI e 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.

Ler só os rolos que mudaram: GET /api/v1/rolos?desde=2026-10-17T00:00:00 com o cabeçalho Authorization: Bearer ; guarde a data do último rolo recebido e use-a no próximo desde. Mandar rolos ao beneficiador: POST /api/v1/remessas com os cabeçalhos Authorization: Bearer e Idempotency-Key: e o corpo {"idFornecedor": 12, "tipoServico": "TINTURARIA", "rolos": [101, 102]}. Repetir a chamada com o mesmo Idempotency-Key devolve a mesma remessa, sem duplicar. A chave precisa poder escrever e só alcança as telas que o perfil dela vê.

Envie a chave no cabeçalho Authorization: Bearer <chave> (ou X-API-Key). Exemplo:
curl -H "Authorization: Bearer tnk_..." SEU_TENKA/api/v1/clientes?limit=50

A chave só enxerga os dados da sua empresa (isolamento por tenant). É somente leitura (GET). Paginação por ?limit (máx. 200) e ?offset. Limite de 120 requisições por minuto por chave (retorna HTTP 429 se exceder).

Toda chamada à API pública responde com o acesso de UMA pessoa — a dona da chave. Quando a chave não tem dono, ou o dono foi desligado, não existe acesso a aplicar, e a plataforma tem três posturas possíveis: OBSERVAR (só registra), AVISAR (atende e devolve um cabeçalho dizendo que um dia vai recusar) e RECUSAR (403, com o motivo e o conserto no corpo). Hoje a conta está em AVISAR.

Porque virar antes da hora derruba a integração de quem confia na conta — e quem confia é justamente quem não está olhando. O critério nunca foi um prazo: é esta tela não mostrar mais nenhuma chave marcada. Enquanto houver uma, o painel de prontidão diz quantas são, quais são e o que fazer com cada uma. Quando chegar a zero, ele diz que está pronto, e a virada passa a ser uma decisão sem risco.

O feed é a API v1 em outro formato: somente leitura, escopado à conta da chave, com o mesmo rate-limit. Revogar a chave corta o Excel e o Sheets na hora. Coluna monetária segue a regra da API para chave sem dono.

Quem lê é o dono da chave. As regras de linha do grupo dele (Painéis ▸ componente ▸ "Regras de linha para esta fonte") são aplicadas antes de qualquer filtro seu; colunas de valor só saem se o dono pode ver valores — a coluna que falta é a máscara, não um erro. Toda consulta deixa rastro na Auditoria (quem, qual dataset, quantas linhas). Conexão direta ao banco não existe de propósito: ela furaria o isolamento entre empresas e a governança de valores.

Chave de API não vai para a lixeira: excluir (ou o botão Revogar) revoga a chave, que para de autenticar na hora, e a revogação fica na trilha de auditoria. Na ficha só o nome se edita; o escopo do MCP (leitura) e de escrita muda pelo botão Escopo — escrita vazia é nenhuma escrita.

Em Configurações › Chaves de API, o botão "Gerar chave de sandbox" emite uma chave que começa com tnk_sbx_. Ela só funciona no endereço da sandbox: um servidor separado, com dados de demonstração, na mesma versão da produção, que volta ao estado inicial toda semana — teste leitura e escrita à vontade. Vale 90 dias e até 1.000 chamadas por dia; passando do teto, a sandbox responde "limite atingido" até a meia-noite. Na produção ela é recusada com a explicação, e a chave de produção é recusada na sandbox. Guarde a chave ao gerar: ela aparece uma única vez.

Quando a plataforma abre o A2A e a conta liga em Configurações › Parâmetros › Integrações, outro agente de IA usa uma chave desta tela para pedir tarefas ao Tenkai. Ele vê só o que a pessoa dona da chave vê. Consultas voltam na hora. Ações, como baixar um título, só são propostas: a tarefa fica esperando, a pessoa autoriza e o agente confirma na mesma tarefa; antes disso nada é gravado, e a proposta vence em 15 minutos. Para permitir ações, marque na chave as que ela pode propor. Cada pedido fica na Auditoria.

Rolos, lotes, remessas, ordens de produção, fichas técnicas e talões só saem pela chave se a pessoa dona dela tiver acesso à tela de onde o dado vem (Rolos, Rastro do lote, Industrialização, Ordens de produção, Ficha técnica, Ordem de corte). Para abrir remessa ou lançar apontamento, a chave precisa ser de escrita e o dono precisa poder incluir na tela. Gere a chave no nome de quem opera essas telas; sem acesso, a resposta diz qual tela falta.

Administrador do tenant (mesma audiência de "Usuários e grupos de acesso"). As chaves valem para a empresa toda — trate-as como senha.

Ela aparece marcada aqui. Hoje a chamada ainda é atendida e volta com um aviso no cabeçalho; depois da virada, passa a receber 403. É o caso mais comum e o mais perigoso: a integração continua funcionando meses depois da saída, com o acesso de alguém que não trabalha mais na casa. O conserto é emitir uma chave por pessoa ATIVA e revogar a antiga — nunca reaproveitar a chave transferindo o dono.

Add-in exige conta Microsoft Partner Center, publicação em loja e manutenção por versão do Office — e nenhum dos concorrentes começa por ele. O feed OData é o caminho nativo do Excel e do Power BI, funciona no Mac e no navegador, e entra em planilha que já existe.

A faixa avisa que você não está na produção: HOMOLOGAÇÃO (o servidor onde a equipe confere a próxima versão), SANDBOX (o ambiente de testes de integração, com dados de demonstração recriados toda semana) ou DESENVOLVIMENTO. Nesses servidores nenhum e-mail, WhatsApp, cobrança, nota fiscal, aviso no celular ou chamada para outro sistema sai de verdade: tudo fica registrado como bloqueado. Na produção a faixa não aparece.