Exemplos de uso

Você pode conversar em linguagem natural; o cliente monta as chamadas MCP. Os exemplos abaixo mostram o JSON apenas para tornar cada decisão verificável.

O padrão mais seguro

Leia o contexto

Chame get_chargefy_account_info e confirme organização, ambiente e acesso.

Descubra a operação

Use chargefy_api_search em vez de adivinhar o operation_id.

Leia o contrato

Consulte chargefy_api_details, principalmente antes de uma escrita.

Verifique o estado atual

Leia o recurso ou encontre o ID correto antes de alterar.

Escreva com confirmação e idempotência

Mostre operação, data, ID e ambiente; depois use um intent_id novo.

A confirmação humana é uma política do cliente ou uma instrução sua. O servidor valida escopo, capacidade, schema e idempotência, mas não abre uma tela de confirmação a cada escrita.

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 prompt evita três erros comuns: ambiente implícito, operação adivinhada e alteração sem revisão.

Consultar dados

Listar clientes

Peça:

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

Depois de confirmar o contexto, a chamada de leitura pode ser:

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

Se a conexão tiver somente teste, livemode pode ser omitido.

Filtrar por email

Filtros pertencem à operação. Consulte chargefy_api_details antes de usá-los:

{
  "arguments": {
    "filters": {
      "email": "nome@email.com"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

Chaves desconhecidas são rejeitadas; não são ignoradas silenciosamente.

Consultar pelo ID

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

O resultado é o objeto público completo. Um ID de outra organização ou ambiente não é retornado.

Encontrar um recurso sem saber o ID

Use a busca por texto para clientes, catálogo, descontos, links e invoices:

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

A busca devolve resumos. Quando encontrar os IDs corretos, carregue os objetos completos:

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

fetch_chargefy_resources é útil para investigar relações: reúna até 25 IDs encontrados em objetos ou eventos e carregue todos em uma chamada.

Descobrir antes de executar

Quando o objetivo ainda não aponta para uma operação clara, pesquise:

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

Depois leia o contrato selecionado:

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

Use o input_schema retornado para construir data. A referência em documentation_url explica regras de produto que não cabem no schema.

Criar dados

Criar um cliente

Peça:

Em teste, prepare um cliente com email nome@email.com. Mostre a chamada e aguarde minha confirmação.

Depois da confirmação:

{
  "arguments": {
    "data": {
      "email": "nome@email.com",
      "metadata": {},
      "name": "Cliente"
    },
    "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
    "livemode": false,
    "operation": "customers.create"
  },
  "name": "chargefy_api_write"
}

Se houver timeout depois do envio, repita exatamente essa chamada com o mesmo intent_id.

Criar um link com um preço existente

Depois de confirmar o preço com prices.get, leia os detalhes de payment_links.create e execute:

{
  "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_write"
}

A resposta inclui o objeto payment_link e sua URL pública. Para preço ad-hoc, produto inline ou recorrência, siga as variantes de Criar um link de pagamento.

Atualizar sem substituir

Updates são merge: campos ausentes permanecem iguais.

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

Não reutilize o intent_id da criação. Cada alteração lógica recebe um token novo; o token só se repete no retry da mesma alteração.

Para limpar um campo, confirme no input_schema se ele aceita null ou string vazia. Omitir um campo não o remove.

Planejar um fluxo maior

Para um objetivo com vários recursos, comece com o planner:

{
  "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 planner indica pré-requisitos, ordem das operações e documentação. Em seguida:

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 planner não executa nenhuma alteração por conta própria.

Investigar pagamentos sem movimentar dinheiro

O MCP pode consultar payment intents, cobranças, transações, invoices, assinaturas, reembolsos e disputas. Um prompt ú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.

As operações financeiras de lifecycle não existem na superfície MCP, então a investigação permanece separada da ação.

Paginar

Listagens usam cursor:

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"
}

Use ending_before para voltar. Nunca envie os dois cursores juntos.

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 pode transformar o retry em uma segunda alteração.

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`

Guarde o request_id quando ele aparecer. Ele correlaciona a falha com o log de requests da Chargefy e pode ser enviado por send_chargefy_mcp_feedback.

Prompts prontos

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_write.”

Criar com revisão humana

“Em teste, prepare um cliente com email nome@email.com. 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

Objetos de sistema

Webhooks e eventos

SDKs

MCP

O padrão mais seguro

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

Investigar pagamentos sem movimentar dinheiro

Paginar

Fazer retry

Corrigir erros comuns

Prompts prontos

Continue

Tools e operações

Limites e segurança

​O padrão mais seguro

​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

​Investigar pagamentos sem movimentar dinheiro

​Paginar

​Fazer retry

​Corrigir erros comuns

​Prompts prontos

​Continue

Tools e operações

Limites e segurança

O padrão mais seguro

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

Investigar pagamentos sem movimentar dinheiro

Paginar

Fazer retry

Corrigir erros comuns

Prompts prontos

Continue