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.
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émabearer. 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
Nom
Emplacement
Type
Obligatoire
Description
lang
requête
string
Non
Catalog language; if the store does not have it, its main one.example "es"
Réponse 200
Champ
Type
Description
dataobligatoire
Store
name
string
slug
string
currency
string
languages
string[]
language
string
mode
string
Valeurs: live, test
status
string
closed: the store was temporarily closed from XEN. The catalog can still be read, but quoting, creating an order and another payment attempt answer 409 store_closed.Valeurs: open, closed
closure
object | null
Only with status: closed: the store's message in the requested language (it may be empty) and the reopening date, if the store set one. After that date the store opens again by itself.
message
string
reopensAt
string | null (date-time)
categories
object[]
slug
string
name
string
parent
string | null
order
integer
image
Images | null
Photo URL by size (longest side: xs 96, s 240, m 600, l 1200, xl 2048).
xs
string
s
string
m
string
l
string
xl
string
attributes
object[]
key
string
name
string
shipping
object
zones
object[]
id
string
name
string
regions
string[]
Ids from GET /v1/places.
fee
number
Amount in the store currency, with two decimals.
freeFrom
number | null
toQuote
boolean
Shipping to be quoted: the store sets it on each order.
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
Nom
Emplacement
Type
Obligatoire
Description
Idempotency-Key
en-tête
string
Non
minLength 8 · maxLength 100
Corpsobligatoire
Champ
Type
Description
linesobligatoire
CartLine[]
maxItems 50
productobligatoire
string
Product slug.
quantityobligatoire
integer
min 1
options
object
{ optionId: valueId | [valueIds] }.
*
string | string[]
buyerobligatoire
object
nameobligatoire
string
emailobligatoire
string
phone
string
In international format («+51 987654321») so the consent is tied to their WhatsApp.
document
object
type
string
number
string
consent
string[]
Codes from consentCategories the buyer checked themselves; they are stored on their contact with the order as proof. Unknown codes are ignored.maxItems 20
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.
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
Nom
Emplacement
Type
Obligatoire
Description
serviceId
requête
string
Oui
locationId
requête
string
Oui
professionalId
requête
string
Non
A professional or any.default "any"
from
requête
string (date)
Non
Local date of the location; today by default.
to
requête
string (date)
Non
Up to 13 days after from; 6 by default.
patientType
requête
string
Non
Valeurs: new, existing
appointmentCode
requête
string
Non
When rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentToken
requête
string
Non
Réponse 200
Champ
Type
Description
dataobligatoire
object
timezone
string
days
object[]
date
string (date)
slots
ClinicSlot[]
slot
string
Opaque signed slot (expires in 30 minutes). Pass it as is to POST /v1/clinic/holds.
startsAt
string (date-time)
localStart
string
Local time of the location.example "2026-11-10T10:30"
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
Nom
Emplacement
Type
Obligatoire
Description
Idempotency-Key
en-tête
string
Non
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpsobligatoire
Champ
Type
Description
slotobligatoire
string
patientType
string
Valeurs: new, existing
appointment
object
When rescheduling: the appointment being moved. Its own slot counts as free.
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
Nom
Emplacement
Type
Obligatoire
Description
Idempotency-Key
en-tête
string
Non
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpsobligatoire
Champ
Type
Description
hold
string
Hold id from POST /v1/clinic/holds (or send slot).
holdSecret
string
slot
string
Signed slot, without holding it first.
serviceId
string
If sent, it must match the slot.
locationId
string
professionalId
string
patientType
string
Valeurs: new, existing
forWhom
string
Valeurs: self, dependent
patientobligatoire
object
firstNameobligatoire
string
lastNameobligatoire
string
birthDateobligatoire
string (date)
Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentobligatoire
object
typeobligatoire
string
Valeurs: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatoire
string
phone
string
email
string
guardian
object
Required with forWhom: dependent (minor or dependent person), with their name and document.
name
string
relation
string
phone
string
email
string
document
object
typeobligatoire
string
Valeurs: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatoire
string
reason
string
maxLength 500
channels
string[]
Where the confirmation and reminders go. Empty: none (only the on-screen confirmation). Without the field: email.
visitorIp
string
The visitor's IP: stored truncated with each accepted consent.
consents
object[]
The required ones from GET /v1/clinic must come accepted in their version.
code
string
version
string
accepted
boolean
attribution
object
source
string
landingPath
string
utm
object
*
string
referrer
string
Réponse 201
Champ
Type
Description
dataobligatoire
ClinicAppointmentCreated
code
string
token
string | null
Returned only once; with the same Idempotency-Key, null.
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
Nom
Emplacement
Type
Obligatoire
Description
Idempotency-Key
en-tête
string
Non
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpsobligatoire
Champ
Type
Description
kindobligatoire
string
Valeurs: reclamo, queja
replyChannel
string
Where the answer goes: email requires the email; letter, the address.Valeurs: email, letterdefault "email"
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.
{ 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.
Toute erreur renvoie le même objet, avec un type stable pour votre code et un message lisible.
Statut
Signification
400
The request is not valid (body, parameters, coupon or lines that cannot be sold).
401
The key is missing, invalid or expired.
403
Origin not allowed, secret key in the browser, insufficient scope or module turned off.
404
It does not exist in the key's store or company (in Clinic, also a code or token that doesn't match).
409
The store is temporarily closed (store_closed): the catalog can be read, but no quote, no new order and no new payment attempt. GET /v1/store has its message and reopening date.
429
The key's per-minute limit was exceeded (Retry-After: 60).
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