Implementa el servidor de reservas: versión 2 de la API (heredada)

Nota: En esta página, se describe cómo implementar el servidor de reservas con la versión 2 de la API. Consulta Implementa el servidor de reservas para obtener instrucciones sobre cómo usar la versión más reciente.

Configurar un servidor de reservas de tu lado permitirá que el Centro de acciones cree citas, reservas o reservaciones contigo en nombre del usuario.

Implementa una interfaz de API basada en gRPC

Nota: Todos los socios nuevos deben usar la interfaz de la API de REST en lugar de la API de gRPC.

Implementa una interfaz de API basada en gRPC. Esto permite que Google envíe solicitudes de reserva. La superficie de la API se define con el IDL basado en protobuf de gRPC.

Les pedimos a nuestros socios nuevos que implementen un conjunto recomendado de la API v2. Los socios pueden seleccionar la URL y el puerto que mejor se adapten a su infraestructura.

En esta sección, se presenta un conjunto recomendado de la API v2. Se aplica a los socios que no implementaron la versión 0 de la API. Si eres uno de nuestros socios actuales que implementó la versión 0 de la API, comunícate con Actions Center para obtener más información.

Descarga la definición del servicio en formato .proto que se incluye a continuación para comenzar con la implementación de la API.

Descarga la definición del servicio

Recursos de la API

Familiarízate con los siguientes tipos de recursos que se utilizarán en esta implementación:

• Espacio: Es un espacio del inventario.
• Reserva: Cita para un espacio del inventario

Métodos

Los siguientes métodos de API deben implementarse en tu extremo para el servidor de gRPC:

• CheckAvailability
• CreateBooking
• UpdateBooking
• GetBookingStatus
• ListBookings

Estos 5 métodos definen el conjunto requerido de RPC de BookingService:

// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
  // Gets availability information for an appointment slot
  rpc CheckAvailability(CheckAvailabilityRequest)
      returns (CheckAvailabilityResponse) {}

  // Creates a booking
  rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}

  // Updates an existing booking
  rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}

  // Gets status for an existing booking
  rpc GetBookingStatus(GetBookingStatusRequest)
      returns (GetBookingStatusResponse) {}

  // Lists all upcoming bookings for a user
  rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}

Flujo: Cómo crear una reserva

Figura 1: Crea una reserva a partir de un espacio

Cuando se cree una reserva, Google enviará al socio el nombre, el apellido, el número de teléfono y el correo electrónico del usuario. Desde el punto de vista del socio, esto debe tratarse como una confirmación de la compra como invitado, ya que el Centro de acciones no tiene forma de buscar la cuenta del usuario en el sistema del socio. La reserva final debe mostrarse a los comercios del socio en su sistema, al igual que las reservas que provienen del sistema de reservas del socio.

Esqueleto de implementación en Java

Para comenzar, proporcionamos un servidor de gRPC esqueleto en Java que se puede compilar e instalar. Puedes consultarlo en la sección Samples > gRPC Reference Implementation. Este servidor tiene métodos de gRPC simulados que son necesarios para admitir la integración, incluidos el servicio de autenticación y el servicio de estado.

Requisitos

Error de gRPC y error de lógica empresarial

Cuando un backend del socio controla solicitudes de gRPC, pueden ocurrir dos tipos de errores: errores inesperados que surgen de datos incorrectos y errores de lógica empresarial que indican la imposibilidad de crear o actualizar una reserva (consulta Falla en la reserva), p.ej., si el espacio solicitado no está disponible.

Si se producen errores inesperados, se deben devolver al cliente con códigos de error canónicos de gRPC. Estos son algunos ejemplos:

• INVALID_ARGUMENT se usa en RPCs como CheckAvailability y CreateLease, y se debe devolver si la ranura proporcionada contiene información no válida.
• NOT_FOUND se usa en RPCs como CreateBooking y ListBookings, y se debe devolver si el socio desconoce el identificador proporcionado.

Consulta la referencia de cada método para ver sus códigos de error canónicos de gRPC o la lista completa de códigos de estado.

Por el contrario, los errores de lógica empresarial se deben capturar en Falla de reserva y se deben mostrar en la respuesta de RPC. Los errores de lógica empresarial pueden ocurrir cuando se crea o actualiza un recurso, es decir, cuando se controlan las RPC CreateBooking y UpdateBooking. Estos son algunos ejemplos:

• SLOT_UNAVAILABLE se usa si el espacio solicitado ya no está disponible.
• PAYMENT_ERROR_CARD_TYPE_REJECTED se usa si no se acepta el tipo de tarjeta de crédito proporcionado.

Idempotencia

La comunicación a través de la red no siempre es confiable, y es posible que Google Reserve reintente las RPC si no se recibe ninguna respuesta. Por este motivo, todas las RPCs que mutan el estado (CreateBooking, UpdateBooking) deben ser idempotentes. Los mensajes de solicitud para estas RPCs incluyen tokens de idempotencia para identificar de forma única la solicitud y permitir que el socio distinga entre una RPC reintentada (con la intención de crear una sola reserva) y dos reservas separadas.

Estos son algunos ejemplos:

• Una respuesta correcta de la RPC de CreateBooking incluye la reserva creada y, en algunos casos, el pago se procesa como parte del flujo de reserva. Si se recibe exactamente la misma solicitud CreateBookingRequest por segunda vez (incluido idempotency_token), se debe devolver la misma respuesta CreateBookingResponse. No se crea una segunda reserva y, si corresponde, se le cobra al usuario exactamente una vez. Ten en cuenta que, si falla un intento de CreateBooking, el backend del socio debería volver a intentarlo si se envía la misma solicitud.

El requisito de idempotencia se aplica a todos los métodos que contienen tokens de idempotencia.

Seguridad y autenticación del servidor de gRPC

Las llamadas del Centro de acciones a tu backend deben protegerse con SSL/TLS y autenticación mutua cliente/servidor basada en certificados. Esto requiere el uso de un certificado de servidor válido para tu implementación de gRPC y la aceptación de un certificado de cliente válido.

Certificado del servidor: El servidor del socio debe estar equipado con un certificado de servidor válido asociado al nombre de dominio del servidor (consulta esta lista de autoridades certificadas raíz aceptadas). Las implementaciones del servidor de gRPC esperan publicar una cadena de certificados que conduzca al certificado raíz. La forma más sencilla de lograrlo es agregar los certificados intermedios proporcionados por el host web del socio en formato PEM al certificado del servidor (también en formato PEM).

El certificado del servidor se verifica en el momento de la conexión, y no se aceptan certificados autofirmados. El contenido real del certificado no se verifica siempre que el certificado sea válido. Puedes verificar la validez de tu certificado con el siguiente comando:

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

Nota: Los certificados tienen una fecha de vencimiento. Es responsabilidad del socio asegurarse de que su certificado se actualice antes de que venza para evitar cualquier interrupción del servicio con el Centro de acciones.

Certificado de cliente: Para autenticarnos (como Google) ante el socio, proporcionamos un certificado de cliente emitido por la autoridad de Internet de Google G2 (certificado de AC) con las siguientes propiedades:

Campo	Valor
CN	mapsbooking.businesslink-3.net
SAN	DNS:mapsbooking.businesslink-3.net

El servidor del socio debe rechazar los intentos de conexión sin este certificado de cliente.

Para validar el certificado del cliente, el servidor se basa en un conjunto de certificados raíz de cliente de confianza. Puedes optar por obtener este conjunto de raíces de confianza de una autoridad como Mozilla o instalar el conjunto de raíces que actualmente recomienda la autoridad de Internet de Google G2. En ambos casos, es posible que, en ocasiones, debas actualizar manualmente los certificados raíz.

Implementa el protocolo de verificación de estado de gRPC

Implementa el protocolo de verificación de estado de gRPC. Este protocolo permite que Google supervise el estado del backend de tu implementación de gRPC. La especificación del servicio forma parte de la distribución de gRPC. Según la convención de nomenclatura de GRPC, el nombre del servicio en las llamadas de verificación de estado es ext.maps.booking.partner.v2.BookingService para la API v2 o ext.maps.booking.partner.v0.BookingService para la API v0. La verificación de estado debe ejecutarse en la misma URL y el mismo PUERTO que los demás extremos.

Nota: Consulta las implementaciones de referencia en Ruby.

Otras versiones

Para obtener documentación sobre otras versiones de la API, consulta las siguientes páginas: * API v3 * API v0