Paginación
Los endpoints de lista devuelven hasta 25 elementos por página, del más reciente al más antiguo. Envíelimit para pedir entre 1 y 100 elementos. GET /services, GET /staff, GET /rules y GET /agents devuelven todo en una sola página, en su propio orden.
status, starts_after, starts_before y contact_id en GET /appointments, se combinan entre sí y con la paginación. Para obtener la página siguiente, envíe la misma solicitud, filtros incluidos, con cursor igual a next_cursor. En la última página, next_cursor es null y has_more es false. Trate el cursor como una cadena opaca; su formato puede cambiar.
GET /services, GET /staff, GET /availability y GET /webhooks devuelven todos los elementos en una sola página.
Filtre las listas
Algunos endpoints de lista aceptan filtros como parámetros de consulta. Los filtros se combinan entre sí y concursor.
Para listar las llamadas de ayer de un negocio en Toronto:
+ de un desfase como +01:00, es decir, %2B01:00.
Reintente con seguridad con Idempotency-Key
Un error de red puede dejarle sin saber si una solicitud funcionó. Envíe un encabezadoIdempotency-Key en las solicitudes que crean algo y reintente con la misma clave:
POST /contactsPOST /appointmentsPOST /knowledgePOST /servicesPOST /rulesPOST /billing/checkoutyPOST /billing/extra-numbers/checkoutPOST /widget-keysPOST /phone-numbers/claims,POST /phone-numbers/extra/claimsyPOST /phone-numbers/{phone_number_id}/replace, que lo exigenPOST /team/invitations, que lo exige
POST /webhooks ignora este encabezado para que LobbyStack nunca guarde una copia del secreto de firma. Si una creación falla por un error de red, consulte GET /webhooks antes de reintentar.
POST /contacts/passcodes y POST /contacts/passcodes/generate también lo ignoran, para que LobbyStack nunca guarde una copia de un PIN. Volver a enviar los mismos PIN a POST /contacts/passcodes solo los vuelve a establecer. Si POST /contacts/passcodes/generate falla por un error de red, busque los contactos cuyo passcode.set_at sea de esa solicitud y deles PIN nuevos con contact_ids.
POST /team/claim-link también lo ignora, para que LobbyStack nunca guarde una copia del enlace que entrega el negocio. Cada solicitud envía un enlace nuevo y revoca el anterior, así que después de un error de red, busque en GET /team una invitación pendiente con transfers_ownership antes de reintentar.
book_appointment, create_contact y add_knowledge cuentan como POST /appointments, POST /contacts y POST /knowledge.
- Un reintento con el mismo cuerpo vuelve a recibir la primera respuesta, con el encabezado
Idempotent-Replayed: true. La API no crea una segunda cita. LobbyStack compara los valores JSON, así que el orden de las claves y los espacios no importan. - La misma clave con un cuerpo distinto devuelve
422con el códigoidempotency_key_reused. - Un reintento que llega mientras la primera solicitud sigue en curso espera a que termine y luego recibe su respuesta.
- LobbyStack guarda la clave y el cambio al mismo tiempo. Si la primera solicitud falló con un error, no se guardó nada, así que su reintento se ejecuta de nuevo.
Errores
Los errores siempre tienen la misma forma:details aparece en los errores de validación y en el 409 de POST /onboarding/complete, donde cada path nombra un paso pendiente. Base su lógica en code; la redacción de message puede cambiar.
Reservas a través de la API
La API sigue las mismas reglas que el agente con IA:POST /appointmentsyPOST /appointments/{appointment_id}/reschedulesolo funcionan cuando elbooking_modedel negocio esinstant. Consúltelo conGET /business.- La hora solicitada debe estar dentro del horario de atención, evitar los cierres y otras citas, y estar libre en un Google Calendar conectado. Cuando LobbyStack no puede confirmar que el calendario esté al día, considera la hora como ocupada.
- Un día puede tener varias franjas de atención, como de 09:00 a 12:00 y de 13:00 a 17:00. Envíe cada una como una entrada propia en
hours. Un negocio sin horario de atención no tiene horas disponibles para reservar. - Las nuevas reservas se sincronizan con el calendario conectado y ponen en cola los SMS habituales de confirmación y recordatorio. LobbyStack solo los envía a los contactos que aceptaron recibir SMS. En una instancia autoalojada, envíe
"sms_consent": truecuando el cliente haya aceptado al reservar. En LobbyStack Cloud, los SMS salen del número compartido de LobbyStack y solo el agente puede obtener ese consentimiento, durante una llamada, así quesms_consentno tiene efecto. - Si cambia el
phonede un contacto conPATCH /contacts/{contact_id}, LobbyStack retira su aceptación de recibir SMS, ya que la dio para el número anterior. Un contacto que se dio de baja sigue dado de baja. - Para reservar con una persona concreta, envíe
staff_id. Sin él, LobbyStack elige a un miembro del personal disponible que ofrezca el servicio. - La cancelación funciona en cualquier modo de reserva. Cancelar una cita que ya está cancelada la devuelve sin cambios. Cuando cancela una cita futura y el cliente aceptó recibir SMS, LobbyStack le envía un SMS para avisarle.
Personal
GET /staff lista a todas las personas que atienden citas, con active y los service_ids para los que se puede reservar a cada una. Un servicio sin personal asignado, en el panel o con staff_ids en POST /services y PATCH /services/{service_id}, está abierto a todos los miembros activos del personal.
Un negocio que nunca configuró su personal tiene igualmente un miembro activo del personal, con el nombre del negocio. Las reservas se asignan a esa persona, así que GET /staff la devuelve como a cualquier otro miembro del personal, y puede enviar su id como staff_id.
Envíe staff_id a:
GET /availability, para listar solo las horas en que esa persona está libre.POST /appointments, para reservar con esa persona.POST /appointments/{appointment_id}/reschedule, para pasar la cita a esa persona. Sin él, la cita conserva su miembro del personal.
staff_id que no sea un miembro activo del personal del negocio, o que no ofrezca el servicio, devuelve 400 con el código invalid_request. Pasar una cita a otro miembro del personal devuelve 409 conflict cuando cualquiera de las dos personas tiene su propio calendario conectado; en ese caso, cancele la cita y reserve una nueva.