Llaves de API

Genere y gestione las claves de API de su empresa para integrar Tenka con BI (Power BI, Metabase), hojas de cálculo o sistemas propios. Cada clave da acceso solo lectura a sus datos vía API REST.

Genere una clave solo para esto. En Excel: Datos ▸ Obtener datos ▸ De otras fuentes ▸ Fuente OData ▸ pegue la URL del feed; en Avanzado, agregue el encabezado Authorization con el valor "Bearer SUA_CHAVE". Excel lista las tablas (Clientes, Contratos, Movimientos…) y sigue las páginas solo. En Power BI es el mismo camino (fuente OData).

En una celda: =IMPORTDATA("…/api/v1/feed/csv/clientes.csv?api_key=SUA_CHAVE&sep=,&dec=."). El sep=, y el dec=. hacen que Sheets lea los números como números. Cada recurso tiene su CSV (contratos.csv, movimentacoes.csv…).

La lista trae cada clave con el nombre, el prefijo, cuándo se creó y se usó por última vez, la situación, el alcance del MCP y la marca de identidad irregular. Arriba están las reglas de una clave por persona, la preparación para el cambio de identidad y el panel Generar clave — la clave nace a su nombre y aparece en claro una sola vez: cópiela en el acto.

Dele un nombre (ej.: "Integración Power BI") y haga clic en Generar clave. La clave aparece una única vez — cópiela y guárdela en un gestor de secretos. En la base de datos solo queda el hash; ni siquiera el soporte puede recuperar la clave después. Si se filtra o ya no la necesita, use Revocar (la integración se detiene de inmediato).

/api/v1/me — datos de su tenant.
/api/v1/clientes — id, código, nombre, CPF/CNPJ.
/api/v1/contratos — número, estado, vigencia.
/api/v1/movimentacoes — descripción, valor, vencimiento, estado.
/api/v1/tickets — solicitudes.

Use el bloque "Probar ahora": pegue la clave, elija el recurso y haga clic en Probar — Tenka llama a su propia API y muestra el JSON. O haga clic en "Abrir explorador (Swagger UI)" para navegar y probar cada endpoint visualmente (botón Authorize → pegue la clave). Para generar un cliente automático, descargue la especificación OpenAPI (JSON) e impórtela en Postman o en un generador de código.

Si no hay ninguna clave registrada, el panel dice MEDIDOR SIN DATOS — y no "listo para cambiar". La diferencia importa: cero claves marcadas en cero claves existentes no prueba nada, y tratar eso como aprobación es la forma más común de que un medidor mienta. Si la medición no consigue clasificar todo, también avisa, en lugar de completar la cuenta con una suposición.

Con su clave: GET https://SEU-TENKA/api/v1/analitico lista los datasets (los de la plataforma y los que su empresa creó en el BI), con las columnas y lo que es filtrable. Para traer un dataset: GET /api/v1/analitico/financeiro?formato=csv — Power BI (Obtener datos ▸ Web) y Metabase (fuente CSV/URL) lo leen directo. Parámetros: colunas=a,b · filtros=campo=valor;campo2>valor2;campo3~contem · agrupamento=campo · funcao=SOMA|MEDIA|CONTAGEM|MAIOR|MENOR|MEDIANA. El JSON trae count, truncado y regrasDeLinhaAplicadas; el CSV viene con BOM para que Excel lo abra en UTF-8 y una última línea "# TRUNCADO" cuando pasó de 1.000 filas.

El servidor MCP del Tenka (/mcp, con la misma clave) pasó a ofrecer listar_datasets_bi (el catálogo), metricas_do_dataset_bi (lo que se puede medir en una fuente) y consultar_dataset_bi (las filas, o el agrupamiento por una dimensión, hasta 50 filas por respuesta con el total declarado). Un asistente de IA conectado a su Tenka responde "cuánto vendimos por cliente este mes" leyendo el dataset gobernado — nunca la base. Las reglas de fila y el Ver Valores del dueño de la clave valen igual.

Agregue ?fonte=snapshot a la consulta del dataset (/api/v1/analitico/financeiro?fonte=snapshot&formato=csv) para recibir la foto grabada a la hora configurada de la empresa, con atualizadoEm en la respuesta — instantánea y sin tocar la base operativa, ideal para que Power BI se actualice de madrugada. Cuando no hay foto (empresa nueva, o el dueño de la clave tiene regla de fila, que la foto no recorta), la API responde en vivo y lo dice en `fonte`.

GET /api/v1/analitico/{dataset}?pagina=2&tamanho=200 devuelve la segunda página de 200 filas del conjunto consultado (que respeta el tope de 1.000 filas, declarado en "truncado"). La respuesta trae pagina, tamanho, totalNaConsulta y temMais. Sin los parámetros, viene el conjunto entero hasta el tope, como antes. Vale para JSON y CSV.

El cuadro plegable "Cómo usar la API" reúne las reglas (autenticación, solo lectura, alcance por empresa, paginación y límite), los endpoints, el probador que llama a la propia API con la clave pegada y las URL listas del feed para Excel, Power BI y 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.

Leer solo los rollos que cambiaron: GET /api/v1/rolos?desde=2026-10-17T00:00:00 con la cabecera Authorization: Bearer ; guarde la fecha del último rollo recibido y úsela en el próximo desde. Enviar rollos al beneficiador: POST /api/v1/remessas con las cabeceras Authorization: Bearer e Idempotency-Key: y el cuerpo {"idFornecedor": 12, "tipoServico": "TINTURARIA", "rolos": [101, 102]}. Repetir la llamada con el mismo Idempotency-Key devuelve la misma remesa, sin duplicarla. La clave necesita permiso de escritura y solo alcanza las pantallas que ve su perfil.

Envíe la clave en el encabezado Authorization: Bearer <clave> (o X-API-Key). Ejemplo:
curl -H "Authorization: Bearer tnk_..." SEU_TENKA/api/v1/clientes?limit=50

La clave solo ve los datos de su empresa (aislamiento por tenant). Es de solo lectura (GET). Paginación mediante ?limit (máx. 200) y ?offset. Límite de 120 solicitudes por minuto por clave (devuelve HTTP 429 si se excede).

Toda llamada a la API pública responde con el acceso de UNA persona — la dueña de la clave. Cuando la clave no tiene dueño, o el dueño fue desvinculado, no existe acceso a aplicar, y la plataforma tiene tres posturas posibles: OBSERVAR (solo registra), AVISAR (atiende y devuelve un encabezado diciendo que un día va a rechazar) y RECHAZAR (403, con el motivo y el arreglo en el cuerpo). Hoy la cuenta está en AVISAR.

Porque cambiar antes de tiempo tumba la integración de quien confía en la cuenta — y quien confía es justamente quien no está mirando. El criterio nunca fue un plazo: es que esta pantalla ya no muestre ninguna clave marcada. Mientras haya una, el panel de preparación dice cuántas son, cuáles son y qué hacer con cada una. Cuando llegue a cero, dice que está listo, y el cambio pasa a ser una decisión sin riesgo.

El feed es la API v1 en otro formato: solo lectura, con alcance a la cuenta de la clave, con el mismo rate-limit. Revocar la clave corta Excel y Sheets en el acto. Las columnas monetarias siguen la regla de la API para clave sin dueño.

Quien lee es el dueño de la clave. Las reglas de fila de su grupo (Paneles ▸ componente ▸ "Reglas de fila para esta fuente") se aplican antes de cualquier filtro suyo; las columnas de valor solo salen si el dueño puede ver valores — la columna que falta es la máscara, no un error. Toda consulta deja rastro en la Auditoría (quién, qué dataset, cuántas filas). La conexión directa a la base no existe a propósito: rompería el aislamiento entre empresas y la gobernanza de valores.

La clave de API no va a la papelera: excluir (o el botón Revocar) revoca la clave, que deja de autenticar en el acto, y la revocación queda en la auditoría. En la ficha solo se edita el nombre; el alcance del MCP (lectura) y de escritura cambia por el botón Alcance — escritura vacía es ninguna escritura.

En Configuración › Claves de API, el botón "Generar clave de sandbox" emite una clave que empieza con tnk_sbx_. Solo funciona en la dirección del sandbox: un servidor separado, con datos de demostración, en la misma versión de producción, que vuelve al estado inicial cada semana — pruebe lectura y escritura libremente. Vale 90 días y hasta 1.000 llamadas por día; por encima del límite, el sandbox responde "límite alcanzado" hasta la medianoche. Producción la rechaza con la explicación, y el sandbox rechaza la clave de producción. Guarde la clave al generarla: aparece una sola vez.

Cuando la plataforma abre A2A y la cuenta lo activa en Configuración › Parámetros › Integraciones, otro agente de IA usa una clave de esta pantalla para pedir tareas a Tenkai. Ve solo lo que ve la persona dueña de la clave. Las consultas vuelven al instante. Las acciones, como dar de baja un título, solo se proponen: la tarea espera, la persona autoriza y el agente confirma en la misma tarea; antes nada se graba, y la propuesta vence en 15 minutos. Para permitir acciones, marque en la clave las que puede proponer. Cada pedido queda en la Auditoría.

Rollos, lotes, remesas, órdenes de producción, fichas técnicas y talones solo salen por la clave si la persona dueña tiene acceso a la pantalla de donde viene el dato (Rollos, Rastro del lote, Industrialización, Órdenes de producción, Ficha técnica, Orden de corte). Para abrir remesa o registrar producción, la clave debe ser de escritura y el dueño debe poder incluir en la pantalla. Genere la clave a nombre de quien opera esas pantallas; sin acceso, la respuesta dice qué pantalla falta.

Administrador del tenant (misma audiencia de "Usuarios y grupos de acceso"). Las claves valen para toda la empresa — trátelas como una contraseña.

Aparece marcada aquí. Hoy la llamada todavía se atiende y vuelve con un aviso en el encabezado; después del cambio, pasa a recibir 403. Es el caso más común y el más peligroso: la integración sigue funcionando meses después de la salida, con el acceso de alguien que ya no trabaja en la casa. El arreglo es emitir una clave por persona ACTIVA y revocar la antigua — nunca reaprovechar la clave transfiriendo el dueño.

Un add-in exige cuenta de Microsoft Partner Center, publicación en tienda y mantenimiento por versión de Office — y ninguno de los competidores empieza por él. El feed OData es el camino nativo de Excel y de Power BI, funciona en Mac y en el navegador, y entra en una planilla que ya existe.

La franja avisa que usted no está en producción: HOMOLOGACIÓN (el servidor donde el equipo revisa la próxima versión), SANDBOX (el entorno de pruebas de integración, con datos de demostración recreados cada semana) o DESARROLLO. En esos servidores ningún correo, WhatsApp, cobro, factura, aviso al celular o llamada a otro sistema sale de verdad: todo queda registrado como bloqueado. En producción la franja no aparece.