Clés API

Générez et gérez les clés d'API de votre entreprise pour intégrer Tenka avec un BI (Power BI, Metabase), des feuilles de calcul ou vos propres systèmes. Chaque clé donne un accès en lecture seule à vos données via l'API REST.

Générez une clé rien que pour cela. Dans Excel : Données ▸ Obtenir des données ▸ À partir d'autres sources ▸ Flux OData ▸ collez l'URL du flux ; dans Avancé, ajoutez l'en-tête Authorization avec la valeur « Bearer SUA_CHAVE ». Excel liste les tables (Clients, Contrats, Mouvements…) et suit les pages tout seul. Dans Power BI, c'est le même chemin (flux OData).

Dans une cellule : =IMPORTDATA("…/api/v1/feed/csv/clientes.csv?api_key=SUA_CHAVE&sep=,&dec=."). Le sep=, et le dec=. font que Sheets lit les nombres comme des nombres. Chaque ressource a son propre CSV (contratos.csv, movimentacoes.csv…).

La liste montre chaque clé avec le nom, le préfixe, la date de création et de dernier usage, la situation, la portée du MCP et la marque d’identité irrégulière. En haut, les règles d’une clé par personne, la préparation au basculement d’identité et le panneau Générer une clé — la clé est créée à votre nom et affichée en clair une seule fois : copiez-la tout de suite.

Donnez-lui un nom (ex. : « Intégration Power BI ») et cliquez sur Générer une clé. La clé n'apparaît qu'une seule fois — copiez-la et conservez-la dans un coffre-fort de secrets. Seul le hash reste en base ; même le support ne peut plus récupérer la clé ensuite. En cas de fuite ou si elle n'est plus nécessaire, utilisez Révoquer (l'intégration s'arrête immédiatement).

/api/v1/me — données de votre tenant.
/api/v1/clientes — id, code, nom, CPF/CNPJ.
/api/v1/contratos — numéro, statut, validité.
/api/v1/movimentacoes — description, montant, échéance, statut.
/api/v1/tickets — demandes.

Utilisez le bloc « Tester maintenant » : collez la clé, choisissez la ressource et cliquez sur Tester — Tenka appelle sa propre API et affiche le JSON. Ou cliquez sur « Ouvrir l'explorateur (Swagger UI) » pour parcourir et tester chaque endpoint visuellement (bouton Authorize → collez la clé). Pour générer un client automatique, téléchargez la spécification OpenAPI (JSON) et importez-la dans Postman ou un générateur de code.

S'il n'y a aucune clé enregistrée, le panneau affiche COMPTEUR SANS DONNÉES — et non « prêt à basculer ». La différence compte : zéro clé signalée sur zéro clé existante ne prouve rien, et traiter cela comme une approbation est la façon la plus courante pour un compteur de mentir. Si la mesure ne parvient pas à tout classer, il le signale aussi, au lieu de compléter le calcul par une supposition.

Avec votre clé : GET https://SEU-TENKA/api/v1/analitico liste les jeux de données (ceux de la plateforme et ceux que votre entreprise a créés dans la BI), avec les colonnes et ce qui est filtrable. Pour récupérer un jeu de données : GET /api/v1/analitico/financeiro?formato=csv — Power BI (Obtenir des données ▸ Web) et Metabase (source CSV/URL) le lisent directement. Paramètres : colunas=a,b · filtros=campo=valor;campo2>valor2;campo3~contem · agrupamento=campo · funcao=SOMA|MEDIA|CONTAGEM|MAIOR|MENOR|MEDIANA. Le JSON contient count, truncado et regrasDeLinhaAplicadas ; le CSV arrive avec un BOM pour qu'Excel l'ouvre en UTF-8 et une dernière ligne « # TRUNCADO » quand il a dépassé 1 000 lignes.

Le serveur MCP du Tenka (/mcp, avec la même clé) propose désormais listar_datasets_bi (le catalogue), metricas_do_dataset_bi (ce qu'on peut mesurer dans une source) et consultar_dataset_bi (les lignes, ou le regroupement par une dimension, jusqu'à 50 lignes par réponse avec le total déclaré). Un assistant IA connecté à votre Tenka répond à « combien avons-nous vendu par client ce mois-ci » en lisant le jeu de données gouverné — jamais la base. Les règles de ligne et le Voir les montants du propriétaire de la clé s'appliquent de la même façon.

Ajoutez ?fonte=snapshot à la requête du jeu de données (/api/v1/analitico/financeiro?fonte=snapshot&formato=csv) pour recevoir l'instantané enregistré à l'heure configurée de l'entreprise, avec atualizadoEm dans la réponse — immédiat et sans toucher la base opérationnelle, idéal pour que Power BI se mette à jour la nuit. Quand il n'y a pas d'instantané (nouvelle entreprise, ou le propriétaire de la clé a une règle de ligne, que l'instantané ne filtre pas), l'API répond en direct et l'indique dans `fonte`.

GET /api/v1/analitico/{dataset}?pagina=2&tamanho=200 renvoie la deuxième page de 200 lignes de l'ensemble interrogé (qui respecte le plafond de 1 000 lignes, déclaré dans « truncado »). La réponse contient pagina, tamanho, totalNaConsulta et temMais. Sans les paramètres, l'ensemble complet arrive jusqu'au plafond, comme avant. Cela vaut pour JSON et CSV.

Le cadre repliable « Utiliser l’API » réunit les règles (authentification, lecture seule, portée par entreprise, pagination et limite), les endpoints, le testeur qui appelle l’API avec la clé collée et les URL prêtes du flux pour Excel, Power BI et 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.

Lire seulement les rouleaux modifiés : GET /api/v1/rolos?desde=2026-10-17T00:00:00 avec l’en-tête Authorization: Bearer ; gardez la date du dernier rouleau reçu et utilisez-la comme prochain desde. Envoyer des rouleaux au façonnier : POST /api/v1/remessas avec les en-têtes Authorization: Bearer et Idempotency-Key: et le corps {"idFornecedor": 12, "tipoServico": "TINTURARIA", "rolos": [101, 102]}. Répéter l’appel avec la même Idempotency-Key renvoie le même envoi, sans doublon. La clé doit pouvoir écrire et n’atteint que les écrans que voit son profil.

Envoyez la clé dans l'en-tête Authorization: Bearer <clé> (ou X-API-Key). Exemple :
curl -H "Authorization: Bearer tnk_..." SEU_TENKA/api/v1/clientes?limit=50

La clé ne voit que les données de votre entreprise (isolation par tenant). Elle est en lecture seule (GET). Pagination via ?limit (max. 200) et ?offset. Limite de 120 requêtes par minute par clé (renvoie HTTP 429 en cas de dépassement).

Chaque appel à l'API publique répond avec l'accès d'UNE personne — le propriétaire de la clé. Quand la clé n'a pas de propriétaire, ou que le propriétaire est parti, il n'y a aucun accès à appliquer, et la plateforme a trois postures possibles : OBSERVER (enregistre seulement), AVERTIR (répond et renvoie un en-tête disant qu'un jour elle refusera) et REFUSER (403, avec le motif et la correction dans le corps). Aujourd'hui, le compte est en AVERTIR.

Parce que basculer trop tôt fait tomber l'intégration de ceux qui comptent sur le compte — et ceux qui comptent dessus sont justement ceux qui ne regardent pas. Le critère n'a jamais été un délai : c'est que cet écran n'affiche plus aucune clé signalée. Tant qu'il en reste une, le panneau de préparation dit combien il y en a, lesquelles et quoi faire de chacune. Quand il arrive à zéro, il dit que c'est prêt, et la bascule devient une décision sans risque.

Le flux est l'API v1 sous un autre format : lecture seule, limité au compte de la clé, avec le même rate-limit. Révoquer la clé coupe Excel et Sheets immédiatement. Les colonnes monétaires suivent la règle de l'API pour les clés sans propriétaire.

Celui qui lit, c'est le propriétaire de la clé. Les règles de ligne de son groupe (Tableaux de bord ▸ composant ▸ « Règles de ligne pour cette source ») sont appliquées avant tout filtre de votre part ; les colonnes de montant ne sortent que si le propriétaire peut voir les montants — la colonne manquante est le masque, pas une erreur. Chaque requête laisse une trace dans l'Audit (qui, quel jeu de données, combien de lignes). La connexion directe à la base n'existe volontairement pas : elle romprait l'isolement entre entreprises et la gouvernance des montants.

Une clé d’API ne va pas à la corbeille : supprimer (ou le bouton Révoquer) révoque la clé, qui cesse aussitôt d’authentifier, et la révocation reste dans la piste d’audit. Sur la fiche, seul le nom se modifie ; la portée MCP (lecture) et d’écriture change via le bouton Portée — écriture vide signifie aucune écriture.

Dans Paramètres › Clés d’API, le bouton « Générer une clé de sandbox » émet une clé qui commence par tnk_sbx_. Elle ne fonctionne qu’à l’adresse de la sandbox : un serveur séparé, avec des données de démonstration, dans la même version que la production, qui revient à l’état initial chaque semaine — testez lecture et écriture librement. Elle est valable 90 jours et jusqu’à 1 000 appels par jour ; au-delà, la sandbox répond « limite atteinte » jusqu’à minuit. La production la refuse avec l’explication, et la sandbox refuse la clé de production. Conservez la clé à sa création : elle n’est affichée qu’une fois.

Quand la plateforme ouvre A2A et que le compte l’active dans Paramètres › Paramètres › Intégrations, un autre agent IA utilise une clé de cet écran pour confier des tâches à Tenkai. Il ne voit que ce que voit la personne propriétaire de la clé. Les consultations reviennent tout de suite. Les actions, comme solder une facture, sont seulement proposées : la tâche attend, la personne autorise et l’agent confirme dans la même tâche ; avant cela rien n’est enregistré, et la proposition expire au bout de 15 minutes. Pour permettre des actions, cochez sur la clé celles qu’elle peut proposer. Chaque demande va dans l’Audit.

Rouleaux, lots, envois, ordres de fabrication, fiches techniques et bons de coupe ne sortent par la clé que si son propriétaire a accès à l’écran d’où vient la donnée (Rouleaux, Traçabilité du lot, Façonnage, Ordres de fabrication, Fiche technique, Ordre de coupe). Pour ouvrir un envoi ou déclarer la production, la clé doit permettre l’écriture et le propriétaire doit pouvoir créer sur l’écran. Créez la clé au nom de qui utilise ces écrans ; sans accès, la réponse indique l’écran manquant.

Administrateur du tenant (même public que « Utilisateurs et groupes d'accès »). Les clés s'appliquent à toute l'entreprise — traitez-les comme un mot de passe.

Elle apparaît signalée ici. Aujourd'hui, l'appel est encore servi et revient avec un avertissement dans l'en-tête ; après la bascule, il reçoit un 403. C'est le cas le plus fréquent et le plus dangereux : l'intégration continue de fonctionner des mois après le départ, avec l'accès de quelqu'un qui ne travaille plus dans l'entreprise. La correction consiste à émettre une clé par personne ACTIVE et à révoquer l'ancienne — jamais réutiliser la clé en transférant le propriétaire.

Un complément exige un compte Microsoft Partner Center, une publication en boutique et une maintenance par version d'Office — et aucun des concurrents ne commence par là. Le flux OData est le chemin natif d'Excel et de Power BI, fonctionne sur Mac et dans le navigateur, et s'intègre à un classeur qui existe déjà.

La bande indique que vous n’êtes pas en production : RECETTE (le serveur où l’équipe vérifie la prochaine version), SANDBOX (l’environnement de test d’intégration, avec des données de démonstration recréées chaque semaine) ou DÉVELOPPEMENT. Sur ces serveurs, aucun e-mail, WhatsApp, encaissement, facture, notification mobile ni appel vers un autre système ne part réellement : tout est enregistré comme bloqué. En production, la bande n’apparaît pas.