Resumen del Cliente API
Introducción a WhataloClient — el cliente REST tipado para acceder a datos de la tienda desde el código servidor de tu plugin.
El WhataloClient es un cliente REST tipado para acceder a datos de la tienda desde el código servidor de tu plugin. Cada método se mapea directamente a un endpoint REST de Whatalo y devuelve respuestas completamente tipadas.
Modelo de Seguridad
La API de Whatalo usa API keys para autenticación. Las API keys son credenciales exclusivas del servidor — nunca deben incluirse en JavaScript del lado del cliente, en código del navegador ni en el frontend del plugin.
Arquitectura
Plugin Frontend (iframe) Plugin Backend (tu servidor) API de Whatalo
│ │ │
│ 1. sessionToken() │ │
│──────────────────────────► │ │
│ 2. Bearer <session-token> │ │
│──────────────────────────► │ │
│ 3. Verificar token con WHATALO_CLIENT_SECRET │
│ │ │
│ 4. X-API-Key: wk_live_* │
│ │──────────────────────────►│
│ │ 5. Datos de respuesta │
│ │◄──────────────────────────│
│ 6. Datos filtrados │ │
│◄───────────────────────── │ │Qué Va Dónde
| Componente | ¿Tiene API Key? | ¿Tiene Session Token? | ¿Llama a la API directamente? |
|---|---|---|---|
| Plugin Frontend (iframe) | No — nunca | Sí — JWT de corta duración | No — nunca |
| Plugin Backend (tu servidor) | Sí — WHATALO_API_KEY | Sí — valida desde el frontend | Sí |
| Admin de Whatalo (host) | N/A | Sí — emite tokens | N/A |
El WhataloClient está pensado exclusivamente para tu backend. Consulta Session Tokens para entender cómo tu frontend se autentica con tu backend, y Autenticación para el panorama completo.
Elegir Entre Acceso Frontend y Backend
Usa la capa más pequeña que resuelva el trabajo:
| Necesidad | Capa recomendada |
|---|---|
Contexto de sesión dentro del iframe (storeId, storeName, locale, theme) | useWhataloContext() |
Datos de la tienda en solo lectura dentro del iframe (orders, products, store.timezone) | useWhataloData() |
| Escrituras, webhooks, exports o lógica confiable del servidor | WhataloClient |
Si tu plugin solo necesita datos de lectura en el frontend, prefiere Data Bridge en lugar de crear un backend solo para reenviar lecturas.
Instalación
El cliente viene incluido en @whatalo/plugin-sdk — no se necesita ningún paquete adicional.
import { WhataloClient } from "@whatalo/plugin-sdk";
const client = new WhataloClient({
apiKey: process.env.WHATALO_API_KEY!,
// baseUrl defaults to "https://api.whatalo.com/v1"
});Opciones del Constructor
| Opción | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
apiKey | string | — | Requerido. API key con alcance de tienda (wk_live_* o wk_test_*) |
baseUrl | string | https://api.whatalo.com/v1 | URL base de la API |
timeout | number | 30000 | Tiempo de espera de la solicitud en milisegundos |
retries | number | 0 | Número de reintentos para errores 5xx (0–3). Backoff exponencial: 2s, 4s, 8s |
fetch | Function | globalThis.fetch | Implementación personalizada de fetch (útil para pruebas) |
onRequest | Function | — | Callback invocado antes de cada solicitud |
onResponse | Function | — | Callback invocado después de cada respuesta (incluye duración) |
Autenticación
Cada solicitud incluye automáticamente:
X-API-Key: <apiKey>
Content-Type: application/jsonTu apiKey tiene alcance de tienda. Se emite cuando un comerciante instala tu plugin. Nunca la expongas del lado del cliente.
Encabezados de Límite de Tasa
El cliente lee los encabezados de límite de tasa de cada respuesta y los expone a través de client.rateLimit:
const products = await client.products.list({ page: 1, per_page: 25 });
// Read current rate limit state after any request
console.log(client.rateLimit);
// { limit: 100, remaining: 97, reset: 1709280000 }| Campo | Descripción |
|---|---|
limit | Máximo de solicitudes por ventana |
remaining | Solicitudes restantes en la ventana actual |
reset | Marca de tiempo Unix cuando se restablece la ventana |
Espacios de Nombres de Recursos
El cliente expone 8 espacios de nombres de recursos. Cada espacio cubre un área de la tienda del comerciante.
| Espacio de nombres | Descripción |
|---|---|
client.products.* | Gestión del catálogo de productos |
client.orders.* | Consulta de pedidos y actualizaciones de estado |
client.customers.* | Acceso a datos de clientes |
client.categories.* | Gestión de categorías de productos |
client.discounts.* | Gestión de códigos de descuento |
client.store.* | Configuración y metadatos de la tienda |
client.inventory.* | Seguimiento y ajustes de inventario |
client.webhooks.* | Gestión de suscripciones de webhooks |
Ejemplo Rápido
import { WhataloClient } from "@whatalo/plugin-sdk";
const client = new WhataloClient({
apiKey: process.env.WHATALO_API_KEY!,
});
// List the first page of active products
const { data, pagination } = await client.products.list({
page: 1,
per_page: 25,
status: "active",
});
console.log(`${pagination.total} total products`);
// Fetch a single order by ID
const order = await client.orders.get("order-id-123");
console.log(order.status);
// Read current store information
const store = await client.store.get();
console.log(store.currency);Comportamiento de Reintentos
Cuando se configura retries, el cliente reintenta automáticamente en respuestas 5xx usando backoff exponencial:
const client = new WhataloClient({
apiKey: process.env.WHATALO_API_KEY!,
retries: 3, // Retry up to 3 times on server errors
});| Intento | Retraso antes del reintento |
|---|---|
| 1er reintento | 2 segundos |
| 2do reintento | 4 segundos |
| 3er reintento | 8 segundos |
En respuestas 429 Rate Limited, el cliente no reintenta automáticamente a menos que retries > 0. Usa el campo RateLimitError.retryAfter para programar tu propio retraso. Consulta Errores y Límites de Tasa para más detalles.