Développeurs

API de XEN

Votre site lit le catalogue, chiffre le panier et crée des commandes dans XEN.

Démarrer

Chaque requête part vers l’URL de base avec la clé de votre boutique dans l’en-tête Authorization. Commencez avec une clé de test et passez à la clé réelle quand votre site est prêt.

URL de base
https://api.xeneural.com/v1
Version
1.0.0
curl https://api.xeneural.com/v1/products \
  -H "Authorization: Bearer pk_test_…"

Authentification

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.

Schéma bearer. Store key created in XEN → Developers → API keys.

Clé publique (pk)
Elle s’utilise dans le navigateur et ne répond qu’aux origines que vous avez enregistrées pour elle.
Clé secrète (sk)
Uniquement de serveur à serveur. Ne la placez jamais dans le code que télécharge le navigateur.
Portées par clé
Chaque clé porte ses propres portées. Une route qui en demande une que la clé n’a pas répond 403.Portées citées par la référence: orders:read, payments:write, leads:create, clinic:read, appointments:create, appointments:manage, appointments:read, requests:create

Catalogue

Paramètres

NomEmplacementTypeObligatoireDescription
langrequêtestringNonCatalog language; if the store does not have it, its main one.example "es"

Réponse 200

ChampTypeDescription
dataobligatoireStore
namestring
slugstring
currencystring
languagesstring[]
languagestring
modestringValeurs: live, test
statusstringclosed: 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.Valeurs: open, closed
closureobject | nullOnly 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.
messagestring
reopensAtstring | null (date-time)
categoriesobject[]
slugstring
namestring
parentstring | null
orderinteger
imageImages | nullPhoto URL by size (longest side: xs 96, s 240, m 600, l 1200, xl 2048).
xsstring
sstring
mstring
lstring
xlstring
attributesobject[]
keystring
namestring
shippingobject
zonesobject[]
idstring
namestring
regionsstring[]Ids from GET /v1/places.
feenumberAmount in the store currency, with two decimals.
freeFromnumber | null
toQuotebooleanShipping to be quoted: the store sets it on each order.
pickupobject[]
idstring
namestring
addressstring
paymentMethodsstring[]
checkoutFieldsobject[]
idstring
labelstring
typestringValeurs: text, textarea, number, date, bool, select
requiredboolean
stockobject
showQuantityboolean
bannersobject[]
idstring
textstring
imagestring | null
urlstring | null
couponstring | null
kindstring
consentCategoriesobject[]WhatsApp message categories the buyer can accept at checkout (unchecked boxes). Empty if the company doesn't use Conversations.
codestring
namestring

Erreurs: 401 403 429

Paramètres

NomEmplacementTypeObligatoireDescription
langrequêtestringNonCatalog language; if the store does not have it, its main one.example "es"
categoryrequêtestringNon
qrequêtestringNon
price_minrequêtestringNon
price_maxrequêtestringNon
expandrequêtestringNonWith options each product comes with its full page (description, bullets and options).Valeurs: options
preorderrequêtebooleanNon
salerequêtebooleanNon
featuredrequêtebooleanNon
sortrequêtestringNonValeurs: default, price_asc, price_desc, newest, name
pagerequêteintegerNonmin 1
limitrequêteintegerNonmin 1 · max 100

Réponse 200

ChampTypeDescription
dataProduct | ProductDetail[]
pageinteger
limitinteger
totalinteger
hasMoreboolean

Erreurs: 400 401 403 429

Paramètres

NomEmplacementTypeObligatoireDescription
slugcheminstringOui
langrequêtestringNonCatalog language; if the store does not have it, its main one.example "es"

Réponse 200

ChampTypeDescription
dataobligatoireProductDetail
slugstring
namestring
skustring | null
imagesImages[]
xsstring
sstring
mstring
lstring
xlstring
priceobject
amountnumberAmount in the store currency, with two decimals.
compareAtnumber | null
currencystring
onSaleboolean
unitstringValeurs: unit, person
mininteger
categoriesstring[]
tagsstring[]
attributesobject
preorderobject
enabledboolean
depositnumber | null
featuredboolean
availabilityAvailability
statusstringValeurs: in, limited, out
quantityintegerOnly if the store publishes quantities.
publishedAtstring | null (date-time)
descriptionstring
bulletsstring[]
optionsobject[]
idstring
namestring
kindstringValeurs: variant, addon
requiredboolean
minintegerHow many values must be chosen at least (0 = optional; equal to max = exactly that many).
maxinteger
whenobject | nullConditional option: shown, and counted, only if one of values was chosen in option option.
optionstring
valuesstring[]
valuesobject[]
idstring
namestring
priceDeltanumberAmount in the store currency, with two decimals.
skustring | null
availabilityAvailability
statusstringValeurs: in, limited, out
quantityintegerOnly if the store publishes quantities.
seoobject
titlestring
descriptionstring

Erreurs: 401 403 404 429

Paramètres

NomEmplacementTypeObligatoireDescription
parentrequêtestringNonexample "state:CO-DC"

Réponse 200

ChampTypeDescription
dataobligatoireobject[]
idstring
namestring

Erreurs: 400 401 403 429

Panier et commandes

Corpsobligatoire

ChampTypeDescription
linesobligatoireCartLine[]maxItems 50
productobligatoirestringProduct slug.
quantityobligatoireintegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
shippingShipping
methodobligatoirestringValeurs: ship, pickup
statestringState or department (GET /v1/places).
citystringCity of that state (GET /v1/places?parent=).
pickupIdstring
couponstring
emailstringFor the coupon's per-buyer usage limit.
langstring

Réponse 200

ChampTypeDescription
dataobligatoireQuote
linesobject[]
productstring
namestring
skustring | null
imageImages | nullPhoto URL by size (longest side: xs 96, s 240, m 600, l 1200, xl 2048).
xsstring
sstring
mstring
lstring
xlstring
optionsobject[]
quantityinteger
unitPricenumber | null
totalnumberAmount in the store currency, with two decimals.
availabilityAvailability
statusstringValeurs: in, limited, out
quantityintegerOnly if the store publishes quantities.
issuestring | nullValeurs: 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
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
promotionobject | null
namestring
kindstring
couponstring | null
amountnumberAmount in the store currency, with two decimals.
freeShippingobject | null
namestring
couponstring | null
couponobject | null
codestring
issuestring | nullValeurs: 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
shippingobject
feenumberAmount in the store currency, with two decimals.
zoneobject | null
idstring
namestring
freeboolean
toQuotebooleanThe total goes without shipping: the store quotes it later (it can't be paid online yet).
issuestring | nullValeurs: 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
totalnumberAmount in the store currency, with two decimals.
currencystring
issuesobject[]If there is any, POST /v1/orders answers 400.
lineinteger | null
codestring | nullValeurs: 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

Erreurs: 400 401 403 409 429

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.

Paramètres

NomEmplacementTypeObligatoireDescription
Idempotency-Keyen-têtestringNonminLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
linesobligatoireCartLine[]maxItems 50
productobligatoirestringProduct slug.
quantityobligatoireintegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
buyerobligatoireobject
nameobligatoirestring
emailobligatoirestring
phonestringIn international format («+51 987654321») so the consent is tied to their WhatsApp.
documentobject
typestring
numberstring
consentstring[]Codes from consentCategories the buyer checked themselves; they are stored on their contact with the order as proof. Unknown codes are ignored.maxItems 20
shippingobligatoireobject
methodobligatoirestringValeurs: ship, pickup
pickupIdstring
addressobject
linestring
statestring
citystring
zipstring
notesstring
paymentobligatoireobject
methodobligatoirestringValeurs: preorder, cod, external, gateway
returnUrlstringWith gateway: where the buyer returns to (https).
fieldsobjectExtra checkout fields by id.
couponstring
notestring
langstring

Réponse 201

ChampTypeDescription
dataobligatoireobject
codestring
tokenstring | nullShown only once.
statusstring
totalnumberAmount in the store currency, with two decimals.
currencystring
nextNextStepWhat the website does after creating the order.
typestringValeurs: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValeurs: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Erreurs: 400 401 403 409 429

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiOrder code.example "OBL-000123"
tokenrequêtestringNonBuyer token returned by POST /v1/orders (with the public key).

Réponse 200

ChampTypeDescription
dataobligatoireOrder
codestring
statusstringValeurs: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValeurs: live, test
createdAtstring (date-time)
buyerobject
namestring
emailstring
linesobject[]
namestring
skustring | null
optionsobject[]
quantityinteger
unitPricenumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberAmount in the store currency, with two decimals.
toQuoteboolean
totalsobject
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
shippingnumberAmount in the store currency, with two decimals.
taxnumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValeurs: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Erreurs: 401 403 404 429

Paiements

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiOrder code.example "OBL-000123"

Corps

ChampTypeDescription
tokenstringBuyer token returned by POST /v1/orders (with the public key).
returnUrlstring

Réponse 200

ChampTypeDescription
dataobligatoireobject
codestring
nextNextStepWhat the website does after creating the order.
typestringValeurs: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValeurs: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Erreurs: 400 401 403 404 409 429

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiOrder code.example "OBL-000123"

Corpsobligatoire

ChampTypeDescription
tokenstringBuyer token returned by POST /v1/orders (with the public key).
transactionIdobligatoirestringThe 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.

Réponse 200

ChampTypeDescription
dataobligatoireOrder
codestring
statusstringValeurs: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValeurs: live, test
createdAtstring (date-time)
buyerobject
namestring
emailstring
linesobject[]
namestring
skustring | null
optionsobject[]
quantityinteger
unitPricenumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberAmount in the store currency, with two decimals.
toQuoteboolean
totalsobject
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
shippingnumberAmount in the store currency, with two decimals.
taxnumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValeurs: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Erreurs: 400 401 403 404 429

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiOrder code.example "OBL-000123"

Corpsobligatoire

ChampTypeDescription
amountobligatoirenumberAmount in the store currency, with two decimals.
referenceobligatoirestring
methodstringHow it was collected, for the history.

Réponse 200

ChampTypeDescription
dataobligatoireOrder
codestring
statusstringValeurs: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValeurs: live, test
createdAtstring (date-time)
buyerobject
namestring
emailstring
linesobject[]
namestring
skustring | null
optionsobject[]
quantityinteger
unitPricenumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberAmount in the store currency, with two decimals.
toQuoteboolean
totalsobject
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
shippingnumberAmount in the store currency, with two decimals.
taxnumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValeurs: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Erreurs: 400 401 403 404 429

Demandes

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.

Paramètres

NomEmplacementTypeObligatoireDescription
Idempotency-Keyen-têtestringNonminLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
typeobligatoirestringValeurs: contact, quote, newsletter
namestring
emailstring
phonestring
messagestringmaxLength 2000
fieldsobjectExtra checkout fields by id.
consentbooleanAgreed to be contacted by the store.
langstring

Réponse 201

ChampTypeDescription
dataobligatoireobject
idstring
statusstringValeurs: new, contacted, closed

Erreurs: 400 401 403 429

Clinique

Scope clinic:read. With a live key, the clinic must have online booking published.

Réponse 200

ChampTypeDescription
dataobligatoireClinicProfile
namestring
countrystringValeurs: PE, CO
phonestring
whatsappstring
emailstring
licenseobject | null
labelstringexample "COP"
verifyUrlstring
locationsobject[]
idstring
namestring
addressstring
referencestring
geoobject | null
latnumber
lngnumber
timezonestringexample "America/Lima"
hoursobject[]
dayOfWeekintegermin 0 · max 6
opensstringexample "09:00"
closesstringexample "20:00"
servicesobject[]
idstring
codestring
namestring
descriptionstring
categorystring | null
durationMininteger
modestringinstant confirms on booking; request waits for the clinic to confirm.Valeurs: instant, request
patientTypesstring[]
prepstring
professionalsobject[]
idstring
titlestring
namestring
specialtystring
licenseobject | null
typestring | null
numberstring
rnestring | nullNational Specialist Registry number, if any.
biostring
photoUrlstring | null
acceptsNewboolean
serviceIdsstring[]Published services they see patients for: their own list and the service's, as availability uses.
policiesobject
gridMininteger
minNoticeMininteger
minNoticeNewMininteger
maxDaysAheadinteger
holdSecondsinteger
cancelUntilHoursinteger
consentsobject[]
codestring
versionstring
requiredboolean
textstring

Erreurs: 401 403 429

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.

Paramètres

NomEmplacementTypeObligatoireDescription
serviceIdrequêtestringOui
locationIdrequêtestringOui
professionalIdrequêtestringNonA professional or any.default "any"
fromrequêtestring (date)NonLocal date of the location; today by default.
torequêtestring (date)NonUp to 13 days after from; 6 by default.
patientTyperequêtestringNonValeurs: new, existing
appointmentCoderequêtestringNonWhen rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentTokenrequêtestringNon

Réponse 200

ChampTypeDescription
dataobligatoireobject
timezonestring
daysobject[]
datestring (date)
slotsClinicSlot[]
slotstringOpaque signed slot (expires in 30 minutes). Pass it as is to POST /v1/clinic/holds.
startsAtstring (date-time)
localStartstringLocal time of the location.example "2026-11-10T10:30"
durationMininteger
professionalobject
idstring
namestring
nextAvailableDatestring | null (date)

Erreurs: 400 401 403 404 429

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.

Paramètres

NomEmplacementTypeObligatoireDescription
Idempotency-Keyen-têtestringNonWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
slotobligatoirestring
patientTypestringValeurs: new, existing
appointmentobjectWhen rescheduling: the appointment being moved. Its own slot counts as free.
codestring
tokenstring

Réponse 201

ChampTypeDescription
dataobligatoireobject
holdstring
holdSecretstringShown only once.
expiresAtstring (date-time)

Erreurs: 400 401 403 404 409 429

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.

Paramètres

NomEmplacementTypeObligatoireDescription
Idempotency-Keyen-têtestringNonWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
holdstringHold id from POST /v1/clinic/holds (or send slot).
holdSecretstring
slotstringSigned slot, without holding it first.
serviceIdstringIf sent, it must match the slot.
locationIdstring
professionalIdstring
patientTypestringValeurs: new, existing
forWhomstringValeurs: self, dependent
patientobligatoireobject
firstNameobligatoirestring
lastNameobligatoirestring
birthDateobligatoirestring (date)Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentobligatoireobject
typeobligatoirestringValeurs: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatoirestring
phonestring
emailstring
guardianobjectRequired with forWhom: dependent (minor or dependent person), with their name and document.
namestring
relationstring
phonestring
emailstring
documentobject
typeobligatoirestringValeurs: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatoirestring
reasonstringmaxLength 500
channelsstring[]Where the confirmation and reminders go. Empty: none (only the on-screen confirmation). Without the field: email.
visitorIpstringThe visitor's IP: stored truncated with each accepted consent.
consentsobject[]The required ones from GET /v1/clinic must come accepted in their version.
codestring
versionstring
acceptedboolean
attributionobject
sourcestring
landingPathstring
utmobject
*string
referrerstring

Réponse 201

ChampTypeDescription
dataobligatoireClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValeurs: requested, confirmed
startsAtstring (date-time)
localStartstring
timezonestring
serviceobject
idstring
namestring
professionalobject
idstring
namestring
locationobject
idstring
namestring
addressstring
manageUntilstring (date-time)Until when the website can cancel or reschedule.

Erreurs: 400 401 403 404 409 410 429

Scope appointments:manage with the token. With a secret key and appointments:read, without token. Code or token that don't match: 404.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"
tokenrequêtestringNon“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Réponse 200

ChampTypeDescription
dataobligatoireClinicAppointment
codestring
statusstringValeurs: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValeurs: none, sent, confirmed, declined
startsAtstring (date-time)
localStartstring
timezonestring
durationMininteger
serviceobject
idstring
namestring
professionalobject
idstring
titlestring
namestring
locationobject
idstring
namestring
addressstring
canConfirmboolean
canCancelboolean
canRescheduleboolean
manageUntilstring (date-time)
latebooleanSomeone tried to cancel or reschedule inside the window.
prepstring
rescheduledTostring | nullCode of the new appointment if it was rescheduled.

Erreurs: 401 403 404 429

Scope appointments:manage.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"

Corpsobligatoire

ChampTypeDescription
tokenobligatoirestring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Réponse 200

ChampTypeDescription
dataobligatoireClinicAppointment
codestring
statusstringValeurs: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValeurs: none, sent, confirmed, declined
startsAtstring (date-time)
localStartstring
timezonestring
durationMininteger
serviceobject
idstring
namestring
professionalobject
idstring
titlestring
namestring
locationobject
idstring
namestring
addressstring
canConfirmboolean
canCancelboolean
canRescheduleboolean
manageUntilstring (date-time)
latebooleanSomeone tried to cancel or reschedule inside the window.
prepstring
rescheduledTostring | nullCode of the new appointment if it was rescheduled.

Erreurs: 400 401 403 404 409 429

Scope appointments:manage. Inside the window it answers 409 policy_violation and the appointment is marked late.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"

Corpsobligatoire

ChampTypeDescription
tokenobligatoirestring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
reasonstringmaxLength 300

Réponse 200

ChampTypeDescription
dataobligatoireClinicAppointment
codestring
statusstringValeurs: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValeurs: none, sent, confirmed, declined
startsAtstring (date-time)
localStartstring
timezonestring
durationMininteger
serviceobject
idstring
namestring
professionalobject
idstring
titlestring
namestring
locationobject
idstring
namestring
addressstring
canConfirmboolean
canCancelboolean
canRescheduleboolean
manageUntilstring (date-time)
latebooleanSomeone tried to cancel or reschedule inside the window.
prepstring
rescheduledTostring | nullCode of the new appointment if it was rescheduled.

Erreurs: 400 401 403 404 409 429

Scope appointments:manage. It returns the new code and its token; the previous link no longer manages it.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"
Idempotency-Keyen-têtestringNonWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
tokenobligatoirestring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
holdobligatoirestring
holdSecretobligatoirestring

Réponse 201

ChampTypeDescription
dataobligatoireClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValeurs: requested, confirmed
startsAtstring (date-time)
localStartstring
timezonestring
serviceobject
idstring
namestring
professionalobject
idstring
namestring
locationobject
idstring
namestring
addressstring
manageUntilstring (date-time)Until when the website can cancel or reschedule.

Erreurs: 400 401 403 404 409 410 429

Scope appointments:manage. It marks the clinic's messages as read.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"
tokenrequêtestringOui“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Réponse 200

ChampTypeDescription
dataobligatoireClinicMessage[]
idstring
directionstringValeurs: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Erreurs: 401 403 404 429

Scope appointments:manage. The clinic sees it in XEN (Clinic, Messages) and gets a bell notification.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"
Idempotency-Keyen-têtestringNonWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
tokenobligatoirestring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
textobligatoirestringmaxLength 2000

Réponse 201

ChampTypeDescription
dataobligatoireClinicMessage
idstring
directionstringValeurs: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Erreurs: 400 401 403 404 429

Scope appointments:manage. One per appointment; it can be corrected until the clinic imports it into the record.

Paramètres

NomEmplacementTypeObligatoireDescription
codecheminstringOuiAppointment code.example "CT-000123"

Corpsobligatoire

ChampTypeDescription
tokenobligatoirestring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
answersobligatoireobjectReason, medical history, allergies, medication, pregnancy, habits, anxiety (1 to 5).

Réponse 201

ChampTypeDescription
dataobligatoireobject
idstring
receivedAtstring (date-time)

Erreurs: 400 401 403 404 409 429

Scope requests:create. With phone or email; per-phone limit (429).

Paramètres

NomEmplacementTypeObligatoireDescription
Idempotency-Keyen-têtestringNonWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
kindobligatoirestringValeurs: contact, callback, urgent, waitlist, arco, job
namestring
phonestring
emailstring
messagestringmaxLength 4000
preferencesobject
attributionobject

Réponse 201

ChampTypeDescription
dataobligatoireobject
idstring
statusstringValeurs: new, contacted, closed

Erreurs: 400 401 403 429

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.

Paramètres

NomEmplacementTypeObligatoireDescription
Idempotency-Keyen-têtestringNonWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpsobligatoire

ChampTypeDescription
kindobligatoirestringValeurs: reclamo, queja
replyChannelstringWhere the answer goes: email requires the email; letter, the address.Valeurs: email, letterdefault "email"
consumerobligatoireobject
nameobligatoirestring
documentobject
typestring
numberstring
addressstring
phonestring
emailstring
guardianstringParent or guardian if a minor.
serviceobject
descriptionstring
amountnumber
currencystring
detailobligatoirestringmaxLength 4000
requeststringmaxLength 2000

Réponse 201

ChampTypeDescription
dataobligatoireobject
codestringexample "LR-000015"
dueAtstring (date-time)
createdAtstring (date-time)

Erreurs: 400 401 403 429

Webhooks

XEN prévient votre serveur par un POST signé chaque fois que quelque chose change dans votre boutique. Les webhooks se créent dans XEN, sous Développeurs, et chacun reçoit les événements que vous choisissez.

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.

Événements

  • order.createdorder.created notice
  • order.updatedorder.updated notice
  • catalog.updatedcatalog.updated notice
  • promo.updatedpromo.updated notice
  • appointment.createdappointment.created notice
  • appointment.updatedappointment.updated notice
  • appointment.confirmedappointment.confirmed notice
  • appointment.cancelledappointment.cancelled notice
  • appointment.rescheduledappointment.rescheduled notice
  • appointment.completedappointment.completed notice
  • appointment.no_showappointment.no_show notice
  • message.createdmessage.created notice

En-têtes

NomEmplacementTypeObligatoireDescription
X-Xen-Eventen-têtestringOui
X-Xen-Deliveryen-têtestringOui
X-Xen-Signatureen-têtestringOui

Corps de l’avis

ChampTypeDescription
idstringDelivery id (also in X-Xen-Delivery).
typestringValeurs: 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
createdstring (date-time)
modestring | nullValeurs: live, test, null
dataobject{ 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.

Vérifier la signature

Séparez t et v1 de X-Xen-Signature, calculez le HMAC-SHA256 de <t>.<corps> avec le secret du webhook sur le corps tel qu’il est arrivé, puis comparez-le à v1 en temps constant.

import crypto from "node:crypto";

const verifyXenSignature = (header, rawBody, secret) => {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const received = String(parts.v1 || "");
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
};

Erreurs et limites

Toute erreur renvoie le même objet, avec un type stable pour votre code et un message lisible.

StatutSignification
400The request is not valid (body, parameters, coupon or lines that cannot be sold).
401The key is missing, invalid or expired.
403Origin not allowed, secret key in the browser, insufficient scope or module turned off.
404It does not exist in the key's store or company (in Clinic, also a code or token that doesn't match).
409The 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.
429The key's per-minute limit was exceeded (Retry-After: 60).

Forme de l’erreur

ChampTypeDescription
errorobject
typestringValeurs: 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
messagestring

Types d’erreur

  • 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

Limite par minute

Chaque clé a une limite de requêtes par minute. Au-delà, l’API répond 429 et l’en-tête Retry-After indique combien de secondes attendre.

Commandes sans doublon

Envoyez l’en-tête Idempotency-Key avec POST /orders. Si vous répétez la requête avec la même clé, vous recevez la commande déjà créée au lieu d’une nouvelle.minLength 8 · maxLength 100