Integrar com agentes de IA
O que o Vipter publica para que um agente de IA (Claude Code, Cursor, Codex, ChatGPT e similares) integre a API sem ajuda humana: a skill vipter-api no formato Agent Skills, o llms.txt com instruções, toda a documentação em Markdown, o OpenAPI 3.1 e a coleção Postman; como apontar o agente para cada um, o que pedir a ele e o que nunca entregar a ele.
Grande parte das integrações hoje é escrita por um agente de IA a partir de um pedido em linguagem natural. O Vipter publica o que esse agente precisa ler para acertar de primeira: as regras da API num arquivo de skill, um índice de páginas em llms.txt, cada página em Markdown, e a descrição da API em OpenAPI e em coleção Postman. Esta página diz onde está cada peça e como usar.
O que está publicado
| Peça | Endereço | Para que serve |
|---|---|---|
Skill vipter-api | https://docs.vipter.com/skills/vipter-api/SKILL.md | Instruções no formato Agent Skills (frontmatter name e description, corpo em Markdown): autenticação, convenções, objetos e seus equivalentes na Stripe, fluxos passo a passo, armadilhas. É o primeiro arquivo que o agente deve ler. |
| Índice de skills | https://docs.vipter.com/skills/index.json | Lista as skills publicadas, com versão e links. |
llms.txt | https://docs.vipter.com/llms.txt | Resumo para agentes no topo e a lista de todas as páginas, em três idiomas, com o link do Markdown de cada uma. |
| Páginas em Markdown | qualquer página desta central com .md no fim | Exemplo: https://docs.vipter.com/pt-br/developers/api-reference.md. Sem menu, sem HTML, só o conteúdo. |
| OpenAPI 3.1 | https://api.vipter.com/v1/openapi.json | Cada endpoint, parâmetro e objeto, com os esquemas. Serve para gerar clientes e para o agente conferir campos. |
| Coleção Postman | https://api.vipter.com/v1/postman.json | Gerada do OpenAPI a cada chamada: uma pasta por recurso, autenticação por variável apiKey, corpos de exemplo. Importa no Postman, no Bruno e no Insomnia. |
Nada disso pede chave. A chave entra só quando o agente roda o código que escreveu.
Como apontar o agente
Instale a skill no projeto, para que ela seja carregada quando a tarefa falar de Vipter:
mkdir -p .claude/skills/vipter-api
curl -sL https://docs.vipter.com/skills/vipter-api/SKILL.md -o .claude/skills/vipter-api/SKILL.mdDepois, peça a integração em linguagem natural:
Integre o checkout do nosso app com o Vipter: ao clicar em "assinar", crie uma sessão
de checkout com o ID do usuário, redirecione, e libere o plano no webhook
checkout.session.completed. A chave está em VIPTER_API_KEY. Use a skill vipter-api.O que pedir ao agente
Pedidos que a skill cobre bem, por ordem de frequência:
- Checkout com o usuário identificado: sessão de checkout com
client_reference_id, redirecionamento, confirmação porGETe por webhook. O roteiro humano está em SaaS: do cadastro ao dashboard. - Cobrança avulsa na assinatura:
POST /v1/subscriptions/{id}/chargescomIdempotency-Key, tratamento do402. - Uso medido: criar medidor, reportar eventos, dar preço na oferta ou na assinatura.
- Webhooks: endpoint, verificação da assinatura, deduplicação,
switchpor tipo de evento. - Migração da Stripe: trocar os trechos de código listados em Migrar da Stripe para o Vipter mantendo os dois provedores durante o corte.
Peça sempre que o código leia a chave de uma variável de ambiente e que confirme a chave com GET /v1/account antes de qualquer outra chamada. A skill já instrui isso; dizer de novo não custa.
O que nunca entregar ao agente
- A chave
vk_live_…no prompt. O agente não precisa dela para escrever o código; precisa dela para rodar. Coloque a chave no.envdo projeto e deixe o agente ler o nome da variável, não o valor. Se a chave vazou num chat, revogue e crie outra. - O segredo
whsec_…do endpoint, pelo mesmo motivo. - Permissão de rodar cobranças em produção sem conexão de teste. O Vipter não tem modo de teste; a conexão de teste do provedor é o que separa um teste de uma cobrança real. Veja Testar sem modo de teste.
Conferir o que o agente fez
- Os logs de requisições na aba Desenvolvedores mostram cada chamada que a chave fez, com status e duração.
- As entregas de cada endpoint mostram se o servidor do agente respondeu 2xx.
GET /v1/eventslista o que aconteceu na loja, no catálogo do endpoint.
O que vem a seguir
Um servidor MCP remoto, para o agente consultar e agir na loja sem escrever código, e um SDK fino em Node.js estão planejados, sem data. A skill, o OpenAPI e a coleção Postman já cobrem a integração por código.
O que fazer a seguir
- Leia a skill para saber o que o agente vai saber.
- Veja as convenções da API que a skill resume.
- Para uma migração, comece por Migrar da Stripe para o Vipter.
Migrar da Stripe para o Vipter
Guia para quem já cobra com a Stripe e vai passar a cobrar pelo Vipter, no todo ou só no Brasil: o que corresponde a quê (Price → oferta, Invoice → pedido), o que não migra (cartões salvos e assinaturas em curso), as mudanças no código de checkout, webhooks, cobranças avulsas e uso medido, com diffs em Node.js, e um plano de corte em cinco etapas que mantém os dois lado a lado durante a transição.
Uso medido (Meters)
Como cobrar por consumo deixando a conta com o Vipter, no formato dos Billing Meters da Stripe: criar um medidor, dar preço ao uso na oferta ou na assinatura, enviar eventos de uso, ler o período aberto e o que acontece quando o ciclo fecha, com exemplos em curl e Node.js, franquia, faixas de preço, limiar de cobrança e as diferenças em relação à Stripe.