Como ativar reservas assíncronas

Observação: fale com seu contato do Google se quiser ativar as reservas assíncronas. Além disso, reservas assíncronas são compatíveis apenas com integrações da API REST v3.

As reservas síncronas são aquelas confirmadas ou recusadas em tempo real.

As reservas assíncronas são definidas como reservas que o comerciante confirma ou recusa mais tarde.

Uma reserva é especificada como síncrona ou assíncrona no nível da disponibilidade. Isso também significa que, para um determinado comerciante e serviço, pode haver slots de disponibilidade síncronos e assíncronos.

Para determinar a implementação apropriada, primeiro identifique em qual categoria seu inventário se encaixa:

• Ativar somente reservas síncronas: todos os comerciantes e serviços são confirmados instantaneamente.
• Ativar reservas assíncronas: alguns ou todos os comerciantes e serviços exigem confirmação manual do comerciante.

Critérios de reserva assíncrona

• A modificação de um agendamento assíncrono no Reservar com o Google não é compatível.
• Reservas assíncronas que exigem pagamentos não são aceitas.
• Os comerciantes precisam ser capazes de aceitar ou recusar a reserva pelo sistema on-line do parceiro (por exemplo, o painel do host do restaurante). Chamar o comerciante em nome do usuário para determinar se ele aceita ou recusa uma reserva não é permitido.
• Não é possível propor um novo horário de reserva ao comerciante. A solicitação de reserva precisa ser aceita ou recusada no estado original.

Como ativar apenas reservas síncronas

A reserva síncrona é a implementação padrão. Para mais informações, consulte o guia de integração completo.

Como ativar a reserva assíncrona

Se alguns ou todos os comerciantes usarem um fluxo de agendamento assíncrono, as seguintes alterações precisarão ser feitas:

• Modo de confirmação: todas as representações de slots de disponibilidade agora contêm um campo confirmation_mode, que descreve como as reservas desse horário são confirmadas. Especifique os confirmation_mode de cada slot de disponibilidade para os seguintes:

  • No feed de disponibilidade, confirmation_mode é especificado no nível de disponibilidade.
  • Nos métodos da API Booking Server, confirmation_mode é especificado no nível do slot
  • Nos métodos da API Real-Time Updates, confirmation_mode é especificado no nível de disponibilidade
• Status da reserva: todas as representações de reservas contêm um campo status, que representa o estado delas. Foram adicionados três novos valores de status assíncronos: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT e FAILED. Use esses novos valores de status ao processar criações, recusas e falhas de reservas assíncronas.
• Atualizações de reserva: todas as atualizações assíncronas do status das reservas precisam ser informadas pelo método bookings.patch da API Booking Notification.

O diagrama abaixo mostra como o modo de confirmação e o status da reserva são usados em uma interação típica de reserva assíncrona.

Figura 1: Fluxo de reserva assíncrono

1. Os feeds de disponibilidade foram atualizados para que o modo de confirmação de cada slot de disponibilidade seja especificado. É importante ter essas informações no feed para que possamos explicar a natureza assíncrona da reserva ao usuário no início do fluxo.
2. Quando BatchAvailabilityLookup ou CheckAvailability é chamado, transmitimos o modo de confirmação e, de preferência, o mesmo modo de confirmação a ser retornado. Isso garante que o usuário veja a mensagem apropriada.
3. Quando CreateBooking é chamado, transmitimos o modo de confirmação para indicar o modo de confirmação antecipado. Quando a solicitação de reserva assíncrona é enviada, ela é retornada com o status PENDING_MERCHANT_CONFIRMATION.
4. Quando o comerciante aceita ou recusa uma solicitação de reserva, o status da reserva é atualizado por meio do método bookings.patch da API Booking Notification. Se você quiser recusar automaticamente as reservas que não são respondidas em tempo hábil, faça isso com o mesmo método de atualização em tempo real.

Feeds de disponibilidade

No feed de disponibilidade, especifique se cada slot é síncrono ou assíncrono. Para fazer isso, defina o novo campo confirmation_mode.

Observação:o confirmation_mode é armazenado na seção de disponibilidade dos feeds de disponibilidade e de atualizações em tempo real. No entanto, esse campo é armazenado no nível do slot para as APIs do servidor de reserva.

// Mode by which bookings for an availability slot are confirmed.
//
enum ConfirmationMode {
  // The confirmation mode was not specified.
  // Synchronous confirmation will be assumed.
  CONFIRMATION_MODE_UNSPECIFIED = 0;
  // Bookings for this availability will be confirmed synchronously.
  CONFIRMATION_MODE_SYNCHRONOUS = 1;
  // Bookings for this availability will be confirmed asynchronously.
  CONFIRMATION_MODE_ASYNCHRONOUS = 2;
}

Embora o modo de confirmação seja síncrono se nenhum modo for especificado, é altamente recomendável especificar um modo de forma explícita, já que isso remove qualquer confusão em relação às omissões acidentais.

Assíncrono

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    }
  ]
}

Síncrono

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    }
  ]
}

Síncrono e assíncrono

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    },
    {
      "merchant_id": "10002",
      "service_id": "1000",
      "spots_open": 4,
      "spots_total": 4,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 2
      },
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    }

  ]
}

Servidor de reserva

BatchAvailabilityLookup ou CheckAvailability

Em BatchAvailabilityLookupResponse (BAL) ou CheckAvailabilityResponse (CA), retorne o mesmo confirmation_mode conforme especificado no feed de disponibilidade e transmitido por meio de BatchAvailabilityLookupRequest ou CheckAvailabilityRequest.

BAL assíncrona

{
  "slot_time_availability": [
    {
      "slot_time": {
        "duration_sec": "3600",
        "resource_ids": {
          "party_size": 3
        },
        "service_id": "1000",
        "start_sec": "1546458300",
        "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
      },
      "available": true
    }
  ]
}

BAL síncrona

{
  "slot_time_availability": [
    {
      "slot_time": {
        "duration_sec": "3600",
        "resource_ids": {
          "party_size": 3
        },
        "service_id": "1000",
        "start_sec": "1546458300",
        "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
      },
      "available": true
    }
  ]
}

CA assíncrono

{
  "slot": {
    "duration_sec": "3600",
    "merchant_id": "317652",
    "resources": {
      "party_size": 3
    },
    "service_id": "1000",
    "start_sec": "1546458300",
    "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
  },
  "count_available": 1,
  "duration_requirement": "DO_NOT_SHOW_DURATION"
}

CA síncrono

{
  "slot": {
    "duration_sec": "3600",
    "merchant_id": "317652",
    "resources": {
      "party_size": 3
    },
    "service_id": "1000",
    "start_sec": "1546458300",
    "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
  },
  "count_available": 1,
  "duration_requirement": "DO_NOT_SHOW_DURATION"
}

CreateBooking

Retorne o status correto para a reserva usando as opções disponíveis abaixo:

// Status of a booking.
//
// Updating booking status does not change the status of the associated payment.
// Prepayment status updates should be done using the PrepaymentStatus enum.
enum BookingStatus {
  // Not specified.
  BOOKING_STATUS_UNSPECIFIED = 0;
  // Booking has been confirmed
  CONFIRMED = 1;
  // Booking is awaiting confirmation by the merchant before it can transition
  // into CONFIRMED status. Only applicable to non-payments Dining or
  // Beauty verticals.
  PENDING_MERCHANT_CONFIRMATION = 2;
  // Booking has been canceled on behalf of the user.
  // The merchant can still trigger a manual refund.
  CANCELED = 3;
  // User did not show for the appointment
  NO_SHOW = 4;
  // User did not show for the appointment in violation of the cancellation
  // policy.
  NO_SHOW_PENALIZED = 5;
  // Booking could not be completed by the async backend due to a failure.
  FAILED = 6;
  // Booking was asynchronously declined by the merchant. Only applicable to
  // non-payments Dining or Beauty verticals.
  DECLINED_BY_MERCHANT = 7;
}

Em CreateBookingResponse, retorne o confirmation_mode atual para o slot agregado da reserva fornecido em CreateBookingRequest. Além disso, quando a reserva for assíncrona, defina status como PENDING_MERCHANT_CONFIRMATION. Confira se o confirmation_mode é o que o usuário e o que o Reservar com o Google espera para não confundir o usuário.

Assíncrono

{
  "booking": {
    "slot": {
      "duration_sec": "3600",
      "merchant_id": "100001",
      "resources": {
        "party_size": 2
      },
      "service_id": "1000",
      "start_sec": "1546647234",
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    },
    "user_information": {
      "email": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "PENDING_MERCHANT_CONFIRMATION"
  }
}

Sincronização

{
  "booking": {
    "slot": {
      "duration_sec": "3600",
      "merchant_id": "100001",
      "resources": {
        "party_size": 2
      },
      "service_id": "1000",
      "start_sec": "1546647234",
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    },
    "user_information": {
      "email": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "CONFIRMED"
  }
}

UpdateBooking

Na versão inicial do assíncrono, as modificações do usuário em uma reserva existente não são compatíveis. Em vez disso, o usuário precisa cancelar a reserva e criar uma nova.

Atualizações em tempo real

Para atualizações em tempo real das disponibilidades, é preciso especificar confirmation_mode. Isso se aplica aos seguintes métodos:

RTU de inventário (ReplaceServiceAvailability ou BatchReplaceServiceAvailability)

Usando o método availability.replace (lote) ou método services.availability.replace, defina confirmation_mode como CONFIRMATION_MODE_ASYNCHRONOUS no Availability

Assíncrono

{
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {
          "startTime": "2014-10-02T15:30:00.00Z",
          "duration": "3600s",
          "spotsOpen": "0",
          "spotsTotal": "2",
          "availabilityTag": "1000001",
          "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
        }
      ]
    }
  ]
}

Síncrono

{
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {
          "startTime": "2014-10-02T15:30:00.00Z",
          "duration": "3600s",
          "spotsOpen": "0",
          "spotsTotal": "2",
          "availabilityTag": "1000001",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

Síncrono e assíncrono

{
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {
          "startTime": "2014-10-02T15:30:00.00Z",
          "duration": "3600s",
          "spotsOpen": "0",
          "spotsTotal": "2",
          "availabilityTag": "1000001",
          "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
        },
        {
          "startTime": "2014-10-03T11:00:00.00Z",
          "duration": "5400s",
          "spotsOpen": "1",
          "spotsTotal": "1",
          "availabilityTag": "1000002",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

API Booking Notification

As atualizações assíncronas de um status de reserva precisam ser feitas por meio do método bookings.patch da API Booking Notification.

Ao atualizar o status, inclua o nome do campo status em updateMask.

Status	Descrição
CONFIRMED	O comerciante confirmou a reserva.
FAILED	O parceiro não pôde confirmar ou recusar a reserva junto ao comerciante.
DECLINED_BY_MERCHANT	O comerciante recusou a reserva.

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"DECLINED_BY_MERCHANT"}

No caso de uma falha na reserva, defina o status da reserva como FAILED e especifique o bookings_crash. Se o status for definido como qualquer outra coisa, o booking_failure será ignorado.

Observação: os campos booking_failure são transmitidos como argumentos de consulta no URL.

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status&booking_failure.cause="SLOT_UNAVAILABLE"

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"FAILED"}

Notificações por e-mail

Para reservas assíncronas, há cinco possíveis e-mails relacionados ao status da reserva que são enviados aos usuários.

Observação:os e-mails de lembrete e feedback serão enviados além dos e-mails correspondentes aos seguintes status de reserva:

• PENDING_MERCHANT_CONFIRMATION
• CONFIRMED
• DECLINED_BY_MERCHANT
• FAILED
• CANCELED