Guía Rápida para Integraciones de Socios

Esta página es la referencia única del flujo de conexión para integraciones de socios — productos SaaS, plataformas de logística/envíos, herramientas de marketing y cualquier servicio externo que necesite actuar en nombre de uno o más comerciantes de Whatalo. Enlaza las páginas de referencia de esta sección en un solo camino lineal para que exista exactamente una forma correcta de implementarlo.

El patrón en una frase

Tú, como socio integrador, registras UN solo cliente OAuth para todo tu producto. No está vinculado a ninguna tienda en particular. Cada comerciante que quiere conectar tu integración hace clic en un botón "Autorizar", elige su tienda en la pantalla de consentimiento de Whatalo, y eso genera un access token independiente vinculado a su tienda — todo bajo tu único client_id.

El flujo completo

1. Registra tu cliente OAuth una sola vez. Esto lo haces tú, como socio — no por cada comerciante. Recibes un client_id y un client_secret que identifican tu integración para todos los comerciantes que se conecten alguna vez. Ver Registro de clientes.

2. Guarda client_id y client_secret en el entorno de tu backend. Viven en configuración del lado del servidor (gestor de secretos, variables de entorno) — nunca en el bundle de una app móvil, un bundle de navegador, ni en ningún código del lado del cliente.

   El client secret, y cada refresh_token que recibas después, nunca deben exponerse en código frontend ni enviarse al navegador. Son secretos del lado del servidor durante toda la vida de la integración.

3. Agrega un botón "Conectar con Whatalo" que redirija al comerciante a GET /oauth/authorize con los scopes que tu integración necesita (incluye write:webhooks si vas a autorregistrar un webhook en el paso 6). Ver Flujo de autorización para la forma completa de la solicitud, incluyendo PKCE, y Scopes para la tabla completa de scopes.

   El comerciante no crea ni provee ninguna credencial en este paso. Inicia sesión en Whatalo, elige la tienda que quiere conectar, revisa los scopes solicitados y hace clic en Autorizar. Esa es toda su participación en el flujo OAuth.

4. Maneja el callback en tu servidor e intercambia el code recibido por tokens en POST /oauth/token. La respuesta contiene access_token, refresh_token, expires_in y scope. Este intercambio ocurre servidor a servidor, usando tu client_secret — nunca en el navegador del comerciante. Ver Token endpoint.

5. Persiste los tokens en tu propia base de datos, asociados a la tienda del comerciante. Guarda el access_token, el refresh_token y la expiración que derivas de expires_in — los necesitas para cada llamada posterior a la API en nombre de ese comerciante. El refresh_token rota: cada renovación en POST /oauth/token devuelve un refresh_token nuevo, así que sobrescribe el valor guardado cada vez. El refresh_token también tiene su propia expiración, y presentar uno ya rotado revoca toda la familia de tokens del comerciante — así que conserva siempre solo el más reciente. Ver Token endpoint para los detalles de renovación y rotación.

6. Autorregistra tu webhook con POST /v1/webhooks, usando el access_token que acabas de recibir. Esto requiere el scope write:webhooks concedido en el paso 3. La respuesta incluye un secret de firma (en data.secret) que se devuelve una sola vez — guárdalo de inmediato junto a los tokens de ese comerciante. Ver Webhooks.

7. Verifica la firma de cada webhook entrante antes de confiar en su payload. Ver Seguridad de Webhooks para el esquema HMAC-SHA256 exacto y un ejemplo completo de verificación.

Ejemplo de callback handler

El ejemplo de abajo muestra los pasos 4 a 6 juntos: intercambiar el código de autorización por tokens, persistirlos para el comerciante y luego autorregistrar de inmediato un webhook con el access token resultante.

// Handler estilo Express montado en el redirect_uri que registraste en el paso 1.
// `codeVerifier` y `expectedState` se guardaron del lado del servidor (sesión o
// caché de corta duración) al construir la redirección a /oauth/authorize en el paso 3.
export async function handleOAuthCallback(req, res) {
  const { code, state } = req.query;
  const { codeVerifier, expectedState, merchant } =
    await getPendingAuthorization(state);

  if (state !== expectedState) {
    return res.status(400).send("Invalid state");
  }

  // Paso 4 — intercambia el código por tokens, servidor a servidor.
  const tokenResponse = await fetch("https://app.whatalo.com/oauth/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization:
        "Basic " +
        Buffer.from(
          `${process.env.WHATALO_CLIENT_ID}:${process.env.WHATALO_CLIENT_SECRET}`
        ).toString("base64"),
    },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      redirect_uri: process.env.WHATALO_REDIRECT_URI,
      client_id: process.env.WHATALO_CLIENT_ID,
      code_verifier: codeVerifier,
    }),
  });

  const { access_token, refresh_token, expires_in } =
    await tokenResponse.json();

  // Paso 5 — persiste los tokens en TU base de datos, asociados a la tienda de
  // este comerciante, antes que nada. Con ellos llamas a la API después y
  // renuevas cuando el access_token expira. El refresh_token rota en cada
  // renovación, así que sobrescribe siempre el valor guardado con el más nuevo.
  await saveTokensForMerchant(merchant, {
    access_token,
    refresh_token,
    expires_at: Date.now() + expires_in * 1000,
  });

  // Paso 6 — autorregistra tu webhook con el access token que acabas de recibir.
  // Requiere el scope write:webhooks solicitado en el paso 3.
  const webhookResponse = await fetch("https://api.whatalo.com/v1/webhooks", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${access_token}`,
    },
    body: JSON.stringify({
      url: "https://your-app.com/webhooks/whatalo",
      events: ["order.created", "order.updated"],
    }),
  });

  const { data: webhook } = await webhookResponse.json();

  // data.secret se devuelve SOLO en esta respuesta — persístelo ahora, junto a
  // los tokens de este comerciante, para la verificación de firma del paso 7.
  await saveWebhookSecretForMerchant(merchant, webhook.secret);

  return res.redirect("/connected");
}

Páginas relacionadas