- 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.
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 }.pagecomeça em 1 epageSizevale 20 quando omitido. Comparetotalcom 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_transactionseget_transactionusamapproved,pending,refused,refundedechargeback.list_payment_link_transactionsrepassa o status como a API o devolve naquele endpoint, em que um pagamento aprovado épaid. Veja valores e status.
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.
Links de pagamento
O link é a oferta que se envia ao comprador, pelocheckoutUrl. 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.
list_payment_links
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.
get_payment_link
Escopo: links:read.
Busca um link pelo id (UUID): configuração, status, números e checkoutUrl. Link inexistente ou de outra conta responde 404.
create_payment_link
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_linksantes de tentar de novo. - Para uma cobrança única, envie
maxPayments: 1. SemmaxPayments, o mesmo link pode ser pago várias vezes. Com1, 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
applepayougooglepaysemcredit_card, e nada é criado. Incluir a carteira emmethodsnão garante que ela esteja disponível para toda empresa, navegador ou dispositivo. - O link nasce ativo. Ele fica disponível no
checkoutUrle herda os pixels de rastreamento padrão da empresa. Criar o link não gera cobrança nem movimenta dinheiro. redirectUrlnã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.
update_payment_link
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,slugecheckoutUrlnão mudam. Repetir a mesma chamada leva ao mesmo resultado e não cria nada. methodstroca a lista inteira. Para manter uma carteira digital que o link já aceita, envie a lista completa, comcredit_carde o código da carteira: uma lista sem ele remove a carteira do link. A API recusa carteira digital semcredit_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. Comstatusnum link arquivado, a ferramenta recusa e nada é alterado; os outros campos de um link arquivado podem ser alterados numa chamada semstatus. - Link sem valor fixo não pode ser alterado. Quando
priceModeé diferente defixed, a API responde400apontandopriceMode, mesmo que a chamada só pause o link.
list_payment_link_transactions
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
statuspaidsão vendas, etotalconta as tentativas. - A lista não tem agregado. Não some
amountentre páginas para chegar a um total. - O
statusvem como a API o devolve neste endpoint. Valores já vistos, sem que a lista seja fechada:paid,pending,refused,declined,expired,refundedechargedback. 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
createdAtpassar da data procurada. - Use
metricspara totais, em vez de somar páginas. Semstatus,metrics.totalemetrics.countincluem recusadas, pendentes e estornadas. Para o total vendido, filtre porstatus: "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
documentcria outro cliente igual. Com umdocumentque já é de um cliente ativo da empresa, a API recusa com400e nada é criado. - Procure antes de cadastrar. Use
list_customerspara 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_customerantes 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
documentque já é de outro cliente ativo da empresa volta com erro400. - Não arquiva nem exclui cliente.
Erros
Uma falha na chamada de uma ferramenta volta como resultado da ferramenta, comisError: 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
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.