Pular para o conteúdo principal
O servidor MCP tem 12 ferramentas: 8 de consulta e 4 de escrita. Cada conexão vê só as que a credencial cobre:
  • Pelo login, o nível de acesso escolhido na autorização. Somente leitura vê as 8 de consulta; Leitura e escrita vê as 12.
  • Pela chave de API, os escopos da chave. Em modo somente leitura (?readonly=true), vê só as de consulta.
As 4 de escrita são create_payment_link, update_payment_link, create_customer e update_customer. Cada uma exige, pelo login, o nível Leitura e escrita e, pela chave, o escopo de escrita indicado nela. O assistente recebe a descrição e o schema de entrada de cada ferramenta pelo próprio protocolo. Esta página resume o que importa para quem configura a conexão e revisa o que o assistente faz.

Convenções

  • Dinheiro em centavos. Todo valor entra e sai como inteiro em centavos de real: 9900 é R$ 99,00. Vale também para as transações de um link, que a API devolve em reais: o servidor converte antes de responder.
  • Listas paginadas. As listas devolvem { data, total, page, pageSize }. page começa em 1 e pageSize vale 20 quando omitido. Compare total com o que já foi recebido para saber se há mais páginas.
  • Resultado com tamanho limitado. O texto de um resultado tem até 24.000 caracteres. Acima disso ele chega cortado, com um aviso no fim, e o JSON fica incompleto: refine os filtros ou peça páginas menores.
  • Entrada conferida antes. Valor fora do formato e, nas ferramentas que recebem parâmetros, parâmetro desconhecido são recusados antes de qualquer chamada à API.
  • Dois vocabulários de status. list_transactions e get_transaction usam approved, pending, refused, refunded e chargeback. list_payment_link_transactions repassa o status como a API o devolve naquele endpoint, em que um pagamento aprovado é paid. Veja valores e status.
Cada lista tem o seu máximo de pageSize, para a página caber inteira no resultado: Em list_payment_links, uma página além do fim devolve data vazio. Em list_transactions e list_customers, devolve erro 404 com a mensagem “Página inválida”, que só indica o fim da lista. As ferramentas levam as anotações do protocolo (readOnlyHint, destructiveHint e idempotentHint). As de consulta são marcadas como somente leitura; update_payment_link e update_customer, como destrutivas, porque sobrescrevem valores. Um cliente MCP pode usar essas anotações para pedir confirmação antes de uma escrita.

Conta

get_account_context

Escopo: qualquer credencial válida. Não recebe parâmetros. Mostra em nome de qual empresa a conexão age e o que a credencial permite. Devolve company (id, slug e displayName), scopes e readOnly. Use para confirmar a conta antes de uma escrita ou para entender por que uma ferramenta não aparece. Pelo login, scopes mostra o nível: Somente leitura traz links:read, transactions:read e customers:read; Leitura e escrita traz também links:write e customers:write. readOnly é true só no modo somente leitura do endereço, usado com a chave; pelo login, vem false nos dois níveis. O link é a oferta que se envia ao comprador, pelo checkoutUrl. A transação é cada pagamento feito nele. Criar um link não gera cobrança. As ferramentas de link devolvem estes campos: acceptsOneTime, maxPayments, salesCount, views, conversionRate e activeSubscriptions podem não vir. Campo ausente não significa false, zero nem sem limite. Escopo: links:read. Lista os links da conta, uma página por vez, com busca e filtros. O resultado traz também counts (active, paused, archived e total), que conta todos os links da conta por status, sem considerar filtros nem página. counts pode não vir. Escopo: links:read. Busca um link pelo id (UUID): configuração, status, números e checkoutUrl. Link inexistente ou de outra conta responde 404. Escopo: links:write. Pelo login, exige o nível Leitura e escrita. Cria um link de valor fixo e devolve o link criado, já com o checkoutUrl. Cuidados:
  • A criação não é idempotente. Cada chamada cria um link novo, inclusive quando repete uma chamada que terminou em erro de rede ou de prazo. Na dúvida, confira com list_payment_links antes de tentar de novo.
  • Para uma cobrança única, envie maxPayments: 1. Sem maxPayments, o mesmo link pode ser pago várias vezes. Com 1, a API arquiva o link depois do primeiro pagamento aprovado.
  • Só valor fixo e pagamento avulso. A ferramenta não cria link de assinatura nem link em que o comprador escolhe o valor, não envia imagem e não vincula cliente ao link.
  • Carteira digital depende do cartão. A API recusa applepay ou googlepay sem credit_card, e nada é criado. Incluir a carteira em methods não garante que ela esteja disponível para toda empresa, navegador ou dispositivo.
  • O link nasce ativo. Ele fica disponível no checkoutUrl e herda os pixels de rastreamento padrão da empresa. Criar o link não gera cobrança nem movimenta dinheiro.
  • redirectUrl não confirma pagamento. O retorno é liberado por empresa, e os parâmetros que chegam no endereço podem ser alterados pelo comprador. Confirme o pagamento pela API.
  • A API só cria link para empresa aprovada. Quando ela recusa, o erro diz o motivo.
  • O link sai sem Vendedor responsável. Vale para a conexão do login e para a chave de API, mesmo que quem autorizou a conexão seja da equipe.
Escopo: links:write. Para mudar status, a credencial precisa também de links:read, porque a ferramenta lê o link antes de alterar. Pelo login, exige o nível Leitura e escrita, que já inclui links:read. Altera um link existente. Envie o id e só os campos a mudar, ao menos um: o que for omitido fica como está. Aceita os campos da criação e mais status. Cuidados:
  • Cada campo enviado sobrescreve o valor atual. id, slug e checkoutUrl não mudam. Repetir a mesma chamada leva ao mesmo resultado e não cria nada.
  • methods troca a lista inteira. Para manter uma carteira digital que o link já aceita, envie a lista completa, com credit_card e o código da carteira: uma lista sem ele remove a carteira do link. A API recusa carteira digital sem credit_card, e nada é alterado.
  • Não arquiva, não exclui nem desarquiva. Isso vale também para o link que a API arquivou ao atingir maxPayments. Com status num link arquivado, a ferramenta recusa e nada é alterado; os outros campos de um link arquivado podem ser alterados numa chamada sem status.
  • Link sem valor fixo não pode ser alterado. Quando priceMode é diferente de fixed, a API responde 400 apontando priceMode, mesmo que a chamada só pause o link.
Escopo: links:read. Lista todas as tentativas de pagamento de um link, da mais recente para a mais antiga. Recebe o id do link, page e pageSize (de 1 a 50). Link inexistente ou de outra conta responde 404. Cada item traz id (da transação), amount em centavos, status, paymentMethod, installments, customer (id, name e email do comprador), createdAt e paidAt, que é null quando a transação não foi paga. Cuidados:
  • Nem toda tentativa é venda. Além das pagas, vêm o Pix gerado e abandonado, as pendentes e as recusadas. Só os itens com status paid são vendas, e total conta as tentativas.
  • A lista não tem agregado. Não some amount entre páginas para chegar a um total.
  • O status vem como a API o devolve neste endpoint. Valores já vistos, sem que a lista seja fechada: paid, pending, refused, declined, expired, refunded e chargedback. Não trate como pago um status desconhecido.

Transações

As duas ferramentas só consultam. O servidor não faz estorno nem emite recibo.

list_transactions

Escopo: transactions:read. Lista as transações da empresa, da mais recente para a mais antiga. O resultado traz metrics, o agregado de todas as transações do filtro, e não só da página: total (soma bruta), net (soma líquida, só das aprovadas), count (quantidade) e ticket (ticket médio bruto). metrics pode não vir. Cuidados:
  • Não há filtro por data, método de pagamento, valor nem link, e a ordem é fixa. Para um período, percorra as páginas e pare quando createdAt passar da data procurada.
  • Use metrics para totais, em vez de somar páginas. Sem status, metrics.total e metrics.count incluem recusadas, pendentes e estornadas. Para o total vendido, filtre por status: "approved".

get_transaction

Escopo: transactions:read. Consulta uma transação pelo id (UUID): status atual, valores, taxas e motivo de uma recusa. As duas ferramentas devolvem os mesmos campos por transação: Com os juros repassados ao comprador, net não é amount menos totalFeeAmount. net é um valor calculado e vem também na transação pending: não é dinheiro recebido. items[].unitPrice pode incluir os juros do parcelamento; para o preço do produto, use productAmount.

Clientes

list_customers

Escopo: customers:read. Lista os clientes cadastrados na empresa. Cada item traz só id, name, email, phone, type (pf ou pj), createdAt e archivedAt. Documento, endereço e observações não vêm na lista: use get_customer. Não há filtro por tipo de pessoa nem por data de cadastro, e cliente arquivado não aparece na lista.

get_customer

Escopo: customers:read. Consulta o cadastro completo de um cliente pelo id (UUID): id, name, email, phone, document (CPF ou CNPJ só com dígitos, ou null), type, address, notes, createdAt, archivedAt e anonymizedAt. Cliente arquivado continua consultável pelo id. No cliente anonimizado (anonymizedAt preenchido), os dados pessoais foram apagados em definitivo e document sai null.

create_customer

Escopo: customers:write. Pelo login, exige o nível Leitura e escrita. Cadastra um cliente e devolve o cadastro criado. Só grava o cadastro: não cria cobrança nem link. Cuidados:
  • O cadastro não é idempotente. Repetir a chamada sem document cria outro cliente igual. Com um document que já é de um cliente ativo da empresa, a API recusa com 400 e nada é criado.
  • Procure antes de cadastrar. Use list_customers para conferir se o cliente já existe.

update_customer

Escopo: customers:write e customers:read. A ferramenta sempre lê o cadastro atual antes de gravar. Pelo login, exige o nível Leitura e escrita, que já inclui customers:read. Altera o cadastro de um cliente pelo id. Envie só os campos a mudar, ao menos um, entre name, email, phone, document, type, address e notes. Texto vazio remove o document e pede para limpar address e notes; o cadastro devolvido mostra o que ficou. Cuidados:
  • Cada campo enviado substitui o valor atual, sem como desfazer pelo servidor. Consulte o cadastro com get_customer antes de sobrescrever. Repetir a mesma chamada deixa o cadastro no mesmo estado.
  • Cliente anonimizado é recusado. Nada é enviado à API: os dados pessoais dele foram apagados em definitivo.
  • Documento repetido é recusado. Um document que já é de outro cliente ativo da empresa volta com erro 400.
  • Não arquiva nem exclui cliente.

Erros

Uma falha na chamada de uma ferramenta volta como resultado da ferramenta, com isError: true e um texto que começa com Erro:. Entrada inválida. A entrada é conferida antes de qualquer chamada à API. O erro lista cada campo com o problema, em português:
Entrada inválida
Erro da API. O texto traz o status HTTP e o que a API informou: mensagem, código, campo e ID da requisição. Por exemplo, ao criar um link com valor fora da faixa aceita:
Erro da API
Sem resposta da API. Cada chamada à API tem prazo de 30 segundos. Um timeout não determina o resultado: depois de um erro de prazo ou de rede numa criação, confira com a ferramenta de listagem antes de tentar de novo. Escrita confirmada com resposta inesperada. Se a API confirmar uma criação ou alteração e responder num formato que o servidor não reconhece, o resultado é { written: true, id, warning } no lugar do link ou do cadastro. A escrita foi feita: não repita a chamada.

Limites de uso

  • Duas chamadas de ferramenta em andamento por credencial, ou seja, por chave ou por conexão autorizada. As seguintes esperam a vez, até 32. Acima disso, a chamada volta com erro pedindo para tentar de novo, sem ser enviada à API.
  • Uma mensagem JSON-RPC por requisição, com corpo de até 64 KiB.
  • Resposta de até 90 segundos. Passado esse tempo, o servidor encerra a resposta.
  • Limite da API por credencial. Com a chave, as chamadas das ferramentas contam no limite por chave. Uma conexão autorizada tem o mesmo limite, contado por conexão.