{"openapi":"3.1.0","info":{"title":"NexoCesta Retailer API","version":"2.0.0","description":"NexoCesta convierte intención de compra en SKU y cantidades dentro del catálogo autenticado del retailer. El checkout, pagos y logística permanecen bajo control del retailer. Los endpoints Public Demo están separados de Retailer Integration API V1.","contact":{"name":"NexoCesta Integration Engineering"}},"servers":[{"url":"https://nexocesta.nexocesta.workers.dev","description":"Production"},{"url":"https://nexocesta-preview.nexocesta.workers.dev","description":"Preview / sandbox"},{"url":"http://localhost:8787","description":"Local Worker"}],"tags":[{"name":"Public Demo API","description":"Experiencia pública con Mercado Nexo y datos ficticios."},{"name":"Retailer Integration API","description":"Operaciones B2B aisladas por API key y retailer."},{"name":"Integration Administration","description":"Provisionamiento operativo protegido por Cloudflare Secret."}],"paths":{"/api/v1/health":{"get":{"tags":["Public Demo API"],"summary":"Estado y versión del Worker","responses":{"200":{"description":"Servicio disponible"}}}},"/api/v1/intent/resolve":{"post":{"tags":["Public Demo API"],"summary":"Resuelve intención demo","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentRequest"}}}},"responses":{"200":{"description":"Intención resuelta"},"400":{"description":"No existe resolución canónica segura"}}}},"/api/v1/intent-to-cart":{"post":{"tags":["Public Demo API"],"summary":"Intent-to-cart del catálogo demo","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentRequest"}}}},"responses":{"200":{"description":"Carrito demo consolidado"}}}},"/api/v1/demo/intent-to-cart":{"post":{"tags":["Public Demo API"],"summary":"Intent-to-cart read-only para Retailer Digital Twin","description":"Ejecuta el mismo core contra catálogo demo sin persistir analytics ni caché de intención.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentRequest"}}}},"responses":{"200":{"description":"Carrito demo consolidado con persistence=read-only"}}}},"/api/v1/integration/capabilities":{"get":{"tags":["Retailer Integration API"],"summary":"Descubre capacidades y manifest del retailer autenticado","security":[{"retailerApiKey":[]}],"responses":{"200":{"description":"Capacidades"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/catalog/import/csv":{"post":{"tags":["Retailer Integration API"],"summary":"Importa CSV al tenant autenticado","security":[{"retailerApiKey":[]}],"parameters":[{"name":"storeId","in":"query","schema":{"type":"string"}},{"name":"replace","in":"query","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","required":["csv"],"properties":{"csv":{"type":"string"}}}}}},"responses":{"200":{"description":"Reporte explícito","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportResult"}}}},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/catalog/import/json":{"post":{"tags":["Retailer Integration API"],"summary":"Importa feed JSON canónico","security":[{"retailerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogFeed"}}}},"responses":{"200":{"description":"Reporte explícito","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportResult"}}}},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/catalog/products":{"get":{"tags":["Retailer Integration API"],"summary":"Lista productos del retailer autenticado","security":[{"retailerApiKey":[]}],"parameters":[{"name":"storeId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":250,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Catálogo tenant-scoped"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/catalog/products/{sku}":{"get":{"tags":["Retailer Integration API"],"summary":"Obtiene un SKU dentro del tenant","security":[{"retailerApiKey":[]}],"parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string"}},{"name":"storeId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Producto"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"PRODUCT_NOT_FOUND"},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/cart/resolve":{"post":{"tags":["Retailer Integration API"],"summary":"Headless intent-to-cart para el catálogo del retailer","security":[{"retailerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/IntentRequest"},{"type":"object","required":["storeId"],"properties":{"storeId":{"type":"string"}}}]},"examples":{"carneAsada":{"value":{"prompt":"Quiero hacer carne asada para 10 personas","storeId":"nexoretail-store-001"}}}}}},"responses":{"200":{"description":"Intención, carrito y arreglo SKU/quantity"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/cart/handoff":{"post":{"tags":["Retailer Integration API"],"summary":"Entrega SKU y cantidades al modo de carrito configurado","security":[{"retailerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartHandoffRequest"}}}},"responses":{"200":{"description":"Handoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartHandoffResponse"}}}},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"OUT_OF_STOCK"},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/hosted-carts/{id}":{"post":{"tags":["Retailer Integration API"],"summary":"Lee un carrito hosted mediante capability token de corta duración","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string","description":"Token opaco transportado en el fragmento de redirectUrl, fuera de logs HTTP."}}}}}},"responses":{"200":{"description":"Carrito hosted piloto"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Token, carrito o expiración inválidos"},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/doctor":{"get":{"tags":["Retailer Integration API"],"summary":"Readiness: READY, READY_FOR_DEMO o NOT_READY","security":[{"retailerApiKey":[]}],"responses":{"200":{"description":"Diagnóstico operativo"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/admin/retailers":{"post":{"tags":["Integration Administration"],"summary":"Crea o actualiza retailer, store y manifest","security":[{"adminKey":[]}],"responses":{"201":{"description":"Retailer provisionado"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integration/admin/api-keys":{"post":{"tags":["Integration Administration"],"summary":"Crea API key; el secreto sólo aparece una vez","security":[{"adminKey":[]}],"responses":{"201":{"description":"API key creada"},"401":{"description":"Credencial ausente, inválida o revocada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La solicitud no cumple el contrato","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Límite lógico excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"retailerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"nxk_…","description":"API key del retailer. Enviar sólo desde backend."},"adminKey":{"type":"apiKey","in":"header","name":"X-Nexo-Admin-Key","description":"Secret operativo global; nunca se expone al navegador."}},"schemas":{"IntentRequest":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":3,"maxLength":2000,"example":"Quiero hacer carne asada para 10 personas"},"location":{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2}}}}},"RetailerCapabilities":{"type":"object","additionalProperties":false,"required":["catalogMode","inventory","pricing","cartHandoff","multiStore"],"properties":{"catalogMode":{"enum":["api","csv","json","manual"]},"inventory":{"enum":["realtime","periodic","none"]},"pricing":{"enum":["realtime","periodic","catalog"]},"cartHandoff":{"enum":["api","deep_link","javascript_sdk","hosted","custom"]},"multiStore":{"type":"boolean"}}},"CatalogProductInput":{"type":"object","additionalProperties":false,"required":["sku","name","packageQuantity","packageUnit","price","currency"],"properties":{"sku":{"type":"string","example":"ABC001"},"name":{"type":"string","example":"Maíz pozolero 1 kg"},"brand":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":"string"},"packageQuantity":{"type":"number","exclusiveMinimum":0},"packageUnit":{"enum":["g","kg","ml","l","piece"]},"price":{"type":"number","minimum":0},"currency":{"type":"string","example":"MXN"},"stock":{"type":"integer","minimum":0},"storeId":{"type":"string"},"imageUrl":{"type":"string","format":"uri"},"productUrl":{"type":"string","format":"uri"},"barcode":{"type":"string"},"active":{"type":"boolean","default":true}}},"CatalogFeed":{"type":"object","additionalProperties":false,"required":["retailerId","generatedAt","products"],"properties":{"retailerId":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"products":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProductInput"}}}},"CatalogImportResult":{"type":"object","required":["importId","retailerId","received","accepted","rejected","created","updated","deactivated","errors"],"properties":{"importId":{"type":"string","format":"uuid"},"retailerId":{"type":"string"},"received":{"type":"integer"},"accepted":{"type":"integer"},"rejected":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"deactivated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"item":{"type":"integer"},"sku":{"type":"string"},"field":{"type":"string"},"cause":{"type":"string"}}}}}},"CartItem":{"type":"object","additionalProperties":false,"required":["sku","quantity"],"properties":{"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1}}},"CartHandoffRequest":{"type":"object","additionalProperties":false,"required":["retailerId","items"],"properties":{"retailerId":{"type":"string"},"storeId":{"type":"string"},"items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CartItem"}},"returnUrl":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"CartHandoffResponse":{"type":"object","required":["mode","status"],"properties":{"mode":{"enum":["api","deep_link","javascript_sdk","hosted","custom"]},"status":{"enum":["ready","created","requires_client_action","unsupported"]},"cartId":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"enum":["AUTH_REQUIRED","INVALID_API_KEY","RETAILER_NOT_FOUND","STORE_NOT_FOUND","PRODUCT_NOT_FOUND","OUT_OF_STOCK","CATALOG_VALIDATION_ERROR","CART_HANDOFF_UNSUPPORTED","AI_UNAVAILABLE","RATE_LIMITED","INVALID_REQUEST","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"array","items":{}},"requestId":{"type":"string","format":"uuid"}}}}}}}}