REST API y alcance por inquilino

Vea cómo la REST API de Booknetic SaaS funciona por inquilino, usa claves API y conecta sistemas externos al inquilino correcto de forma segura.

Versión:

SaaS
- Regular
- SaaS

Categorías

Para qué sirve este REST API

Booknetic incluye un WordPress REST API para trabajar con datos Booknetic de sistemas externos.

En una instalación normal de Booknetic, REST API está disponible en este espacio de nombres:

/wp-json/booknetic/v1/

en Booknetic SaaS, el mismo Booknetic REST API es compatible con los inquilinos. Eso significa que la solicitud API de un inquilino funciona dentro del propio espacio de trabajo Booknetic de ese inquilino.

Úselo cuando un inquilino o su desarrollador quiera conectar Booknetic con sistemas como:

un tablero interno;
un CRM o base de datos de clientes;
una herramienta de presentación de informes;
una herramienta de conciliación de pagos;
una aplicación móvil o web personalizada que necesita datos de reserva de inquilinos.

La regla más importante es:

Autentíquese como el inquilino a cuyos datos desea acceder. La respuesta API tiene como alcance los datos de ese inquilino.

Para conocer la experiencia general de administración de inquilinos, consulte Referencia del panel de administración de inquilinos. Para conocer el límite de datos del inquilino, consulte Aislamiento de datos y límites de permisos.

Base URL

El espacio de nombres REST es:

/wp-json/booknetic/v1

Por lo tanto, una solicitud completa suele verse así:

https://your-domain.com/wp-json/booknetic/v1/appointments

En una configuración SaaS, utilice el inquilino URL que pertenece al inquilino que realiza la solicitud.

URL de inquilinos en modo directorio

Si su plataforma utiliza URL de inquilinos de estilo directorio, el inquilino slug aparece después de su dominio principal:

https://your-domain.com/tenant-slug/

Dependiendo de cómo esté configurado su enrutamiento SaaS, el REST URL con ámbito de inquilino se puede crear a partir de ese mismo contexto de inquilino URL, por ejemplo:

https://your-domain.com/tenant-slug/wp-json/booknetic/v1/appointments

URL de inquilinos en modo de subdominio

Si su plataforma utiliza URL de inquilino de estilo subdominio, el inquilino slug aparece antes de su dominio principal:

https://tenant-slug.your-domain.com/

Luego, REST URL usa ese subdominio de inquilino:

https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments

El modo de subdominio requiere DNS y soporte de hosting. Si no está seguro de qué estilo URL utiliza su plataforma, revise URL de inquilinos y enrutamiento antes de proporcionar a los desarrolladores las URL API.

Autenticación

Las solicitudes Booknetic REST utilizan la autenticación WordPress REST. Para integraciones de servidor a servidor, la opción práctica es Contraseña de aplicación WordPress/autenticación básica.

La solicitud envía un encabezado de autenticación básica HTTP utilizando el nombre de usuario WordPress del usuario inquilino y la contraseña de la aplicación de ese usuario:

Authorization: Basic base64(username:application-password)
Content-Type: application/json

con curl, puede escribirlo así:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments?skip=0&limit=20'

O, si su desarrollador quiere crear el encabezado manualmente:

curl -H 'Authorization: Basic <base64-tenant-username-and-application-password>' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments?skip=0&limit=20'

Seguridad: No utilice las credenciales de administrador WordPress del propietario de SaaS para las integraciones de inquilinos. Cree credenciales para el usuario inquilino propietario de la integración.

Cómo funciona el alcance por inquilino

En términos sencillos, una solicitud REST con ámbito de inquilino funciona así:

El desarrollador envía una solicitud al espacio de nombres estándar Booknetic REST:

/wp-json/booknetic/v1/...

La solicitud se autentica como un usuario WordPress conectado a un inquilino.
Booknetic resuelve ese contexto de inquilino.
Booknetic lee o escribe datos dentro del alcance de ese inquilino.
La respuesta contiene únicamente los datos de ese inquilino.

Por ejemplo, si Aurora Wellness Studio se autentica con su propio usuario inquilino y llama:

GET /wp-json/booknetic/v1/customers

La respuesta debe contener clientes de Aurora Wellness Studio, no clientes de otro inquilino.

Los permisos del plan y las capacidades del usuario aún se aplican. Si el plan de un inquilino no incluye un módulo, una llamada API para ese módulo puede fallar o no devolver datos utilizables incluso si las credenciales son válidas.

A qué pueden acceder los inquilinos a través del REST API

El espacio de nombres público REST es para datos del inquilino Booknetic y acciones seleccionadas del módulo Booknetic.

Los recursos comunes para los inquilinos incluyen:

Recurso	Punto final de ejemplo	Notas
Citas	`GET /appointments`	Enumere los datos de la cita para el ámbito del inquilino actual.
Detalle de la cita	`GET /appointments/{id}`	Devuelve la cita sólo si pertenece al ámbito autenticado y los permisos permiten el acceso.
Estado de la cita	`PUT /appointments/{id}/change-status`	Cambia el estado de la cita cuando el usuario tiene permiso.
Clientes	`GET /customers`, `POST /customers`, `PUT /customers/{id}`	Lista de clientes/creación/actualización para el alcance del inquilino actual.
Ubicaciones	`GET /locations`, `POST /locations`, `PUT /locations/{id}`	El acceso a la ubicación depende del plan y los permisos del inquilino.
Servicios	`GET /services`, `GET /services/categories`, `GET /services/extras`	Útil para listas seleccionadas y búsqueda de servicios.
Staff	`GET /staffs`	la ruta es `staffs`, no `staff`.
Pagos	`GET /payments/{appointmentId}`, `PUT /payments/{appointmentId}`	La información de pago está vinculada a una cita ID.
Panel de control	`GET /dashboard/stats`, `GET /dashboard/upcoming-appointments`, `GET /dashboard/graph`	Datos de estilo panel para el ámbito autenticado.
Notificaciones	`GET /notifications`, `POST /notifications/mark-as-read`	Puntos finales de notificación en la aplicación cuando estén disponibles.

Nota importante sobre la creación/actualización de citas

Algunas referencias públicas de API describen rutas de creación y actualización de citas. En la fuente Booknetic revisada para este lote de documentación de SaaS, POST /appointments y PUT /appointments/{id} existen rutas, pero el controlador revisado devuelve una respuesta vacía para esas acciones.

Por eso, no cree una integración de producción que dependa de la creación/actualización de citas a través de esas rutas a menos que el soporte de Booknetic o Ingeniería confirmen el cuerpo de la solicitud admitido y el comportamiento de tiempo de ejecución para su versión.

Para las integraciones de citas, las acciones documentadas más seguras son enumerar las citas, leer los detalles de las citas, eliminarlas cuando esté permitido y cambiar el estado cuando esté permitido.

Lo que no está disponible a través del público REST API

Booknetic SaaS también tiene pantallas del lado del propietario para administrar la plataforma. Esas pantallas no son las mismas que las del inquilino público REST API.

La fuente revisada no encontró un endpoint REST público /wp-json/booknetic/v1/ para operaciones de SaaS del lado del propietario, como:

enumerar todos los inquilinos;
crear o editar inquilinos;
eliminar inquilinos;
gestionar planes SaaS;
cambiar la configuración de SaaS;
gestionar campos personalizados a nivel de plataforma;
mutar el editor de workflow SaaS;
administrar las claves del inquilino API de forma centralizada desde la cuenta del propietario;
utilizando una clave de propietario para consultar los datos operativos de todos los inquilinos.

Esas pantallas del lado del propietario utilizan rutas de administración internas dentro del área de administración WordPress. No están documentados como puntos finales públicos REST API y no deben usarse como puntos finales de integración de cara al cliente.

Utilice el propietario de SaaS UI para operaciones del lado del propietario, como Tenants, Plans, Pagos, y SaaS Settings.

Ejemplo: conseguir citas para un inquilino

Esta solicitud enumera citas para el usuario inquilino representado por las credenciales:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments?skip=0&limit=20'

Ejemplo de forma de respuesta:

{
  "data": [],
  "meta": {
    "total": 0,
    "skip": 0,
    "limit": 20
  }
}

Un inquilino con citas recibirá objetos de cita en su interior. data.

Ejemplo: listar clientes

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/customers?skip=0&limit=50'

Ejemplo de forma de respuesta:

{
  "data": [],
  "meta": {
    "total": 0,
    "skip": 0,
    "limit": 50
  }
}

Ejemplo: crear un cliente

Utilice esto solo con las credenciales del inquilino que debería ser propietario del registro de cliente:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -X POST 'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/customers' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "QA",
    "last_name": "Customer",
    "email": "[email protected]",
    "phone": "+15555550199",
    "note": "Imported via API"
  }'

Una acción de creación/actualización de cliente exitosa devuelve una forma ID de cliente como por ejemplo:

{
  "customer_id": 123
}

Si la validación falla, Booknetic puede devolver un error de validación con detalles a nivel de campo.

Ejemplo: cambiar el estado de una cita

Cuando el usuario inquilino autenticado tiene permiso para cambiar el estado de la cita:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -X PUT 'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/appointments/123/change-status' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "approved",
    "run_workflows": 1
  }'

Utilice la cita ID que pertenece a ese inquilino. No utilice este punto final para probar la cita ID de otro inquilino.

Ejemplo: actualizar el estado de pago de una cita

Si una herramienta de conciliación externa necesita marcar el pago de una cita como pagado:

curl -u '[email protected]:xxxx xxxx xxxx xxxx xxxx xxxx' \
  -X PUT 'https://tenant-slug.your-domain.com/wp-json/booknetic/v1/payments/123' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "paid",
    "paid_amount": 50
  }'

Se espera que el estado de pago value sea uno de:

pending
paid
canceled
not_paid

el {appointmentId} en el URL está la cita ID conectada al pago.

Formas de respuesta y error.

Los puntos finales de lista suelen devolver:

{
  "data": [
    {}
  ],
  "meta": {
    "total": 42,
    "skip": 0,
    "limit": 20
  }
}

Los puntos finales de un solo elemento suelen devolver:

{
  "data": {}
}

Crear/actualizar puntos finales puede devolver un ID:

{
  "id": 123
}

o, para clientes:

{
  "customer_id": 123
}

Los errores de validación pueden incluir un 422 respuesta con detalles del campo:

{
  "code": "422",
  "message": "Validation failed",
  "data": {
    "status": 422,
    "errors": {
      "email": "Please enter a valid email"
    }
  }
}

Límites de tarifas

La fuente de Booknetic SaaS revisada para este lote de documentación no identificó una política pública de límite de tasa de REST específica de Booknetic.

Eso hace no Esto significa que las integraciones deberían enviar tráfico ilimitado. Las llamadas REST aún usan su sitio WordPress, recursos de alojamiento, base de datos, complementos de seguridad, capas de almacenamiento en caché y cualquier firewall o regla CDN que haya configurado.

Comportamiento de integración recomendado:

usar paginación con skip y limit en lugar de pedirlo todo repetidamente;
evitar círculos electorales estrechos;
almacenar en caché los resultados en su sistema externo cuando sea posible;
reintentar las solicitudes fallidas con un retroceso en lugar de repetirlas inmediatamente;
programe grandes trabajos de sincronización fuera de sus horas de mayor actividad;
monitorear los trabajadores del hosting CPU, PHP y la carga de la base de datos.

Si ejecuta una integración de gran volumen, pruébela en preparación o durante una ventana de poco tráfico antes de usarla en producción.

REST API frente a webhooks

REST API y los webhooks resuelven diferentes problemas.

necesidad	uso
Su sistema externo quiere leer o actualizar los datos del Booknetic a pedido	REST API
Booknetic o un proveedor de pagos debe notificar a su sitio cuando ocurre un evento	Webhook
Un desarrollador inquilino quiere incluir datos de citas en un panel	REST API
Stripe necesita informarle a Booknetic SaaS que se pagó una renovación de suscripción	Gancho web Stripe

Para eventos de facturación de Stripe SaaS, consulte Configuración del webhook Stripe para facturación SaaS.

Si está creando integraciones de reserva de inquilinos, no confunda los webhooks de facturación Stripe con las llamadas del inquilino Booknetic REST API. Los webhooks Stripe son para actualizaciones de facturación de suscripciones de SaaS. El Booknetic REST API es para datos de reserva de inquilinos.

Preguntas comunes

¿Puede mi inquilino darle acceso a su desarrollador API?

Sí, el inquilino puede otorgar a un desarrollador acceso API en el ámbito del inquilino mediante el uso de credenciales para ese usuario inquilino, generalmente a través de un flujo de autenticación básica/contraseña de aplicación WordPress.

Comparta credenciales únicamente con desarrolladores confiables. Trate las contraseñas de las aplicaciones como secretos y revoquelas cuando la integración ya no sea necesaria.

¿Puedo usar la clave API de un propietario para leer las citas y los clientes de cada inquilino?

No se encontró ninguna clave pública REST de inquilinos cruzados del lado del propietario en la fuente revisada.

Si necesita datos de varios inquilinos a través del REST API público, el modelo más seguro es llamar al punto final de cada inquilino con sus propias credenciales y mantener los datos separados en su sistema externo.

No intente eludir los límites del inquilino utilizando rutas de administración internas o acceso directo a la base de datos a menos que tenga un proceso interno controlado y revisado por seguridad. El acceso directo a la base de datos puede exponer datos privados de inquilinos/clientes y no debe tratarse como un método normal de integración de clientes.

¿Puede el propietario de SaaS gestionar inquilinos y planes a través de REST?

No a través de un punto final público REST que se encuentra en la fuente revisada.

Utilice el panel de administración del propietario de SaaS para la gestión de inquilinos, planes, configuraciones de SaaS, pagos de SaaS y workflow de la plataforma.

¿Hay un separado `booknetic-saas/v1` ¿Espacio de nombres REST?

Sin público separado booknetic-saas/v1 El espacio de nombres se encontró en la fuente revisada para este lote de documentación.

Utilice el espacio de nombres estándar Booknetic REST:

/wp-json/booknetic/v1/

¿Existe un SDK oficial?

No se identificó ningún Booknetic SaaS REST SDK oficial en el material fuente utilizado para esta página.

Los desarrolladores pueden llamar al REST API directamente con clientes estándar HTTP como curl, JavaScript fetch, Clientes PHP HTTP, Python requests, o cartero.

¿Cómo funciona el versionado de API?

El espacio de nombres actual incluye la versión en la ruta:

/wp-json/booknetic/v1/

Si Booknetic introduce una versión futura de REST, normalmente aparecerá como un nuevo espacio de nombres como v2. Mantenga las integraciones escritas en el espacio de nombres documentado para su versión Booknetic instalada.

¿Por qué un punto final devuelve errores de permiso para un inquilino pero no para otro?

Primero verifique estos elementos:

¿Es correcto el nombre de usuario/contraseña de la aplicación?
¿La contraseña de la aplicación sigue activa?
¿Ese usuario WordPress pertenece al inquilino que espera?
¿El plan del inquilino incluye el módulo al que llamas?
¿Tiene el usuario la capacidad necesaria para esa acción?
¿Está llamando al inquilino correcto URL?

Las capacidades del plan se aplican a las llamadas API. Si el inquilino no puede acceder a un módulo en el panel de inquilinos, la acción API relacionada también puede fallar.

Mejores prácticas para propietarios de SaaS

Antes de brindar orientación sobre API a los inquilinos:

confirme el estilo del inquilino URL que utiliza su plataforma;
crear credenciales separadas para cada integración de inquilinos;
nunca comparta las credenciales de administrador WordPress del propietario de SaaS;
habilitar solo los módulos y capacidades del plan que el inquilino debería usar;
documentar qué sistema externo posee cada contraseña de aplicación;
revocar las contraseñas de aplicaciones no utilizadas;
probar un no destructivo GET solicitud antes de enviar solicitudes de creación/actualización/eliminación;
Mantenga los datos de los inquilinos separados también en sistemas externos.

Lista de verificación de solución rápida de problemas

problema	Que comprobar
`401` no autorizado	Nombre de usuario, contraseña de la aplicación, contraseña revocada, encabezado de autenticación básica con formato incorrecto.
`403` o permiso denegado	Capacidad del plan de inquilino, capacidad del usuario, acceso al módulo.
vacio `data` matriz	Es posible que el inquilino aún no tenga registros, que los filtros sean demasiado limitados o que la solicitud esté dirigida a un inquilino diferente.
Se esperan datos de inquilino incorrectos	Verifique el inquilino URL y el usuario autenticado. No reutilice un usuario WordPress entre inquilinos a menos que se configure intencionalmente.
`404` punto final no encontrado	Confirma que la ruta está debajo `/wp-json/booknetic/v1/` y comprobar la ortografía de la ruta, por ejemplo `staffs` en lugar de `staff`.
Crear/actualizar no se comporta como se esperaba	Confirme que el punto final sea compatible con su versión Booknetic instalada antes de confiar en él.
Respuestas lentas	Reduzca el sondeo, pagina y verifique los recursos de alojamiento/servidor WordPress.