Exemplos de uso

Você faz o pedido com as suas palavras e o assistente monta as chamadas. Os exemplos abaixo mostram o pedido e, logo abaixo, o JSON da chamada que o assistente faz. O JSON serve para você conferir o que está acontecendo, não para digitar.

O jeito mais seguro de usar

Um bom assistente segue cinco passos antes de alterar qualquer coisa:

Confere onde está

Chama get_chargefy_account_info para saber a organização, o ambiente e o nível de acesso da conexão.

Descobre a operação certa

Usa chargefy_api_search em vez de chutar o nome da operação.

Lê o contrato

Consulta chargefy_api_details para saber quais campos a operação aceita, principalmente antes de criar ou alterar algo.

Olha o estado atual

Lê o recurso ou encontra o ID certo antes de alterar.

Altera com confirmação e proteção contra duplicidade

Mostra a operação, os dados, o ID e o ambiente para você aprovar; depois executa com um intent_id novo.

A confirmação humana acontece no assistente, não no servidor da Chargefy. O servidor confere permissão, formato dos dados e duplicidade, mas não abre uma tela de confirmação a cada alteração. Por isso vale pedir explicitamente: “me mostre antes de executar”. Atualizações (chargefy_api_update) são marcadas como destrutivas, e a maioria dos assistentes pede confirmação antes delas por conta própria.

Prompt inicial recomendado

Use a conexão Chargefy. Primeiro mostre a organização, os ambientes e o nível de acesso. Trabalhe em teste. Faça apenas leituras até eu autorizar uma alteração. Antes de qualquer escrita, mostre a tool, a operação, os IDs, o data e o intent_id.

Esse pedido evita os três erros mais comuns: mexer no ambiente errado, chutar a operação e alterar algo sem você ver antes.

Consultar dados

Listar clientes

Peça:

Liste os 10 clientes mais recentes no ambiente de teste. Não altere dados.

Depois de conferir o contexto, o assistente faz esta chamada:

{
  "arguments": {
    "limit": 10,
    "livemode": false,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

Se a conexão só tem o ambiente de teste, livemode nem precisa aparecer.

Filtrar por email

Cada operação aceita filtros próprios. O assistente descobre quais em chargefy_api_details antes de usar:

{
  "arguments": {
    "filters": {
      "email": "[email protected]"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

Um filtro que a operação não conhece dá erro na hora. Ele não é ignorado em silêncio, o que evita uma lista errada passar por certa.

Consultar pelo ID

{
  "arguments": {
    "id": "inv_nzaq15x9dEszxCj3",
    "operation": "invoices.get"
  },
  "name": "chargefy_api_read"
}

O resultado é o objeto completo, igual ao da API. Um ID de outra organização ou de outro ambiente não é encontrado.

Encontrar um recurso sem saber o ID

Peça, por exemplo, “encontre o produto Essencial”. Para clientes, catálogo, descontos, links e faturas, o assistente usa a busca por texto:

{
  "arguments": {
    "query": "essencial",
    "resources": [
      "products",
      "prices"
    ]
  },
  "name": "search_chargefy_resources"
}

A busca devolve só um resumo de cada resultado. Com os IDs certos em mãos, o assistente carrega os objetos completos:

{
  "arguments": {
    "ids": [
      "prod_HtXRoNzqYjmy2pQk",
      "price_SdZX69Sm47CoNX6m"
    ]
  },
  "name": "fetch_chargefy_resources"
}

fetch_chargefy_resources é a ferramenta para investigar: o assistente junta até 25 IDs que apareceram em um objeto ou em eventos e carrega todos de uma vez, por exemplo para montar a linha do tempo de um pagamento.

Descobrir antes de executar

Quando o pedido não aponta para uma operação óbvia, o assistente pesquisa no catálogo:

{
  "arguments": {
    "query": "link de pagamento",
    "risk": "R1"
  },
  "name": "chargefy_api_search"
}

E lê o contrato da operação escolhida:

{
  "arguments": {
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_details"
}

O input_schema da resposta diz quais campos entram em data. O link em documentation_url leva à página da referência com as regras de produto que não cabem no schema.

Criar dados

Criar um cliente

Peça:

Em teste, prepare um cliente com email [email protected]. Mostre a chamada e aguarde minha confirmação.

Depois que você confirma:

{
  "arguments": {
    "data": {
      "email": "[email protected]",
      "metadata": {},
      "name": "Cliente"
    },
    "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
    "livemode": false,
    "operation": "customers.create"
  },
  "name": "chargefy_api_create"
}

Se der timeout depois do envio, o assistente repete exatamente essa chamada, com o mesmo intent_id. A Chargefy devolve o cliente já criado em vez de criar outro.

Criar um link com um preço existente

O assistente confirma que o preço existe com prices.get, lê o contrato de payment_links.create e executa:

{
  "arguments": {
    "data": {
      "label": "Plano Essencial",
      "line_items": [
        {
          "price_id": "price_xC9prXwEQpkJghuD"
        }
      ]
    },
    "intent_id": "b6a2f8d1-77c3-4e19-a5d0-2c4e9f81b3a7",
    "livemode": false,
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_create"
}

A resposta traz o link criado e a URL pública, pronta para compartilhar. Para link com preço avulso, produto criado na hora ou recorrência, veja as variantes em Criar um link de pagamento.

Atualizar sem substituir

Uma atualização só mexe nos campos enviados. O que não aparece em data continua como estava.

{
  "arguments": {
    "id": "cus_9UjeV34PYKN9Cuqb",
    "data": {
      "name": "Cliente atualizado"
    },
    "intent_id": "e57d20c4-9b1a-4f36-8e02-6a3c1d94f7b8",
    "operation": "customers.update"
  },
  "name": "chargefy_api_update"
}

O intent_id da criação não serve para a atualização. Cada alteração recebe um código novo; o mesmo código só se repete quando a mesma alteração é reenviada depois de uma falha.

Para apagar o valor de um campo, é preciso enviá-lo como null ou vazio (o input_schema diz qual dos dois a operação aceita). Deixar o campo de fora não apaga nada.

Planejar um fluxo maior

Para um objetivo que envolve vários recursos, como “vender um plano mensal”, o assistente pode começar pelo planejador:

{
  "arguments": {
    "context": "Já tenho o cliente e quero operar somente em teste.",
    "goal": "Criar um produto mensal e gerar um link de pagamento"
  },
  "name": "chargefy_implementation_planner"
}

O planejador devolve os pré-requisitos, a ordem das operações e as páginas de documentação. A partir daí, o assistente:

confirme o plano;
descubra e detalhe cada operação;
leia objetos existentes;
use um intent_id diferente por criação ou atualização;
valide o resultado de cada etapa antes de seguir.

O planejador só planeja. Ele não executa nenhuma alteração.

Implementar pagamentos white-label

O assistente pode ajudar a construir a integração no seu código. Escolha o caminho e peça que ele leia o guia completo:

Objetivo	Caminho
Uma página pronta com a sua marca e domínio	Checkout hospedado e configuração da página.
Uma tela de pagamento construída no seu produto	Checkout white-label com Chargefy.js.

Use get_chargefy_account_info, chargefy_api_search e chargefy_api_details para conferir o que a conexão pode executar. O MCP cria catálogo, clientes e links na organização autorizada; ele consulta Checkout Sessions, setup intents e payment intents, mas não os cria nem confirma pagamentos. Essas etapas são implementadas pela API pública no backend, com a coleta de cartão pelo Chargefy.js no navegador. Marca e domínio são configurados no Dashboard.

Chargefy for Platforms

Esta seção só se aplica ao Chargefy for Platforms, que opera pagamentos para suas organizações filhas.

Conecte com uma chave de plataforma. A conexão passa a consultar a própria organização e, a cada chamada, uma das suas organizações filhas. A identidade vem da chave; o destino vai no pedido, em on_behalf_of. São coisas separadas de propósito, como na API pública (chave da plataforma + header Organization):

{
  "arguments": {
    "on_behalf_of": "org_7Dk9mQ2vX5rT8pWN",
    "operation": "payment_intents.list"
  },
  "name": "chargefy_api_read"
}

O destino nunca é presumido. Sem on_behalf_of, a chamada consulta a organização da plataforma — um pedido feito para uma filha não é respondido em silêncio com os dados da plataforma. Descubra os ids com organizations.list. O vínculo é conferido a cada chamada, não congelado na autorização: a filha que sai da plataforma para de responder na chamada seguinte, sem nada a revogar à mão. E toda consulta fica registrada com a filha realmente consultada. Somente leitura nas filhas. Criar ou atualizar dentro de uma organização filha não existe no MCP — on_behalf_of é aceito apenas em chargefy_api_read e chargefy_resource_fetch. Um Payment Link criado pelo MCP pertence à organização do escopo e usa a marca dela. Para gerar uma página de pagamento para uma filha com a marca da plataforma, implemente no backend a chamada de API com a chave da plataforma e Organization da filha, seguindo Marca e domínio próprio da plataforma. Na interface própria, o navegador usa a chave publicável da plataforma e o setup intent da filha no mesmo ambiente. Um ambiente por conexão: a chave já é de teste ou de produção, e uma conexão nunca enxerga os dados da outra. Crie a de teste primeiro, confira o alcance e só depois conecte a de produção. Três limites viram erro:

Tentativa	Resposta
`on_behalf_of` numa conexão de organização	`platform_required`. A conexão alcança apenas a própria organização.
`on_behalf_of` com uma filha que não é sua, ou inativa	`not_found`. Uma organização fora das suas filhas ativas responde igual a uma inexistente.
`on_behalf_of` numa operação que escreve	A entrada é recusada: criar e atualizar dentro de uma filha não faz parte do MCP.

Uso Chargefy for Platforms e quero implementar um checkout próprio com Chargefy.js para minhas organizações filhas. Leia o guia white-label e a seção de Platforms, confira as permissões do MCP e implemente as chamadas no meu backend com a chave e o escopo corretos. Teste em sandbox e confirme pagamentos por webhooks assinados.

Investigar pagamentos sem movimentar dinheiro

O assistente consulta payment intents, cobranças, transações, faturas, assinaturas, reembolsos e disputas, mas não consegue agir sobre nenhum deles. Isso torna a investigação segura por construção. Um pedido útil:

No ambiente ao vivo e somente para leitura, consulte o payment intent pi_Q3zX5Sqaeiq5n6WT. Carregue os recursos relacionados que estiverem identificados no resultado e monte uma linha do tempo com status, valores e horários. Não confirme, capture, cancele nem reembolse nada.

Como capturar, cancelar e reembolsar não existem no MCP, mesmo um pedido mal escrito não consegue movimentar dinheiro.

Paginar

Listas grandes vêm em páginas. O assistente avança assim:

Faça a primeira leitura

Escolha limit entre 1 e 100. O padrão é 10.

Leia has_more

Se for true, copie o id do último objeto em data.

Busque a próxima página

Repita operação, ambiente e filtros com starting_after.

{
  "arguments": {
    "limit": 25,
    "operation": "customers.list",
    "starting_after": "cus_9UjeV34PYKN9Cuqb"
  },
  "name": "chargefy_api_read"
}

ending_before faz o caminho inverso. Os dois nunca vão juntos na mesma chamada.

Fazer retry

Situação	O que repetir
`rate_limited`	Aguarde `retry_after_ms`; preserve argumentos e escopo
Timeout em leitura	Repita a mesma chamada
Timeout em escrita	Repita operação, ID, `data` e o mesmo `intent_id`
`invalid_arguments`	Corrija conforme `param` e `chargefy_api_details`
Erro com `retryable: false`	Não repita sem mudar permissão, contexto ou entrada

Trocar o intent_id depois de um timeout transforma a repetição em uma segunda alteração. É assim que se cria um cliente duplicado sem querer.

Corrigir erros comuns

Código	Causa	Próximo passo
`no_scope`	Ambiente ambíguo ou nenhum escopo ativo	Consulte a conta e informe `livemode`; reconecte se necessário
`environment_disabled`	Ambiente desligado para a organização	Peça habilitação a um administrador
`operation_not_found`	`operation_id` inexistente ou tool errada	Use `chargefy_api_search`
`operation_not_granted`	Método fora da concessão da conexão	Autorize novamente
`write_not_allowed`	Escopo somente leitura	Use um escopo de escrita
`missing_capability`	Usuário sem a capacidade do recurso	Revise a função do usuário
`invalid_arguments`	Schema, filtro, ID ou `intent_id` inválido	Compare com `chargefy_api_details`
`idempotency_key_reused`	Mesmo `intent_id` com parâmetros diferentes	Recupere a intenção original ou gere um token para a nova ação
`idempotency_key_in_progress`	A mesma escrita ainda está processando	Aguarde e repita com o mesmo `intent_id`
`rate_limited`	Bucket esgotado	Aguarde `retry_after_ms`

Quando um erro vier com request_id, guarde esse valor. Ele localiza a chamada no log de requests do painel e pode ser enviado junto com um relato pela ferramenta send_chargefy_mcp_feedback.

Pedidos prontos para copiar

Auditar sem alterar

“Use a Chargefy somente para leitura. Confirme o ambiente de teste, liste invoices abertas e resuma valor, vencimento e status. Não chame chargefy_api_create nem chargefy_api_update.”

Criar com revisão humana

“Em teste, prepare um cliente com email [email protected]. Consulte o schema, mostre data e intent_id e só execute depois da minha confirmação.”

Investigar uma falha

“Consulte a request req_j8ii31CD75absd7t e os objetos relacionados que estiverem disponíveis. Monte uma linha do tempo e preserve o request_id. Não altere nenhum recurso.”

Montar catálogo e link

“Planeje a venda de um plano mensal de R$ 99,90 em teste. Depois da minha aprovação, crie o produto, o preço e o link. Use um intent_id novo em cada escrita e valide cada resposta.”

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

O jeito mais seguro de usar

Prompt inicial recomendado

Consultar dados

Listar clientes

Filtrar por email

Consultar pelo ID

Encontrar um recurso sem saber o ID

Descobrir antes de executar

Criar dados

Criar um cliente

Criar um link com um preço existente

Atualizar sem substituir

Planejar um fluxo maior

Implementar pagamentos white-label

Chargefy for Platforms

Investigar pagamentos sem movimentar dinheiro

Paginar

Fazer retry

Corrigir erros comuns

Pedidos prontos para copiar

Continue

Tools e operações

Limites e segurança

​O jeito mais seguro de usar

​Prompt inicial recomendado

​Consultar dados

​Listar clientes

​Filtrar por email

​Consultar pelo ID

​Encontrar um recurso sem saber o ID

​Descobrir antes de executar

​Criar dados

​Criar um cliente

​Criar um link com um preço existente

​Atualizar sem substituir

​Planejar um fluxo maior

​Implementar pagamentos white-label

​Chargefy for Platforms

​Investigar pagamentos sem movimentar dinheiro

​Paginar

​Fazer retry

​Corrigir erros comuns

​Pedidos prontos para copiar

​Continue

Tools e operações

Limites e segurança

O jeito mais seguro de usar

Prompt inicial recomendado

Consultar dados

Listar clientes

Filtrar por email

Consultar pelo ID

Encontrar um recurso sem saber o ID

Descobrir antes de executar

Criar dados

Criar um cliente

Criar um link com um preço existente

Atualizar sem substituir

Planejar um fluxo maior

Implementar pagamentos white-label

Chargefy for Platforms

Investigar pagamentos sem movimentar dinheiro

Paginar

Fazer retry

Corrigir erros comuns

Pedidos prontos para copiar

Continue