CLI winal

MODO PRUEBA

winal es el CLI oficial de desarrollador, estilo stripe-cli: inicia sesión contra un servidor Winal, dispara cobros de prueba y escucha los eventos del tenant en tiempo real — reenviándolos a tu servidor local ya firmados, sin exponer un endpoint público ni registrarlo de antemano.

Instalación

Mientras no haya un paquete publicado en NuGet.org, empaqueta e instala localmente desde el repo (cli/Winal.Cli):

bash
cd cli/Winal.Cli
dotnet pack -c Release -o ./nupkg
dotnet tool install -g winal --add-source ./nupkg

Deja el comando winal disponible en tu PATH. Para actualizar tras un cambio: dotnet tool update -g winal --add-source ./nupkg. O, durante desarrollo del propio CLI, córrelo directo sin empaquetar: dotnet run --project cli/Winal.Cli -- <comando> [opciones].

Los 4 comandos

winal login

Pide interactivamente la URL base del servidor y tu API key, y las guarda en ~/.winal/config.json con permisos 600 (el archivo contiene la clave en claro; solo tu usuario puede leerlo). Los otros tres comandos leen esta configuración.

$ winal login
Base URL del servidor [http://localhost:8080]:
API key (sk_test_... / sk_live_...): ****************************************

Listo. Guardado en ~/.winal/config.json (permisos 600).
  base_url = http://localhost:8080
  api_key  = sk_test_68Vo…mK

winal charge --amount <centavos> [--method card] [--token tok_sim_ok] [--currency MXN]

Crea un payment_intent, lo confirma (vía Winal.Sdk, el SDK oficial de servidor) y hace polling hasta un estado terminal imprimiendo la línea de tiempo — nunca asume éxito por la respuesta local de confirm, siempre confirma con un GET posterior (regla de arquitectura #5). --amount es en centavos, igual que amount_minor en toda la Api.

$ winal charge --amount 8490 --method card --token tok_sim_ok
winal charge — 84.90 MXN vía card (http://localhost:8080)

  [14:32:01] creado       → requires_payment_method
  [14:32:01] confirmado   → processing
    intento 09a0ac5c-3cca-42eb-9609-a9b65df9da6a: pending · conector=sim · método=card
  [14:32:02] poll #2      → succeeded

Cobro exitoso: 84.90 MXN (id=cf2b7b5e-7d60-4caa-a14a-5c5281deac9e)

Tokens de prueba disponibles (conector sim, tabla completa en Modo de pruebas): tok_sim_ok, tok_sim_auth, tok_sim_3ds, tok_sim_insufficient, tok_sim_fraud, tok_sim_issuer_down, tok_sim_provider_500, tok_sim_slow.

winal listen --forward-to <url> [--print-only]

Hace polling de GET /v1/events cada 2 segundos desde el último evento visto. Para cada evento nuevo: lo imprime en consola (hora, event_type, monto, event_id) y, si no pasaste --print-only, lo reenvía como POST a --forward-to con un header Gateway-Signature recalculada con un secreto de sesión (whsec_cli_...) que genera e imprime al arrancar — nunca el secreto real de un endpoint registrado en el tenant.

$ winal listen --forward-to http://localhost:4242/webhook
winal listen — http://localhost:8080

Reenviando a http://localhost:4242/webhook
Secreto de sesión: whsec_cli_3f9a1c...
  Cada evento se reenvía con 'Gateway-Signature' calculada con ESTE secreto (no el real
  del tenant): verifica tu firma localmente sin registrar un endpoint público.

Esperando eventos… (Ctrl+C para salir)

14:32:02  payment_intent.succeeded      · 84.90 MXN  3af1e9c2-...
    → 200 http://localhost:4242/webhook
Por qué un secreto de SESIÓN y no el real del tenant
winal listen no registra ningún endpoint (no llama POST /v1/webhook_endpoints) — solo hace polling de lectura sobre /v1/events. Para probar tu código de verificación de firma sin exponer un puerto público, firma él mismo cada evento reenviado con un secreto propio, usando exactamente el mismo esquema HMAC que la plataforma real (ver Webhooks → Gateway-Signature). Tu receptor de pruebas debe verificar con ESE secreto de sesión, no con el de un endpoint real.
Necesitas al menos un endpoint registrado
/v1/events solo se llena si el tenant tiene al menos un webhook_endpoint activo — cualquier URL sirve, incluso una que nunca reciba tráfico (ver Eventos y polling). Si winal listen no muestra nada, confirma que ya registraste uno.

winal status

Consulta GET /status (estado agregado api/database/worker) y GET /health/ready del servidor configurado.

$ winal status
winal status — http://localhost:8080

  status       operational
  version      1.0.0.0
  api          up
  database     up
  worker       unknown

  /health/ready   ready

Flujo típico de desarrollo local

  1. winal login — apunta a tu servidor local con una API key de prueba (portal → API Keys → Generar clave de prueba).
  2. Registra un endpoint de webhook (cualquier URL activa el llenado de /v1/events, ver arriba).
  3. En una terminal: winal listen --forward-to http://localhost:4242/webhook, con tu receptor de pruebas escuchando ahí.
  4. En otra terminal: winal charge --amount 8490 --method card para disparar un cobro de prueba.
  5. Verifica en listen que payment_intent.succeeded aparece, se reenvía y tu receptor confirma la firma.
  6. winal status en cualquier momento para confirmar que el servidor sigue arriba.

Detalle completo, snippets de verificación de firma en Python y notas de implementación en cli/README.md del repo.