Adicionar agendamentos assíncronos

Observação:não estamos aceitando novos parceiros para agendamentos assíncronos. Além disso, as reservas assíncronas são compatíveis apenas com integrações da API REST v3.

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 um determinado comerciante e serviço pode ter horários disponíveis síncronos e assíncronos.

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

• 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.

Critérios de reserva assíncrona

• Não é possível modificar uma reserva assíncrona no Centro de ações.
• Os comerciantes precisam aceitar ou recusar a reserva no sistema on-line do parceiro (por exemplo, painel de gestão do restaurante). Não é permitido fazer uma chamada para o comerciante de modo a verificar se ele aceita ou recusa uma reserva.
• 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. Consulte a documentação de integração completa de reservas para mais informações.

Como ativar o agendamento assíncrono

Se alguns ou todos os comerciantes usarem um fluxo de reserva assíncrono, será necessário fazer as seguintes alterações:

• 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 um deles da seguinte forma:

  • No feed de disponibilidade, confirmation_mode é especificado no nível de disponibilidade.
  • Nos métodos da API Booking Server, o confirmation_mode é especificado no nível do horário.
  • 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. Três novos valores de status assíncronos foram introduzidos: 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 de reserva são usados em uma interação típica 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 incluir essas informações no feed, porque elas ajudam a explicar a natureza assíncrona da reserva para o usuário no início do fluxo.
2. Quando BatchAvailabilityLookup ou CheckAvailability é chamado, enviamos o modo de confirmação, e, em um cenário ideal, o mesmo modo é retornado. Isso garante que o usuário veja a mensagem apropriada.
3. Quando CreateBooking é chamado, enviamos o modo de confirmação para indicar o modo de confirmação esperado. Quando a solicitação de reserva assimétrica é enviada, a reserva é 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. Se você quiser recusar automaticamente as reservas que não forem respondidas em tempo hábil, utilize 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.

Observação:o confirmation_mode é armazenado na seção de disponibilidade dos Feeds de disponibilidade e das Atualizações em tempo real. No entanto, ele é salvo no nível do horário nas APIs Booking Server.

// 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 valor porque isso evita confusões causadas por omissões acidentais.

Assíncrona

{
  "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

No 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 horário agregado da reserva fornecido em CreateBookingRequest. Além disso, quando a reserva for assíncrona, defina status como PENDING_MERCHANT_CONFIRMATION. Verifique se o confirmation_mode mostra o status esperado pelo usuário e pelo Reservar com o Google para evitar mal-entendidos.

Assíncrona

{
  "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"
  }
}

Síncrono

{
  "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 modo assíncrono, os usuários não podem fazer modificações em uma reserva existente. 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, especifique confirmation_mode. Isso se aplica aos seguintes métodos:

RTU de inventário (ReplaceServiceAvailability ou BatchReplaceServiceAvailability)

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

Assíncrona

{
  "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

Para fazer atualizações assíncronas em um status de reserva, use o 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 a booking_failure. 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

No caso de reservas assíncronas, é possível enviar cinco e-mails relacionados ao status da reserva.

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

• PENDING_MERCHANT_CONFIRMATION
• CONFIRMED
• DECLINED_BY_MERCHANT
• FAILED
• CANCELED