{"openapi":"3.1.0","info":{"title":"XEN API","version":"1.0.0","description":"XEN public API for company websites: a store's catalog, cart, orders and payments, and a clinic's appointment booking and management. It authenticates with the store or company key (`Authorization: Bearer pk_… | sk_…`): the public one (`pk_`) from the browser and only from its origins; the secret one (`sk_`) only server to server. A `test` key also reads the store in draft."},"servers":[{"url":"https://api.xeneural.com/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Store key created in XEN → Developers → API keys."}},"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":"Only if the store publishes quantities."}}},"Images":{"type":"object","description":"Photo URL by size (longest side: 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`: the store was temporarily closed from XEN. The catalog can still be read, but quoting, creating an order and another payment attempt answer 409 `store_closed`."},"closure":{"type":["object","null"],"description":"Only with `status: closed`: the store's message in the requested language (it may be empty) and the reopening date, if the store set one. After that date the store opens again by itself.","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 from `GET /v1/places`."},"fee":{"type":"number","description":"Amount in the store currency, with two decimals."},"freeFrom":{"type":["number","null"]},"toQuote":{"type":"boolean","description":"Shipping to be quoted: the store sets it on each order."}}}},"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":"WhatsApp message categories the buyer can accept at checkout (unchecked boxes). Empty if the company doesn't use Conversations."}}},"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":"Amount in the store currency, with two decimals."},"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":"How many values must be chosen at least (0 = optional; equal to `max` = exactly that many)."},"max":{"type":"integer"},"when":{"type":["object","null"],"description":"Conditional option: shown, and counted, only if one of `values` was chosen in option `option`.","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":"Amount in the store currency, with two decimals."},"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":"Product slug."},"quantity":{"type":"integer","minimum":1},"options":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"`{ optionId: valueId | [valueIds] }`."}}},"Shipping":{"type":"object","required":["method"],"properties":{"method":{"type":"string","enum":["ship","pickup"]},"state":{"type":"string","description":"State or department (`GET /v1/places`)."},"city":{"type":"string","description":"City of that state (`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":"Amount in the store currency, with two decimals."},"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":"Amount in the store currency, with two decimals."},"discount":{"type":"number","description":"Amount in the store currency, with two decimals."},"promotion":{"type":["object","null"],"properties":{"name":{"type":"string"},"kind":{"type":"string"},"coupon":{"type":["string","null"]},"amount":{"type":"number","description":"Amount in the store currency, with two decimals."}}},"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":"Amount in the store currency, with two decimals."},"zone":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"free":{"type":"boolean"},"toQuote":{"type":"boolean","description":"The total goes without shipping: the store quotes it later (it can't be paid online yet)."},"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":"Amount in the store currency, with two decimals."},"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":"If there is any, `POST /v1/orders` answers 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":"Amount in the store currency, with two decimals."},"total":{"type":"number","description":"Amount in the store currency, with two decimals."}}}},"shipping":{"type":"object","properties":{"method":{"type":"string"},"zone":{"type":["object","null"]},"pickup":{"type":["object","null"]},"fee":{"type":"number","description":"Amount in the store currency, with two decimals."},"toQuote":{"type":"boolean"}}},"totals":{"type":"object","properties":{"subtotal":{"type":"number","description":"Amount in the store currency, with two decimals."},"discount":{"type":"number","description":"Amount in the store currency, with two decimals."},"shipping":{"type":"number","description":"Amount in the store currency, with two decimals."},"tax":{"type":"number","description":"Amount in the store currency, with two decimals."},"total":{"type":"number","description":"Amount in the store currency, with two decimals."},"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":"What the website does after creating the order.","properties":{"type":{"type":"string","enum":["confirmation","cash_on_delivery","external_payment","redirect"]},"url":{"type":"string","description":"With `redirect`: the gateway checkout."},"provider":{"type":"string","enum":["wompi","mercadopago","bold"]},"reference":{"type":"string"},"amount":{"type":"number","description":"Amount in the store currency, with two decimals."},"currency":{"type":"string"}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"Delivery id (also in `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 }` shaped like `GET /v1/orders/{code}`, `{ store, product }` or `{ promo }`; the appointment ones and `message.created`, `{ code, status, startsAt, serviceId, professionalId, locationId }` without clinical data."}}},"ClinicError":{"type":"object","description":"Booking error with extra data.","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":"With `slot_unavailable`: up to 3 nearby slots."},"reason":{"type":"string","description":"With `policy_violation`: `inside_cancel_window`, `min_notice`, `max_future_appointments`, `not_cancellable`, `not_reschedulable`, `not_confirmable` or `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` confirms on booking; `request` waits for the clinic to confirm."},"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":"National Specialist Registry number, if any."}}},"bio":{"type":"string"},"photoUrl":{"type":["string","null"]},"acceptsNew":{"type":"boolean"},"serviceIds":{"type":"array","items":{"type":"string"},"description":"Published services they see patients for: their own list and the service's, as availability uses."}}}},"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":"Opaque signed slot (expires in 30 minutes). Pass it as is to `POST /v1/clinic/holds`."},"startsAt":{"type":"string","format":"date-time"},"localStart":{"type":"string","example":"2026-11-10T10:30","description":"Local time of the location."},"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":"Returned only once; with the same `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":"Until when the website can cancel or reschedule."}}},"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":"Someone tried to cancel or reschedule inside the window."},"prep":{"type":"string"},"rescheduledTo":{"type":["string","null"],"description":"Code of the new appointment if it was rescheduled."}}},"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":"The request is not valid (body, parameters, coupon or lines that cannot be sold).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"The key is missing, invalid or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"Origin not allowed, secret key in the browser, insufficient scope or module turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"It does not exist in the key's store or company (in Clinic, also a code or token that doesn't match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"The store is temporarily closed (`store_closed`): the catalog can be read, but no quote, no new order and no new payment attempt. `GET /v1/store` has its message and reopening date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"The key's per-minute limit was exceeded (`Retry-After: 60`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/store":{"get":{"summary":"The store: status (open or temporarily closed), currency, languages, categories, shipping, payment methods, checkout fields and banners","parameters":[{"name":"lang","in":"query","schema":{"type":"string","example":"es"},"description":"Catalog language; if the store does not have it, its main one."}],"responses":{"200":{"description":"OK","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":"Catalog with filters, sorting and pages","parameters":[{"name":"lang","in":"query","schema":{"type":"string","example":"es"},"description":"Catalog language; if the store does not have it, its main one."},{"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":"With `options` each product comes with its full page (description, bullets and options)."},{"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":"OK","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":"Product page with options, variants and availability","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","schema":{"type":"string","example":"es"},"description":"Catalog language; if the store does not have it, its main one."}],"responses":{"200":{"description":"OK","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":"States of the store's country, or the cities of one","parameters":[{"name":"parent","in":"query","schema":{"type":"string","example":"state:CO-DC"}}],"responses":{"200":{"description":"OK","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":"Current prices, promotions, coupon, shipping and stock for some lines","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":"For the coupon's per-buyer usage limit."},"lang":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","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":"Creates the order","description":"With the same `Idempotency-Key` header it returns the order already created (without token). With `gateway` the order waits for its payment and `next.url` leads to the checkout of the store gateway (Wompi, Mercado Pago or Bold); on return, report the transaction with `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":"In international format («+51 987654321») so the consent is tied to their WhatsApp."},"document":{"type":"object","properties":{"type":{"type":"string"},"number":{"type":"string"}}},"consent":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Codes from `consentCategories` the buyer checked themselves; they are stored on their contact with the order as proof. Unknown codes are ignored."}}},"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":"With `gateway`: where the buyer returns to (https)."}}},"fields":{"type":"object","additionalProperties":true,"description":"Extra checkout fields by id."},"coupon":{"type":"string"},"note":{"type":"string"},"lang":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"code":{"type":"string"},"token":{"type":["string","null"],"description":"Shown only once."},"status":{"type":"string"},"total":{"type":"number","description":"Amount in the store currency, with two decimals."},"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":"Order status (secret key with `orders:read`, or public key with the token)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Order code."},{"name":"token","in":"query","schema":{"type":"string","description":"Buyer token returned by `POST /v1/orders` (with the public key)."}}],"responses":{"200":{"description":"OK","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":"Another payment attempt with the gateway","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Buyer token returned by `POST /v1/orders` (with the public key)."},"returnUrl":{"type":"string"}}}}}},"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Order code."}],"responses":{"200":{"description":"OK","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":"The website came back from the gateway: XEN looks up the transaction and applies it","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Order code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactionId"],"properties":{"token":{"type":"string","description":"Buyer token returned by `POST /v1/orders` (with the public key)."},"transactionId":{"type":"string","description":"The `id` Wompi adds, or the `payment_id` Mercado Pago adds, to the return URL. With Bold it may be empty: XEN looks the payment up by the order."}}}}}},"responses":{"200":{"description":"OK","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":"The website reports a payment it collected itself (secret key with `payments:write` only)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"OBL-000123"},"description":"Order code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","reference"],"properties":{"amount":{"type":"number","description":"Amount in the store currency, with two decimals."},"reference":{"type":"string"},"method":{"type":"string","description":"How it was collected, for the history."}}}}}},"responses":{"200":{"description":"OK","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":"Leaves a lead: contact, quote request or newsletter","description":"With email or phone (the newsletter needs an email). `fields` are the extra checkout fields the store defines (event date, guests…), without requiring the mandatory ones. With the same `Idempotency-Key` header it returns the one already created. Scope `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":"Extra checkout fields by id."},"consent":{"type":"boolean","description":"Agreed to be contacted by the store."},"lang":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","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":"The clinic: locations with hours and time zone, bookable services, professionals, policies and consents","description":"Scope `clinic:read`. With a `live` key, the clinic must have online booking published.","responses":{"200":{"description":"OK","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":"Free slots of a service at a location (up to 14 days)","description":"Scope `clinic:read`. It counts each professional's schedule, their appointments, live holds, blocks, the minimum notice (longer for new patients) and the horizon. It doesn't expose the chair.","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":"A professional or `any`."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Local date of the location; today by default."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Up to 13 days after `from`; 6 by default."},{"name":"patientType","in":"query","schema":{"type":"string","enum":["new","existing"]}},{"name":"appointmentCode","in":"query","schema":{"type":"string"},"description":"When rescheduling: the code of the appointment being moved (with `appointmentToken`); its own slot counts as free."},{"name":"appointmentToken","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","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":"Holds a slot while the patient fills in their details","description":"Scope `appointments:create`. The hold lasts `holdSeconds`; if another booking won the slot, 409 `slot_unavailable` with up to 3 `alternatives` for the same patient type. The booking must use the `patientType` the hold was made with. The same `Idempotency-Key` of an expired hold answers 410. With too many live holds at the clinic, 429.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"With the same key it returns what was already created (without 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":"When rescheduling: the appointment being moved. Its own slot counts as free.","properties":{"code":{"type":"string"},"token":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"hold":{"type":"string"},"holdSecret":{"type":"string","description":"Shown only once."},"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`, with alternatives.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/holds/{hold}/release":{"post":{"summary":"Releases a held slot the visitor didn't book","description":"Scope `appointments:create`, secret key (`sk_`) only. With the hold secret, it deletes the hold and its slot locks: `released: true`. If the hold is gone (expired or taken by the appointment that used it), `released: false`. A secret that doesn't match answers 404, like any other “not found”.","parameters":[{"name":"hold","in":"path","required":true,"schema":{"type":"string"},"description":"Hold id from `POST /v1/clinic/holds`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["holdSecret"],"properties":{"holdSecret":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","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":"Books the appointment","description":"Scope `appointments:create`. It creates or reuses the patient by document without telling whether they existed, creates the appointment (`instant` → `confirmed`, `request` → `requested`), notifies the clinic, sends the email and the webhook. Per-phone write limit (429). `410 hold_expired` if the hold expired.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"With the same key it returns what was already created (without token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patient"],"properties":{"hold":{"type":"string","description":"Hold id from `POST /v1/clinic/holds` (or send `slot`)."},"holdSecret":{"type":"string"},"slot":{"type":"string","description":"Signed slot, without holding it first."},"serviceId":{"type":"string","description":"If sent, it must match the slot."},"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":"Required. Someone under 18 (on the clinic's local date) books with `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":"Required with `forWhom: dependent` (minor or dependent person), with their name and document.","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":"Where the confirmation and reminders go. Empty: none (only the on-screen confirmation). Without the field: email."},"visitorIp":{"type":"string","description":"The visitor's IP: stored truncated with each accepted consent."},"consents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"version":{"type":"string"},"accepted":{"type":"boolean"}}},"description":"The required ones from `GET /v1/clinic` must come accepted in their version."},"attribution":{"type":"object","properties":{"source":{"type":"string"},"landingPath":{"type":"string"},"utm":{"type":"object","additionalProperties":{"type":"string"}},"referrer":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Created","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` (with alternatives) or `policy_violation` (`min_notice`, `max_future_appointments`, `consents_not_configured`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"410":{"description":"`hold_expired`: the hold expired; pick a slot again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}":{"get":{"summary":"The appointment for “My appointment”: status, date, service, professional, location and instructions","description":"Scope `appointments:manage` with the token. With a secret key and `appointments:read`, without token. Code or token that don't match: 404.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."},{"name":"token","in":"query","required":false,"schema":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."}}],"responses":{"200":{"description":"OK","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":"The patient confirms they're coming","description":"Scope `appointments:manage`.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."}}}}}},"responses":{"200":{"description":"OK","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`: inside the cancellation window (`cancelUntilHours`) or the appointment no longer allows the change; the website asks to call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/cancel":{"post":{"summary":"Cancels the appointment (outside the cancellation window)","description":"Scope `appointments:manage`. Inside the window it answers 409 `policy_violation` and the appointment is marked `late`.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."},"reason":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"OK","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`: inside the cancellation window (`cancelUntilHours`) or the appointment no longer allows the change; the website asks to call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/reschedule":{"post":{"summary":"Reschedules to a held slot: a new linked appointment","description":"Scope `appointments:manage`. It returns the new `code` and its `token`; the previous link no longer manages it.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"With the same key it returns what was already created (without token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","hold","holdSecret"],"properties":{"token":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."},"hold":{"type":"string"},"holdSecret":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","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`: inside the cancellation window (`cancelUntilHours`) or the appointment no longer allows the change; the website asks to call.","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":"Stops the appointment's notices (email or WhatsApp)","description":"Scope `appointments:manage`. It only turns channels off, never on, and records the revocation. It's the target of the “Stop receiving these notices” link in every email.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."},"email":{"type":"boolean","enum":[false]},"whatsapp":{"type":"boolean","enum":[false]},"visitorIp":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","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`: inside the cancellation window (`cancelUntilHours`) or the appointment no longer allows the change; the website asks to call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/appointments/{code}/messages":{"get":{"summary":"The appointment's thread with the clinic (messages only, never clinical data)","description":"Scope `appointments:manage`. It marks the clinic's messages as read.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."},{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."}}],"responses":{"200":{"description":"OK","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":"The patient writes to the clinic","description":"Scope `appointments:manage`. The clinic sees it in XEN (Clinic, Messages) and gets a bell notification.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"With the same key it returns what was already created (without token)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","text"],"properties":{"token":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."},"text":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Created","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-admission: history, allergies and medication before the appointment","description":"Scope `appointments:manage`. One per appointment; it can be corrected until the clinic imports it into the record.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"CT-000123"},"description":"Appointment code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","answers"],"properties":{"token":{"type":"string","description":"“My appointment” token returned by the booking (it also goes in the emails). Never in the path."},"answers":{"type":"object","additionalProperties":true,"description":"Reason, medical history, allergies, medication, pregnancy, habits, anxiety (1 to 5)."}}}}}},"responses":{"201":{"description":"Created","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`: inside the cancellation window (`cancelUntilHours`) or the appointment no longer allows the change; the website asks to call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicError"}}}},"429":{"$ref":"#/components/responses/E429"}}}},"/clinic/requests":{"post":{"summary":"Leaves a request: contact, callback, urgent, waiting list, data rights (ARCO) or job application","description":"Scope `requests:create`. With phone or email; per-phone limit (429).","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"With the same key it returns what was already created (without 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":"Created","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":"Complaints book entry","description":"Scope `requests:create`. It returns the code (`LR-…`) and the answer deadline (15 business days), and sends the copy to the consumer's email with the provider's identification.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"With the same key it returns what was already created (without 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":"Where the answer goes: `email` requires the email; `letter`, the address."},"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":"Parent or guardian if a minor."}}},"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":"Created","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":"“My plan”: the treatment plan of an appointment's patient","description":"With the appointment code and manage token (those returned by `POST /v1/clinic/appointments`) and the patient's birth date. Returns the current plan in the patient's words, the teeth that need care and what was already done; never findings or diagnoses. If any value does not match, it answers 404 as if it did not exist. Every read is logged in the clinical record access log. Company secret key (`sk_`) with `appointments:manage` only, from the website server.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","token","birthDate"],"properties":{"code":{"type":"string","example":"CT-000123","description":"Appointment code."},"token":{"type":"string","description":"Appointment manage token (in the body, never in the path)."},"birthDate":{"type":"string","format":"date","example":"1990-05-17","description":"Patient's birth date."},"clientIp":{"type":"string","example":"198.51.100.23","description":"IP of the patient who opened “My plan” on the website: it goes to the access log. Without it (or if it isn't an IP), the caller's."}}}}}},"responses":{"200":{"description":"OK","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":"Explanation of the procedure for the patient."},"teeth":{"type":"array","items":{"type":"string"},"description":"Teeth in FDI notation."},"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":"When it was done or when it is scheduled."},"professional":{"type":["string","null"]}}}}}},{"type":"null"}]},"teethNeedingCare":{"type":"array","items":{"type":"string"},"description":"FDI teeth with pending treatment."},"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":"This document","security":[],"parameters":[{"name":"lang","in":"query","schema":{"type":"string","enum":["es","en"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"webhooks":{"order.created":{"post":{"summary":"order.created notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"order.updated":{"post":{"summary":"order.updated notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"catalog.updated":{"post":{"summary":"catalog.updated notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"promo.updated":{"post":{"summary":"promo.updated notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.created":{"post":{"summary":"appointment.created notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.updated":{"post":{"summary":"appointment.updated notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.confirmed":{"post":{"summary":"appointment.confirmed notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.cancelled":{"post":{"summary":"appointment.cancelled notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.rescheduled":{"post":{"summary":"appointment.rescheduled notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.completed":{"post":{"summary":"appointment.completed notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"appointment.no_show":{"post":{"summary":"appointment.no_show notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}},"message.created":{"post":{"summary":"message.created notice","description":"Signed in `X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of \"<t>.<body>\">` with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.","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":"Received"}}}}}}