Cada petición va a la URL base con la clave de tu tienda en la cabecera Authorization. Empieza con una clave de prueba y cambia a la real cuando tu web esté lista.
API pública de XEN para las webs de las empresas: el catálogo, el carrito, los pedidos y los pagos de una tienda, y la reserva y la gestión de citas de una clínica. Se autentica con la clave de la tienda o de la empresa (Authorization: Bearer pk_… | sk_…): la pública (pk_) desde el navegador y solo desde sus orígenes; la secreta (sk_) solo de servidor a servidor. Una clave test también lee la tienda en borrador.
Esquemabearer. Clave de la tienda creada en XEN → Desarrolladores → Claves de la API.
Clave pública (pk)
Va en el navegador y solo responde a los orígenes que registraste para ella.
Clave secreta (sk)
Solo de servidor a servidor. Nunca la pongas en el código que descarga el navegador.
Alcances por clave
Cada clave lleva sus alcances. Una ruta que pide uno que la clave no tiene responde 403.Alcances que pide la referencia: orders:read, payments:write, leads:create, clinic:read, appointments:create, appointments:manage, appointments:read, requests:create
Catálogo
Parámetros
Nombre
Dónde
Tipo
Obligatorio
Descripción
lang
consulta
string
No
Idioma del catálogo; si la tienda no lo tiene, el principal.example "es"
Respuesta 200
Campo
Tipo
Descripción
dataobligatorio
Store
name
string
slug
string
currency
string
languages
string[]
language
string
mode
string
Valores: live, test
categories
object[]
slug
string
name
string
parent
string | null
order
integer
image
Images | null
URL de la foto por tamaño (lado mayor: 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 de GET /v1/places.
fee
number
Importe en la moneda de la tienda, con dos decimales.
freeFrom
number | null
toQuote
boolean
Envío a cotizar: la tienda pone su valor en cada pedido.
Con la misma cabecera Idempotency-Key devuelve el pedido ya creado (sin testigo). Con gateway el pedido espera su pago y next.url lleva al checkout de la pasarela de la tienda (Wompi, Mercado Pago o Bold); al volver, informa la transacción con gateway-return.
Parámetros
Nombre
Dónde
Tipo
Obligatorio
Descripción
Idempotency-Key
cabecera
string
No
minLength 8 · maxLength 100
Cuerpoobligatorio
Campo
Tipo
Descripción
linesobligatorio
CartLine[]
maxItems 50
productobligatorio
string
Slug de la ficha.
quantityobligatorio
integer
min 1
options
object
{ idDeOpción: idDeValor | [idsDeValor] }.
*
string | string[]
buyerobligatorio
object
nameobligatorio
string
emailobligatorio
string
phone
string
En formato internacional («+51 987654321») para que el consentimiento quede atado a su WhatsApp.
document
object
type
string
number
string
consent
string[]
Códigos de consentCategories que el comprador marcó él mismo; quedan en su contacto con el pedido como prueba. Las que no existen se ignoran.maxItems 20
shippingobligatorio
object
methodobligatorio
string
Valores: ship, pickup
pickupId
string
address
object
line
string
state
string
city
string
zip
string
notes
string
paymentobligatorio
object
methodobligatorio
string
Valores: preorder, cod, external, gateway
returnUrl
string
Con gateway: a dónde vuelve el comprador (https).
fields
object
Campos extra del checkout por id.
coupon
string
note
string
lang
string
Respuesta 201
Campo
Tipo
Descripción
dataobligatorio
object
code
string
token
string | null
Se muestra una sola vez.
status
string
total
number
Importe en la moneda de la tienda, con dos decimales.
Con correo o celular (el boletín pide correo). fields son los campos extra que la tienda define para el checkout (fecha del evento, invitados…), sin exigir los obligatorios. Con la misma cabecera Idempotency-Key devuelve la ya creada. Alcance leads:create.
Alcance clinic:read. Cuenta el horario de cada profesional, sus citas, los holds vivos, los bloqueos, la antelación mínima (más larga para pacientes nuevos) y el horizonte. No expone el sillón.
Parámetros
Nombre
Dónde
Tipo
Obligatorio
Descripción
serviceId
consulta
string
Sí
locationId
consulta
string
Sí
professionalId
consulta
string
No
Un profesional o any.default "any"
from
consulta
string (date)
No
Fecha local de la sede; por defecto, hoy.
to
consulta
string (date)
No
Hasta 13 días después de from; por defecto, 6.
patientType
consulta
string
No
Valores: new, existing
appointmentCode
consulta
string
No
Al reprogramar: el código de la cita que se mueve (con appointmentToken); su hueco cuenta como libre.
appointmentToken
consulta
string
No
Respuesta 200
Campo
Tipo
Descripción
dataobligatorio
object
timezone
string
days
object[]
date
string (date)
slots
ClinicSlot[]
slot
string
Hueco opaco y firmado (vence en 30 minutos). Se pasa tal cual a POST /v1/clinic/holds.
Alcance appointments:create. El hold dura holdSeconds; si otra reserva ganó el hueco, 409 slot_unavailable con hasta 3 alternatives del mismo tipo de paciente. La reserva tiene que ser del patientType con que se apartó. La misma Idempotency-Key de un hold vencido responde 410. Con demasiados holds vivos en la clínica, 429.
Parámetros
Nombre
Dónde
Tipo
Obligatorio
Descripción
Idempotency-Key
cabecera
string
No
Con la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100
Cuerpoobligatorio
Campo
Tipo
Descripción
slotobligatorio
string
patientType
string
Valores: new, existing
appointment
object
Al reprogramar: la cita que se mueve. Su hueco cuenta como libre.
Alcance appointments:create. Crea o reutiliza al paciente por su documento sin decir si ya existía, crea la cita (instant → confirmed, request → requested), avisa a la clínica, manda el correo y el webhook. Límite de escrituras por teléfono (429). 410 hold_expired si el hold venció.
Parámetros
Nombre
Dónde
Tipo
Obligatorio
Descripción
Idempotency-Key
cabecera
string
No
Con la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100
Cuerpoobligatorio
Campo
Tipo
Descripción
hold
string
Id del hold de POST /v1/clinic/holds (o manda slot).
holdSecret
string
slot
string
Hueco firmado, sin apartar antes.
serviceId
string
Si viene, tiene que coincidir con el hueco.
locationId
string
professionalId
string
patientType
string
Valores: new, existing
forWhom
string
Valores: self, dependent
patientobligatorio
object
firstNameobligatorio
string
lastNameobligatorio
string
birthDateobligatorio
string (date)
Obligatoria. Un menor de 18 años (en la fecha local de la clínica) reserva con forWhom: dependent.
documentobligatorio
object
typeobligatorio
string
Valores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatorio
string
phone
string
email
string
guardian
object
Obligatorio con forWhom: dependent (menor o persona a cargo), con su nombre y su documento.
name
string
relation
string
phone
string
email
string
document
object
typeobligatorio
string
Valores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatorio
string
reason
string
maxLength 500
channels
string[]
Por dónde recibe la confirmación y los recordatorios. Vacío: ninguno (solo la confirmación en pantalla). Sin el campo: correo.
visitorIp
string
IP del visitante: se guarda recortada con cada consentimiento aceptado.
consents
object[]
Los obligatorios de GET /v1/clinic tienen que venir aceptados en su versión.
code
string
version
string
accepted
boolean
attribution
object
source
string
landingPath
string
utm
object
*
string
referrer
string
Respuesta 201
Campo
Tipo
Descripción
dataobligatorio
ClinicAppointmentCreated
code
string
token
string | null
Se devuelve una sola vez; con la misma Idempotency-Key, null.
Alcance requests:create. Devuelve el código (LR-…) y la fecha límite de respuesta (15 días hábiles), y manda la copia al correo del consumidor con la identificación del proveedor.
Parámetros
Nombre
Dónde
Tipo
Obligatorio
Descripción
Idempotency-Key
cabecera
string
No
Con la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100
Cuerpoobligatorio
Campo
Tipo
Descripción
kindobligatorio
string
Valores: reclamo, queja
replyChannel
string
Por dónde quiere la respuesta: email exige el correo; letter, el domicilio.Valores: email, letterdefault "email"
XEN avisa a tu servidor con un POST firmado cada vez que cambia algo de tu tienda. Los webhooks se crean en XEN, en Desarrolladores, y cada uno recibe los eventos que eliges.
Firmado en X-Xen-Signature: t=<segundos>,v1=<HMAC-SHA256 hex de "<t>.<cuerpo>"> con el secreto del webhook. Responde 2xx en menos de 5 s; si no, XEN reintenta con espera creciente durante unas 22 horas y pausa el webhook tras 20 fallos seguidos.
{ order } con la forma de GET /v1/orders/{code}, { store, product } o { promo }; los de la cita y message.created, { code, status, startsAt, serviceId, professionalId, locationId } sin datos clínicos.
Verificar la firma
Separa t y v1 de X-Xen-Signature, calcula el HMAC-SHA256 de <t>.<cuerpo> con el secreto del webhook sobre el cuerpo tal como llegó y compáralo con v1 en tiempo constante.
Cada clave tiene un límite de peticiones por minuto. Al pasarlo, la API responde 429 y la cabecera Retry-After dice cuántos segundos esperar.
Pedidos sin duplicados
Envía la cabecera Idempotency-Key en POST /orders. Si repites la petición con la misma clave, recibes el pedido ya creado en lugar de uno nuevo.minLength 8 · maxLength 100