Genera tu cliente · Documentación de Winal

No necesitas esperar a que exista un SDK en tu lenguaje: Winal publica su contrato OpenAPI completo, así que puedes generar un cliente tipado en prácticamente cualquier stack — o integrar directo con curl/REST. Todo el API es JSON sobre HTTPS en snake_case.

El contrato OpenAPI

La especificación viva se sirve en tiempo de ejecución desde tu propia instancia:

el contrato

GET https://api.winal.com.mx/openapi/v1.json

Es un documento OpenAPI 3 con cada ruta de /v1 y /public, sus esquemas de request/response y el securityScheme Bearer. Una copia versionada del mismo contrato vive en el repositorio como sdks/openapi.json (la base de los SDKs oficiales). Descárgalo así:

bash

curl -s "https://api.winal.com.mx/openapi/v1.json" -o winal-openapi.json

Alcance del documento público

El contrato cubre la superficie de integración: /v1/* y /public/*. Las rutas internas del portal (/admin, /portal-auth) quedan fuera a propósito — no son API de terceros.

SDKs oficiales

Mantenemos cuatro SDKs generados y probados con un smoke E2E real contra el API. Todos salen del mismo contrato OpenAPI de arriba.

Lenguaje	Generador	En el repo
C# / .NET	Kiota	`sdks/csharp`
TypeScript	Kiota	`sdks/typescript`
PHP	openapi-generator	`sdks/php`
Python	openapi-generator	`sdks/python`

Como se generan del contrato, siguen la misma convención snake_case y los mismos nombres de recurso que ves en la Referencia de API.

Genera un cliente en cualquier lenguaje

Con el contrato en la mano, openapi-generator produce un cliente idiomático para Java, Go, Ruby, PHP, Python, Kotlin, Swift, Rust y muchos más. El patrón es siempre el mismo: -i el contrato, -g el generador, -o la carpeta de salida.

bash · Java

openapi-generator-cli generate \
  -i winal-openapi.json \
  -g java \
  -o ./winal-java

bash · Go

openapi-generator-cli generate \
  -i winal-openapi.json \
  -g go \
  -o ./winal-go \
  --additional-properties=packageName=winal

bash · Ruby

openapi-generator-cli generate \
  -i winal-openapi.json \
  -g ruby \
  -o ./winal-ruby \
  --additional-properties=gemName=winal

bash · PHP

openapi-generator-cli generate \
  -i winal-openapi.json \
  -g php \
  -o ./winal-php

bash · Python

openapi-generator-cli generate \
  -i winal-openapi.json \
  -g python \
  -o ./winal-python \
  --additional-properties=packageName=winal

Instala el generador con Homebrew (brew install openapi-generator), npm (npm i -g @openapitools/openapi-generator-cli) o el JAR oficial. La lista completa de generadores está en su documentación; el contrato de Winal es OpenAPI 3 estándar, así que cualquiera funciona. Recuerda configurar en el cliente generado el Bearer token (tu sk_test_…) — ver Autenticación y seguridad.

Un cliente generado NO valida por ti

El generador te da tipos y llamadas cómodas, pero la idempotencia (Idempotency-Key en cada POST que mueve dinero) y la verificación de firma de webhooks siguen siendo tu responsabilidad. Ver Webhooks.

¿Sin generador? curl y REST directo

Cualquier stack con un cliente HTTP integra sin dependencias: pones el header Authorization: Bearer, mandas JSON y lees JSON. No hace falta librería.

bash

curl -s "https://api.winal.com.mx/v1/payment_intents" \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount_minor": 84900, "currency": "MXN" }'

Y si prefieres tu terminal a escribir código, el CLI winal envuelve los flujos más comunes (login/charge/listen/status).