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.
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.
Esquemabearer. 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
Nome
Onde
Tipo
Obrigatório
Descrição
lang
consulta
string
Não
Catalog language; if the store does not have it, its main one.example "es"
Resposta 200
Campo
Tipo
Descrição
dataobrigatório
Store
name
string
slug
string
currency
string
languages
string[]
language
string
mode
string
Valores: 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.Valores: 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.
Parâmetros
Nome
Onde
Tipo
Obrigatório
Descrição
Idempotency-Key
cabeçalho
string
Não
minLength 8 · maxLength 100
Corpoobrigatório
Campo
Tipo
Descrição
linesobrigatório
CartLine[]
maxItems 50
productobrigatório
string
Product slug.
quantityobrigatório
integer
min 1
options
object
{ optionId: valueId | [valueIds] }.
*
string | string[]
buyerobrigatório
object
nameobrigatório
string
emailobrigatório
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.
Parâmetros
Nome
Onde
Tipo
Obrigatório
Descrição
serviceId
consulta
string
Sim
locationId
consulta
string
Sim
professionalId
consulta
string
Não
A professional or any.default "any"
from
consulta
string (date)
Não
Local date of the location; today by default.
to
consulta
string (date)
Não
Up to 13 days after from; 6 by default.
patientType
consulta
string
Não
Valores: new, existing
appointmentCode
consulta
string
Não
When rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentToken
consulta
string
Não
Resposta 200
Campo
Tipo
Descrição
dataobrigatório
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.
Parâmetros
Nome
Onde
Tipo
Obrigatório
Descrição
Idempotency-Key
cabeçalho
string
Não
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpoobrigatório
Campo
Tipo
Descrição
slotobrigatório
string
patientType
string
Valores: 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.
Parâmetros
Nome
Onde
Tipo
Obrigatório
Descrição
Idempotency-Key
cabeçalho
string
Não
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpoobrigatório
Campo
Tipo
Descrição
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
Valores: new, existing
forWhom
string
Valores: self, dependent
patientobrigatório
object
firstNameobrigatório
string
lastNameobrigatório
string
birthDateobrigatório
string (date)
Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentobrigatório
object
typeobrigatório
string
Valores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobrigatório
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
typeobrigatório
string
Valores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobrigatório
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
Resposta 201
Campo
Tipo
Descrição
dataobrigatório
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.
Parâmetros
Nome
Onde
Tipo
Obrigatório
Descrição
Idempotency-Key
cabeçalho
string
Não
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Corpoobrigatório
Campo
Tipo
Descrição
kindobrigatório
string
Valores: reclamo, queja
replyChannel
string
Where the answer goes: email requires the email; letter, the address.Valores: email, letterdefault "email"
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.
{ 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.
Todo erro responde com o mesmo objeto, com um tipo estável para o seu código e uma mensagem para ler.
Status
Significado
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).
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