> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Exemplos de uso > Use o MCP em consultas, investigações e alterações seguras com prompts e chamadas completas. 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 Chame `get_chargefy_account_info` e confirme organização, ambiente e acesso. Use `chargefy_api_search` em vez de adivinhar o `operation_id`. Consulte `chargefy_api_details`, principalmente antes de uma escrita. Leia o recurso ou encontre o ID correto antes de alterar. 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: ```json theme={"theme":"css-variables"} { "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: ```json theme={"theme":"css-variables"} { "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 ```json theme={"theme":"css-variables"} { "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: ```json theme={"theme":"css-variables"} { "arguments": { "query": "essencial", "resources": [ "products", "prices" ] }, "name": "search_chargefy_resources" } ``` A busca devolve resumos. Quando encontrar os IDs corretos, carregue os objetos completos: ```json theme={"theme":"css-variables"} { "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: ```json theme={"theme":"css-variables"} { "arguments": { "query": "link de pagamento", "risk": "R1" }, "name": "chargefy_api_search" } ``` Depois leia o contrato selecionado: ```json theme={"theme":"css-variables"} { "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: ```json theme={"theme":"css-variables"} { "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: ```json theme={"theme":"css-variables"} { "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](/api-reference/payment-links/create). ## Atualizar sem substituir Updates são merge: campos ausentes permanecem iguais. ```json theme={"theme":"css-variables"} { "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: ```json theme={"theme":"css-variables"} { "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: 1. confirme o plano; 2. descubra e detalhe cada operação; 3. leia objetos existentes; 4. use um `intent_id` diferente por criação ou atualização; 5. 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: Escolha `limit` entre 1 e 100. O padrão é 10. Se for `true`, copie o `id` do último objeto em `data`. Repita operação, ambiente e filtros com `starting_after`. ```json theme={"theme":"css-variables"} { "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 “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`.” “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.” “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.” “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.” ## Continue Consulte argumentos, limites e a matriz completa de operações. Entenda rate limits, auditoria e ações que exigem a API REST.