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 Cómo implementar el servidor de reservas si necesitas instrucciones para usar con la versión más reciente.

Configurar un servidor de reservas por tu parte permitirá que el Centro de acciones cree citas / reservas / 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 le permite a Google enviar 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 API v2. Los socios pueden seleccionar la URL y el PORT que funcionen mejor para su infraestructura.

En esta sección, se presenta un conjunto recomendado de API v2. Se aplica a los socios que no han implementado la versión 0 de la API. Si deseas obtener más información sobre nuestros socios actuales que implementaron la versión 0 de la API, comunícate con el Centro de acciones.

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: cita para un espacio del inventario

Métodos

Es obligatorio que se implementen los siguientes métodos de la API en tu extremo para el servidor 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 desde un horario disponible

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 debe tratarse como una confirmación de la compra como invitado desde el punto de vista del socio, 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 se realizan en el sistema de reservas del socio.

Implementación de esqueleto en Java

Para comenzar, proporcionamos un servidor de gRPC en Java que se puede compilar e instalar. Puedes consultarlo en la sección Muestras > Implementación de referencia de gRPC. Este servidor usó stubs de los métodos de gRPC necesarios para admitir la integración, incluidos el servicio de autenticación y de estado.

Requisitos

Error de gRPC y error de lógica empresarial

Pueden producirse dos tipos de errores cuando el backend de un socio controla las solicitudes de gRPC: 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 horario solicitado no está disponible.

Si se detectan errores inesperados, se deben mostrar al cliente con los códigos de error canónicos de gRPC. Los ejemplos incluyen, entre otros, los siguientes:

• INVALID_{8/} se usa en RPC, como CheckAvailability y CreateLease, y debe mostrarse si el espacio proporcionado contiene información no válida.
• NOT_FOUND se usa en RPC, como CreateBooking y ListBooking, y se debe mostrar si el socio desconoce el identificador proporcionado.

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

Por el contrario, los errores de lógica empresarial deben capturarse en un error de reserva y mostrarse en la respuesta de RPC. Pueden encontrar errores de lógica empresarial cuando se crea o actualiza un recurso, es decir, cuando se controlan las RPC CreateBooking y UpdatesBooking. Los ejemplos incluyen, entre otros, los siguientes:

• Se usa SLOT_UNAVAILABLE si la ranura solicitada ya no está disponible.
• PAYMENT_ERROR_CARD_TYPE_REJECTED se utiliza 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 Reserva puede reintentar las RPC si no se recibe ninguna respuesta. Por este motivo, todas las RPC que mutan el estado (CreateBooking, UpdateBooking) deben ser idempotentes. Los mensajes de solicitud para estas RPC incluyen tokens de idempotencia a fin de identificar de forma única la solicitud y permitir que el socio distinga entre una RPC que se reintentó (con la intención de crear una sola reserva) y dos reservas separadas.

Los ejemplos incluyen, entre otros, los siguientes:

• 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 CreateBookingRequest por segunda vez (incluido idempotency_token), entonces se debe mostrar la misma CreateBookingResponse. No se crea una segunda reserva y se le cobra al usuario exactamente una vez, si corresponde. Ten en cuenta que, si falla un intento de CreateBooking, el backend del socio debe 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 protegerse con SSL/TLS y con una autenticación mutua de cliente y servidor basada en certificados. Esto requiere el uso de un certificado de servidor válido para la 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 del servidor GRPC esperan entregar una cadena de certificados que conduce al certificado raíz. La forma más fácil de lograr esto es anexar 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 certificados autofirmados. No se verifica el contenido real del certificado, siempre y cuando 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 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 Google Internet Authority G2 (certificado de CA) 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 de cliente, el servidor se basa en un conjunto de certificados raíz de cliente de confianza. Puedes 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 G2 de Google. En ambos casos, es posible que, a veces, 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 GRPC. Este protocolo permite que Google supervise el estado del backend de tu implementación de gRPC. La especificación de servicio es parte de la distribución de GRPC. De acuerdo con 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 PORT que los otros extremos.

Nota: Consulta las implementaciones de referencia en Ruby.

Otras versiones

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