La skill spidi para Claude Code

Cuando le pides a tu agente de IA que integre pagos, lo normal es que se invente un endpoint a mitad de camino, o que dé el trabajo por terminado en cuanto ve un 200. La skill spidi es la manera de que no te pase: un paquete de criterio y procedimiento que instalas en Claude Code para que tu propio agente trabaje con SPIDI sin inventar y sin darse por aprobado a sí mismo.

La skill spidi: responde preguntas e integra pagosGuion: .docx · .yaml

Dos trabajos, no uno

Es lo primero que conviene saber, porque mucha gente solo conoce el segundo.

1. Responder

"¿Cuánto dura una sesión de pago?" · "¿Con qué campo concilio un pago contra mi extracto bancario?" · "¿Por qué mi due_date_session no expira nada?" · "¿Qué valores admite user_type?"

La skill consulta esta misma documentación y responde citando el documento del que sale la respuesta. No registra cuentas, no monta nada, no arranca ningún procedimiento: una pregunta se contesta y termina ahí.

Y si la documentación no lo dice, lo dice. No lo supone. Esa es la mitad del valor: preguntas como "¿qué porcentaje exacto de comisión del banco me aplican?" o "¿cómo hago un reembolso?" tienen hoy una única respuesta honesta, y es que eso no está documentado. Un agente que se las inventa con aplomo es peor que no tener agente.

2. Integrar

Escribir la aplicación y cerrar el ciclo: crear el acuerdo y la sesión, forzar las dos fases del pago, lanzar un reto de firma corrupta contra tu propio servidor, y comprobar con el simulador —no contigo— que las tres cosas pasaron.

Este trabajo sí tiene procedimiento, y la skill lo sigue paso a paso.

Qué resuelve

Un agente de IA integrando pagos sin nadie mirando por encima falla de formas concretas, no aleatorias:

• Se inventa un endpoint o un campo cuando no está seguro, con total aplomo.
• Confunde "el pagador pagó" con "el dinero es tuyo". Son dos fases distintas —paid y accredited— y dar el pedido por bueno en el primero es el error más caro de todos.
• Se contesta a sí mismo. Si el webhook_url apunta al propio simulador en vez de a tu servidor, todo sale en verde y no se ha probado nada.
• Nunca comprueba la firma de verdad. Un 200 no demuestra que tu código la verifica: solo lo demuestra un rechazo a una firma corrompida.

Los cuatro están escritos dentro de la skill como criterios que no se negocian.

Por qué no sabe la API de memoria

Es deliberado, y es la decisión de diseño más importante de la pieza.

La skill no lleva copia del catálogo de endpoints. Lleva criterio —qué tiene que cumplir lo que escribe— y procedimiento —cómo se comprueba que lo cumple—. El conocimiento lo consulta por HTTP, en cada sesión, contra este portal.

Dos consecuencias, y las dos importan:

• No se desactualiza. El día que cambiemos una página, el agente lee la versión nueva sin que nadie reinstale nada. No hay una copia del catálogo envejeciendo dentro del paquete.
• Si no puede alcanzar la documentación, se para y te lo dice en vez de improvisar de memoria. Un agente offline recitando endpoints de pagos es exactamente el fallo que esto existe para evitar.

Cada respuesta viene con la versión del corpus que usó. No sirve para invalidar nada: sirve para reproducir. Si algo salió mal, se puede reconstruir después contra la documentación exacta que lo produjo.

Qué hace por ti cuando integra

• Distingue tus dos tokens, el de consola y el de API, y sabe que iniciar sesión en la consola invalida el de consola que ya tenías guardado.
• Guarda tus credenciales por entorno, nunca escritas en el código, en un fichero spidi.env que además añade a tu .gitignore. El mismo código tiene que poder correr en tu máquina y en un servidor.
• Reutiliza las credenciales que ya tengas antes de registrar una cuenta nueva. Registrar por costumbre te parte la traza en dos y te hace depurar en el sitio equivocado.
• Cierra el ciclo de verdad y solo entonces te dice que la integración funciona.
• Te acompaña al mudarte a un servidor: sabe qué cambia (la URL pública, el enrutado, que el relay se para) y qué no debería cambiar.

Qué NO hace

Tan importante como lo anterior, para que sepas cuándo no molestarla:

• No sustituye a la documentación. No sabe nada que este portal no diga. Si prefieres leerlo tú, el camino es el mismo.
• No sale a producción por ti. Trabaja contra el simulador. Las credenciales reales y la URL de producción las entrega SPIDI, y eso es una conversación con personas.
• No decide reglas de negocio. Qué precio pones, cómo repartes un split o qué haces con un pago fallido son decisiones tuyas.
• No inventa lo que no está. Si preguntas por reembolsos, suscripciones o límites de tasa, te va a decir que no están documentados — porque hoy no lo están.
• No es multi-herramienta. Está hecha para Claude Code. No es un plugin de tu IDE ni un servicio en la nube.

Cómo se le pide

No hace falta invocarla por su nombre. Se activa sola, y desde la versión 1.7.0 tampoco hace falta que digas «SPIDI»: le basta con reconocer su vocabulario —agreement_id, «acuerdo de liquidación», los dos tiempos— o que hables de recibir pagos en Venezuela. Es a propósito: quien lleva media hora integrando deja de repetir el nombre, y ahí es justo donde una respuesta de memoria hace más daño. Vale con hablar normal:

¿Cuánto dura una sesión de pago de SPIDI antes de expirar?

Haz una app en Node que reciba pagos con SPIDI y verifique los webhooks.

El webhook de SPIDI no me llega, y la traza no dice nada.

Sube mi integración de SPIDI a un servidor.

Las dos primeras son los dos trabajos; las dos últimas son los sitios donde más tiempo se pierde a mano.

Si prefieres hacerlo tú

La skill no sabe nada que esta documentación no diga: sigue exactamente las mismas guías que seguirías tú. El mismo camino, a mano, es Recibe tu primer pago y Conducir el ciclo en el simulador.

→ Cómo se instala