Integrar

Integrar en tu stack

Un kit de mejores prácticas por stack, con código probado. Tu agente instala el que corresponde y sigue las reglas de ese framework.

terminal
npx talo-hub skills install                # detecta el stack del proyecto
npx talo-hub skills install --stack laravel  # o elegilo
npx talo-hub skills list                   # todos los kits

Kits

KitQué cubre
Next.js + Vercel
--stack nextjs-vercel		Route handlers y Server Actions, webhook con body crudo, variables por entorno de Vercel, Deployment Protection, Firewall y Cron para conciliar.
Node.js (Express, Fastify, NestJS, Koa)
--stack node-express		Cliente del hub, body crudo solo en la ruta del webhook, idempotencia en Postgres y un job de conciliación por cron. También Fastify, NestJS y Koa.
Python (FastAPI, Django, Flask)
--stack python		Cliente httpx2, el body crudo en FastAPI y Django, csrf_exempt, hmac.compare_digest, una tabla de eventos procesados y un comando de conciliación.
PHP + Laravel
--stack laravel		Cliente Http, $request->getContent(), el webhook fuera del CSRF, hash_equals, colas y el scheduler para conciliar.
Edge (Cloudflare Workers, Supabase Edge Functions, Deno)
--stack edge		Firma verificada con Web Crypto, secretos del runtime, idempotencia en D1 o Postgres, y Cron Triggers o pg_cron para conciliar.

Las reglas de cualquier integración

Todos los kits cumplen estas diez reglas. Si tu stack no tiene kit, tu agente las aplica con las herramientas de tu framework.

  1. Solo en el servidor. La key (TALO_HUB_API_KEY) y el secreto del webhook (TALO_HUB_WEBHOOK_SECRET) viven en variables de entorno del servidor, sandbox y producción en entornos distintos. Al navegador solo llegan el CVU, el alias, el monto, el estado y el vencimiento.
  2. Crear el cobro sin duplicarlo. POST /api/v1/payments con external_id = el id del pedido. Reintentar con el mismo external_id devuelve el mismo cobro. Si venció, usá un external_id nuevo.
  3. Verificar cada webhook sobre el body crudo. Antes de parsear el JSON: t dentro de 5 minutos, v1 de 64 caracteres hex, HMAC-SHA256 de "<t>.<body>" comparado en tiempo constante. Si falla, 400. Los eventos sin firma de events listen se aceptan solo en desarrollo local (next dev, o TALO_HUB_DEV_FORWARD=1 con una key tph_test_).
  4. Que la ruta quede accesible. Nada delante del webhook puede redirigir, pedir login ni desafiar: sin CSRF, sesión, protección anti-bots ni Deployment Protection. Registrá la URL https final.
  5. Responder 2xx en menos de 10 segundos. Guardá lo necesario, respondé y después hacé lo lento. Un evento repetido también recibe 2xx.
  6. Cada evento una sola vez, en la base. Los ids de evento van con una restricción única en la base o en Redis, nunca en memoria: las funciones serverless no la comparten.
  7. Releer el cobro antes de actuar. GET /api/v1/payments/{id}: SUCCESS u OVERPAID entrega el pedido una sola vez (update condicional), UNDERPAID pide el resto, EXPIRED ofrece un cobro nuevo.
  8. Conciliar. Un job programado relee los cobros que siguen PENDING o UNDERPAID, por si alguna entrega nunca llegó.
  9. Consultar el estado solo para la pantalla. Cada 3 a 10 segundos mientras el comprador mira el pedido. El pedido se entrega desde el webhook o la conciliación, nunca desde el navegador.
  10. Probarlo en sandbox. Transferencia exacta, de menos y de más, el mismo evento dos veces, un ping al webhook y npx talo-hub doctor.

Otro stack

Pedile a tu agente que lea /docs/stacks.md: tiene las reglas, qué buscar en la documentación de cada framework y el verificador en pseudocódigo. Lo prueba con el vector de prueba antes de desplegar.