binkio-api

Una skill es una carpeta con instrucciones que Claude carga cuando el tema sale. Ésta le da lo que la referencia OpenAPI no puede darle: por qué las cosas son como son, y los errores concretos que ya ha cometido alguien integrándose.

⬇️ Descargar binkio-api-skill.zip

Para quién

Para ti, que te vas a integrar. No hace falta ser cliente de Binkio para usarla, y no contiene nada interno: todo lo que trae es sobre la API pública, que está documentada en este mismo sitio.

Qué sabe

• Qué campo es el bruto y cuál el neto, que es de lejos la confusión más cara: amount es lo que pedía el cobro, net_amount lo que ingresó el comercio, y net_currency puede no ser la moneda del enlace.
• Cómo se verifica la firma de un webhook sin dejar abierta la puerta a una repetición, con código que funciona en Node, Python y PHP — incluida la trampa de reserializar el JSON, que hace que la firma no valide nunca y no da ninguna pista de por qué.
• Qué hacer con cada error, agrupados por la reacción correcta —reintentar, arreglar la petición, parar y avisar a una persona— en vez de una lista alfabética.
• Los flujos completos: cobro, cobro cruzado, QR de mostrador, retiros, conversiones, depósitos y cómo recorrer una lista paginada hasta el final.
• Ocho errores de integración que ya cometió alguien, con qué pasa y qué hacer en su lugar.

Y lo primero que hace ante cualquier duda concreta es descargar el contrato vivo de https://api.binkio.com/v1/openapi.json, porque es la única fuente que no se queda vieja.

Instalar en Claude Code

# en tu proyecto
mkdir -p .claude/skills
unzip ~/Downloads/binkio-api-skill.zip -d .claude/skills/

Queda como .claude/skills/binkio-api/SKILL.md. Claude la carga solo cuando el tema lo pide — no ocupa contexto mientras no la necesites.

Para tenerla en todos tus proyectos, descomprime en ~/.claude/skills/.

Comprobar que quedó

Pregúntale algo que sin la skill no sabría:

¿El amount del webhook payment_link.paid de Binkio es lo que cobré o lo que me ingresaron?

Con la skill responde que es lo que pedía el enlace —el bruto, idéntico al de GET /v1/payment_links/{code}— y que el ingreso es net_amount. Sin ella, lo más probable es que se lo invente.

Qué NO trae

Sólo contiene lo que ya está publicado en esta documentación sobre la API pública. No trae credenciales, datos de clientes ni nada que no puedas leer aquí.

:::tip Siempre la versión actual El zip se vuelve a generar cada vez que se publica este sitio, así que lo que descargas coincide con la documentación que estás leyendo. :::