cross-tenant · k-anónimo · POS + storefront + stocking
Sugerí lo que
tus clientes
ya querían comprar.
Motor de recomendaciones que aprende co-ocurrencia desde las ventas de toda la red. Privacidad k-anónima por diseño. Una llamada para POS, otra para storefront, otra para decidir qué stockear.
$ curl https://api.ez-recommendations.huggian.com/v1/recommendations \
-H "X-API-Key: ezr_basic_xxxxxxxx" \
-d '{"basket":[...],"available":[...],"limit":3}'
# clientes que compraron coca también compraron
{
"items": [
{ "product_id": "5f1a...", "score": 0.78 },
{ "product_id": "7c92...", "score": 0.55 },
{ "product_id": "ab1e...", "score": 0.41 }
],
"k_anon_satisfied": true,
"cohort_size": 47
}POS upsell · Storefront PDP · Stocking suggestions. Una API, tres superficies.
¿Por qué ez-recommendations?
La señal de toda la red.
Privada, rápida, accionable.
Ocho decisiones de diseño que diferencian un motor que corre en producción de un experimento que se rompe en el primer día.
Cross-tenant
Aprende de toda la red
Cada venta de cada tenant suma señal global. Co-ocurrencia basket-aware con confidence score. Cuanto más vende la red, mejor son tus sugerencias.
Privacidad
k-anonimato por diseño
Ningún par de productos aparece en una recomendación hasta que cleared el threshold de tenants distintos. Tu mix de productos nunca queda expuesto a competidores.
Latencia
POS-grade speed
p95 sub-50ms para reads. UNION ALL sobre índices canónicos, basket-size caps, cohort cache. Diseñado para el momento exacto entre scanner y total.
Stocking
Decisiones de compra
Endpoint inverso: "lo que tus clientes ya querían y vos no vendés todavía". Convertí señal de la red en decisión de stock — sin guess work.
Categorías
Agrupado por rubro
Proyección de categorías paralela vía ez-catalog. Cold-start fallback automático cuando el par exacto todavía no tiene señal — rubro relacionado lo sustituye.
Forgery-safe
Reversal endurecido
Los reversal usan los items originales de la venta, no los enviados por el caller. Reviews adversariales de seguridad: actores comprometidos no pueden envenenar la red.
Tiers
Free → Enterprise
Plan free para evaluar (1k sales/mes), Basic para un POS, Pro multi-tenant, Enterprise sin tope. Usage por endpoint medido y expuesto vía admin API.
Idempotencia
Retry-safe
UNIQUE(api_key_id, sale_id, kind) en outbox: reintentos retornan 409, nunca duplican. Worker procesa por fila, poison messages aislados.
Integración
Tres pasos para
que la red
trabaje para vos.
REST + JSON. Sin SDK propietario. Si podés hacer un POST, ya podés integrar.
Provisioná tu API key
Plan Free sin tarjeta. Definí tier + scopes (ingest, read, stocking) + tenant whitelist. Argon2id-hash, key prefix indexado.
# X-API-Key en cada request
curl https://api.ez-recommendations.huggian.com/v1/recommendations \
-H "X-API-Key: ezr_basic_XXXXXXXX" \
-d '{...}'Emití cada venta
POST /v1/ingest/sale con tenant_id + sale_id + items (UUIDs de ez-catalog). Idempotente, 202 Accepted, fire-and-forget desde tu outbox.
// JavaScript
await fetch(API + '/v1/ingest/sale', {
method: 'POST',
headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
tenant_id: companyId,
sale_id: saleId,
items: [productAUuid, productBUuid, productCUuid],
})
});Consultá en el momento
POST /v1/recommendations con el basket actual + inventory disponible. Devuelve top-K filtrado a productos que tenés en stock.
// Python
import requests
r = requests.post(API + '/v1/recommendations',
headers={'X-API-Key': KEY},
json={'basket': cart_uuids, 'available': stock_uuids, 'limit': 5})
for item in r.json()['items']:
print(item['product_id'], item['score'])Planes
Pagás por uso,
no por servidor.
Quotas mensuales claras, rate limit por minuto, sin sorpresas. Cambio de plan en cualquier momento.
Free
Para probar la API + integrar en staging.
- 500 sales / mes
- 100 reads / mes
- 10 stocking / mes
- 30 reqs / min
- Solo sandbox · sin tarjeta
Basic
Una integración productiva — POS o e-commerce.
- 50.000 sales / mes
- 150.000 reads / mes
- 5.000 stocking / mes
- 600 reqs / min
- Soporte por email · 48h
Pro
Multi-tenant integrators · agencias · marketplaces.
- 500.000 sales / mes
- 1.500.000 reads / mes
- 50.000 stocking / mes
- 2.500 reqs / min
- Soporte prioritario · 24h
Enterprise
Sin tope. SLA contractual, DPA, deploy dedicado on request.
- Volúmenes sin tope
- Rate limit 15.000+ / min
- SLA 99.9% contractual
- DPA + Ley 25.326
- Onboarding asistido
Todos los planes incluyen TLS, RFC 7807 errors, audit log y RBAC por scope. ez-recommendations corre por encima de ez-catalog — requiere al menos plan Basic de ez-catalog para resolver UUIDs canónicos.
Preguntas frecuentes
Las dudas honestas,
respondidas.
¿Cómo aprende el motor sin compartir mis datos con competidores?
k-anonimato a nivel de proyección. Un par de productos solo entra al pool global cuando lo aportaron al menos N tenants distintos (config min_distinct_companies). Si tu mix es único, tus pares no salen de tu cuenta. Si es popular, se cuenta como uno entre muchos.
¿Qué surfaces puedo construir con la API?
Tres canónicas: POS cart upsell (basket-aware, 2s debounce recomendado), Storefront PDP/cart drawer ("clientes también compraron"), y un dashboard de stocking para que el dueño descubra qué productos suma a su catálogo. Mismo endpoint, distintos filtros.
¿Qué identificador usa? ¿Necesito mapear productos a algún SKU global?
Usamos los UUIDs de ez-catalog como clave canónica. Resolución barcode → UUID es por ez-catalog (también un servicio nuestro). Si ya integraste ez-catalog, ez-recommendations sale "gratis". Si no, el resolver corre del lado del worker.
¿Cómo evita el motor sugerir productos que no tengo?
Pasás tu inventario activo en cada request como parámetro "available". La query filtra a nivel DB con un UNION ALL sobre dos índices canónicos — never recomienda nada fuera de tu stock.
¿Qué pasa con devoluciones / notas de crédito?
Endpoint POST /v1/ingest/reversal. Forgery-safe: ignora los items que mandás y usa los items originales de la sale_id. Un caller comprometido NO puede envenenar la red enviando reversal de pares populares.
¿Cuánto tarda en producir señal útil?
Depende del volumen + el cohort_size global. Free tier típicamente sandbox. En Basic con 100k sales/mes, los pares más frecuentes cruzan el threshold k-anónimo en 2-4 semanas. La response incluye k_anon_satisfied:bool — si el threshold todavía no está cleared el cliente puede ocultar el rail.
¿Cómo funciona el rate limit?
Token bucket por API key. Capacidad y refill ratio dependen del tier (30/min Free, 300/min Basic, 1000/min Pro, 10000/min Enterprise). 429 con header Retry-After.
¿Hay compliance con Ley 25.326?
k-anonimato + opt-out de tenant + DPA disponible en Enterprise. Mandatory participation se gatea en config min_cohort_size: hasta que la red cleared el threshold, los reads devuelven empty + k_anon_satisfied:false. Auditoría completa en reco_audit_log.
Plan Free · sandbox · sin tarjeta
Probá la integración
sin gastar un peso.
500 sales + 100 reads para integrar end-to-end y verificar que todo conecta. Cuando estés listo para producción, Basic te abre 50k sales / 150k reads desde $29.999.
Un producto de Huggian · También: ez-catalog · ez-stock · Hecho en Argentina