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.
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.
Schemabearer. 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
Nome
Dove
Tipo
Obbligatorio
Descrizione
lang
query
string
No
Catalog language; if the store does not have it, its main one.example "es"
Risposta 200
Campo
Tipo
Descrizione
dataobbligatorio
Store
name
string
slug
string
currency
string
languages
string[]
language
string
mode
string
Valori: live, test
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.
Parametri
Nome
Dove
Tipo
Obbligatorio
Descrizione
Idempotency-Key
intestazione
string
No
minLength 8 · maxLength 100
Corpoobbligatorio
Campo
Tipo
Descrizione
linesobbligatorio
CartLine[]
maxItems 50
productobbligatorio
string
Product slug.
quantityobbligatorio
integer
min 1
options
object
{ optionId: valueId | [valueIds] }.
*
string | string[]
buyerobbligatorio
object
nameobbligatorio
string
emailobbligatorio
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.
Parametri
Nome
Dove
Tipo
Obbligatorio
Descrizione
serviceId
query
string
Sì
locationId
query
string
Sì
professionalId
query
string
No
A professional or any.default "any"
from
query
string (date)
No
Local date of the location; today by default.
to
query
string (date)
No
Up to 13 days after from; 6 by default.
patientType
query
string
No
Valori: new, existing
appointmentCode
query
string
No
When rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentToken
query
string
No
Risposta 200
Campo
Tipo
Descrizione
dataobbligatorio
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.
Parametri
Nome
Dove
Tipo
Obbligatorio
Descrizione
Idempotency-Key
intestazione
string
No
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpoobbligatorio
Campo
Tipo
Descrizione
slotobbligatorio
string
patientType
string
Valori: 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.
Parametri
Nome
Dove
Tipo
Obbligatorio
Descrizione
Idempotency-Key
intestazione
string
No
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpoobbligatorio
Campo
Tipo
Descrizione
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
Valori: new, existing
forWhom
string
Valori: self, dependent
patientobbligatorio
object
firstNameobbligatorio
string
lastNameobbligatorio
string
birthDateobbligatorio
string (date)
Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentobbligatorio
object
typeobbligatorio
string
Valori: DNI, CE, PAS, CC, TI, RC, OTRO
numberobbligatorio
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
typeobbligatorio
string
Valori: DNI, CE, PAS, CC, TI, RC, OTRO
numberobbligatorio
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
Risposta 201
Campo
Tipo
Descrizione
dataobbligatorio
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.
Parametri
Nome
Dove
Tipo
Obbligatorio
Descrizione
Idempotency-Key
intestazione
string
No
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpoobbligatorio
Campo
Tipo
Descrizione
kindobbligatorio
string
Valori: reclamo, queja
replyChannel
string
Where the answer goes: email requires the email; letter, the address.Valori: email, letterdefault "email"
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.
{ 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.
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