REST Resource: inventory.partners.merchants.services.availability

Recurso: disponibilidade

Um horário disponível no serviço do comerciante, indicando o horário e o número de vagas.

Representação JSON
{
  "startTime": string,
  "duration": string,
  "spotsTotal": string,
  "spotsOpen": string,
  "availabilityTag": string,
  "resources": {
    object (Resources)
  },
  "paymentOptionId": [
    string
  ],
  "recurrence": {
    object (Recurrence)
  },
  "scheduleException": [
    {
      object (ScheduleException)
    }
  ],
  "deposit": {
    object (Deposit)
  },
  "noShowFee": {
    object (NoShowFee)
  },
  "requireCreditCard": enum (RequireCreditCard),
  "ticketTypeId": [
    string
  ],
  "durationRequirement": enum (DurationRequirement),
  "schedulingRuleOverrides": {
    object (SchedulingRuleOverrides)
  },
  "confirmationMode": enum (ConfirmationMode)
}
Campos
startTime

string (Timestamp format)

Início do horário disponível.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

duration

string (Duration format)

Duração do horário disponível

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

spotsTotal

string (int64 format)

Número total de vagas e vagas em aberto desse horário disponível. Exemplos:

  • Aula de ioga com 10 vagas e 3 já reservadas: availability {spotsTotal: 10, spotsOpen: 7 ...}
  • Sessão de massagem rápida que já está totalmente reservada: availability {spotsTotal: 1, spotsOpen: 0 ...}

Observação: se você enviar solicitações usando o formato de compactação de disponibilidade definido abaixo, esses dois campos serão inferidos.

  • Uma recorrência envolve spotsTotal=1 e spotsOpen=1.
  • Uma ScheduleException indica que spotsTotal=1 e spotsOpen=0.
spotsOpen

string (int64 format)

Número de vagas abertas.

availabilityTag

string

Uma string opaca opcional para identificar esse horário disponível. Se definida, ela será incluída nas solicitações que reservam/atualizam/cancelam compromissos.

resources

object (Resources)

Recursos opcionais usados para diferenciar esse horário disponível de outros quando diferentes membros da equipe ou salas fazem parte do serviço.

Por exemplo, a mesma aula de ioga com dois professores:

availability { resources { staffId: "1" staffName: "Amy" }
               spotsTotal: 10 spotsOpen: 7 }
availability { resources { staffId: "2" staffName: "John" }
               spotsTotal: 5 spotsOpen: 2 }
paymentOptionId[]

string

Uma lista de códigos que fazem referência às opções de pagamento disponíveis para pagar pelo espaço. As opções de pagamento reais são definidas no nível do comerciante e também podem ser compartilhadas entre vários deles.

Esse campo modifica qualquer payment_option_ids especificado na mensagem de serviço. Da mesma forma, os payment_option_ids definidos aqui NÃO precisam estar presentes na mensagem de serviço, mas precisam ser adicionados no nível do comerciante.

recurrence

object (Recurrence)

As informações de recorrência da disponibilidade, representando mais de um horário de início. Uma recorrência deve conter compromissos por um dia útil.

scheduleException[]

object (ScheduleException)

Os horários em que esse serviço não pode ser programado. Para limitar o número de mensagens scheduleException, considere unir as exceções adjacentes.

deposit

object (Deposit)

Um depósito opcional para a disponibilidade da vaga. Substitui o depósito de serviço, se ele tiver sido especificado.

noShowFee

object (NoShowFee)

Taxa opcional de não comparecimento para essa disponibilidade. Substitui a taxa de não comparecimento do serviço, se ela tiver sido especificada.

requireCreditCard

enum (RequireCreditCard)

Indica se o usuário precisa informar um cartão de crédito para reservar esse horário. Se o valor não for definido, ele será herdado do nível de serviço, se estiver indicado lá. (Opcional)

ticketTypeId[]

string

Indica uma lista de tipos de ingresso compatíveis com esse espaço disponível. Se esse campo não for definido, todos os tipos de ingresso no serviço pai estarão disponíveis para o espaço. Os valores desse campo precisam ser definidos no serviço pai. Exemplos:

  • Serviço com quatro tipos de ingresso: TicketType {ticketTypeId: "adult_1" shortDescription: "Adult weekdays"} TicketType {ticketTypeId: "adult_2" shortDescription: "Adult weekends"} TicketType {ticketTypeId: "youth_1" shortDescription: "Youth weekdays"} TicketType {ticketTypeId: "youth_2" shortDescription: "Youth weekends"}

Para representar o inventário durante dias úteis: availability {ticketTypeId: "adult_1" ticketTypeId: "youth_1"...} Para representar o inventário durante feriados: availability {ticketTypeId: "adult_2" ticketTypeId: "youth_2"...}

  • Serviço com três tipos de ingresso: TicketType {ticketTypeId: "adult" shortDescription: "Adult"} TicketType {ticketTypeId: "youth" shortDescription: "Youth"} TicketType {ticketTypeId: "senior" shortDescription: "Senior"}

Para indicar que todos os três tipos de ingresso estão disponíveis para esse espaço, use availability {ticketTypeId: "adult" ticketTypeId: "youth" ticketTypeId: "senior" ...} ou "availability {...}" (não defina ticketTypeId nele).

(opcional)

durationRequirement

enum (DurationRequirement)

O requisito para mostrar a duração e/ou o horário de término dos slots. Este campo será ignorado se o horário não estiver disponível. Não é usado na indústria de Coisas legais para fazer. (opcional)

schedulingRuleOverrides

object (SchedulingRuleOverrides)

Regras de programação de disponibilidade. Se os campos forem preenchidos, eles substituirão as regras de programação correspondentes nas SchedulingRules no nível de serviço.

confirmationMode

enum (ConfirmationMode)

O modo de confirmação que será usado ao agendar essa disponibilidade. As tentativas de criar agendamentos para horários com o modo CONFIRMATION_MODE_SYNCHRONOUS precisam ser confirmadas ou negadas imediatamente. As tentativas de criar agendamentos para horários com o modo CONFIRMATION_MODE_ASYNCHRONOUS precisam ser confirmadas ou negadas imediatamente.

Recursos

Um recurso é usado para diferenciar os espaços disponíveis quando diferentes membros da equipe ou salas fazem parte do serviço. É possível usar vários espaços e intervalos para o mesmo serviço quando eles têm recursos diferentes.

Representação JSON
{
  "staffId": string,
  "staffName": string,
  "roomId": string,
  "roomName": string,
  "partySize": integer
}
Campos
staffId

string

Código opcional de um membro da equipe que presta o serviço. Esse campo identifica o membro da equipe em todos os comerciantes, serviços e registros de disponibilidade. Ele também precisa ser estável ao longo do tempo para permitir a correlação com agendamentos anteriores. Esse campo precisa estar presente se staffName também estiver.

staffName

string

Nome opcional de um membro da equipe que presta o serviço. Esse campo será exibido aos usuários que fizerem um agendamento e deve ser legível por humanos, em vez de um identificador opaco. Ele precisa estar presente se staffId também estiver.

roomId

string

Um código opcional para a sala onde o serviço está localizado. Esse campo identifica a sala em todos os comerciantes, serviços e registros de disponibilidade. Ele também precisa ser estável ao longo do tempo para permitir a correlação com agendamentos anteriores. O campo precisa estar presente se roomName também estiver.

roomName

string

Um nome opcional para a sala onde o serviço está localizado. Esse campo será exibido aos usuários que fizerem um agendamento e deve ser legível por humanos, em vez de um identificador opaco. (opcional, mas obrigatório se o roomId estiver presente) No restaurante, o nome de uma sala só deve ser usado em áreas de estar, como bar ou pátio, e não para cardápios com preço fixo, atividades especiais ou qualquer outro valor que não seja do quarto, como reserva ou jantar. É altamente recomendável que não haja uma sala associada à área de estar padrão.

partySize

integer

Aplicável somente para refeições: a quantidade de pessoas que podem ser acomodadas durante esse período. Um restaurante pode estar associado a vários espaços ao mesmo tempo, cada um especificando um partySize diferente, se, por exemplo, duas, três ou quatro pessoas puderem fazer uma reserva.

Recorrência

As mensagens de recorrência são opcionais, mas permitem uma representação mais compacta dos espaços disponíveis repetidos consistentemente. Em geral, elas representam a programação de trabalho de um dia. As mensagens de ScheduleException são usadas para representar períodos reservados/indisponíveis no dia de trabalho.

Requisitos:

  1. A expansão de espaços disponíveis ou recorrências NÃO pode criar espaços idênticos. Se os códigos, o startTime, a duração e os recursos corresponderem, os espaços serão considerados iguais.
  2. NÃO misture o formato de disponibilidade padrão e a recorrência nos espaços de um único serviço. A recorrência beneficia comerciantes/serviços que oferecem compromissos. O formato padrão é voltado para comerciantes/serviços com aulas programadas regularmente.
  3. As recorrências não devem durar mais de 24 horas.
Representação JSON
{
  "repeatUntil": string,
  "repeatEvery": string
}
Campos
repeatUntil

string (Timestamp format)

O carimbo de data/hora inclusivo máximo (UTC) em que a disponibilidade se repete.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

repeatEvery

string (Duration format)

Define o tempo entre os horários disponíveis consecutivos.

Exemplo: uma disponibilidade com duração de 20 min, repeatEvery igual a 30 min, startTime igual a 9h e repeatUntil igual a 11h resultará em um período com horários entre 9-9h20, 9h30-9h50, 10-10h20, 10h30-10h50, 11-11h20. (obrigatório)

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

ScheduleException

As mensagens de ScheduleException representam períodos reservados/indisponíveis no dia de trabalho, que são exceções à recorrência descrita acima. Como os horários são reservados, a lista de exceções deve ser atualizada para mostrar os períodos indisponíveis. A recorrência não pode ser modificada.

Representação JSON
{
  "timeRange": {
    object (TimeRange)
  }
}
Campos
timeRange

object (TimeRange)

Período da exceção. Os espaços descritos pela recorrência que se sobrepõem a esse período fechado serão considerados indisponíveis.

Exemplo: se a recorrência especificar uma duração de 20 min com repeatEvery igual a 30 min, startTime igual a 9h e repeatUntil igual a 11h, uma ScheduleException com timeRange de 9h45-11h fará com os horários entre 9h30-9h50, 10-10h20 e 10h30-10h50 fiquem indisponíveis.

Como esse é o período em que a empresa está fechada, o espaço que começa às 11h não seria afetado.

DurationRequirement

Esse enum indica os requisitos para o usuário confirmar ou visualizar a duração/horário de término dos slots solicitados.

Enums
DURATION_REQUIREMENT_UNSPECIFIED O processamento do horário de término não é especificado. Esse é o padrão.
DO_NOT_SHOW_DURATION O horário de término não é mostrado ao usuário.
MUST_SHOW_DURATION O horário de término precisa ser mostrado ao usuário antes que o agendamento possa ser feito.

SchedulingRuleOverrides

Regras de agendamento no nível de disponibilidade.

Representação JSON
{
  "lastBookableSec": string,
  "firstBookableSec": string,
  "lastOnlineCancellableSec": string
}
Campos
lastBookableSec

string (int64 format)

O último horário (em segundos) em que esse espaço pode ser reservado. Esse carimbo de data/hora precisa ser anterior ao startSec do horário em questão. Se você quiser oferecer a possibilidade de reservar após o horário de início, use o nível de serviço SchedulingRules.min_booking_before_end_time. Ao usá-lo, ele substituirá o que estiver especificado no min_booking_buffer do SchedulingRules correspondente do serviço.

firstBookableSec

string (int64 format)

O primeiro horário (em segundos) em que esse espaço pode ser reservado. Esse carimbo de data/hora precisa ser anterior ao startSec do horário ou o lastBookableSec, se especificado.

lastOnlineCancellableSec

string (int64 format)

Se definido, indica a última vez (em segundos, desde a época do Unix) em que esse horário específico pode ser cancelado pelo Reservar com o Google. Esse campo substitui todas as regras de cancelamento do nível de serviço. (opcional)

ConfirmationMode

Os modos de confirmação usados ao agendar disponibilidades.

Enumerações
CONFIRMATION_MODE_UNSPECIFIED O modo de confirmação não foi especificado. A confirmação síncrona será presumida.
CONFIRMATION_MODE_SYNCHRONOUS Os agendamentos para essa disponibilidade serão confirmados de forma síncrona.
CONFIRMATION_MODE_ASYNCHRONOUS Os agendamentos para essa disponibilidade serão confirmados de forma assíncrona.

Métodos

replace

Substitui e retorna a Availability de um Service existente de um comerciante gerenciado pelo agregador especificado.