Desenvolvedores

API da XEN

Seu site lê o catálogo, calcula o carrinho e cria pedidos na XEN.

Começar

Cada requisição vai para a URL base com a chave da sua loja no cabeçalho Authorization. Comece com uma chave de teste e troque pela real quando o site estiver pronto.

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

Autenticação

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.

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

Chave pública (pk)
Vai no navegador e só responde às origens que você registrou para ela.
Chave secreta (sk)
Somente de servidor para servidor. Nunca a coloque no código que o navegador baixa.
Escopos por chave
Cada chave tem seus próprios escopos. Uma rota que pede um escopo que a chave não tem responde 403.Escopos citados na referência: orders:read, payments:write, leads:create, clinic:read, appointments:create, appointments:manage, appointments:read, requests:create

Catálogo

Parâmetros

NomeOndeTipoObrigatórioDescrição
langconsultastringNãoCatalog language; if the store does not have it, its main one.example "es"

Resposta 200

CampoTipoDescrição
dataobrigatórioStore
namestring
slugstring
currencystring
languagesstring[]
languagestring
modestringValores: 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.Valores: 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
typestringValores: 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

Erros: 401 403 429

Parâmetros

NomeOndeTipoObrigatórioDescrição
langconsultastringNãoCatalog language; if the store does not have it, its main one.example "es"
categoryconsultastringNão
qconsultastringNão
price_minconsultastringNão
price_maxconsultastringNão
expandconsultastringNãoWith options each product comes with its full page (description, bullets and options).Valores: options
preorderconsultabooleanNão
saleconsultabooleanNão
featuredconsultabooleanNão
sortconsultastringNãoValores: default, price_asc, price_desc, newest, name
pageconsultaintegerNãomin 1
limitconsultaintegerNãomin 1 · max 100

Resposta 200

CampoTipoDescrição
dataProduct | ProductDetail[]
pageinteger
limitinteger
totalinteger
hasMoreboolean

Erros: 400 401 403 429

Parâmetros

NomeOndeTipoObrigatórioDescrição
slugcaminhostringSim
langconsultastringNãoCatalog language; if the store does not have it, its main one.example "es"

Resposta 200

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

Erros: 401 403 404 429

Parâmetros

NomeOndeTipoObrigatórioDescrição
parentconsultastringNãoexample "state:CO-DC"

Resposta 200

CampoTipoDescrição
dataobrigatórioobject[]
idstring
namestring

Erros: 400 401 403 429

Carrinho e pedidos

Corpoobrigatório

CampoTipoDescrição
linesobrigatórioCartLine[]maxItems 50
productobrigatóriostringProduct slug.
quantityobrigatóriointegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
shippingShipping
methodobrigatóriostringValores: 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

Resposta 200

CampoTipoDescrição
dataobrigatórioQuote
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
statusstringValores: in, limited, out
quantityintegerOnly if the store publishes quantities.
issuestring | nullValores: 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 | nullValores: 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 | nullValores: 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 | nullValores: 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

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
Idempotency-KeycabeçalhostringNãominLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
linesobrigatórioCartLine[]maxItems 50
productobrigatóriostringProduct slug.
quantityobrigatóriointegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
buyerobrigatórioobject
nameobrigatóriostring
emailobrigatóriostring
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
shippingobrigatórioobject
methodobrigatóriostringValores: ship, pickup
pickupIdstring
addressobject
linestring
statestring
citystring
zipstring
notesstring
paymentobrigatórioobject
methodobrigatóriostringValores: preorder, cod, external, gateway
returnUrlstringWith gateway: where the buyer returns to (https).
fieldsobjectExtra checkout fields by id.
couponstring
notestring
langstring

Resposta 201

CampoTipoDescrição
dataobrigatórioobject
codestring
tokenstring | nullShown only once.
statusstring
totalnumberAmount in the store currency, with two decimals.
currencystring
nextNextStepWhat the website does after creating the order.
typestringValores: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValores: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Erros: 400 401 403 409 429

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimOrder code.example "OBL-000123"
tokenconsultastringNãoBuyer token returned by POST /v1/orders (with the public key).

Resposta 200

CampoTipoDescrição
dataobrigatórioOrder
codestring
statusstringValores: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValores: 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
statusstringValores: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Erros: 401 403 404 429

Pagamentos

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimOrder code.example "OBL-000123"

Corpo

CampoTipoDescrição
tokenstringBuyer token returned by POST /v1/orders (with the public key).
returnUrlstring

Resposta 200

CampoTipoDescrição
dataobrigatórioobject
codestring
nextNextStepWhat the website does after creating the order.
typestringValores: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValores: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Erros: 400 401 403 404 409 429

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimOrder code.example "OBL-000123"

Corpoobrigatório

CampoTipoDescrição
tokenstringBuyer token returned by POST /v1/orders (with the public key).
transactionIdobrigatóriostringThe 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.

Resposta 200

CampoTipoDescrição
dataobrigatórioOrder
codestring
statusstringValores: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValores: 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
statusstringValores: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Erros: 400 401 403 404 429

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimOrder code.example "OBL-000123"

Corpoobrigatório

CampoTipoDescrição
amountobrigatórionumberAmount in the store currency, with two decimals.
referenceobrigatóriostring
methodstringHow it was collected, for the history.

Resposta 200

CampoTipoDescrição
dataobrigatórioOrder
codestring
statusstringValores: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValores: 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
statusstringValores: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Erros: 400 401 403 404 429

Solicitações

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.

Parâmetros

NomeOndeTipoObrigatórioDescrição
Idempotency-KeycabeçalhostringNãominLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
typeobrigatóriostringValores: contact, quote, newsletter
namestring
emailstring
phonestring
messagestringmaxLength 2000
fieldsobjectExtra checkout fields by id.
consentbooleanAgreed to be contacted by the store.
langstring

Resposta 201

CampoTipoDescrição
dataobrigatórioobject
idstring
statusstringValores: new, contacted, closed

Erros: 400 401 403 429

Clínica

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

Resposta 200

CampoTipoDescrição
dataobrigatórioClinicProfile
namestring
countrystringValores: 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.Valores: 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

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
serviceIdconsultastringSim
locationIdconsultastringSim
professionalIdconsultastringNãoA professional or any.default "any"
fromconsultastring (date)NãoLocal date of the location; today by default.
toconsultastring (date)NãoUp to 13 days after from; 6 by default.
patientTypeconsultastringNãoValores: new, existing
appointmentCodeconsultastringNãoWhen rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentTokenconsultastringNão

Resposta 200

CampoTipoDescrição
dataobrigatórioobject
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)

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
Idempotency-KeycabeçalhostringNãoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
slotobrigatóriostring
patientTypestringValores: new, existing
appointmentobjectWhen rescheduling: the appointment being moved. Its own slot counts as free.
codestring
tokenstring

Resposta 201

CampoTipoDescrição
dataobrigatórioobject
holdstring
holdSecretstringShown only once.
expiresAtstring (date-time)

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
Idempotency-KeycabeçalhostringNãoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
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
patientTypestringValores: new, existing
forWhomstringValores: self, dependent
patientobrigatórioobject
firstNameobrigatóriostring
lastNameobrigatóriostring
birthDateobrigatóriostring (date)Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentobrigatórioobject
typeobrigatóriostringValores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobrigatóriostring
phonestring
emailstring
guardianobjectRequired with forWhom: dependent (minor or dependent person), with their name and document.
namestring
relationstring
phonestring
emailstring
documentobject
typeobrigatóriostringValores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobrigatóriostring
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

Resposta 201

CampoTipoDescrição
dataobrigatórioClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValores: 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.

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"
tokenconsultastringNão“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Resposta 200

CampoTipoDescrição
dataobrigatórioClinicAppointment
codestring
statusstringValores: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValores: 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.

Erros: 401 403 404 429

Scope appointments:manage.

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"

Corpoobrigatório

CampoTipoDescrição
tokenobrigatóriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Resposta 200

CampoTipoDescrição
dataobrigatórioClinicAppointment
codestring
statusstringValores: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValores: 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.

Erros: 400 401 403 404 409 429

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"

Corpoobrigatório

CampoTipoDescrição
tokenobrigatóriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
reasonstringmaxLength 300

Resposta 200

CampoTipoDescrição
dataobrigatórioClinicAppointment
codestring
statusstringValores: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValores: 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.

Erros: 400 401 403 404 409 429

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"
Idempotency-KeycabeçalhostringNãoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
tokenobrigatóriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
holdobrigatóriostring
holdSecretobrigatóriostring

Resposta 201

CampoTipoDescrição
dataobrigatórioClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValores: 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.

Erros: 400 401 403 404 409 410 429

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"
tokenconsultastringSim“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Resposta 200

CampoTipoDescrição
dataobrigatórioClinicMessage[]
idstring
directionstringValores: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Erros: 401 403 404 429

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"
Idempotency-KeycabeçalhostringNãoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
tokenobrigatóriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
textobrigatóriostringmaxLength 2000

Resposta 201

CampoTipoDescrição
dataobrigatórioClinicMessage
idstring
directionstringValores: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Erros: 400 401 403 404 429

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
codecaminhostringSimAppointment code.example "CT-000123"

Corpoobrigatório

CampoTipoDescrição
tokenobrigatóriostring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
answersobrigatórioobjectReason, medical history, allergies, medication, pregnancy, habits, anxiety (1 to 5).

Resposta 201

CampoTipoDescrição
dataobrigatórioobject
idstring
receivedAtstring (date-time)

Erros: 400 401 403 404 409 429

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
Idempotency-KeycabeçalhostringNãoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
kindobrigatóriostringValores: contact, callback, urgent, waitlist, arco, job
namestring
phonestring
emailstring
messagestringmaxLength 4000
preferencesobject
attributionobject

Resposta 201

CampoTipoDescrição
dataobrigatórioobject
idstring
statusstringValores: new, contacted, closed

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

Parâmetros

NomeOndeTipoObrigatórioDescrição
Idempotency-KeycabeçalhostringNãoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Corpoobrigatório

CampoTipoDescrição
kindobrigatóriostringValores: reclamo, queja
replyChannelstringWhere the answer goes: email requires the email; letter, the address.Valores: email, letterdefault "email"
consumerobrigatórioobject
nameobrigatóriostring
documentobject
typestring
numberstring
addressstring
phonestring
emailstring
guardianstringParent or guardian if a minor.
serviceobject
descriptionstring
amountnumber
currencystring
detailobrigatóriostringmaxLength 4000
requeststringmaxLength 2000

Resposta 201

CampoTipoDescrição
dataobrigatórioobject
codestringexample "LR-000015"
dueAtstring (date-time)
createdAtstring (date-time)

Erros: 400 401 403 429

Webhooks

A XEN avisa o seu servidor com um POST assinado sempre que algo muda na sua loja. Os webhooks são criados na XEN, em Desenvolvedores, e cada um recebe os eventos que você escolhe.

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.

Eventos

  • 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

Cabeçalhos

NomeOndeTipoObrigatórioDescrição
X-Xen-EventcabeçalhostringSim
X-Xen-DeliverycabeçalhostringSim
X-Xen-SignaturecabeçalhostringSim

Corpo do aviso

CampoTipoDescrição
idstringDelivery id (also in X-Xen-Delivery).
typestringValores: 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 | nullValores: 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.

Verificar a assinatura

Separe t e v1 de X-Xen-Signature, calcule o HMAC-SHA256 de <t>.<corpo> com o segredo do webhook sobre o corpo exatamente como chegou e compare com v1 em tempo constante.

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

Erros e limites

Todo erro responde com o mesmo objeto, com um tipo estável para o seu código e uma mensagem para ler.

StatusSignificado
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).

Formato do erro

CampoTipoDescrição
errorobject
typestringValores: 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

Tipos de erro

  • 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 por minuto

Cada chave tem um limite de requisições por minuto. Ao passar dele, a API responde 429 e o cabeçalho Retry-After diz quantos segundos esperar.

Pedidos sem duplicidade

Envie o cabeçalho Idempotency-Key em POST /orders. Se repetir a requisição com a mesma chave, você recebe o pedido já criado em vez de um novo.minLength 8 · maxLength 100