{"openapi":"3.1.0","info":{"title":"XEN API","version":"1.0.0","description":"API pública de XEN para las webs de las empresas: el catálogo, el carrito, los pedidos y los pagos de una tienda, y la reserva y la gestión de citas de una clínica. Se autentica con la clave de la tienda o de la empresa (`Authorization: Bearer pk_… | sk_…`): la pública (`pk_`) desde el navegador y solo desde sus orígenes; la secreta (`sk_`) solo de servidor a servidor. Una clave `test` también lee la tienda en borrador."},"servers":[{"url":"https://api.xeneural.com/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Clave de la tienda creada en XEN → Desarrolladores → Claves de la API."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["missing_api_key","invalid_api_key","expired_api_key","origin_not_allowed","secret_key_in_browser","insufficient_scope","rate_limited","module_inactive","not_found","invalid_request","forbidden","internal_error","slot_unavailable","hold_expired","policy_violation","store_closed"]},"message":{"type":"string"}}}}},"Availability":{"type":"object","properties":{"status":{"type":"string","enum":["in","limited","out"]},"quantity":{"type":"integer","description":"Solo si la tienda publica cantidades."}}},"Images":{"type":"object","description":"URL de la foto por tamaño (lado mayor: xs 96, s 240, m 600, l 1200, xl 2048).","properties":{"xs":{"type":"string"},"s":{"type":"string"},"m":{"type":"string"},"l":{"type":"string"},"xl":{"type":"string"}}},"Store":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["open","closed"],"description":"`closed`: la tienda cerró temporalmente desde XEN. El catálogo se sigue leyendo, pero cotizar, crear un pedido y otro intento de pago responden 409 `store_closed`."},"closure":{"type":["object","null"],"description":"Solo con `status: closed`: el mensaje de la tienda en el idioma pedido (puede venir vacío) y la reapertura, si la tienda la fijó. Pasada esa fecha, la tienda vuelve a abrir sola.","properties":{"message":{"type":"string"},"reopensAt":{"type":["string","null"],"format":"date-time"}}},"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"parent":{"type":["string","null"]},"order":{"type":"integer"},"image":{"oneOf":[{"$ref":"#/components/schemas/Images"},{"type":"null"}]}}}},"attributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}}}},"shipping":{"type":"object","properties":{"zones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"regions":{"type":"array","items":{"type":"string"},"description":"Ids de `GET /v1/places`."},"fee":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"freeFrom":{"type":["number","null"]},"toQuote":{"type":"boolean","description":"Envío a cotizar: la tienda pone su valor en cada pedido."}}}},"pickup":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}}}}}},"paymentMethods":{"type":"array","items":{"type":"string","enum":["preorder","cod","external","gateway"]}},"checkoutFields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","textarea","number","date","bool","select"]},"required":{"type":"boolean"}}}},"stock":{"type":"object","properties":{"showQuantity":{"type":"boolean"}}},"banners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"image":{"type":["string","null"]},"url":{"type":["string","null"]},"coupon":{"type":["string","null"]},"kind":{"type":"string"}}}},"consentCategories":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"description":"Categorías de mensajes de WhatsApp que el comprador puede aceptar al pagar (casillas sin marcar). Vacío si la empresa no usa Conversaciones."}}},"Product":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"sku":{"type":["string","null"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/Images"}},"price":{"type":"object","properties":{"amount":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"compareAt":{"type":["number","null"]},"currency":{"type":"string"},"onSale":{"type":"boolean"}}},"unit":{"type":"string","enum":["unit","person"]},"min":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"attributes":{"type":"object","additionalProperties":true},"preorder":{"type":"object","properties":{"enabled":{"type":"boolean"},"deposit":{"type":["number","null"]}}},"featured":{"type":"boolean"},"availability":{"$ref":"#/components/schemas/Availability"},"publishedAt":{"type":["string","null"],"format":"date-time"}}},"ProductDetail":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"description":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["variant","addon"]},"required":{"type":"boolean"},"min":{"type":"integer","description":"Cuántos valores hay que elegir como mínimo (0 = opcional; igual a `max` = exactamente esos)."},"max":{"type":"integer"},"when":{"type":["object","null"],"description":"Opción condicionada: solo se muestra, y solo cuenta, si en la opción `option` se eligió alguno de `values`.","properties":{"option":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"priceDelta":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"sku":{"type":["string","null"]},"availability":{"$ref":"#/components/schemas/Availability"}}}}}}},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}}}}}]},"CartLine":{"type":"object","required":["product","quantity"],"properties":{"product":{"type":"string","description":"Slug de la ficha."},"quantity":{"type":"integer","minimum":1},"options":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"`{ idDeOpción: idDeValor | [idsDeValor] }`."}}},"Shipping":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["ship","pickup"]},"state":{"type":"string","description":"Departamento (`GET /v1/places`)."},"city":{"type":"string","description":"Ciudad del departamento (`GET /v1/places?parent=`)."},"pickupId":{"type":"string"}}},"Quote":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"name":{"type":"string"},"sku":{"type":["string","null"]},"image":{"oneOf":[{"$ref":"#/components/schemas/Images"},{"type":"null"}]},"options":{"type":"array","items":{"type":"object"}},"quantity":{"type":"integer"},"unitPrice":{"type":["number","null"]},"total":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"availability":{"$ref":"#/components/schemas/Availability"},"issue":{"type":["string","null"],"enum":[null,"not_found","no_price","option_required","option_invalid","min_quantity","out_of_stock","insufficient_stock","zone_not_covered","pickup_not_found","region_required","method_not_allowed","coupon_not_found","coupon_not_for_store","coupon_not_started","coupon_expired","coupon_exhausted","coupon_buyer_limit","coupon_min_subtotal","coupon_not_applicable"]}}}},"subtotal":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"discount":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"promotion":{"type":["object","null"],"properties":{"name":{"type":"string"},"kind":{"type":"string"},"coupon":{"type":["string","null"]},"amount":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."}}},"freeShipping":{"type":["object","null"],"properties":{"name":{"type":"string"},"coupon":{"type":["string","null"]}}},"coupon":{"type":["object","null"],"properties":{"code":{"type":"string"},"issue":{"type":["string","null"],"enum":[null,"not_found","no_price","option_required","option_invalid","min_quantity","out_of_stock","insufficient_stock","zone_not_covered","pickup_not_found","region_required","method_not_allowed","coupon_not_found","coupon_not_for_store","coupon_not_started","coupon_expired","coupon_exhausted","coupon_buyer_limit","coupon_min_subtotal","coupon_not_applicable"]}}},"shipping":{"type":"object","properties":{"fee":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"zone":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"free":{"type":"boolean"},"toQuote":{"type":"boolean","description":"El total va sin envío: la tienda lo cotiza después (no se puede pagar en línea todavía)."},"issue":{"type":["string","null"],"enum":[null,"not_found","no_price","option_required","option_invalid","min_quantity","out_of_stock","insufficient_stock","zone_not_covered","pickup_not_found","region_required","method_not_allowed","coupon_not_found","coupon_not_for_store","coupon_not_started","coupon_expired","coupon_exhausted","coupon_buyer_limit","coupon_min_subtotal","coupon_not_applicable"]}}},"total":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"currency":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"line":{"type":["integer","null"]},"code":{"type":["string","null"],"enum":[null,"not_found","no_price","option_required","option_invalid","min_quantity","out_of_stock","insufficient_stock","zone_not_covered","pickup_not_found","region_required","method_not_allowed","coupon_not_found","coupon_not_for_store","coupon_not_started","coupon_expired","coupon_exhausted","coupon_buyer_limit","coupon_min_subtotal","coupon_not_applicable"]}}},"description":"Si hay alguno, `POST /v1/orders` responde 400."}}},"Order":{"type":"object","properties":{"code":{"type":"string"},"status":{"type":"string","enum":["new","pending_payment","paid","confirmed","preparing","ready","shipped","delivered","cancelled","refunded"]},"mode":{"type":"string","enum":["live","test"]},"createdAt":{"type":"string","format":"date-time"},"buyer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}},"lines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"sku":{"type":["string","null"]},"options":{"type":"array","items":{"type":"object"}},"quantity":{"type":"integer"},"unitPrice":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"total":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."}}}},"shipping":{"type":"object","properties":{"method":{"type":"string"},"zone":{"type":["object","null"]},"pickup":{"type":["object","null"]},"fee":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"toQuote":{"type":"boolean"}}},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"discount":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"shipping":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"tax":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"total":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"currency":{"type":"string"}}},"coupon":{"type":["string","null"]},"payment":{"type":"object","properties":{"method":{"type":"string"},"status":{"type":"string","enum":["unpaid","partial","paid","refunded"]}}},"timeline":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}}},"NextStep":{"type":"object","description":"Qué hace la web después de crear el pedido.","properties":{"type":{"type":"string","enum":["confirmation","cash_on_delivery","external_payment","redirect"]},"url":{"type":"string","description":"Con `redirect`: el checkout de la pasarela."},"provider":{"type":"string","enum":["wompi","mercadopago","bold"]},"reference":{"type":"string"},"amount":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"currency":{"type":"string"}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"Id de la entrega (también en `X-Xen-Delivery`)."},"type":{"type":"string","enum":["order.created","order.updated","catalog.updated","promo.updated","appointment.created","appointment.updated","appointment.confirmed","appointment.cancelled","appointment.rescheduled","appointment.completed","appointment.no_show","message.created","ping"]},"created":{"type":"string","format":"date-time"},"mode":{"type":["string","null"],"enum":["live","test",null]},"data":{"type":"object","description":"`{ order }` con la forma de `GET /v1/orders/{code}`, `{ store, product }` o `{ promo }`; los de la cita y `message.created`, `{ code, status, startsAt, serviceId, professionalId, locationId }` sin datos clínicos."}}},"ClinicError":{"type":"object","description":"Error de la reserva con datos extra.","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["slot_unavailable","hold_expired","policy_violation","rate_limited"]},"message":{"type":"string"},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/ClinicSlot"},"description":"Con `slot_unavailable`: hasta 3 huecos cercanos."},"reason":{"type":"string","description":"Con `policy_violation`: `inside_cancel_window`, `min_notice`, `max_future_appointments`, `not_cancellable`, `not_reschedulable`, `not_confirmable` o `intake_already_imported`."},"callPhone":{"type":"string"}}}}},"ClinicProfile":{"type":"object","properties":{"name":{"type":"string"},"country":{"type":"string","enum":["PE","CO"]},"phone":{"type":"string"},"whatsapp":{"type":"string"},"email":{"type":"string"},"license":{"type":["object","null"],"properties":{"label":{"type":"string","example":"COP"},"verifyUrl":{"type":"string"}}},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"reference":{"type":"string"},"geo":{"type":["object","null"],"properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"timezone":{"type":"string","example":"America/Lima"},"hours":{"type":"array","items":{"type":"object","properties":{"dayOfWeek":{"type":"integer","minimum":0,"maximum":6},"opens":{"type":"string","example":"09:00"},"closes":{"type":"string","example":"20:00"}}}}}}},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":["string","null"]},"durationMin":{"type":"integer"},"mode":{"type":"string","enum":["instant","request"],"description":"`instant` confirma al reservar; `request` espera a que la clínica confirme."},"patientTypes":{"type":"array","items":{"type":"string","enum":["new","existing"]}},"prep":{"type":"string"}}}},"professionals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"name":{"type":"string"},"specialty":{"type":"string"},"license":{"type":["object","null"],"properties":{"type":{"type":["string","null"]},"number":{"type":"string"},"rne":{"type":["string","null"],"description":"Registro Nacional de Especialista, si lo tiene."}}},"bio":{"type":"string"},"photoUrl":{"type":["string","null"]},"acceptsNew":{"type":"boolean"},"serviceIds":{"type":"array","items":{"type":"string"},"description":"Servicios publicados que atiende: su propia lista y la del servicio, como la disponibilidad."}}}},"policies":{"type":"object","properties":{"gridMin":{"type":"integer"},"minNoticeMin":{"type":"integer"},"minNoticeNewMin":{"type":"integer"},"maxDaysAhead":{"type":"integer"},"holdSeconds":{"type":"integer"},"cancelUntilHours":{"type":"integer"}}},"consents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"version":{"type":"string"},"required":{"type":"boolean"},"text":{"type":"string"}}}}}},"ClinicSlot":{"type":"object","properties":{"slot":{"type":"string","description":"Hueco opaco y firmado (vence en 30 minutos). Se pasa tal cual a `POST /v1/clinic/holds`."},"startsAt":{"type":"string","format":"date-time"},"localStart":{"type":"string","example":"2026-11-10T10:30","description":"Hora local de la sede."},"durationMin":{"type":"integer"},"professional":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"ClinicAppointmentCreated":{"type":"object","properties":{"code":{"type":"string"},"token":{"type":["string","null"],"description":"Se devuelve una sola vez; con la misma `Idempotency-Key`, `null`."},"status":{"type":"string","enum":["requested","confirmed"]},"startsAt":{"type":"string","format":"date-time"},"localStart":{"type":"string"},"timezone":{"type":"string"},"service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"professional":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}}},"manageUntil":{"type":"string","format":"date-time","description":"Hasta cuándo la web puede cancelar o reprogramar."}}},"ClinicAppointment":{"type":"object","properties":{"code":{"type":"string"},"status":{"type":"string","enum":["requested","confirmed","arrived","in_chair","completed","no_show","cancelled","rescheduled"]},"confirmation":{"type":"string","enum":["none","sent","confirmed","declined"]},"startsAt":{"type":"string","format":"date-time"},"localStart":{"type":"string"},"timezone":{"type":"string"},"durationMin":{"type":"integer"},"service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"professional":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"name":{"type":"string"}}},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}}},"canConfirm":{"type":"boolean"},"canCancel":{"type":"boolean"},"canReschedule":{"type":"boolean"},"manageUntil":{"type":"string","format":"date-time"},"late":{"type":"boolean","description":"Se intentó cancelar o reprogramar dentro de la ventana."},"prep":{"type":"string"},"rescheduledTo":{"type":["string","null"],"description":"Código de la cita nueva si se reprogramó."}}},"ClinicMessage":{"type":"object","properties":{"id":{"type":"string"},"direction":{"type":"string","enum":["patient","clinic"]},"text":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"read":{"type":"boolean"}}}},"responses":{"E400":{"description":"La petición no es válida (cuerpo, parámetros, cupón o líneas que no se pueden vender).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"Falta la clave, no es válida o venció.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"Origen no permitido, clave secreta en el navegador, alcance insuficiente o módulo apagado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"No existe en la tienda o la empresa de la clave (en Clínica, también un código o token que no calza).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"La tienda está cerrada temporalmente (`store_closed`): se lee el catálogo, pero no se cotiza, no se crea el pedido ni se abre otro intento de pago. `GET /v1/store` trae su mensaje y la reapertura.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Se pasó el límite por minuto de la clave (`Retry-After: 60`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/store":{"get":{"summary":"La tienda: estado (abierta o cerrada temporalmente), moneda, idiomas, categorías, envío, medios de pago, campos del checkout y banners","parameters":[{"name":"lang","in":"query","schema":{"type":"string","example":"es"},"description":"Idioma del catálogo; si la tienda no lo tiene, el principal."}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Store"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/products":{"get":{"summary":"Catálogo con filtros, orden y página","parameters":[{"name":"lang","in":"query","schema":{"type":"string","example":"es"},"description":"Idioma del catálogo; si la tienda no lo tiene, el principal."},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"price_min","in":"query","schema":{"type":"string"}},{"name":"price_max","in":"query","schema":{"type":"string"}},{"name":"expand","in":"query","schema":{"type":"string","enum":["options"]},"description":"Con `options` cada pieza trae su ficha completa (descripción, viñetas y opciones)."},{"name":"preorder","in":"query","schema":{"type":"boolean"}},{"name":"sale","in":"query","schema":{"type":"boolean"}},{"name":"featured","in":"query","schema":{"type":"boolean"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["default","price_asc","price_desc","newest","name"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Product"},{"$ref":"#/components/schemas/ProductDetail"}]}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/products/{slug}":{"get":{"summary":"Ficha con opciones, variantes y disponibilidad","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","schema":{"type":"string","example":"es"},"description":"Idioma del catálogo; si la tienda no lo tiene, el principal."}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/places":{"get":{"summary":"Departamentos del país de la tienda, o las ciudades de uno","parameters":[{"name":"parent","in":"query","schema":{"type":"string","example":"state:CO-DC"}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/cart/quote":{"post":{"summary":"Precios vigentes, promociones, cupón, envío y existencias de unas líneas","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLine"},"maxItems":50},"shipping":{"$ref":"#/components/schemas/Shipping"},"coupon":{"type":"string"},"email":{"type":"string","description":"Para el límite de usos del cupón por comprador."},"lang":{"type":"string"}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Quote"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/orders":{"post":{"summary":"Crea el pedido","description":"Con la misma cabecera `Idempotency-Key` devuelve el pedido ya creado (sin testigo). Con `gateway` el pedido espera su pago y `next.url` lleva al checkout de la pasarela de la tienda (Wompi, Mercado Pago o Bold); al volver, informa la transacción con `gateway-return`.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lines","buyer","shipping","payment"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLine"},"maxItems":50},"buyer":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","description":"En formato internacional («+51 987654321») para que el consentimiento quede atado a su WhatsApp."},"document":{"type":"object","properties":{"type":{"type":"string"},"number":{"type":"string"}}},"consent":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Códigos de `consentCategories` que el comprador marcó él mismo; quedan en su contacto con el pedido como prueba. Las que no existen se ignoran."}}},"shipping":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["ship","pickup"]},"pickupId":{"type":"string"},"address":{"type":"object","properties":{"line":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"notes":{"type":"string"}}}}},"payment":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["preorder","cod","external","gateway"]},"returnUrl":{"type":"string","description":"Con `gateway`: a dónde vuelve el comprador (https)."}}},"fields":{"type":"object","additionalProperties":true,"description":"Campos extra del checkout por id."},"coupon":{"type":"string"},"note":{"type":"string"},"lang":{"type":"string"}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"code":{"type":"string"},"token":{"type":["string","null"],"description":"Se muestra una sola vez."},"status":{"type":"string"},"total":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"currency":{"type":"string"},"next":{"$ref":"#/components/schemas/NextStep"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/orders/{code}":{"get":{"summary":"Estado del pedido (clave secreta con `orders:read`, o pública con el testigo)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Código del pedido."},{"name":"token","in":"query","schema":{"type":"string","description":"Testigo del comprador que devolvió `POST /v1/orders` (con la clave pública)."}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/orders/{code}/checkout":{"post":{"summary":"Otro intento de pago con la pasarela","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Testigo del comprador que devolvió `POST /v1/orders` (con la clave pública)."},"returnUrl":{"type":"string"}}}}}},"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Código del pedido."}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"code":{"type":"string"},"next":{"$ref":"#/components/schemas/NextStep"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/orders/{code}/gateway-return":{"post":{"summary":"La web volvió de la pasarela: XEN consulta la transacción y la aplica","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Código del pedido."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactionId"],"properties":{"token":{"type":"string","description":"Testigo del comprador que devolvió `POST /v1/orders` (con la clave pública)."},"transactionId":{"type":"string","description":"El `id` que agrega Wompi o el `payment_id` que agrega Mercado Pago a la URL de vuelta. Con Bold puede ir vacío: XEN busca el pago por el pedido."}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/orders/{code}/payments":{"post":{"summary":"La web informa un pago que cobró ella (solo clave secreta con `payments:write`)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Código del pedido."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","reference"],"properties":{"amount":{"type":"number","description":"Importe en la moneda de la tienda, con dos decimales."},"reference":{"type":"string"},"method":{"type":"string","description":"Cómo se cobró, para el historial."}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/leads":{"post":{"summary":"Deja una solicitud: contacto, cotización o boletín","description":"Con correo o celular (el boletín pide correo). `fields` son los campos extra que la tienda define para el checkout (fecha del evento, invitados…), sin exigir los obligatorios. Con la misma cabecera `Idempotency-Key` devuelve la ya creada. Alcance `leads:create`.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["contact","quote","newsletter"]},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"message":{"type":"string","maxLength":2000},"fields":{"type":"object","additionalProperties":true,"description":"Campos extra del checkout por id."},"consent":{"type":"boolean","description":"Aceptó que la tienda lo contacte."},"lang":{"type":"string"}}}}}},"responses":{"201":{"description":"Creada","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","contacted","closed"]}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic":{"get":{"summary":"La clínica: sedes con horario y zona, servicios reservables, profesionales, políticas y consentimientos","description":"Alcance `clinic:read`. Con una clave `live`, la clínica tiene que tener publicada la reserva en línea.","responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicProfile"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/availability":{"get":{"summary":"Huecos libres de un servicio en una sede (hasta 14 días)","description":"Alcance `clinic:read`. Cuenta el horario de cada profesional, sus citas, los holds vivos, los bloqueos, la antelación mínima (más larga para pacientes nuevos) y el horizonte. No expone el sillón.","parameters":[{"name":"serviceId","in":"query","required":true,"schema":{"type":"string"}},{"name":"locationId","in":"query","required":true,"schema":{"type":"string"}},{"name":"professionalId","in":"query","schema":{"type":"string","default":"any"},"description":"Un profesional o `any`."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Fecha local de la sede; por defecto, hoy."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Hasta 13 días después de `from`; por defecto, 6."},{"name":"patientType","in":"query","schema":{"type":"string","enum":["new","existing"]}},{"name":"appointmentCode","in":"query","schema":{"type":"string"},"description":"Al reprogramar: el código de la cita que se mueve (con `appointmentToken`); su hueco cuenta como libre."},{"name":"appointmentToken","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"timezone":{"type":"string"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/ClinicSlot"}}}}},"nextAvailableDate":{"type":["string","null"],"format":"date"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/holds":{"post":{"summary":"Aparta un hueco mientras el paciente completa sus datos","description":"Alcance `appointments:create`. El hold dura `holdSeconds`; si otra reserva ganó el hueco, 409 `slot_unavailable` con hasta 3 `alternatives` del mismo tipo de paciente. La reserva tiene que ser del `patientType` con que se apartó. La misma `Idempotency-Key` de un hold vencido responde 410. Con demasiados holds vivos en la clínica, 429.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Con la misma clave devuelve lo ya creado (sin token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slot"],"properties":{"slot":{"type":"string"},"patientType":{"type":"string","enum":["new","existing"]},"appointment":{"type":"object","description":"Al reprogramar: la cita que se mueve. Su hueco cuenta como libre.","properties":{"code":{"type":"string"},"token":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"hold":{"type":"string"},"holdSecret":{"type":"string","description":"Se muestra una sola vez."},"expiresAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`slot_unavailable`, con alternativas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/holds/{hold}/release":{"post":{"summary":"Suelta un hueco apartado que el visitante no reservó","description":"Alcance `appointments:create`, solo clave secreta (`sk_`). Con el secreto del hold, borra el hold y sus celdas: `released: true`. Si el hold ya no está (venció o lo tomó la cita que lo usó), `released: false`. Un secreto que no calza responde 404, igual que cualquier otro «no encontrado».","parameters":[{"name":"hold","in":"path","required":true,"schema":{"type":"string"},"description":"Id del hold de `POST /v1/clinic/holds`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["holdSecret"],"properties":{"holdSecret":{"type":"string"}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"released":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments":{"post":{"summary":"Reserva la cita","description":"Alcance `appointments:create`. Crea o reutiliza al paciente por su documento sin decir si ya existía, crea la cita (`instant` → `confirmed`, `request` → `requested`), avisa a la clínica, manda el correo y el webhook. Límite de escrituras por teléfono (429). `410 hold_expired` si el hold venció.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Con la misma clave devuelve lo ya creado (sin token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patient"],"properties":{"hold":{"type":"string","description":"Id del hold de `POST /v1/clinic/holds` (o manda `slot`)."},"holdSecret":{"type":"string"},"slot":{"type":"string","description":"Hueco firmado, sin apartar antes."},"serviceId":{"type":"string","description":"Si viene, tiene que coincidir con el hueco."},"locationId":{"type":"string"},"professionalId":{"type":"string"},"patientType":{"type":"string","enum":["new","existing"]},"forWhom":{"type":"string","enum":["self","dependent"]},"patient":{"type":"object","required":["firstName","lastName","birthDate","document"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"birthDate":{"type":"string","format":"date","description":"Obligatoria. Un menor de 18 años (en la fecha local de la clínica) reserva con `forWhom: dependent`."},"document":{"type":"object","required":["type","number"],"properties":{"type":{"type":"string","enum":["DNI","CE","PAS","CC","TI","RC","OTRO"]},"number":{"type":"string"}}},"phone":{"type":"string"},"email":{"type":"string"}}},"guardian":{"type":"object","description":"Obligatorio con `forWhom: dependent` (menor o persona a cargo), con su nombre y su documento.","properties":{"name":{"type":"string"},"relation":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"document":{"type":"object","required":["type","number"],"properties":{"type":{"type":"string","enum":["DNI","CE","PAS","CC","TI","RC","OTRO"]},"number":{"type":"string"}}}}},"reason":{"type":"string","maxLength":500},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","email"]},"description":"Por dónde recibe la confirmación y los recordatorios. Vacío: ninguno (solo la confirmación en pantalla). Sin el campo: correo."},"visitorIp":{"type":"string","description":"IP del visitante: se guarda recortada con cada consentimiento aceptado."},"consents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"version":{"type":"string"},"accepted":{"type":"boolean"}}},"description":"Los obligatorios de `GET /v1/clinic` tienen que venir aceptados en su versión."},"attribution":{"type":"object","properties":{"source":{"type":"string"},"landingPath":{"type":"string"},"utm":{"type":"object","additionalProperties":{"type":"string"}},"referrer":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicAppointmentCreated"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`slot_unavailable` (con alternativas) o `policy_violation` (`min_notice`, `max_future_appointments`, `consents_not_configured`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"410":{"description":"`hold_expired`: el hold venció; elige un hueco otra vez.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}":{"get":{"summary":"La cita para «Mi cita»: estado, fecha, servicio, profesional, sede e indicaciones","description":"Alcance `appointments:manage` con el token. Con clave secreta y `appointments:read`, sin token. Código o token que no calzan: 404.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."},{"name":"token","in":"query","required":false,"schema":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicAppointment"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/confirm":{"post":{"summary":"El paciente confirma que viene","description":"Alcance `appointments:manage`.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicAppointment"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`policy_violation`: dentro de la ventana de cancelación (`cancelUntilHours`) o la cita ya no admite el cambio; la web pide llamar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/cancel":{"post":{"summary":"Cancela la cita (fuera de la ventana de cancelación)","description":"Alcance `appointments:manage`. Dentro de la ventana responde 409 `policy_violation` y la cita queda marcada `late`.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."},"reason":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicAppointment"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`policy_violation`: dentro de la ventana de cancelación (`cancelUntilHours`) o la cita ya no admite el cambio; la web pide llamar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/reschedule":{"post":{"summary":"Reprograma a un hueco apartado: cita nueva enlazada","description":"Alcance `appointments:manage`. Devuelve el nuevo `code` y su `token`; el enlace anterior deja de servir para gestionar.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Con la misma clave devuelve lo ya creado (sin token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","hold","holdSecret"],"properties":{"token":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."},"hold":{"type":"string"},"holdSecret":{"type":"string"}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicAppointmentCreated"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`policy_violation`: dentro de la ventana de cancelación (`cancelUntilHours`) o la cita ya no admite el cambio; la web pide llamar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"410":{"description":"`hold_expired`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/preferences":{"post":{"summary":"Baja de los avisos de la cita (correo o WhatsApp)","description":"Alcance `appointments:manage`. Solo apaga, nunca enciende, y deja la revocación registrada. Es el destino del enlace «Dejar de recibir estos avisos» de cada correo.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."},"email":{"type":"boolean","enum":[false]},"whatsapp":{"type":"boolean","enum":[false]},"visitorIp":{"type":"string"}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"email":{"type":"boolean"},"whatsapp":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`policy_violation`: dentro de la ventana de cancelación (`cancelUntilHours`) o la cita ya no admite el cambio; la web pide llamar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/messages":{"get":{"summary":"Hilo de la cita con la clínica (solo mensajes, nunca datos clínicos)","description":"Alcance `appointments:manage`. Marca leídos los mensajes de la clínica.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."},{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClinicMessage"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"summary":"El paciente escribe a la clínica","description":"Alcance `appointments:manage`. La clínica lo ve en XEN (Clínica, Mensajes) y le suena la campana.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Con la misma clave devuelve lo ya creado (sin token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","text"],"properties":{"token":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."},"text":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClinicMessage"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/intake":{"post":{"summary":"Pre-admisión: antecedentes, alergias y medicación antes de la cita","description":"Alcance `appointments:manage`. Una por cita; se puede corregir hasta que la clínica la importe a la historia.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Código de la cita."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","answers"],"properties":{"token":{"type":"string","description":"Token de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta."},"answers":{"type":"object","additionalProperties":true,"description":"Motivo, antecedentes, alergias, medicación, embarazo, hábitos, ansiedad (1 a 5)."}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"description":"`policy_violation`: dentro de la ventana de cancelación (`cancelUntilHours`) o la cita ya no admite el cambio; la web pide llamar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/requests":{"post":{"summary":"Deja una solicitud: contacto, llamada, urgencia, lista de espera, derechos ARCO o postulación","description":"Alcance `requests:create`. Con teléfono o correo; límite por teléfono (429).","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Con la misma clave devuelve lo ya creado (sin token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["contact","callback","urgent","waitlist","arco","job"]},"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"message":{"type":"string","maxLength":4000},"preferences":{"type":"object","additionalProperties":true},"attribution":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["new","contacted","closed"]}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/complaints":{"post":{"summary":"Hoja del Libro de Reclamaciones","description":"Alcance `requests:create`. Devuelve el código (`LR-…`) y la fecha límite de respuesta (15 días hábiles), y manda la copia al correo del consumidor con la identificación del proveedor.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Con la misma clave devuelve lo ya creado (sin token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","consumer","detail"],"properties":{"kind":{"type":"string","enum":["reclamo","queja"]},"replyChannel":{"type":"string","enum":["email","letter"],"default":"email","description":"Por dónde quiere la respuesta: `email` exige el correo; `letter`, el domicilio."},"consumer":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"document":{"type":"object","properties":{"type":{"type":"string"},"number":{"type":"string"}}},"address":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"guardian":{"type":"string","description":"Padre, madre o apoderado si es menor."}}},"service":{"type":"object","properties":{"description":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"}}},"detail":{"type":"string","maxLength":4000},"request":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Creado","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"code":{"type":"string","example":"LR-000015"},"dueAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/portal/plan":{"post":{"summary":"«Mi plan»: el plan de tratamiento del paciente de una cita","description":"Con el código y el token de gestión de la cita (los que devolvió `POST /v1/clinic/appointments`) y la fecha de nacimiento del paciente. Devuelve el plan vigente en palabras del paciente, las piezas que necesitan atención y lo ya realizado; nunca hallazgos ni diagnósticos. Si algún dato no coincide, responde 404 igual que si no existiera. Cada lectura queda en la bitácora de accesos de la historia clínica. Solo clave secreta de la empresa (`sk_`) con `appointments:manage`, desde el servidor de la web.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","token","birthDate"],"properties":{"code":{"type":"string","example":"CT-000123","description":"Código de la cita."},"token":{"type":"string","description":"Token de gestión de la cita (va en el cuerpo, nunca en la ruta)."},"birthDate":{"type":"string","format":"date","example":"1990-05-17","description":"Fecha de nacimiento del paciente."},"clientIp":{"type":"string","example":"198.51.100.23","description":"IP del paciente que abrió «Mi plan» en la web: queda en la bitácora de accesos. Sin ella (o si no es una IP), la de quien llama."}}}}}},"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"patientFirstName":{"type":"string"},"plan":{"oneOf":[{"type":"object","properties":{"code":{"type":"string","example":"PT-000045"},"name":{"type":"string"},"status":{"type":"string","enum":["proposed","accepted","in_progress","completed"]},"currency":{"type":"string","example":"PEN"},"subtotal":{"type":"number","description":"Suma de los ítems, antes del descuento del plan"},"discount":{"type":"number"},"total":{"type":"number"},"paid":{"type":"number"},"balance":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"procedure":{"type":"string"},"layperson":{"type":"string","description":"Explicación del procedimiento para el paciente."},"teeth":{"type":"array","items":{"type":"string"},"description":"Piezas en notación FDI."},"surfaces":{"type":"array","items":{"type":"string","enum":["M","D","V","L","O"]}},"phase":{"type":"string","enum":["urgency","systemic","hygiene","corrective","maintenance"]},"status":{"type":"string","enum":["proposed","accepted","scheduled","done","cancelled"]},"price":{"type":"number"},"date":{"type":["string","null"],"format":"date-time","description":"Cuándo se hizo o para cuándo está agendado."},"professional":{"type":["string","null"]}}}}}},{"type":"null"}]},"teethNeedingCare":{"type":"array","items":{"type":"string"},"description":"Piezas FDI con tratamiento pendiente."},"records":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"procedure":{"type":"string"},"professional":{"type":["string","null"]},"status":{"type":"string","enum":["done"]},"price":{"type":["number","null"]}}}}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/openapi.json":{"get":{"summary":"Este documento","security":[],"parameters":[{"name":"lang","in":"query","schema":{"type":"string","enum":["es","en"]}}],"responses":{"200":{"description":"Correcto","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"webhooks":{"order.created":{"post":{"summary":"Aviso order.created","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"order.updated":{"post":{"summary":"Aviso order.updated","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"catalog.updated":{"post":{"summary":"Aviso catalog.updated","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"promo.updated":{"post":{"summary":"Aviso promo.updated","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.created":{"post":{"summary":"Aviso appointment.created","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.updated":{"post":{"summary":"Aviso appointment.updated","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.confirmed":{"post":{"summary":"Aviso appointment.confirmed","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.cancelled":{"post":{"summary":"Aviso appointment.cancelled","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.rescheduled":{"post":{"summary":"Aviso appointment.rescheduled","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.completed":{"post":{"summary":"Aviso appointment.completed","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"appointment.no_show":{"post":{"summary":"Aviso appointment.no_show","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}},"message.created":{"post":{"summary":"Aviso message.created","description":"Firmado en `X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de \"<t>.<cuerpo>\">` con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.","parameters":[{"name":"X-Xen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Delivery","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Xen-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Recibido"}}}}}}