Adicionar agendamentos assíncronos

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

As reservas assíncronas são confirmadas ou recusadas posteriormente pelo comerciante.

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 horários de disponibilidade síncronos e assíncronos.

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

Critérios de reserva assíncrona

  • Não é possível modificar um agendamento assíncrono na Central de ações.
  • Os comerciantes precisam aceitar ou recusar a reserva pelo sistema on-line do parceiro (por exemplo, o painel de hospedagem do restaurante). Não é permitido ligar para o comerciante em nome do usuário para saber se ele aceita ou recusa uma reserva.
  • Não é possível propor um novo horário de reserva ao comerciante. A solicitação de agendamento 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 a documentação de integração completa de horários.

Como ativar o agendamento assíncrono

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

  • Modo de confirmação: todas as representações de horários disponíveis agora contêm um campo confirmation_mode que descreve como as reservas desse horário são confirmadas. Especifique o confirmation_mode de cada horário disponível para:

    • 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, o confirmation_mode é especificado no nível de disponibilidade.
  • Status da reserva: todas as representações de reservas têm um campo status que representa o estado da reserva. Foram introduzidos 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 agendamento: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íncrona
Figura 1:fluxo de reserva assíncrona
  1. Os feeds de disponibilidade foram atualizados para que o modo de confirmação de cada horário disponível seja especificado. É importante ter essas informações no feed para que possamos explicar a natureza assíncrona da reserva para o usuário no início do fluxo.
  2. Quando BatchAvailabilityLookup ou CheckAvailability é chamado, transmitimos o modo de confirmação e, idealmente, o mesmo modo de confirmação a ser retornado. Isso garante que o usuário receba a mensagem adequada.
  3. Quando CreateBooking é chamado, transmitimos o modo de confirmação para indicar o modo de confirmação previsto. 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, o status da reserva é atualizado pelo método bookings.patch da API Booking Notification em tempo real. Se você quiser recusar automaticamente reservas que não forem respondidas em tempo hábil, use o mesmo método de atualização em tempo real.

Feeds de disponibilidade

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

// 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, porque isso remove qualquer confusão relacionada a 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

Na BatchAvailabilityLookupResponse (BAL) ou CheckAvailabilityResponse (CA), retorne o mesmo confirmation_mode especificado no feed de disponibilidade e transmitido pelo 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 da 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;
}

No CreateBookingResponse, retorne o confirmation_mode atual para o slot agregado da reserva fornecido no CreateBookingRequest. Além disso, quando o agendamento for assíncrono, defina status como PENDING_MERCHANT_CONFIRMATION. Verifique se o confirmation_mode é o que o usuário e o Reservar com o Google esperam 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": "johnsmith@gmail.com",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "+1 800-123-4567",
      "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": "johnsmith@gmail.com",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "+1 800-123-4567",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "CONFIRMED"
  }
}

UpdateBooking

Na versão inicial do modo assíncrono, não há suporte para modificações do usuário em um agendamento. Em vez disso, o usuário precisa cancelar o agendamento e criar um novo.

Atualizações em tempo real

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

RTU de inventário (ReplaceServiceAvailability ou BatchReplaceServiceAvailability)

Usando o método availability.replace (lote) ou services.availability.replace, defina confirmation_mode como CONFIRMATION_MODE_ASYNCHRONOUS em 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 pelo método bookings.patch da API Booking Notification.

Ao atualizar o status, inclua o nome do campo status no 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"}

Em caso de falha na reserva, defina o status como FAILED e especifique o recurso booking_Failure. Se o status for definido como qualquer outra coisa, o booking_failure vai ser ignorado.

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.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED