Sviluppatori

API di XEN

Il tuo sito legge il catalogo, calcola il carrello e crea ordini in XEN.

Iniziare

Ogni richiesta va all’URL di base con la chiave del tuo negozio nell’intestazione Authorization. Inizia con una chiave di prova e passa a quella reale quando il sito è pronto.

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

Autenticazione

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.

Schema bearer. Store key created in XEN → Developers → API keys.

Chiave pubblica (pk)
Si usa nel browser e risponde solo alle origini che hai registrato per lei.
Chiave segreta (sk)
Solo da server a server. Non metterla mai nel codice che scarica il browser.
Ambiti per chiave
Ogni chiave ha i suoi ambiti. Una rotta che ne chiede uno che la chiave non ha risponde 403.Ambiti citati nel riferimento: orders:read, payments:write, leads:create, clinic:read, appointments:create, appointments:manage, appointments:read, requests:create

Catalogo

Parametri

NomeDoveTipoObbligatorioDescrizione
langquerystringNoCatalog language; if the store does not have it, its main one.example "es"

Risposta 200

CampoTipoDescrizione
dataobbligatorioStore
namestring
slugstring
currencystring
languagesstring[]
languagestring
modestringValori: live, test
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
typestringValori: 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

Errori: 401 403 429

Parametri

NomeDoveTipoObbligatorioDescrizione
langquerystringNoCatalog language; if the store does not have it, its main one.example "es"
categoryquerystringNo
qquerystringNo
price_minquerystringNo
price_maxquerystringNo
expandquerystringNoWith options each product comes with its full page (description, bullets and options).Valori: options
preorderquerybooleanNo
salequerybooleanNo
featuredquerybooleanNo
sortquerystringNoValori: default, price_asc, price_desc, newest, name
pagequeryintegerNomin 1
limitqueryintegerNomin 1 · max 100

Risposta 200

CampoTipoDescrizione
dataProduct | ProductDetail[]
pageinteger
limitinteger
totalinteger
hasMoreboolean

Errori: 400 401 403 429

Parametri

NomeDoveTipoObbligatorioDescrizione
slugpercorsostringSì
langquerystringNoCatalog language; if the store does not have it, its main one.example "es"

Risposta 200

CampoTipoDescrizione
dataobbligatorioProductDetail
slugstring
namestring
skustring | null
imagesImages[]
xsstring
sstring
mstring
lstring
xlstring
priceobject
amountnumberAmount in the store currency, with two decimals.
compareAtnumber | null
currencystring
onSaleboolean
unitstringValori: unit, person
mininteger
categoriesstring[]
tagsstring[]
attributesobject
preorderobject
enabledboolean
depositnumber | null
featuredboolean
availabilityAvailability
statusstringValori: in, limited, out
quantityintegerOnly if the store publishes quantities.
publishedAtstring | null (date-time)
descriptionstring
bulletsstring[]
optionsobject[]
idstring
namestring
kindstringValori: 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
statusstringValori: in, limited, out
quantityintegerOnly if the store publishes quantities.
seoobject
titlestring
descriptionstring

Errori: 401 403 404 429

Parametri

NomeDoveTipoObbligatorioDescrizione
parentquerystringNoexample "state:CO-DC"

Risposta 200

CampoTipoDescrizione
dataobbligatorioobject[]
idstring
namestring

Errori: 400 401 403 429

Carrello e ordini

Corpoobbligatorio

CampoTipoDescrizione
linesobbligatorioCartLine[]maxItems 50
productobbligatoriostringProduct slug.
quantityobbligatoriointegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
shippingShipping
methodobbligatoriostringValori: 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

Risposta 200

CampoTipoDescrizione
dataobbligatorioQuote
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
statusstringValori: in, limited, out
quantityintegerOnly if the store publishes quantities.
issuestring | nullValori: 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 | nullValori: 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 | nullValori: 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 | nullValori: 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

Errori: 400 401 403 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.

Parametri

NomeDoveTipoObbligatorioDescrizione
Idempotency-KeyintestazionestringNominLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
linesobbligatorioCartLine[]maxItems 50
productobbligatoriostringProduct slug.
quantityobbligatoriointegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
buyerobbligatorioobject
nameobbligatoriostring
emailobbligatoriostring
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
shippingobbligatorioobject
methodobbligatoriostringValori: ship, pickup
pickupIdstring
addressobject
linestring
statestring
citystring
zipstring
notesstring
paymentobbligatorioobject
methodobbligatoriostringValori: preorder, cod, external, gateway
returnUrlstringWith gateway: where the buyer returns to (https).
fieldsobjectExtra checkout fields by id.
couponstring
notestring
langstring

Risposta 201

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

Errori: 400 401 403 429

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìOrder code.example "OBL-000123"
tokenquerystringNoBuyer token returned by POST /v1/orders (with the public key).

Risposta 200

CampoTipoDescrizione
dataobbligatorioOrder
codestring
statusstringValori: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValori: 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
statusstringValori: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errori: 401 403 404 429

Pagamenti

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìOrder code.example "OBL-000123"

Corpo

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

Risposta 200

CampoTipoDescrizione
dataobbligatorioobject
codestring
nextNextStepWhat the website does after creating the order.
typestringValori: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValori: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Errori: 400 401 403 404 429

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìOrder code.example "OBL-000123"

Corpoobbligatorio

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

Risposta 200

CampoTipoDescrizione
dataobbligatorioOrder
codestring
statusstringValori: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValori: 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
statusstringValori: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errori: 400 401 403 404 429

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìOrder code.example "OBL-000123"

Corpoobbligatorio

CampoTipoDescrizione
amountobbligatorionumberAmount in the store currency, with two decimals.
referenceobbligatoriostring
methodstringHow it was collected, for the history.

Risposta 200

CampoTipoDescrizione
dataobbligatorioOrder
codestring
statusstringValori: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValori: 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
statusstringValori: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errori: 400 401 403 404 429

Richieste

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.

Parametri

NomeDoveTipoObbligatorioDescrizione
Idempotency-KeyintestazionestringNominLength 8 · maxLength 100

Corpoobbligatorio

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

Risposta 201

CampoTipoDescrizione
dataobbligatorioobject
idstring
statusstringValori: new, contacted, closed

Errori: 400 401 403 429

Clinica

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

Risposta 200

CampoTipoDescrizione
dataobbligatorioClinicProfile
namestring
countrystringValori: 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.Valori: 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

Errori: 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.

Parametri

NomeDoveTipoObbligatorioDescrizione
serviceIdquerystringSì
locationIdquerystringSì
professionalIdquerystringNoA professional or any.default "any"
fromquerystring (date)NoLocal date of the location; today by default.
toquerystring (date)NoUp to 13 days after from; 6 by default.
patientTypequerystringNoValori: new, existing
appointmentCodequerystringNoWhen rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentTokenquerystringNo

Risposta 200

CampoTipoDescrizione
dataobbligatorioobject
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)

Errori: 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.

Parametri

NomeDoveTipoObbligatorioDescrizione
Idempotency-KeyintestazionestringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
slotobbligatoriostring
patientTypestringValori: new, existing
appointmentobjectWhen rescheduling: the appointment being moved. Its own slot counts as free.
codestring
tokenstring

Risposta 201

CampoTipoDescrizione
dataobbligatorioobject
holdstring
holdSecretstringShown only once.
expiresAtstring (date-time)

Errori: 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.

Parametri

NomeDoveTipoObbligatorioDescrizione
Idempotency-KeyintestazionestringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
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
patientTypestringValori: new, existing
forWhomstringValori: self, dependent
patientobbligatorioobject
firstNameobbligatoriostring
lastNameobbligatoriostring
birthDateobbligatoriostring (date)Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentobbligatorioobject
typeobbligatoriostringValori: DNI, CE, PAS, CC, TI, RC, OTRO
numberobbligatoriostring
phonestring
emailstring
guardianobjectRequired with forWhom: dependent (minor or dependent person), with their name and document.
namestring
relationstring
phonestring
emailstring
documentobject
typeobbligatoriostringValori: DNI, CE, PAS, CC, TI, RC, OTRO
numberobbligatoriostring
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

Risposta 201

CampoTipoDescrizione
dataobbligatorioClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValori: 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.

Errori: 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.

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"
tokenquerystringNo“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Risposta 200

CampoTipoDescrizione
dataobbligatorioClinicAppointment
codestring
statusstringValori: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValori: 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.

Errori: 401 403 404 429

Scope appointments:manage.

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"

Corpoobbligatorio

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

Risposta 200

CampoTipoDescrizione
dataobbligatorioClinicAppointment
codestring
statusstringValori: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValori: 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.

Errori: 400 401 403 404 409 429

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

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"

Corpoobbligatorio

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

Risposta 200

CampoTipoDescrizione
dataobbligatorioClinicAppointment
codestring
statusstringValori: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValori: 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.

Errori: 400 401 403 404 409 429

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

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"
Idempotency-KeyintestazionestringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
tokenobbligatoriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
holdobbligatoriostring
holdSecretobbligatoriostring

Risposta 201

CampoTipoDescrizione
dataobbligatorioClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValori: 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.

Errori: 400 401 403 404 409 410 429

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

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"
tokenquerystringSì“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Risposta 200

CampoTipoDescrizione
dataobbligatorioClinicMessage[]
idstring
directionstringValori: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Errori: 401 403 404 429

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

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"
Idempotency-KeyintestazionestringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
tokenobbligatoriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
textobbligatoriostringmaxLength 2000

Risposta 201

CampoTipoDescrizione
dataobbligatorioClinicMessage
idstring
directionstringValori: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Errori: 400 401 403 404 429

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

Parametri

NomeDoveTipoObbligatorioDescrizione
codepercorsostringSìAppointment code.example "CT-000123"

Corpoobbligatorio

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

Risposta 201

CampoTipoDescrizione
dataobbligatorioobject
idstring
receivedAtstring (date-time)

Errori: 400 401 403 404 409 429

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

Parametri

NomeDoveTipoObbligatorioDescrizione
Idempotency-KeyintestazionestringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
kindobbligatoriostringValori: contact, callback, urgent, waitlist, arco, job
namestring
phonestring
emailstring
messagestringmaxLength 4000
preferencesobject
attributionobject

Risposta 201

CampoTipoDescrizione
dataobbligatorioobject
idstring
statusstringValori: new, contacted, closed

Errori: 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.

Parametri

NomeDoveTipoObbligatorioDescrizione
Idempotency-KeyintestazionestringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobbligatorio

CampoTipoDescrizione
kindobbligatoriostringValori: reclamo, queja
replyChannelstringWhere the answer goes: email requires the email; letter, the address.Valori: email, letterdefault "email"
consumerobbligatorioobject
nameobbligatoriostring
documentobject
typestring
numberstring
addressstring
phonestring
emailstring
guardianstringParent or guardian if a minor.
serviceobject
descriptionstring
amountnumber
currencystring
detailobbligatoriostringmaxLength 4000
requeststringmaxLength 2000

Risposta 201

CampoTipoDescrizione
dataobbligatorioobject
codestringexample "LR-000015"
dueAtstring (date-time)
createdAtstring (date-time)

Errori: 400 401 403 429

Webhook

XEN avvisa il tuo server con un POST firmato ogni volta che cambia qualcosa nel tuo negozio. I webhook si creano in XEN, in Sviluppatori, e ciascuno riceve gli eventi che scegli.

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.

Eventi

  • 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

Intestazioni

NomeDoveTipoObbligatorioDescrizione
X-Xen-EventintestazionestringSì
X-Xen-DeliveryintestazionestringSì
X-Xen-SignatureintestazionestringSì

Corpo dell’avviso

CampoTipoDescrizione
idstringDelivery id (also in X-Xen-Delivery).
typestringValori: 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 | nullValori: 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.

Verificare la firma

Separa t e v1 da X-Xen-Signature, calcola l’HMAC-SHA256 di <t>.<corpo> con il segreto del webhook sul corpo così come è arrivato e confrontalo con v1 in tempo costante.

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))
  );
};

Errori e limiti

Ogni errore risponde con lo stesso oggetto, con un tipo stabile per il tuo codice e un messaggio da leggere.

StatoSignificato
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).
429The key's per-minute limit was exceeded (Retry-After: 60).

Forma dell’errore

CampoTipoDescrizione
errorobject
typestringValori: 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
messagestring

Tipi di errore

  • 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

Limite al minuto

Ogni chiave ha un limite di richieste al minuto. Oltre, l’API risponde 429 e l’intestazione Retry-After indica quanti secondi aspettare.

Ordini senza duplicati

Invia l’intestazione Idempotency-Key con POST /orders. Se ripeti la richiesta con la stessa chiave, ricevi l’ordine già creato invece di uno nuovo.minLength 8 · maxLength 100