OpenAPI y Scalar

El OpenAPI del ambiente es la referencia ejecutable del contrato HTTP. Scalar permite explorarlo y probar requests de manera interactiva.

Endpoints

GET /openapi.json
GET /docs

Anteponé la URL base del ambiente: {base_url}/openapi.json o {base_url}/docs.

Probar una operación

1. Abrir /docs en el ambiente de prueba.
2. Seleccionar la autenticación Bearer.
3. Ingresar una API key test sin comillas.
4. Ejecutar GET /v1/payment-methods y elegir un método activo.
5. Probar POST /v1/payments con una Idempotency-Key nueva.

No uses una key live en capturas, demos o herramientas compartidas.

Qué describe el spec

• autenticación JWT y API key;
• scopes requeridos;
• headers como Idempotency-Key;
• request, response y ejemplos;
• enums y formatos;
• paginación;
• errores públicos;
• webhooks salientes cuando estén modelados.

Los schemas públicos no exponen credenciales, configuración sensible, payloads crudos del procesador ni detalles internos del runtime.

Generación de SDKs

Los operationId estables —por ejemplo listPaymentMethods, createPayment o createRefund— permiten generar clientes. Revisá el resultado antes de publicarlo: debe conservar strings decimales de monto, headers de idempotencia, campos opcionales desconocidos y el envelope de error.

Fuente de verdad

Para rutas, obligatoriedad, schemas y enums prevalece el OpenAPI desplegado en el ambiente consumido. Estas guías explican semántica, flujos y prácticas operativas que el spec no expresa por completo.

Guardá una copia o checksum del spec usado para generar clientes y revisá el changelog antes de actualizarlo. Si encontrás una diferencia entre el spec y el comportamiento observado, reportala con X-Request-Id y el ambiente, sin incluir secretos.