Documentação

Empresas, regiões e pessoas

Cada espaço de trabalho do Pleaxy pertence a uma única empresa. O domínio do seu e-mail não faz parte da árvore: o Pleaxy só o usa como pista quando alguém se cadastra.

• Empresa - a organização no Pleaxy. Não há nada acima dela: nem grupo nem empresa controladora. Seus administradores são os administradores de qualquer um dos seus perfis de comprador ou fornecedor.
• Região - um espaço de trabalho dentro de uma empresa, por exemplo EMEA. Uma região nunca passa para outra empresa.
• Perfis de comprador e fornecedor - os dois lados de uma região, que tem um ou ambos. Cada um tem seus próprios usuários e funções, pedidos de compra, faturas e conexões com compradores ou fornecedores.

Quem fica em qual empresa

• A primeira pessoa de um domínio corporativo cria uma nova empresa e se torna sua administradora.
• Um colega que se cadastra depois vê, depois de confirmar o e-mail, as empresas no Pleaxy que já têm pessoas com o domínio dele, cada uma com suas regiões. Ele pode pedir a um administrador dessas empresas um convite para uma região, ou confirmar que a dele é outra empresa e criar uma separada. Empresas separadas não veem os pedidos, faturas nem fornecedores umas das outras.
• Um administrador que adiciona uma região a adiciona à própria empresa.
• Não é possível unir empresas. Se uma empresa separada foi criada por engano, convide as pessoas dela para as regiões da sua empresa.

Início rápido

Entre, conecte um provedor de nuvem e crie o seu primeiro pedido de compra. O console e os SDKs chamam a mesma API /v1, que você também pode chamar com uma chave de API com escopo (veja Agentes de IA para gerar uma). Algumas ações sempre exigem uma pessoa conectada à Pleaxy, nunca uma chave de API: aprovar, alterar fluxos de aprovação ou a autonomia, e registrar um pagamento.

import { Pleaxy } from "@pleaxy/sdk";

// The base URL is the origin only: the SDK adds /v1/workspaces/<Workspace ID>.
const pleaxy = new Pleaxy({
  baseUrl: "https://api.pleaxy.ai",
  apiKey: process.env.PLEAXY_API_KEY, // "<keyId>.<secret>"
  workspaceId: process.env.PLEAXY_WORKSPACE_ID, // Company profile → Workspace ID
});

// AWS: start the connection, run the returned setup script in your own
// account, then pass back the read-only IAM role it created.
const setup = await pleaxy.cloudConnections.initAwsCloudConnection();
await pleaxy.cloudConnections.createCloudConnection({
  provider: "aws",
  accountLabel: "Production payer",
  awsConnectionId: setup.connectionId,
  roleArn: "arn:aws:iam::912345678901:role/PleaxyBillingRead",
});

const po = await pleaxy.purchaseOrders.createPurchaseOrder({
  supplier: "Amazon Web Services",
  provider: "aws",
  lineItems: [
    {
      scopeType: "sku",
      scopeId: "AWS-EC2-M5LG",
      name: "EC2 m5.large",
      ruleType: "quantity",
      unit: "hr",
      unitPrice: 0.096,
      qty: 5_000,
      nteAmount: 0,
      paymentTerms: "Net 30",
      validFrom: "2026-01-01",
      validUntil: "2026-12-31",
    },
  ],
});

// po.status is "pending_approval" while your approval flow runs, then
// "awaiting_fulfillment". Autonomy, if on, can approve it straight away.

Pedidos de compra e itens de linha

Um pedido de compra é formado por um ou mais itens de linha, cada um com preço e acompanhamento próprios:

• Linhas de SKU - um item específico do catálogo de um fornecedor, cobrado por quantidade × preço unitário. Quando o fornecedor publica um catálogo na Pleaxy, o ID do item na linha é validado no servidor.
• Linhas globais de serviço ou de conta - um teto máximo que cobre um serviço inteiro ou uma conta de nuvem inteira.
• Linhas personalizadas - para qualquer coisa fora do catálogo de um fornecedor, baseadas em quantidade ou em um valor máximo fixo.

Cada linha fica na moeda da região, tem as próprias condições de pagamento e período de validade, e acompanha um saldo em tempo real - consumido vs. restante - em relação a esse período, sinalizando as linhas que estão a caminho de se esgotar antes do prazo.

Conexões de nuvem

A Pleaxy se conecta em modo somente leitura ao faturamento da Amazon Web Services (AWS), Google Cloud, Microsoft Azure e Oracle Cloud Infrastructure (OCI), por meio de um acesso que você cria na sua própria conta com um script de configuração e pode revogar quando quiser. A Pleaxy mantém cada pedido de compra como um registro próprio e não grava pedidos de compra em nenhum provedor de nuvem:

• Amazon Web Services (AWS) - uma função IAM entre contas que a Pleaxy assume. Ela lê as suas faturas emitidas e o Cost Explorer. Para que a AWS imprima o número de um pedido de compra da Pleaxy nas faturas dela, adicione-o em Purchase orders no console AWS Billing and Cost Management.
• Google Cloud - Workload Identity Federation para uma conta de serviço que só pode ler a sua exportação de faturamento do BigQuery. O Google não tem uma API de faturas, então a Pleaxy usa o total do mês da exportação.
• Microsoft Azure - uma credencial federada em um aplicativo no seu próprio tenant. Ela lê as faturas do seu perfil de faturamento e o custo do mês até a data. A Pleaxy não anexa números de pedido de compra a faturas EA.
• Oracle Cloud Infrastructure (OCI) - uma chave de assinatura de API gerada pela Pleaxy; você envia apenas a chave pública. Ela lê as faturas de uso quando a sua conta as tem e, caso contrário, o custo de cada mês fechado.

Gastos com IA

Gastos com IA são o que custam os serviços de IA do faturamento de nuvem que você conectou: Amazon Bedrock, SageMaker, Vertex AI, Azure OpenAI, OCI Generative AI e os modelos do marketplace na mesma fatura. A Pleaxy os mostra por faturador, fornecedor do modelo, modelo e medidor (tokens de entrada, de saída e em cache, horas provisionadas), mês até a data e previsão para o período, em relação ao último mês fechado, e ao lado de cada faturador as linhas de pedido de compra abertas emitidas para ele e o que resta nelas - assim você sabe que o Bedrock vai custar mais do que resta no PO-8842 antes de a fatura chegar. Todo valor está na moeda de faturamento do faturador, nunca convertido nem somado entre moedas.

• O fornecedor é quem fatura. A empresa cujo modelo foi usado é o vendor da linha. Claude no Bedrock é gasto da AWS com vendor anthropic, nunca gasto da Anthropic, então agrupar por faturador corresponde às suas faturas e agrupar por fornecedor do modelo responde quanto você gasta com Claude, seja quem for que fature. Nada é contado duas vezes.
• De onde vem - das linhas de serviços de IA do faturamento de AWS, Google Cloud, Azure e OCI que você conectou, lidas com o mesmo acesso somente leitura do restante da conta e com a mesma escolha de fontes de dados: uma conexão que permite current_cost dá o mês até a data e uma previsão; uma que permite invoices, o mês fechado. A AWS só fornece suas linhas de IA pelo Cost Explorer, então uma conta AWS precisa de current_cost para vê-las, e aí mostra também o mês fechado. Nada de novo é pedido da sua conta, e um tipo de uso que a Pleaxy ainda não conhece é mantido com seu nome bruto, nunca descartado.
• Tabelas de preços - a Pleaxy mantém os preços de lista públicos de cada fornecedor de modelo e faturador que mapeia, com datas de vigência: uma mudança de preço é uma nova entrada, então uma linha é julgada pelo preço que valia no seu dia. A tarifa negociada de um contrato ou seu desconto sobre o preço de lista prevalece; as tabelas em si não podem ser editadas.

Na API, gastos com IA são um recurso só para compradores: GetAiSpend para os números por faturador, fornecedor do modelo, modelo ou centro de custo, ListAiUsageLines para as linhas por trás deles, ListAiRateCards para o preço em vigor em um dia e CheckAiSpend para saber se a previsão cabe nas linhas de pedido de compra abertas e no orçamento. O servidor MCP expõe o mesmo como get_ai_spend e check_ai_spend (veja Agentes de IA).

Além do seu faturamento de nuvem, os gastos com IA cobrem os provedores de IA que você paga diretamente, as linhas de IA dos seus pedidos e faturas, os centros de custo e os limites no provedor:

• Provedores de IA diretos - OpenAI e Anthropic se conectam com uma chave de administrador somente leitura que você cria no console deles e pode revogar; a Mistral também, quando sua organização tem a Admin API dela (um recurso do Enterprise). O OpenRouter se conecta com uma chave de gerenciamento, a CoreWeave com um token de API com a função Billing Viewer e o Databricks com uma entidade de serviço; para o Snowflake, a Pleaxy gera um par de chaves e você atribui a chave pública a um usuário de serviço. A chave é verificada com uma leitura antes de ser salva, guardada criptografada e nunca usada para mudar nada no provedor. As linhas de cada provedor são lidas todo dia e aparecem como faturador próprio (ListAiProviders, CreateAiProvider).
• Faturas de IA conciliadas linha a linha - uma linha de IA em um pedido, um termo de contrato ou uma fatura indica o modelo e o medidor, e cada linha de fatura é conferida com a linha do pedido e o termo do contrato para esse modelo: a tarifa contra o contrato e o preço de tabela do mês, a quantidade contra o uso que o provedor informou, e o que ela consome de um compromisso. As linhas nunca são conciliadas pela descrição. SuggestAiPoLines preenche as linhas de IA de um pedido com o uso do mês anterior, e ListAiCommitments mostra quanto de cada compromisso já foi usado.
• Centros de custo e orçamentos - regras de atribuição associam tags, rótulos, projetos e espaços de trabalho dos provedores a centros de custo (GetAiAttribution). Cada orçamento passa a contar o uso de IA atribuído do mês como gasto em acúmulo, e a Pleaxy alerta quando a previsão chega a 80% ou 100% dele (ListAiCostCenters).
• Limites no provedor - opcionais. Uma linha de pedido aprovada pode definir o teto mensal do próprio provedor: um orçamento da AWS, um limite de projeto da OpenAI, um limite de espaço de trabalho da Anthropic quando a Anthropic o oferece na sua conta, um orçamento ou teto de gastos do Google Cloud, ou um orçamento do Azure, que só alerta. Exige uma credencial separada que você cria, nunca a da conexão somente leitura (SetAiSpendLimit).
• IA por assento - faturas por assento de ChatGPT Enterprise, Claude Enterprise, Microsoft 365 Copilot, GitHub Copilot e Cursor são conferidas com os usuários ativos registrados para o mês (SetAiSeatCount). A Pleaxy não lê seu provedor de identidade: uma pessoa, um script ou um agente registra o número.

Aprovações e autonomia

Cada região tem um fluxo de aprovação para pedidos de compra e outro para pagamentos de faturas, que você edita em Fluxos de trabalho na Pleaxy. Uma nova região começa com uma única etapa direcionada a um administrador da região. Você monta um fluxo com três tipos de etapa:

• Aprovador - uma pessoa aprova.
• Aprovadores em paralelo - várias pessoas diferentes aprovam, cada uma, em qualquer ordem.
• Aprovador condicional - só é acionado quando todas as suas condições são atendidas. As condições podem verificar o valor (na moeda da região), o fornecedor ou o solicitante.

Cada etapa indica uma pessoa específica, e só essa pessoa pode agir nela. Marque uma etapa como Só acima do limite de alto valor e os valores iguais ou inferiores ao limite pulam essa etapa. Um fluxo precisa de pelo menos uma etapa sem condições, para que todo pedido e toda fatura cheguem a uma pessoa. Se você mesmo emitiu o documento, a sua etapa vai para outro administrador. Você só pode aprová-lo pessoalmente quando ninguém mais na região puder, e ele é então marcado como Autoaprovado.

No plano Autonomous, você pode ativar a autonomia, também em Fluxos de trabalho. A Pleaxy então aprova sozinha um pedido de compra ou uma fatura até o seu valor de aprovação automática, como Pleaxy Autonomy, com a mesma trilha de auditoria. Ela nunca faz isso quando uma etapa condicional ou de valor alto se aplica, ou quando um pedido de compra ultrapassa o limite de gastos do solicitante. Para faturas, a regra é mais rígida: só uma fatura conciliada com uma fatura emitida pela AWS pode ser aprovada automaticamente, e nunca uma que um comprador lançou ou uma em outra moeda. As regras de automação permitem tratar um fornecedor de forma diferente: sempre enviar os documentos dele para uma pessoa ou, no plano Autonomous, aprová-los automaticamente até um valor.

Uma chave de API pode ler os fluxos de aprovação e as configurações de autonomia, mas só uma pessoa conectada à Pleaxy pode alterá-los, e uma chave de API nunca aprova uma etapa.

const flow = await pleaxy.approvalChains.get("purchase_order"); // or "invoice_payment"

const autonomy = await pleaxy.settlement.getAutonomy();
// { enabled, maxAutoApproveAmount, approvalThreshold }
// approvalThreshold is the high-value threshold. Change these in Pleaxy, under Workflows.

Conciliação de faturas

Uma fatura cobrada com base em um pedido de compra, de um provedor de nuvem com o qual você tem uma conexão de faturamento ativa, começa com o status de conciliação pending. Executar a conciliação compara o valor faturado com o uso informado pelo provedor:

• Diferença de até 3% → matched, e a fatura segue para o seu fluxo de aprovação de faturas.
• Diferença de mais de 3%, ou em outra moeda → discrepancy. A Pleaxy não converte moedas. Alguém confere a fatura com a conta do provedor e, em seguida, a encaminha para o fluxo de aprovação ou a rejeita. Se a autonomia estiver ativada e a diferença estiver dentro do seu valor de aprovação automática, a Pleaxy a aprova sozinha, dentro dos limites para faturas descritos em Aprovações e autonomia.

Uma fatura sem pedido de compra, ou sem conexão de faturamento com a qual possa ser conferida, fica como unverified. Uma pessoa conectada à Pleaxy a revisa e depois a envia para o fluxo de aprovação ou a rejeita.

Notas de crédito e de débito

Uma nota de crédito reduz o que o comprador deve: mercadoria devolvida, uma correção de preço, um reembolso. O fornecedor a emite sobre a fatura que ela corrige, ou só em nome do comprador, e o comprador pode registrar uma que o fornecedor enviou fora da Pleaxy. Uma nota de crédito que corrige uma fatura e não passa do valor dela é aceita na hora; qualquer outra aguarda o comprador aceitar ou recusar. Ao aceitar um crédito por mercadoria devolvida ou correção de preço, o valor antes dos impostos volta para a linha do pedido de compra, e esse saldo pode ser usado de novo.

Quem liquida os créditos é uma configuração do espaço de trabalho:

• A Pleaxy liquida. Os créditos aceitos são aplicados a faturas em aberto e reduzem o valor a pagar, e uma nota de crédito sobre uma fatura em aberto é aplicada a ela ao ser aceita. Os créditos podem cobrir uma fatura inteira: depois de aprovada, ela fica liquidada por crédito, sem nada a pagar. Recusar uma fatura devolve os créditos aplicados a ela.
• Seu sistema contábil liquida. Nada é compensado na Pleaxy, e cada nota de crédito aceita sai uma vez na exportação de pagamentos, como uma linha negativa.

Uma nota de débito cobra mais sobre uma fatura já enviada, como uma cobrança que ficou de fora. Ela indica a fatura que altera e herda o pedido de compra, a linha e a moeda dela, e depois passa por conciliação, aprovação, pagamento e exportação como qualquer fatura. Não pode alterar uma fatura recusada nem outra nota de débito.

As duas ficam em Faturas no app, vinculadas à fatura que alteram, e as notas de crédito da AWS e da Azure chegam sozinhas como notas de crédito. Na API elas são o recurso de faturas com documentType igual a credit_note ou debit_note (veja CreateInvoice), e um feed de faturas as envia como notas de crédito e de débito UBL, credit e debit memos cXML, ou JSON com documentType.

Pagamentos

A Pleaxy não paga faturas. Quando o fluxo de aprovação de uma fatura é concluído, o comprador a paga no seu próprio ciclo de pagamentos (as faturas aprovadas podem ser exportadas para isso) e registra o pagamento na Pleaxy. O registro não movimenta dinheiro. O fornecedor vê o pagamento como registrado pelo comprador e recebe um aviso de pagamento. Registrar um pagamento exige uma pessoa conectada à Pleaxy, nunca uma chave de API.

Junto com o pagamento, ou a qualquer momento depois, o comprador pode enviar ao fornecedor um aviso de pagamento: o comprovante, como o recibo de transferência do banco (PDF, PNG ou JPEG, até 10 MB), e uma nota de até 1.000 caracteres. O fornecedor é avisado, também no canal do Slack ou do Teams se encaminhar para lá os avisos de pagamento, e encontra o aviso na fatura. Assim como registrar um pagamento, enviá-lo exige uma pessoa conectada à Pleaxy (veja SendRemittance). Exportar para pagamento também funciona com uma única fatura.

Agentes de IA (MCP)

Para conectar um agente como você mesmo, sem chave de API: Conectar um agente de IA.

O servidor MCP da Pleaxy expõe pedidos de compra e faturas como ferramentas para o Claude ou qualquer outro agente compatível com MCP. Ele é uma camada fina: cada chamada de ferramenta é uma requisição autenticada à mesma API /v1 que o console e os SDKs usam, então um agente pode fazer exatamente o que a sua chave de API permite - nada além disso.

1. Gere uma chave de API com escopo com POST /v1/workspaces/:regionId/api-keys enquanto estiver conectado com o seu próprio usuário - uma chave de API existente não pode gerar outra (veja Chaves de API). A chave assume a sua própria função no espaço de trabalho, de comprador ou de fornecedor, e só um administrador pode gerá-la. Uma chave de comprador é somente leitura, a menos que você lhe atribua um procurementRole, como requisitions para criar pedidos de compra. A resposta contém a chave (exibida uma única vez). Em seguida, copie o ID do espaço de trabalho em Perfil da empresa, no console da Pleaxy - você vai precisar dos dois a seguir.
2. Confira se ele roda (Node.js 22.18 ou posterior). O servidor está no npm como pleaxy-mcp, então não há nada para compilar nem clonar: o npx o baixa.
   shell

   npx -y pleaxy-mcp --version

3. Adicione-o ao seu cliente MCP. No Claude Desktop ou no Claude Code, adicione isto à sua configuração MCP. A URL base é apenas a origem - o próprio servidor acrescenta /v1.
   mcp config · json

   {
     "mcpServers": {
       "pleaxy": {
         "command": "npx",
         "args": ["-y", "pleaxy-mcp"],
         "env": {
           "PLEAXY_API_BASE_URL": "https://api.pleaxy.ai",
           "PLEAXY_API_KEY": "<keyId>.<secret>",
           "PLEAXY_WORKSPACE_ID": "<Company profile → Workspace ID>"
         }
       }
     }
   }

Um processo de servidor atende a um espaço de trabalho - uma chave de API, um ID do espaço de trabalho. Chaves de comprador e de fornecedor veem a mesma lista de ferramentas, mas uma chamada fora da função da chave (uma chave de fornecedor chamando create_purchase_order, por exemplo) é rejeitada pela API exatamente como seria via REST.