Desarrolladores

API de XEN

Tu web lee el catálogo, cotiza el carrito y crea pedidos en XEN.

Empezar

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.

URL base
https://api.xeneural.com/v1
Versión
1.0.0
curl https://api.xeneural.com/v1/products \
  -H "Authorization: Bearer pk_test_…"

Autenticación

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.

Esquema bearer. 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

NombreDóndeTipoObligatorioDescripción
langconsultastringNoIdioma del catálogo; si la tienda no lo tiene, el principal.example "es"

Respuesta 200

CampoTipoDescripción
dataobligatorioStore
namestring
slugstring
currencystring
languagesstring[]
languagestring
modestringValores: live, test
categoriesobject[]
slugstring
namestring
parentstring | null
orderinteger
imageImages | nullURL de la foto por tamaño (lado mayor: xs 96, s 240, m 600, l 1200, xl 2048).
xsstring
sstring
mstring
lstring
xlstring
attributesobject[]
keystring
namestring
shippingobject
zonesobject[]
idstring
namestring
regionsstring[]Ids de GET /v1/places.
feenumberImporte en la moneda de la tienda, con dos decimales.
freeFromnumber | null
toQuotebooleanEnvío a cotizar: la tienda pone su valor en cada pedido.
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[]Categorías de mensajes de WhatsApp que el comprador puede aceptar al pagar (casillas sin marcar). Vacío si la empresa no usa Conversaciones.
codestring
namestring

Errores: 401 403 429

Parámetros

NombreDóndeTipoObligatorioDescripción
langconsultastringNoIdioma del catálogo; si la tienda no lo tiene, el principal.example "es"
categoryconsultastringNo
qconsultastringNo
price_minconsultastringNo
price_maxconsultastringNo
expandconsultastringNoCon options cada pieza trae su ficha completa (descripción, viñetas y opciones).Valores: options
preorderconsultabooleanNo
saleconsultabooleanNo
featuredconsultabooleanNo
sortconsultastringNoValores: default, price_asc, price_desc, newest, name
pageconsultaintegerNomin 1
limitconsultaintegerNomin 1 · max 100

Respuesta 200

CampoTipoDescripción
dataProduct | ProductDetail[]
pageinteger
limitinteger
totalinteger
hasMoreboolean

Errores: 400 401 403 429

Parámetros

NombreDóndeTipoObligatorioDescripción
slugrutastringSí
langconsultastringNoIdioma del catálogo; si la tienda no lo tiene, el principal.example "es"

Respuesta 200

CampoTipoDescripción
dataobligatorioProductDetail
slugstring
namestring
skustring | null
imagesImages[]
xsstring
sstring
mstring
lstring
xlstring
priceobject
amountnumberImporte en la moneda de la tienda, con dos decimales.
compareAtnumber | null
currencystring
onSaleboolean
unitstringValores: unit, person
mininteger
categoriesstring[]
tagsstring[]
attributesobject
preorderobject
enabledboolean
depositnumber | null
featuredboolean
availabilityAvailability
statusstringValores: in, limited, out
quantityintegerSolo si la tienda publica cantidades.
publishedAtstring | null (date-time)
descriptionstring
bulletsstring[]
optionsobject[]
idstring
namestring
kindstringValores: variant, addon
requiredboolean
minintegerCuántos valores hay que elegir como mínimo (0 = opcional; igual a max = exactamente esos).
maxinteger
whenobject | nullOpción condicionada: solo se muestra, y solo cuenta, si en la opción option se eligió alguno de values.
optionstring
valuesstring[]
valuesobject[]
idstring
namestring
priceDeltanumberImporte en la moneda de la tienda, con dos decimales.
skustring | null
availabilityAvailability
statusstringValores: in, limited, out
quantityintegerSolo si la tienda publica cantidades.
seoobject
titlestring
descriptionstring

Errores: 401 403 404 429

Parámetros

NombreDóndeTipoObligatorioDescripción
parentconsultastringNoexample "state:CO-DC"

Respuesta 200

CampoTipoDescripción
dataobligatorioobject[]
idstring
namestring

Errores: 400 401 403 429

Carrito y pedidos

Cuerpoobligatorio

CampoTipoDescripción
linesobligatorioCartLine[]maxItems 50
productobligatoriostringSlug de la ficha.
quantityobligatoriointegermin 1
optionsobject{ idDeOpción: idDeValor | [idsDeValor] }.
*string | string[]
shippingShipping
methodobligatoriostringValores: ship, pickup
statestringDepartamento (GET /v1/places).
citystringCiudad del departamento (GET /v1/places?parent=).
pickupIdstring
couponstring
emailstringPara el límite de usos del cupón por comprador.
langstring

Respuesta 200

CampoTipoDescripción
dataobligatorioQuote
linesobject[]
productstring
namestring
skustring | null
imageImages | nullURL de la foto por tamaño (lado mayor: xs 96, s 240, m 600, l 1200, xl 2048).
xsstring
sstring
mstring
lstring
xlstring
optionsobject[]
quantityinteger
unitPricenumber | null
totalnumberImporte en la moneda de la tienda, con dos decimales.
availabilityAvailability
statusstringValores: in, limited, out
quantityintegerSolo si la tienda publica cantidades.
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
subtotalnumberImporte en la moneda de la tienda, con dos decimales.
discountnumberImporte en la moneda de la tienda, con dos decimales.
promotionobject | null
namestring
kindstring
couponstring | null
amountnumberImporte en la moneda de la tienda, con dos decimales.
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
feenumberImporte en la moneda de la tienda, con dos decimales.
zoneobject | null
idstring
namestring
freeboolean
toQuotebooleanEl total va sin envío: la tienda lo cotiza después (no se puede pagar en línea todavía).
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
totalnumberImporte en la moneda de la tienda, con dos decimales.
currencystring
issuesobject[]Si hay alguno, POST /v1/orders responde 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

Errores: 400 401 403 429

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

NombreDóndeTipoObligatorioDescripción
Idempotency-KeycabecerastringNominLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
linesobligatorioCartLine[]maxItems 50
productobligatoriostringSlug de la ficha.
quantityobligatoriointegermin 1
optionsobject{ idDeOpción: idDeValor | [idsDeValor] }.
*string | string[]
buyerobligatorioobject
nameobligatoriostring
emailobligatoriostring
phonestringEn formato internacional («+51 987654321») para que el consentimiento quede atado a su WhatsApp.
documentobject
typestring
numberstring
consentstring[]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
shippingobligatorioobject
methodobligatoriostringValores: ship, pickup
pickupIdstring
addressobject
linestring
statestring
citystring
zipstring
notesstring
paymentobligatorioobject
methodobligatoriostringValores: preorder, cod, external, gateway
returnUrlstringCon gateway: a dónde vuelve el comprador (https).
fieldsobjectCampos extra del checkout por id.
couponstring
notestring
langstring

Respuesta 201

CampoTipoDescripción
dataobligatorioobject
codestring
tokenstring | nullSe muestra una sola vez.
statusstring
totalnumberImporte en la moneda de la tienda, con dos decimales.
currencystring
nextNextStepQué hace la web después de crear el pedido.
typestringValores: confirmation, cash_on_delivery, external_payment, redirect
urlstringCon redirect: el checkout de la pasarela.
providerstringValores: wompi, mercadopago, bold
referencestring
amountnumberImporte en la moneda de la tienda, con dos decimales.
currencystring

Errores: 400 401 403 429

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo del pedido.example "OBL-000123"
tokenconsultastringNoTestigo del comprador que devolvió POST /v1/orders (con la clave pública).

Respuesta 200

CampoTipoDescripción
dataobligatorioOrder
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
unitPricenumberImporte en la moneda de la tienda, con dos decimales.
totalnumberImporte en la moneda de la tienda, con dos decimales.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberImporte en la moneda de la tienda, con dos decimales.
toQuoteboolean
totalsobject
subtotalnumberImporte en la moneda de la tienda, con dos decimales.
discountnumberImporte en la moneda de la tienda, con dos decimales.
shippingnumberImporte en la moneda de la tienda, con dos decimales.
taxnumberImporte en la moneda de la tienda, con dos decimales.
totalnumberImporte en la moneda de la tienda, con dos decimales.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValores: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errores: 401 403 404 429

Pagos

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo del pedido.example "OBL-000123"

Cuerpo

CampoTipoDescripción
tokenstringTestigo del comprador que devolvió POST /v1/orders (con la clave pública).
returnUrlstring

Respuesta 200

CampoTipoDescripción
dataobligatorioobject
codestring
nextNextStepQué hace la web después de crear el pedido.
typestringValores: confirmation, cash_on_delivery, external_payment, redirect
urlstringCon redirect: el checkout de la pasarela.
providerstringValores: wompi, mercadopago, bold
referencestring
amountnumberImporte en la moneda de la tienda, con dos decimales.
currencystring

Errores: 400 401 403 404 429

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo del pedido.example "OBL-000123"

Cuerpoobligatorio

CampoTipoDescripción
tokenstringTestigo del comprador que devolvió POST /v1/orders (con la clave pública).
transactionIdobligatoriostringEl id que agrega Wompi o el payment_id que agrega Mercado Pago a la URL de vuelta. Con Bold puede ir vacío: XEN busca el pago por el pedido.

Respuesta 200

CampoTipoDescripción
dataobligatorioOrder
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
unitPricenumberImporte en la moneda de la tienda, con dos decimales.
totalnumberImporte en la moneda de la tienda, con dos decimales.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberImporte en la moneda de la tienda, con dos decimales.
toQuoteboolean
totalsobject
subtotalnumberImporte en la moneda de la tienda, con dos decimales.
discountnumberImporte en la moneda de la tienda, con dos decimales.
shippingnumberImporte en la moneda de la tienda, con dos decimales.
taxnumberImporte en la moneda de la tienda, con dos decimales.
totalnumberImporte en la moneda de la tienda, con dos decimales.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValores: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errores: 400 401 403 404 429

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo del pedido.example "OBL-000123"

Cuerpoobligatorio

CampoTipoDescripción
amountobligatorionumberImporte en la moneda de la tienda, con dos decimales.
referenceobligatoriostring
methodstringCómo se cobró, para el historial.

Respuesta 200

CampoTipoDescripción
dataobligatorioOrder
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
unitPricenumberImporte en la moneda de la tienda, con dos decimales.
totalnumberImporte en la moneda de la tienda, con dos decimales.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberImporte en la moneda de la tienda, con dos decimales.
toQuoteboolean
totalsobject
subtotalnumberImporte en la moneda de la tienda, con dos decimales.
discountnumberImporte en la moneda de la tienda, con dos decimales.
shippingnumberImporte en la moneda de la tienda, con dos decimales.
taxnumberImporte en la moneda de la tienda, con dos decimales.
totalnumberImporte en la moneda de la tienda, con dos decimales.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValores: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errores: 400 401 403 404 429

Solicitudes

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.

Parámetros

NombreDóndeTipoObligatorioDescripción
Idempotency-KeycabecerastringNominLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
typeobligatoriostringValores: contact, quote, newsletter
namestring
emailstring
phonestring
messagestringmaxLength 2000
fieldsobjectCampos extra del checkout por id.
consentbooleanAceptó que la tienda lo contacte.
langstring

Respuesta 201

CampoTipoDescripción
dataobligatorioobject
idstring
statusstringValores: new, contacted, closed

Errores: 400 401 403 429

Clínica

Alcance clinic:read. Con una clave live, la clínica tiene que tener publicada la reserva en línea.

Respuesta 200

CampoTipoDescripción
dataobligatorioClinicProfile
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 confirma al reservar; request espera a que la clínica confirme.Valores: instant, request
patientTypesstring[]
prepstring
professionalsobject[]
idstring
titlestring
namestring
specialtystring
licenseobject | null
typestring | null
numberstring
rnestring | nullRegistro Nacional de Especialista, si lo tiene.
biostring
photoUrlstring | null
acceptsNewboolean
serviceIdsstring[]Servicios publicados que atiende: su propia lista y la del servicio, como la disponibilidad.
policiesobject
gridMininteger
minNoticeMininteger
minNoticeNewMininteger
maxDaysAheadinteger
holdSecondsinteger
cancelUntilHoursinteger
consentsobject[]
codestring
versionstring
requiredboolean
textstring

Errores: 401 403 429

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

NombreDóndeTipoObligatorioDescripción
serviceIdconsultastringSí
locationIdconsultastringSí
professionalIdconsultastringNoUn profesional o any.default "any"
fromconsultastring (date)NoFecha local de la sede; por defecto, hoy.
toconsultastring (date)NoHasta 13 días después de from; por defecto, 6.
patientTypeconsultastringNoValores: new, existing
appointmentCodeconsultastringNoAl reprogramar: el código de la cita que se mueve (con appointmentToken); su hueco cuenta como libre.
appointmentTokenconsultastringNo

Respuesta 200

CampoTipoDescripción
dataobligatorioobject
timezonestring
daysobject[]
datestring (date)
slotsClinicSlot[]
slotstringHueco opaco y firmado (vence en 30 minutos). Se pasa tal cual a POST /v1/clinic/holds.
startsAtstring (date-time)
localStartstringHora local de la sede.example "2026-11-10T10:30"
durationMininteger
professionalobject
idstring
namestring
nextAvailableDatestring | null (date)

Errores: 400 401 403 404 429

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

NombreDóndeTipoObligatorioDescripción
Idempotency-KeycabecerastringNoCon la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
slotobligatoriostring
patientTypestringValores: new, existing
appointmentobjectAl reprogramar: la cita que se mueve. Su hueco cuenta como libre.
codestring
tokenstring

Respuesta 201

CampoTipoDescripción
dataobligatorioobject
holdstring
holdSecretstringSe muestra una sola vez.
expiresAtstring (date-time)

Errores: 400 401 403 404 409 429

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

NombreDóndeTipoObligatorioDescripción
Idempotency-KeycabecerastringNoCon la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
holdstringId del hold de POST /v1/clinic/holds (o manda slot).
holdSecretstring
slotstringHueco firmado, sin apartar antes.
serviceIdstringSi viene, tiene que coincidir con el hueco.
locationIdstring
professionalIdstring
patientTypestringValores: new, existing
forWhomstringValores: self, dependent
patientobligatorioobject
firstNameobligatoriostring
lastNameobligatoriostring
birthDateobligatoriostring (date)Obligatoria. Un menor de 18 años (en la fecha local de la clínica) reserva con forWhom: dependent.
documentobligatorioobject
typeobligatoriostringValores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatoriostring
phonestring
emailstring
guardianobjectObligatorio con forWhom: dependent (menor o persona a cargo), con su nombre y su documento.
namestring
relationstring
phonestring
emailstring
documentobject
typeobligatoriostringValores: DNI, CE, PAS, CC, TI, RC, OTRO
numberobligatoriostring
reasonstringmaxLength 500
channelsstring[]Por dónde recibe la confirmación y los recordatorios. Vacío: ninguno (solo la confirmación en pantalla). Sin el campo: correo.
visitorIpstringIP del visitante: se guarda recortada con cada consentimiento aceptado.
consentsobject[]Los obligatorios de GET /v1/clinic tienen que venir aceptados en su versión.
codestring
versionstring
acceptedboolean
attributionobject
sourcestring
landingPathstring
utmobject
*string
referrerstring

Respuesta 201

CampoTipoDescripción
dataobligatorioClinicAppointmentCreated
codestring
tokenstring | nullSe devuelve una sola vez; con la misma Idempotency-Key, null.
statusstringValores: requested, confirmed
startsAtstring (date-time)
localStartstring
timezonestring
serviceobject
idstring
namestring
professionalobject
idstring
namestring
locationobject
idstring
namestring
addressstring
manageUntilstring (date-time)Hasta cuándo la web puede cancelar o reprogramar.

Errores: 400 401 403 404 409 410 429

Alcance appointments:manage con el token. Con clave secreta y appointments:read, sin token. Código o token que no calzan: 404.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"
tokenconsultastringNoToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.

Respuesta 200

CampoTipoDescripción
dataobligatorioClinicAppointment
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)
latebooleanSe intentó cancelar o reprogramar dentro de la ventana.
prepstring
rescheduledTostring | nullCódigo de la cita nueva si se reprogramó.

Errores: 401 403 404 429

Alcance appointments:manage.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"

Cuerpoobligatorio

CampoTipoDescripción
tokenobligatoriostringToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.

Respuesta 200

CampoTipoDescripción
dataobligatorioClinicAppointment
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)
latebooleanSe intentó cancelar o reprogramar dentro de la ventana.
prepstring
rescheduledTostring | nullCódigo de la cita nueva si se reprogramó.

Errores: 400 401 403 404 409 429

Alcance appointments:manage. Dentro de la ventana responde 409 policy_violation y la cita queda marcada late.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"

Cuerpoobligatorio

CampoTipoDescripción
tokenobligatoriostringToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.
reasonstringmaxLength 300

Respuesta 200

CampoTipoDescripción
dataobligatorioClinicAppointment
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)
latebooleanSe intentó cancelar o reprogramar dentro de la ventana.
prepstring
rescheduledTostring | nullCódigo de la cita nueva si se reprogramó.

Errores: 400 401 403 404 409 429

Alcance appointments:manage. Devuelve el nuevo code y su token; el enlace anterior deja de servir para gestionar.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"
Idempotency-KeycabecerastringNoCon la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
tokenobligatoriostringToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.
holdobligatoriostring
holdSecretobligatoriostring

Respuesta 201

CampoTipoDescripción
dataobligatorioClinicAppointmentCreated
codestring
tokenstring | nullSe devuelve una sola vez; con la misma Idempotency-Key, null.
statusstringValores: requested, confirmed
startsAtstring (date-time)
localStartstring
timezonestring
serviceobject
idstring
namestring
professionalobject
idstring
namestring
locationobject
idstring
namestring
addressstring
manageUntilstring (date-time)Hasta cuándo la web puede cancelar o reprogramar.

Errores: 400 401 403 404 409 410 429

Alcance appointments:manage. Marca leídos los mensajes de la clínica.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"
tokenconsultastringSíToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.

Respuesta 200

CampoTipoDescripción
dataobligatorioClinicMessage[]
idstring
directionstringValores: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Errores: 401 403 404 429

Alcance appointments:manage. La clínica lo ve en XEN (Clínica, Mensajes) y le suena la campana.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"
Idempotency-KeycabecerastringNoCon la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
tokenobligatoriostringToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.
textobligatoriostringmaxLength 2000

Respuesta 201

CampoTipoDescripción
dataobligatorioClinicMessage
idstring
directionstringValores: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Errores: 400 401 403 404 429

Alcance appointments:manage. Una por cita; se puede corregir hasta que la clínica la importe a la historia.

Parámetros

NombreDóndeTipoObligatorioDescripción
coderutastringSíCódigo de la cita.example "CT-000123"

Cuerpoobligatorio

CampoTipoDescripción
tokenobligatoriostringToken de «Mi cita» que devolvió la reserva (también va en los correos). Nunca en la ruta.
answersobligatorioobjectMotivo, antecedentes, alergias, medicación, embarazo, hábitos, ansiedad (1 a 5).

Respuesta 201

CampoTipoDescripción
dataobligatorioobject
idstring
receivedAtstring (date-time)

Errores: 400 401 403 404 409 429

Alcance requests:create. Con teléfono o correo; límite por teléfono (429).

Parámetros

NombreDóndeTipoObligatorioDescripción
Idempotency-KeycabecerastringNoCon la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
kindobligatoriostringValores: contact, callback, urgent, waitlist, arco, job
namestring
phonestring
emailstring
messagestringmaxLength 4000
preferencesobject
attributionobject

Respuesta 201

CampoTipoDescripción
dataobligatorioobject
idstring
statusstringValores: new, contacted, closed

Errores: 400 401 403 429

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

NombreDóndeTipoObligatorioDescripción
Idempotency-KeycabecerastringNoCon la misma clave devuelve lo ya creado (sin token).minLength 8 · maxLength 100

Cuerpoobligatorio

CampoTipoDescripción
kindobligatoriostringValores: reclamo, queja
replyChannelstringPor dónde quiere la respuesta: email exige el correo; letter, el domicilio.Valores: email, letterdefault "email"
consumerobligatorioobject
nameobligatoriostring
documentobject
typestring
numberstring
addressstring
phonestring
emailstring
guardianstringPadre, madre o apoderado si es menor.
serviceobject
descriptionstring
amountnumber
currencystring
detailobligatoriostringmaxLength 4000
requeststringmaxLength 2000

Respuesta 201

CampoTipoDescripción
dataobligatorioobject
codestringexample "LR-000015"
dueAtstring (date-time)
createdAtstring (date-time)

Errores: 400 401 403 429

Webhooks

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.

Eventos

  • order.createdAviso order.created
  • order.updatedAviso order.updated
  • catalog.updatedAviso catalog.updated
  • promo.updatedAviso promo.updated
  • appointment.createdAviso appointment.created
  • appointment.updatedAviso appointment.updated
  • appointment.confirmedAviso appointment.confirmed
  • appointment.cancelledAviso appointment.cancelled
  • appointment.rescheduledAviso appointment.rescheduled
  • appointment.completedAviso appointment.completed
  • appointment.no_showAviso appointment.no_show
  • message.createdAviso message.created

Cabeceras

NombreDóndeTipoObligatorioDescripción
X-Xen-EventcabecerastringSí
X-Xen-DeliverycabecerastringSí
X-Xen-SignaturecabecerastringSí

Cuerpo del aviso

CampoTipoDescripción
idstringId de la entrega (también en 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 } 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.

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

Errores y límites

Todo error responde con el mismo objeto, con un tipo estable para tu código y un mensaje para leer.

EstadoSignificado
400La petición no es válida (cuerpo, parámetros, cupón o líneas que no se pueden vender).
401Falta la clave, no es válida o venció.
403Origen no permitido, clave secreta en el navegador, alcance insuficiente o módulo apagado.
404No existe en la tienda o la empresa de la clave (en Clínica, también un código o token que no calza).
429Se pasó el límite por minuto de la clave (Retry-After: 60).

Forma del error

CampoTipoDescripción
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
messagestring

Tipos de error

  • 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

Límite por minuto

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