Prompt de intención, ubicación y catálogo disponible por sucursal.
← NexoCesta comercial
Guía para CTO / Tech Lead
Integra intención al carrito sin entregar tu checkout.
NexoCesta convierte una solicitud del comprador en una salida estructurada de SKU y cantidades. Tu ecommerce conserva identidad, precio final, promociones, checkout, pago, inventario y fulfillment.
Arquitectura
Un límite técnico visible.
El núcleo de intención y carrito está desacoplado de HTTP y de la interfaz. La integración comercial agrega un adapter específico para datos y handoff.
Retailer systemsCatálogo · precio · stock · sucursalFuente de verdad del retailer
→NexoCesta coreIntent → matching → pack optimizer → cartNo procesa la transacción
→Retailer cartAdd-to-Cart · checkout · pago · deliveryControl del retailer
El modelo puede estructurar intención; la selección de SKU, precio, stock y presentación se resuelve con código y datos del catálogo.
Carrito estructurado con SKU, cantidades, costos y productos no encontrados.
Modos de integración
Tres patrones, distinta madurez.
No se presentan como conectores universales. Cada modo requiere validación de plataforma, seguridad, catálogo y carrito.
Experiencia gestionada
La ruta de menor fricción: carrito temporal protegido por capability token y conectado a un catálogo aislado.
Implementado · pilotoLauncher dentro del retailer
Existe un launcher browser de referencia que no contiene secretos. Un widget bidireccional completo se implementa por proyecto.
Contrato disponible · no paquete npm públicoMotor sin interfaz
La Retailer API autenticada devuelve intención, matching y arreglos estructurados de SKU y cantidades sin depender del frontend NexoCesta.
API v2.0.0 · no SLA comercialContrato de catálogo
CSV y JSON canónicos. API mediante adapter.
Los endpoints B2B autenticados admiten bodies de hasta 1 MB y un máximo configurable de 500 productos por importación. No envíes datos comerciales a los endpoints demo compartidos.
sku, name, brand, category, subcategory, packageQuantity, packageUnit, price, currency, stock, storeId, imageUrl, productUrl, barcode, active
Campos mínimos: SKU, nombre, presentación, unidad, precio y moneda. Unidades: g, kg, ml, l y piece.
- retailerId derivado de la API key
- storeId validado por retailer
- unicidad retailer + store + SKU
- precio, stock y estado actualizables por reimportación
- reporte de errores e idempotencia
Importación autenticada
POST /api/v1/integration/catalog/import/csv acepta multipart o texto CSV y devuelve un reporte por fila.
Feed canónico directo
POST /api/v1/integration/catalog/import/json valida el JSON Schema y usa exactamente el mismo normalizador que CSV.
Adapter específico
El adapter REST/JSON de referencia valida HTTPS, origen permitido, timeout, schema, paginación y mapeo de campos.
Ver checklist ↓Stock y precios
El retailer sigue siendo la fuente de verdad.
El motor filtra productos activos y con stock mayor a cero, y utiliza precio y presentaciones para construir y optimizar el carrito. En una integración real deben acordarse la frescura del feed, la tienda y la confirmación final en el ecommerce.
Regla de frontera
La propuesta de NexoCesta no sustituye la validación final de stock, precio, promociones o restricciones que hace el carrito del retailer.
Cart Handoff
Contrato y modos de referencia probados.
El RetailerAdapter implementa hosted, deep link y REST API; cada ecommerce real requiere validar su mecanismo Add-to-Cart. No existe un conector universal automático.
Salida de NexoCestaitems: [{ sku, quantity }]
→Adapter del retailerAPI · SDK · deep link · endpoint propio
→Carrito del retailerRevalida y continúa a checkout
Para cotizar el handoff se requiere documentación Add-to-Cart, credenciales de staging y reglas de sesión. NexoCesta no necesita acceso a pagos, tarjetas ni logística.
Seguridad
Demo pública ≠ integración productiva.
La separación debe quedar explícita durante discovery y piloto.
- API keys de alta entropía almacenadas como hash
- Aislamiento por retailer y sucursal
- Zod, límites de body y catálogo
- Allowlist HTTPS y timeout de adapters
- Rotación y revocación de credenciales
- Sin SLA comercial
- Rate limit lógico, no contador global
- Sin conector de checkout universal
- Sin SSO empresarial
- Sin webhooks operativos
- Emitir y custodiar credenciales propias
- Configurar allowlist y staging
- Probar datos, carrito y fallos del adapter
- Acordar frescura y retención
- Definir observabilidad y SLA
Sandbox / demo
Dos superficies separadas.
La demo pública usa “Mercado Nexo Salamanca” y datos ficticios. El sandbox de integración vive en Preview, requiere API key por retailer y mantiene catálogos aislados.
No cargues un catálogo confidencial en la demo pública; solicita credenciales de sandbox.Abrir demo ficticia ↗API docs
Demo pública y Retailer API documentadas.
OpenAPI 3.1 incluye servidores de producción, preview y local, además de auth, schemas, ejemplos y errores B2B.
Documentaciónnexocesta.nexocesta.workers.dev/docs/Abrir interfaz ↗OpenAPI JSON/api/openapiAbrir esquema ↗Health/api/v1/healthComprobar servicio ↗
GET /api/v1/integration/capabilitiesPOST /api/v1/integration/catalog/import/csvPOST /api/v1/integration/catalog/import/jsonGET /api/v1/integration/catalog/productsPOST /api/v1/integration/cart/resolvePOST /api/v1/integration/cart/handoffGET /api/v1/integration/doctorChecklist de readiness
Lo que necesitamos validar contigo.
Para un piloto se puede comenzar con CSV. Para producción necesitamos resolver cada interfaz de manera verificable.
FAQ técnica
Decisiones que no se deben asumir.
La respuesta final depende de la plataforma y las políticas del retailer.
¿La demo pública es apta para datos comerciales?
No. Para un piloto se emite una API key del retailer y se usa el entorno de integración aislado; la demo compartida conserva datos ficticios.
¿Puedo enviar un catálogo JSON?
Sí. El endpoint B2B acepta el JSON canónico documentado. Un JSON propietario con otros campos requiere configurar un adapter de mapeo.
¿Existe SDK Embedded instalable?
Existe un launcher browser de referencia sin secretos, no un widget completo ni un paquete npm público. Embedded se completa por proyecto.
¿Cómo se construye el carrito externo?
Mediante hosted, deep link o un adapter REST que traduce SKU y cantidades al mecanismo Add-to-Cart del retailer. El conector real debe probarse en staging.
¿Quién confirma precio y stock?
El ecommerce del retailer al recibir o abrir el carrito. NexoCesta utiliza el feed disponible para proponer; la fuente transaccional conserva la decisión final.
¿NexoCesta necesita acceso a pagos?
No. Tampoco necesita datos de tarjeta, facturación o logística.