Referencia API v1.0

Documentación
de la API BLYNE

Integra el ID Corporal Universal de BLYNE en tu tienda o plataforma. Recomendaciones de talla con 92% de precisión en menos de 200ms.

REST API

TLS 1.3

<200ms P99

99.99% uptime

Inicio rápido

Obtén tu primera recomendación de talla en menos de 5 minutos. Solo necesitas tu API key y el ID del producto.

1. Instala el SDK

npm install @blyne/sdk

2. Primera llamada

curl -X POST https://api.blyne.app/v1/recommend \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "product_id": "prod_jeans_slim_001",
    "fit_preference": "regular"
  }'

Respuesta en <200ms. La API BLYNE está optimizada para ser llamada en tiempo real durante el proceso de compra, sin afectar la experiencia del usuario.

Autenticación

BLYNE utiliza API keys tipo Bearer para autenticar todas las peticiones. Puedes gestionar tus keys desde el Dashboard → API Keys.

sk_test_Test

Para desarrollo. No genera cargos ni afecta datos reales.

sk_live_Live

Para producción. Requiere verificación de dominio.

# Incluye la API key en el header Authorization
curl https://api.blyne.app/v1/profiles/usr_abc123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Nunca expongas tu API key en el frontend. Usa siempre variables de entorno del servidor. Para llamadas desde el navegador, usa el SDK de cliente con tu publishable_key.

Errores

BLYNE usa códigos HTTP estándar. Los errores devuelven un objeto JSON con error.code y error.message.

Código	Error	Descripción
400	`invalid_request`	Parámetros inválidos o faltantes en la petición.
401	`unauthorized`	API key inválida, expirada o sin permisos suficientes.
404	`not_found`	El recurso solicitado (usuario, producto) no existe.
409	`conflict`	El recurso ya existe (ej: producto con mismo SKU).
422	`insufficient_data`	El perfil del usuario no tiene suficientes medidas para generar una recomendación.
429	`rate_limit_exceeded`	Has superado el límite de peticiones. Ver sección Rate Limits.
500	`internal_error`	Error interno del servidor. Reinténtalo con backoff exponencial.

Límites de tasa

Starter

10 req/s

500 req/min

Growth

100 req/s

5.000 req/min

Enterprise

Sin límite

Personalizado

Perfiles de usuario

POST /v1/profiles

POSThttps://api.blyne.app/v1/profiles

Crea un nuevo perfil corporal para un usuario. El perfil almacena las medidas físicas y preferencias de fit que BLYNE usa para generar recomendaciones.

Parámetro	Tipo	Req.	Descripción
`user_id`	string	Sí	Identificador único del usuario en tu sistema. Máx. 128 caracteres.
`height_cm`	number	Sí	Altura en centímetros. Rango: 100–250.
`weight_kg`	number	Sí	Peso en kilogramos. Rango: 30–300.
`gender`	string	Sí	Género para el modelo de tallas. Valores: male, female, non_binary.
`fit_preference`	string	No	Preferencia de ajuste por defecto. Valores: slim, regular, relaxed. Default: regular.
`measurements`	object	No	Medidas adicionales: chest_cm, waist_cm, hips_cm, inseam_cm.

curl -X POST https://api.blyne.app/v1/profiles \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "height_cm": 178,
    "weight_kg": 74,
    "gender": "male",
    "fit_preference": "regular",
    "measurements": {
      "chest_cm": 96,
      "waist_cm": 82,
      "hips_cm": 98
    }
  }'

GET /v1/profiles/:user_id

GEThttps://api.blyne.app/v1/profiles/:user_id

curl https://api.blyne.app/v1/profiles/usr_abc123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

PATCH /v1/profiles/:user_id

PATCHhttps://api.blyne.app/v1/profiles/:user_id

curl -X PATCH https://api.blyne.app/v1/profiles/usr_abc123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "weight_kg": 76, "fit_preference": "slim" }'

POSThttps://api.blyne.app/v1/recommend

El endpoint principal de BLYNE. Devuelve la talla recomendada con Fit Score, alternativas y un insight textual sobre cómo talla esa prenda específica.

Parámetro	Tipo	Req.	Descripción
`user_id`	string	Sí	ID del usuario con perfil existente en BLYNE.
`product_id`	string	Sí	ID del producto en tu catálogo BLYNE.
`fit_preference`	string	No	Sobreescribe la preferencia del perfil para esta petición.
`locale`	string	No	Idioma del insight textual. Valores: es, en, fr, de. Default: es.

curl -X POST https://api.blyne.app/v1/recommend \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "product_id": "prod_jeans_slim_001",
    "fit_preference": "regular",
    "locale": "es"
  }'

# Response:
# {
#   "size": "M",
#   "fit_score": 92,
#   "confidence": "high",
#   "alternatives": [
#     { "size": "L", "fit_score": 78, "label": "más cómodo" }
#   ],
#   "insight": "Esta marca talla pequeño en hombros. Si tienes hombros anchos, considera la L.",
#   "sizing_system": "EU",
#   "latency_ms": 87
# }

Fit Score

El Fit Score es un porcentaje de 0–100 que indica qué tan bien encaja una talla con el cuerpo y preferencias del usuario. Es el diferenciador clave de BLYNE frente a sistemas de tallas tradicionales.

90–100

Perfecto

75–89

Muy bien

60–74

Aceptable

0–59

No recomendado

POST /v1/recommend/batch

POSThttps://api.blyne.app/v1/recommend/batch

Obtén recomendaciones para múltiples productos en una sola llamada. Ideal para páginas de listado o carritos. Máximo 50 productos por batch.

curl -X POST https://api.blyne.app/v1/recommend/batch \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "products": [
      { "product_id": "prod_001", "fit_preference": "regular" },
      { "product_id": "prod_002", "fit_preference": "slim" },
      { "product_id": "prod_003" }
    ]
  }'

Catálogo de prendas

Para que BLYNE pueda recomendar tallas, necesita conocer las medidas reales de cada prenda en tu catálogo. Puedes subir prendas individualmente o en batch CSV.

¿Qué datos necesita BLYNE? Para cada prenda necesitas las medidas reales en centímetros por talla (pecho, cintura, largo, etc.). No las tallas del fabricante — las medidas físicas de la prenda.

POST /v1/catalog/products

POSThttps://api.blyne.app/v1/catalog/products

Parámetro	Tipo	Req.	Descripción
`product_id`	string	Sí	ID único del producto en tu sistema (SKU, slug, etc.).
`name`	string	Sí	Nombre del producto.
`category`	string	Sí	Categoría: tops, bottoms, dresses, outerwear, footwear.
`brand`	string	Sí	Nombre de la marca.
`sizing_system`	string	No	Sistema de tallas: EU, US, UK, IT. Default: EU.
`measurements`	object	Sí	Objeto con medidas reales por talla. Ver ejemplo.

curl -X POST https://api.blyne.app/v1/catalog/products \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_jeans_slim_001",
    "name": "Jean Slim Fit Azul",
    "category": "bottoms",
    "brand": "BLYNE Denim",
    "sizing_system": "EU",
    "measurements": {
      "XS": { "waist_cm": 72, "hips_cm": 90, "inseam_cm": 76, "rise_cm": 25 },
      "S":  { "waist_cm": 76, "hips_cm": 94, "inseam_cm": 77, "rise_cm": 25 },
      "M":  { "waist_cm": 80, "hips_cm": 98, "inseam_cm": 78, "rise_cm": 26 },
      "L":  { "waist_cm": 86, "hips_cm": 104, "inseam_cm": 79, "rise_cm": 26 },
      "XL": { "waist_cm": 92, "hips_cm": 110, "inseam_cm": 80, "rise_cm": 27 }
    }
  }'

GET /v1/catalog/products

GEThttps://api.blyne.app/v1/catalog/products

curl "https://api.blyne.app/v1/catalog/products?limit=20&category=bottoms" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

DELETE /v1/catalog/products/:product_id

DELETEhttps://api.blyne.app/v1/catalog/products/:product_id

curl -X DELETE https://api.blyne.app/v1/catalog/products/prod_001 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Webhooks

BLYNE envía webhooks para notificarte de eventos importantes en tiempo real. Regístralos desde el Dashboard → Webhooks.

Eventos disponibles

recommendation.generated

Se generó una recomendación de talla para un usuario.

profile.created

Un nuevo perfil corporal fue creado.

profile.updated

Las medidas de un perfil fueron actualizadas.

feedback.received

Un usuario envió feedback sobre una recomendación (devolución, compra, etc.).

catalog.product.created

Un nuevo producto fue añadido al catálogo.

catalog.product.deleted

Un producto fue eliminado del catálogo.

Verificación de firma

Cada webhook incluye el header Blyne-Signature con un HMAC-SHA256 del payload. Verifica siempre la firma antes de procesar el evento.

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// En tu endpoint Express:
app.post('/webhooks/blyne', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['blyne-signature'];
  const isValid = verifyWebhook(req.body, sig, process.env.BLYNE_WEBHOOK_SECRET);
  
  if (!isValid) return res.status(401).send('Invalid signature');
  
  const event = JSON.parse(req.body);
  
  switch (event.type) {
    case 'feedback.received':
      // Actualizar tu sistema de inventario o CRM
      console.log('Feedback:', event.data);
      break;
    case 'recommendation.generated':
      // Analytics o tracking
      break;
  }
  
  res.json({ received: true });
});

SDKs oficiales

JavaScript / Node.js

npm install @blyne/sdk
# o
yarn add @blyne/sdk

Python

pip install blyne-sdk

Shopify (1 clic)

Instala el widget BLYNE en tu tienda Shopify con una sola línea de código en tu tema Liquid.

{%- comment -%} Añade esto en tu theme.liquid antes de </body> {%- endcomment -%}
<script
  src="https://cdn.blyne.app/widget/v1.js"
  data-api-key="{{ shop.metafields.blyne.publishable_key }}"
  data-locale="{{ request.locale.iso_code }}"
  async
></script>

BLYNE API

← Inicio Para Marcas Soporte Changelog