Documentación de Vitruko

Contrato de respuesta

{
  "title": "Cafetera",
  "imageUrl": "https://tienda.com/cafetera-frente.jpg",
  "description": "Descripción publicada por la tienda",
  "url": "https://tienda.com/products/cafetera",
  "images": ["https://tienda.com/cafetera-frente.jpg", "https://tienda.com/cafetera-lateral.jpg"],
  "brand": "Casa",
  "price": { "amount": "129.90", "currency": "PEN" },
  "availability": "in_stock",
  "quality": {
    "productDetected": true,
    "missingFields": [],
    "fieldSources": {
      "title": "json_ld", "description": "json_ld", "images": "json_ld",
      "brand": "json_ld", "price": "json_ld", "availability": "json_ld"
    },
    "warnings": [],
    "extractedAt": "2026-11-07T12:00:00Z"
  }
}

Este es un ejemplo de respuesta completa. Los campos originales title, imageUrl, description y url se mantienen. La descripción, imagen y marca pueden estar vacías. images contiene hasta 20 URLs distintas y su primera imagen coincide con imageUrl. Vitruko devuelve enlaces a las imágenes; no descarga ni almacena esos archivos.

price es null cuando no hay un importe y una moneda publicados que correspondan a una oferta identificable. price.amount es un string decimal en unidades principales: "129.90" PEN significa S/ 129.90, no centavos. No inferimos la moneda por el dominio o el símbolo, no sumamos envío ni convertimos divisas. Un rango de precios no se presenta como un precio único.

availability puede ser in_stock, out_of_stock, preorder, backorder, discontinued o unknown. Refleja lo que publicó la tienda al consultarla; no es una garantía de inventario actual.

Calidad y procedencia

quality.productDetected indica si se identificaron datos de producto en la fuente. missingFields enumera campos ausentes o sin confirmar. fieldSources indica el origen de cada campo disponible: json_ld, microdata, open_graph, html_meta, html_title, product_meta, shopify_json o vtex_json. No es una puntuación de certeza ni una validación comercial.

quality.extractedAt usa UTC y se conserva al responder desde caché. Las advertencias posibles son product_not_confirmed, multiple_products, multiple_offers, price_range y variant_not_confirmed. Si hay varias ofertas o variantes, no elijas una por tu cuenta sin confirmar cuál corresponde al enlace.

url conserva el enlace normalizado: elimina seguimiento conocido y mantiene los identificadores de producto y variante. Una URL de variante se conserva, pero la extracción de su precio y stock depende de que la fuente permita identificar esa oferta. Trata los campos ausentes como datos incompletos y ofrece confirmación o edición en tu aplicación.

Prueba una petición real

Utiliza tu propia clave. Solo se consulta la tienda cuando pulsas «Extraer producto». Esta operación consume una petición de tu cuenta.

Cuotas y caché

Las cabeceras X-Quota-Limit, X-Quota-Remaining y X-Quota-Reset indican tu cuota. Para Scale, las primeras dos indican unlimited. El período Free es el mes UTC; los planes pagados usan su período de facturación.

X-Cache: HIT indica una respuesta en memoria de hasta cinco minutos; MISS, una consulta nueva. Ambas cuentan una petición. Los errores posteriores a admitir la clave también cuentan. Los rechazos de clave, permisos o cuota no se cobran. Respeta Retry-After cuando la API lo indique.

Errores que debes manejar

Alcance y uso de los datos

Vitruko lee Open Graph, JSON-LD y microdatos; complementa fichas compatibles con fuentes públicas de Shopify y VTEX. La consulta tiene un límite de tiempo de doce segundos. No ejecuta JavaScript, no usa sesiones de comprador ni supera CAPTCHA o bloqueos de tiendas. La disponibilidad puede variar.

Los nombres, imágenes y descripciones pertenecen a sus titulares. Comprueba las condiciones de la fuente y tus permisos antes de republicar información. Las imágenes se devuelven como URL; mostrarlas puede conectar el navegador del visitante con la tienda. Revisa los datos antes de guardarlos como definitivos.