Integrar con agentes de IA
Lo que Vipter publica para que un agente de IA (Claude Code, Cursor, Codex, ChatGPT y similares) integre la API sin ayuda humana: la skill vipter-api en el formato Agent Skills, el llms.txt con instrucciones, toda la documentación en Markdown, el OpenAPI 3.1 y la colección Postman; cómo apuntar el agente a cada uno, qué pedirle y qué nunca entregarle.
Gran parte de las integraciones hoy las escribe un agente de IA a partir de un pedido en lenguaje natural. Vipter publica lo que ese agente necesita leer para acertar a la primera: las reglas de la API en un archivo de skill, un índice de páginas en llms.txt, cada página en Markdown, y la descripción de la API en OpenAPI y en colección Postman. Esta página dice dónde está cada pieza y cómo usarla.
Qué está publicado
| Pieza | Dirección | Para qué sirve |
|---|---|---|
Skill vipter-api | https://docs.vipter.com/skills/vipter-api/SKILL.md | Instrucciones en el formato Agent Skills (frontmatter name y description, cuerpo en Markdown): autenticación, convenciones, objetos y sus equivalentes en Stripe, flujos paso a paso, trampas. Es el primer archivo que el agente debe leer. |
| Índice de skills | https://docs.vipter.com/skills/index.json | Lista las skills publicadas, con versión y enlaces. |
llms.txt | https://docs.vipter.com/llms.txt | Un resumen para agentes arriba y la lista de todas las páginas, en tres idiomas, con el enlace al Markdown de cada una. |
| Páginas en Markdown | cualquier página de este centro de ayuda con .md al final | Ejemplo: https://docs.vipter.com/es/developers/api-reference.md. Sin menú, sin HTML, solo el contenido. |
| OpenAPI 3.1 | https://api.vipter.com/v1/openapi.json | Cada endpoint, parámetro y objeto, con los esquemas. Sirve para generar clientes y para que el agente verifique campos. |
| Colección Postman | https://api.vipter.com/v1/postman.json | Generada del OpenAPI en cada llamada: una carpeta por recurso, autenticación por la variable apiKey, cuerpos de ejemplo. Se importa en Postman, Bruno e Insomnia. |
Nada de esto pide clave. La clave entra solo cuando el agente ejecuta el código que escribió.
Cómo apuntar el agente
Instala la skill en el proyecto, para que se cargue cuando la tarea hable 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.mdDespués, pide la integración en lenguaje natural:
Integra el checkout de nuestra app con Vipter: al hacer clic en "suscribirse", crea una
sesión de checkout con el ID del usuario, redirige y activa el plan en el webhook
checkout.session.completed. La clave está en VIPTER_API_KEY. Usa la skill vipter-api.Qué pedirle al agente
Pedidos que la skill cubre bien, por orden de frecuencia:
- Checkout con el usuario identificado: sesión de checkout con
client_reference_id, redirección, confirmación porGETy por webhook. La guía humana está en SaaS: del registro al dashboard. - Cobro adicional en la suscripción:
POST /v1/subscriptions/{id}/chargesconIdempotency-Key, tratamiento del402. - Uso medido: crear medidor, reportar eventos, poner precio en la oferta o en la suscripción.
- Webhooks: endpoint, verificación de la firma, deduplicación,
switchpor tipo de evento. - Migración desde Stripe: cambiar los fragmentos de código listados en Migrar de Stripe a Vipter manteniendo los dos proveedores durante el corte.
Pide siempre que el código lea la clave de una variable de entorno y que confirme la clave con GET /v1/account antes de cualquier otra llamada. La skill ya lo indica; repetirlo no cuesta nada.
Qué nunca entregarle al agente
- La clave
vk_live_…en el prompt. El agente no la necesita para escribir el código; la necesita para ejecutarlo. Pon la clave en el.envdel proyecto y deja que el agente lea el nombre de la variable, no el valor. Si una clave se filtró en un chat, revócala y crea otra. - El secreto
whsec_…del endpoint, por el mismo motivo. - Permiso para ejecutar cobros en producción sin conexión de prueba. Vipter no tiene modo de prueba; la conexión de prueba del proveedor es lo que separa una prueba de un cobro real. Consulta Probar sin modo de prueba.
Verificar lo que hizo el agente
- Los registros de solicitudes en la pestaña Desarrolladores muestran cada llamada que hizo la clave, con estado y duración.
- Las entregas de cada endpoint muestran si el servidor del agente respondió 2xx.
GET /v1/eventslista lo que pasó en la tienda, en el catálogo del endpoint.
Qué viene después
Un servidor MCP remoto, para que el agente consulte y actúe en la tienda sin escribir código, y un SDK ligero en Node.js están planeados, sin fecha. La skill, el OpenAPI y la colección Postman ya cubren la integración por código.
Qué hacer a continuación
- Lee la skill para saber lo que el agente va a saber.
- Mira las convenciones de la API que la skill resume.
- Para una migración, empieza por Migrar de Stripe a Vipter.