Estándares de protocolo

La API sigue un conjunto de estándares de API HTTP y admite la idempotencia para facilitar una integración más sólida.

URLs alojadas en Google

La documentación de cada método alojado en Google proporciona una URL base, que incluye el nombre del método y el número de versión principal. Se crea la URL completa agregando el ID de cuenta de integrador de pagos del emisor al final. Por ejemplo, la documentación para el método echo alojado en Google especifica la URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Si el ID de la cuenta de integrador de pagos del emisor es INTEGRATOR_1, deberá agregarlo al final de la URL que se va a enviar al formulario:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Nota: La página de documentación del extremo para el método específico que estás implementando tendrá la URL más precisa para tu caso.

URLs alojadas por el socio

La documentación de cada método de API alojado por el socio proporciona una URL base, que incluye el nombre del método y el número de versión principal. No debes incluir el ID de cuenta de integrador de pagos (PIAID) en las URLs que alojas.

Entornos de zona de pruebas y producción

Google aloja las APIs de pagos estándar tanto en la zona de pruebas (para fines de desarrollo y pruebas) como en la de producción. Las solicitudes en el entorno de la zona de pruebas de Google no generan ninguna responsabilidad financiera real. Los entornos de zona de pruebas y de producción son completamente separados y no comparten claves ni información de transacciones.

Google espera que tu zona de pruebas esté disponible constantemente, ya que la usaremos para probar primero los cambios y las funciones nuevas.

Ruta base de la zona de pruebas de Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Nota: Si tu integración ya se inició y llama al host https://billpaynotification.sandbox.googleapis.com, puedes continuar haciéndolo. Las integraciones nuevas deben llamar al host “vgw.sandbox.google.com”.

Ruta base de producción de Google

https://vgw.googleapis.com/secure-serving/gsp/

Nota: Si ya se inició la integración y llama al host https://billpaynotification.googleapis.com, puedes continuar haciéndolo. Las integraciones nuevas deben llamar al host “vgw.googleapis.com”.

En esta guía, se usarán los extremos de producción.

Tipo y codificación de contenido

Las cargas útiles de mensajes que usan encriptación PGP deben usar el tipo de contenido application/octet-stream; charset=utf-8. Los cuerpos de solicitud de PGP se deben enviar con la codificación base64url, como se define en rfc4648 §5. Las cargas útiles de mensajes que usan encriptación JWE deben usar el tipo de contenido application/jose; charset=utf-8. La opción Serialización compacta compatible con JWE/JWS controla la codificación para el cuerpo de la solicitud final.

Códigos de estado HTTP

Las APIs de pagos estándar están diseñadas para mostrar un código de estado HTTP 200 para todas las solicitudes que puede procesar el servidor. Esto incluye las solicitudes exitosas y las rechazadas desde la perspectiva de la lógica empresarial o de la aplicación. Las solicitudes que no se pueden procesar no deben generar un código de estado HTTP 200, ya que representan un error entre Google y el socio. En su lugar, la respuesta de la API debe usar los códigos de estado HTTP adecuados que se muestran a continuación con un objeto ErrorResponse opcional.

Errores de HTTP y motivos
400	BAD REQUEST El cliente especificó un argumento no válido. También se puede mostrar si se rechazó la operación porque el sistema no se encuentra en un estado necesario para la ejecución de la operación. Úsalo si los reintentos de la solicitud no se pueden completar hasta que el estado del sistema se corrija de forma explícita. Por ejemplo, si una solicitud de reembolso falla porque hace referencia a una captura que no existe, los reintentos no tendrán éxito hasta que la captura exista en el sistema de los integradores. Nota: No se debe usar BAD_REQUEST (400) en situaciones en las que haya un error de aplicación adecuado disponible. Por ejemplo, las monedas incorrectas deberían mostrar ACCOUNT_DOES_NOT_SUPPORT_CURRENCY con el código 200 si la respuesta estándar tiene ese campo o enum.
401	UNAUTHORIZED La solicitud no tiene credenciales de autenticación válidas para la operación. Por ejemplo, las firmas no válidas o las firmas desconocidas deben mostrar 401.
403	FORBIDDEN / PERMISSION DENIED El emisor de la llamada no tiene permiso para ejecutar la operación especificada.
404	NOT FOUND No se encontró alguna entidad solicitada, como un pago o el usuario.
409	CONFLICT / ABORTED La operación se anuló, por lo general, debido a un problema de simultaneidad, como fallas en la verificación del secuenciador, anulaciones de transacciones, etcétera.
412	PRECONDITION FAILED Este código debe usarse en situaciones en las que una clave de idempotencia se vuelve a usar con diferentes parámetros.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Se agotó un recurso del sistema.
499	CANCELLED La operación se canceló (por lo general, la cancela el emisor).
500	INTERNAL ERROR Errores internos. Esto significa que algunas variantes que espera el sistema subyacente están dañadas.
501	UNIMPLEMENTED La operación no se implementó, no se admite ni se habilitó en este servicio.
503	UNAVAILABLE El servicio no está disponible actualmente. Es probable que esta sea una condición transitoria y que se corrija si vuelves a intentarlo.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED El plazo venció antes de que la operación se pudiera completar. En el caso de las operaciones que cambian el estado del sistema, es posible que se muestre este error incluso si la operación se completó correctamente. Por ejemplo, una respuesta correcta de un servidor podría haberse retrasado lo suficiente como para que el plazo venciera.

Solicitar idempotencia

La idempotencia de solicitud es una estrategia central que se usa en las APIs de pagos estándar para garantizar que las interacciones del sistema entre Google y los socios sean sólidas y tolerantes a errores. Las solicitudes Idempotentes son aquellas que se pueden enviar varias veces, pero tienen el mismo efecto que una sola. Esta estrategia facilita la coherencia eventual entre los sistemas, ya que hace que los reintentos sean seguros, lo que permite que nuestros sistemas lleguen a un acuerdo sobre el estado del recurso.

Nuestra API aprovecha la idempotencia para lo siguiente:

• reducir los problemas de conciliación haciendo que todas las acciones sean fácilmente rastreables y auditables.
• Para evitar las condiciones de carrera, asegúrate de que múltiples solicitudes idénticas del mismo cliente no den como resultado un estado final diferente.
• minimizar el estado, ya que permite que las solicitudes se entiendan de forma aislada, lo que permite mejorar el rendimiento y la capacidad de procesamiento mediante la eliminación de la carga del servidor causada por la retención de datos.
• Evitar la necesidad de campos adicionales para indicar si una solicitud es un reintento

Nota: Los resultados de errores nunca se deben almacenar en caché ni mostrarse de forma idempotente. Además, los reintentos automatizados para errores deben usar una estrategia de retirada exponencial.

Ejemplos

Ejemplo 1: Se perdió la conectividad antes de recibir la respuesta

Situación:

1. Google envía una solicitud al integrador.
2. El servidor del integrador recibe esta solicitud y la procesa correctamente.
3. El servidor de Google se queda sin energía antes de recibir la respuesta del paso 2.
4. La energía del servidor de Google se restablece y la misma solicitud se envía con los mismos parámetros (mismo ID y detalles de la solicitud, pero actualizados requestTimestamp) al servidor del integrador.

Resultado:

En este caso, el servidor del integrador debe responder con la misma respuesta del paso 2, ya que todos los parámetros, excepto responseTimestamp, son iguales. El efecto secundario solo ocurre una vez, en el paso 2. El paso 4 no tiene efectos secundarios.

Ejemplo 2: Solicitud enviada a un servidor en mantenimiento

Situación:

1. La base de datos del servidor integrador está inactiva debido a tareas de mantenimiento.
2. Google envía una solicitud al integrador.
3. El integrador muestra correctamente el código de estado UNAVAILABLE.
4. El servidor de Google recibe la respuesta y programa un reintento.
5. La base de datos del servidor integrador vuelve a estar en línea.
6. Google vuelve a enviar la solicitud del paso 2 (el mismo ID y los mismos detalles de la solicitud, pero se actualizó requestTimestamp). Ten en cuenta que los ID de solicitud para ambas solicitudes deben ser iguales.
7. El servidor integrador recibe la solicitud y muestra un código de estado OK junto con la respuesta completa.

Resultado:

En este caso, el servidor del integrador debe procesar la solicitud del paso 7 y no mostrar HTTP 503 (UNAVAILABLE). En su lugar, el servidor del integrador debe procesar por completo la solicitud y mostrar OK con los mensajes adecuados. Ten en cuenta que, si bien el sistema es UNAVAILABLE, Google puede realizar solicitudes repetidas similares al paso 2. Cada solicitud debe dar como resultado un mensaje similar al del paso 3. Finalmente, se darán los pasos 6 y 7.

Ejemplo 3: El mensaje intentado no coincide con el mensaje inicial debido a un error de recuperación

Situación:

1. Google envía una solicitud al integrador.
2. El servidor del integrador recibe esta solicitud y la procesa correctamente.
3. El servidor de Google se queda sin energía antes de recibir la respuesta del paso 2.
4. Se restablece la energía del servidor de Google y, luego, intenta enviar la misma solicitud, pero, lamentablemente, algunos de los parámetros son diferentes.

Resultado:

En este caso, el servidor del integrador debe responder con un código de error HTTP 412 (PRECONDITION FAILED), que le indica a Google que hay un error en este sistema.