Permitir que outros softwares leiam seus dados

O API Studio: publicação de uma tela por vez, emissão de uma chave, vinculação a um endereço e a mesma publicação que um servidor MCP para um agente de IA.

Cedo ou tarde, algo externo ao TRANXACT precisará dos seus dados: uma ferramenta de relatórios, o sistema de um parceiro, um site que precisa da lista de preços, um agente de IA que recebeu uma pergunta sobre sua empresa. O API Studio, em Plataforma, é onde você decide o que pode ser acessado — uma tela por vez, uma coluna por vez.

Nada é acessível externamente até que alguém publique algo. Não existe uma configuração que abra tudo, nem uma chave que dê acesso a tudo. Uma implantação totalmente nova não possui nenhuma superfície de API, e esse é o ponto de partida correto, em vez de algo que esteja esperando para ser ativado.

As quatro decisões, em ordem

O que	O que decide	Quem costuma fazer isso
Uma exposição	Essa única tela pode sair desta empresa — quais colunas, quais linhas e se algo pode ser gravado de volta.	Quem quer que seja o proprietário dos dados
Um cliente	Existe um programa específico, saiba qual é o nome dele, com quem entrar em contato para obter informações sobre ele e qual usuário ele representa.	Quem gerencia a integração
Uma bolsa	Que este cliente possa alcançar essa exposição, com esses verbos.	Quem gerencia a integração
Um endereço permitido	A chave pode ser apresentada a partir de um navegador, um host, um endereço de servidor ou uma rede.	Quem gerencia a integração

A plataforma oferece três funções para isso e as mantém separadas propositalmente. Um Publicador de API decide o que pode ser publicado e não pode emitir uma chave. Um Registrador de API emite chaves e não pode criar uma exposição. Um Revisor de API lê tudo e não altera nada. Mantido por uma única pessoa, publicar a tabela de folha de pagamento e emitir para si mesmo uma chave que a lê representa um caminho de exportação completo e não testemunhado, no qual cada etapa se assemelha a uma alteração administrativa comum.

Publicando uma tela

Abra a Plataforma → API Studio e escolha uma tela. A lista mostra todas as telas disponíveis no console, lidas diretamente do produto — portanto, qualquer tela incluída nesta versão estará presente.
Marque as colunas que podem ser enviadas. Nada que não esteja marcado é enviado: nem em uma lista, nem em um registro individual, nem no que um servidor retorna. Nada é marcado desde o início, propositalmente.
Defina os verbos. A opção "Ler" está ativada por padrão; criar, alterar e excluir são decisões separadas, pois permitir que o sistema deles leia seu cadastro de itens e permitir que o sistema deles o exclua não são a mesma coisa.
Opcionalmente, restrinja as linhas — apenas faturas lançadas, apenas deste ano. É o mesmo filtro exibido em todas as telas de lista, aplicado no servidor a cada chamada, e nada que o chamador envie pode alterá-lo.
Guarde. É apenas um rascunho, e um rascunho não leva a lugar nenhum. Publique-o quando tiver certeza de que vai publicá-lo.
Clique em "Visualizar" antes de entregar a chave a alguém. Isso mostra exatamente o que o parceiro receberá e quantas colunas foram ocultadas.

Registrando o software

Um cliente é um registro de um software: seu nome, sua função, quem contatar a respeito dele e — o mais importante — qual usuário seu o representa. Cada chamada feita pela chave é feita em nome dessa pessoa. Tudo o que ela não puder fazer, a chave também não poderá.

Esse é o campo mais importante na tela, e é por isso que uma exposição só pode restringir o acesso, nunca ampliá-lo. Aponte uma chave para um usuário criado especificamente para essa finalidade, que possua a função mais específica necessária para realizar a tarefa — e não para um administrador legítimo apenas por conveniência.

A chave em si é exibida apenas uma vez, no momento da emissão, e nunca mais. A emissão de uma nova chave desativa imediatamente a anterior. Uma chave pode ser revogada sem excluir o cliente, portanto, o registro ainda indica quem tinha acesso e quando esse acesso foi removido.

Onde uma chave pode ser usada a partir de

Uma chave sem endereços permitidos não leva a lugar nenhum. Nenhum endereço nomeado é interpretado como inacessível ainda e nunca como acessível de qualquer lugar, pois uma chave vazada que funcione em qualquer computador do mundo representa todo o risco. Existem quatro tipos de entrada: origem por navegador, host de referência, endereço único ou rede no formato CIDR.

Um cliente pode ser marcado como acessível de qualquer lugar, e às vezes isso está correto — um parceiro cujo endereço de saída realmente muda. Trata-se de uma alteração intencional com um aviso ao lado, em vez da configuração padrão.

O que enviar para quem está se integrando

O estúdio imprime os quatro endereços. O endereço base é /api/v1, a chave é inserida no cabeçalho Authorization: Bearer, /api/v1/resources lista os recursos disponíveis com essa chave e /api/v1/openapi.json é equivalente a um documento OpenAPI 3.1.

Ambos são gerados a partir da chave que os solicita. Um parceiro nunca recebe um documento listando quarenta endpoints que ele não pode acessar: o documento dele descreve exatamente o que ele pode acessar e nada mais, e não pode descrever um caminho que seria recusado, porque é construído a partir das mesmas linhas que o manipulador de requisições verifica.

Os mesmos dados para um agente de IA

O endereço /api/v1/mcp é um servidor do Protocolo de Contexto de Modelo (MCTP). Um agente que se conecta a ele recebe uma ferramenta para cada ação que a chave pode executar e nada mais — nenhuma ferramenta para dados não publicados, nenhuma ferramenta para um verbo não concedido. Trata-se da mesma publicação, descrita para um modelo em vez de para um desenvolvedor, de modo que os dois nunca podem ficar desalinhados.

Escreva as instruções do MCP no cliente. É o único lugar onde um modelo é informado de que essas ferramentas acessam um livro-razão real em vez de um ambiente de teste, e o único lugar onde você pode especificar que "pedidos" aqui se refere a pedidos de compra e não a pedidos de venda.

O que acontece em todas as chamadas?

Uma chamada publicada não é um atalho para o banco de dados. Ela é autenticada, verificada em relação à exposição e à permissão concedida e, em seguida, executada como seu usuário de execução por meio da API da plataforma — a mesma rota usada pelo console. Escopo da empresa, escopo da unidade de negócios, restrições de local, períodos fechados, regras de publicação, campos personalizados, lógica personalizada, editabilidade e o registro de auditoria se aplicam, pois são o mesmo código em execução.

Cada chamada é registrada, permitida ou recusada, com a respectiva justificativa. Esse registro fica em Plataforma → API Studio → Registro de Chamadas da API, e a linha mais interessante exibida é a de uma chave proveniente de um endereço não permitido.

Quando não funciona

O que o parceiro vê	O que significa
Essa chave de API não é reconhecida.	Chave incorreta ou uma nova chave foi emitida posteriormente.
Esta chave de API não possui endereços permitidos.	Ninguém disse ainda onde poderá ser usado.
Esta chave de API não pode ser usada a partir daqui.	Ele indica a origem e o endereço de onde a mensagem foi recebida — geralmente o parceiro mudou de servidor.
Nada é publicado aqui como X	O nome está errado, ou a exposição dessa chave não foi concedida, ou ainda é um rascunho.
Esta chave pode não criar X	A exposição ou a concessão não permitem esse verbo.
Você não tem permissão para visualizar X	A concessão está correta, mas o usuário de execução não. O estúdio lista esses itens antes que um parceiro precise encontrá-los.

A lista de clientes exibe uma coluna de prontidão em vez de apenas um status, porque um cliente pode estar ativo, possuir uma chave e ainda assim não conseguir acessar nada — nenhum usuário para executar comandos, nenhum endereço permitido, nenhuma concessão de acesso. Ler a mensagem "ativo" enquanto todas as chamadas retornam "recusado" é como se desenrola uma tarde.