Integra tu API de vehículos
con Shopify.

01 / PREPARACIÓN

Qué necesitas para comenzar

Esta guía explica una integración a medida para tu tienda. No es una app lista para instalar: necesitas un desarrollador que configure el servidor y el formulario.

02 / ARQUITECTURA

Tu clave se queda en el servidor

El navegador consulta una ruta de tu tienda. Shopify envía la solicitud firmada al backend de tu integración y este consulta GetAPI.

La respuesta recorre el camino inverso. No agregues tu API key a Liquid, JavaScript público ni campos del tema. La firma del proxy valida el origen de la solicitud; además necesitas límites para evitar consumo abusivo.

03 / IMPLEMENTACIÓN

De la API a tu tienda, paso a paso

1. Obtén tu API key y prueba el endpoint

   Contrata el plan adecuado y prueba una patente conocida desde tu servidor o Postman. Revisa los campos y permisos en la documentación. Los datos disponibles pueden variar por vehículo y plan.

   curl 'https://chile.getapi.cl/v1/vehicles/plate/ABCD12'   --header 'x-api-key: TU_API_KEY'

2. Crea la integración de Shopify

   Desde el Dev Dashboard, crea una app con la plantilla React Router de Shopify CLI. Usa una tienda de desarrollo para probar. Para una sola tienda puedes elegir distribución personalizada e instalarla con su autorización.

   Es una app técnica propia de la tienda, no una app GetAPI publicada en el App Store. Crear una app con Shopify →

3. Configura los secretos del backend

   Define estas variables en el servidor que aloja tu integración. Mantén también las variables y el almacenamiento de sesiones de la plantilla de Shopify.

   GETAPI_API_KEY=tu_clave_privada
   SHOPIFY_SHOP=tu-tienda.myshopify.com

4. Conecta el App Proxy

   Agrega write_app_proxy a los permisos existentes en shopify.app.toml, configura el proxy y despliega la configuración. Autoriza los nuevos permisos si Shopify lo solicita.

   [app_proxy]
   url = "/proxy"
   prefix = "apps"
   subpath = "getapi"

   Con esta configuración, /apps/getapi/vehiculo se envía a /proxy/vehiculo en tu backend. Si cambias el prefijo o la ruta en Shopify, actualiza también el formulario.

5. Agrega el endpoint y el formulario

   Usa los ejemplos de abajo. En una copia del tema, abre el editor visual y agrega un bloque «Liquid personalizado» donde esté disponible. Pega el formulario una sola vez por página. El ejemplo muestra los datos; no modifica el carrito ni guarda información en pedidos.

6. Despliega y valida antes de activar

   Aloja el backend en HTTPS, actualiza la URL de la app y comprueba la instalación y las consultas. Completa los límites de consumo y la lista de validación antes de publicar el tema.

04 / PARA TU DESARROLLADOR

Ejemplos para adaptar a tu tienda

Base para una integración de una sola tienda con la plantilla React Router de Shopify. No es un paquete de producción: debes incorporar límites por tienda y visitante, monitoreo y la política de datos que corresponda a tu uso.

// app/routes/proxy.vehiculo.ts — plantilla Shopify React Router
import { authenticate } from "../shopify.server";
import type { LoaderFunctionArgs } from "react-router";

export async function loader({ request }: LoaderFunctionArgs) {
  const { session } = await authenticate.public.appProxy(request);
  if (!session || session.shop !== process.env.SHOPIFY_SHOP) {
    return Response.json({ message: "Tienda no autorizada" }, { status: 403 });
  }
  const headers = { "Cache-Control": "no-store" };
  const plate = (new URL(request.url).searchParams.get("plate") || "")
    .toUpperCase().replace(/[\s-]/g, "");
  if (!/^[A-Z0-9]{5,6}$/.test(plate)) {
    return Response.json({ message: "Revisa la patente" }, { status: 400, headers });
  }
  if (!process.env.GETAPI_API_KEY) {
    return Response.json({ message: "Servicio sin configurar" }, { status: 503, headers });
  }
  // Antes de llamar a GetAPI: aplicar límites por tienda y visitante.
  try {
    const response = await fetch(
      "https://chile.getapi.cl/v1/vehicles/plate/" + encodeURIComponent(plate),
      { headers: { "x-api-key": process.env.GETAPI_API_KEY },
        signal: AbortSignal.timeout(15000) }
    );
    if (!response.ok) {
      const status = response.status === 404 ? 404 : response.status === 429 ? 429 : 502;
      const message = status === 404 ? "Vehículo no encontrado"
        : status === 429 ? "Límite de consultas alcanzado" : "No pudimos consultar el vehículo";
      return Response.json({ message }, { status, headers });
    }
    const { data } = await response.json();
    // Exponer únicamente los datos que necesita la tienda.
    return Response.json({
      plate: data.licensePlate || plate,
      brand: data.model?.brand?.name ?? null,
      model: data.model?.name ?? null,
      year: data.year ?? null,
    }, { headers });
  } catch {
    return Response.json({ message: "Servicio temporalmente no disponible" },
      { status: 503, headers });
  }
}

El backend devuelve un objeto reducido: plate, brand, model y year. Consulta la estructura vigente de GetAPI antes de adaptar otros endpoints. Si no hay información para un campo, devuelve null.

<form id="getapi-vehicle-form">
  <label for="getapi-plate">Patente del vehículo</label>
  <input id="getapi-plate" name="plate" placeholder="ABCD12"
    maxlength="8" required autocapitalize="characters">
  <button type="submit">Consultar vehículo</button>
  <p id="getapi-result" role="status" aria-live="polite"></p>
</form>
<script>
  document.querySelector('#getapi-vehicle-form').addEventListener('submit', async (event) => {
    event.preventDefault();
    const form = event.currentTarget;
    const button = form.querySelector('button');
    const result = form.querySelector('#getapi-result');
    button.disabled = true;
    result.textContent = 'Consultando…';
    try {
      const plate = form.querySelector('[name="plate"]').value;
      const response = await fetch('/apps/getapi/vehiculo?plate=' + encodeURIComponent(plate),
        { signal: AbortSignal.timeout(20000) });
      const vehicle = await response.json();
      if (!response.ok) throw new Error(vehicle.message || 'No pudimos realizar la consulta');
      result.textContent = [vehicle.brand, vehicle.model, vehicle.year]
        .filter(Boolean).join(' · ') || 'Vehículo encontrado sin datos descriptivos';
    } catch (error) {
      result.textContent = error.name === 'TimeoutError'
        ? 'La consulta tardó demasiado. Intenta nuevamente.'
        : error.message || 'No pudimos realizar la consulta';
    } finally { button.disabled = false; }
  });
</script>

¿Quieres usar tasación, consulta por VIN, decodificación o recalls? Conserva la misma separación entre formulario y servidor y adapta la validación, el endpoint y los campos según el contrato de cada API.

05 / VALIDACIÓN

Antes de publicar tu integración

• Prueba una patente conocida, una inexistente y una entrada inválida.
• Comprueba las respuestas ante credenciales inválidas, límite de consultas y caída del servicio.
• Verifica que solicitudes sin firma válida y de otras tiendas sean rechazadas.
• Aplica límites por tienda y visitante en el backend; la firma del App Proxy no impide que un visitante repita consultas.
• Revisa que la API key no aparezca en el HTML, las solicitudes del navegador o los logs.
• Prueba el formulario en móvil y con teclado. Confirma que no interfiera con la compra.
• Define qué datos conservarás y su eliminación; informa al comprador sobre su uso.

06 / DUDAS FRECUENTES

Lo que conviene tener claro