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 usarlo con la versión más reciente.

Si configuras un servidor de reservas, el Centro de Acciones podrá crear citas, reservas o reservas 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 reservas. La plataforma de la API se define con el IDL basado en protobuf de gRPC.

Pedimos a nuestros socios nuevos que implementen un conjunto recomendado de la API v2. Los socios pueden seleccionar la URL y el puerto que funcionen mejor para su infraestructura.

En esta sección, se presenta un conjunto recomendado de la API v2. Se aplica a los socios que no implementaron la API v0. En el caso de nuestros socios actuales que implementaron la v0 de la API, comunícate con el Centro de Acciones para obtener más información.

Descarga la definición del servicio en formato .proto 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 usarán en esta implementación:

• Espacio: Es un espacio del inventario.
• Reserva: Es una cita para un espacio del inventario.

Métodos

Los siguientes métodos de API son obligatorios para implementarlos 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 crea una reserva, Google le envía al socio el nombre, el apellido, el número de teléfono y el correo electrónico del usuario. Esto se debe tratar como una confirmación de la compra como invitado desde el punto de vista del socio, ya que Actions Center no tiene forma de buscar la cuenta del usuario en el sistema del socio. La reserva final se debe mostrar a los comercios del socio en su sistema, al igual que las reservas que provienen del sistema de reservas del socio.

Implementación de esqueleto en Java

Para comenzar, proporcionamos un servidor gRPC de esqueleto en Java que se puede compilar y instalar. Consulta la sección Samples > gRPC Reference Implementation. Este servidor eliminó los métodos gRPC necesarios para admitir la integración, incluida la autenticación y el servicio de estado.

Requisitos

Error de gRPC y error de lógica empresarial

Pueden ocurrir dos tipos de errores cuando un backend de socio controla las solicitudes de gRPC: errores inesperados que surgen de datos incorrectos y errores de lógica empresarial que indican la incapacidad de crear o actualizar una reserva (consulta Error de reserva), p.ej., si el horario solicitado no está disponible.

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

• INVALID_ARGUMENT se usa en RPC como CheckAvailability y CreateLease, y se debe mostrar si el espacio proporcionado contiene información no válida.
• NOT_FOUND se usa en RPC como CreateBooking y ListBookings, y se debe mostrar si el socio desconoce el identificador proporcionado.

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

Por el contrario, los errores de lógica empresarial se deben capturar en Booking Failure y mostrarse en la respuesta de RPC. Pueden ocurrir errores de lógica empresarial cuando se crea o actualiza un recurso, es decir, cuando se controlan las RPC CreateBooking y UpdatingBooking. Estos son algunos ejemplos:

• SLOT_UNAVAILABLE se usa si el horario 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 Google Reserve puede reintentar las RPC si no se recibe ninguna respuesta. Por este motivo, todas las RPC que muten el estado (CreateBooking, UpdateBooking) deben ser idempotentes. Los mensajes de solicitud de estas RPC incluyen tokens de idempotencia para identificar de forma exclusiva la solicitud y permitir que el socio distinga entre una RPC reintentada (con la intención de crear una reserva única) y dos reservas separadas.

Estos son algunos ejemplos:

• Una respuesta correcta a la RPC 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 CreateBookingRequest por segunda vez (incluida idempotency_token), se debe mostrar la misma CreateBookingResponse. No se crea una segunda reserva y, si corresponde, se le cobra al usuario exactamente una vez. Ten en cuenta que, si un intento de CreateBooking falla, el backend del socio debería volver a intentarlo si se vuelve a enviar 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 estar protegidas con SSL/TLS con autenticación mutua de cliente y 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 con el nombre de dominio del servidor (consulta esta lista de AC raíz aceptadas). Las implementaciones de servidores de gRPC esperan entregar una cadena de certificados que lleve al certificado raíz. La forma más sencilla de hacerlo es adjuntar los certificados intermedios que proporciona 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 los certificados autofirmados. El contenido real del certificado no se verifica, siempre que 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 interrupciones del servicio en el Centro de Acciones.

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

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

El servidor de socios 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 confiables. Puedes obtener este conjunto de raíces de confianza de una autoridad como Mozilla o instalar el conjunto de raíces que recomienda actualmente la Google Internet Authority G2. En ambos casos, es posible que debas actualizar los certificados raíz de forma manual en ocasiones.

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. Siguiendo la convención de nombres 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 otros extremos.

Nota: Consulta las implementaciones de referencia en Ruby.

Otras versiones

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