Motivación
Como se mencionó en la descripción general, según los casos de uso que el operador desee admitir, el DPA debe implementar una combinación de la API de Google Mobile Data Plan Sharing y la API de Data Plan Agent. En este documento, se describe la API de Data Plan Agent que Google usará para identificar los planes de datos móviles del usuario, recuperar información sobre estos planes y comprar planes de datos.
Autenticación
Antes de que GTAF pueda llamar, el DPA debe autenticar GTAF. Como parte del proceso de incorporación del operador, verificaremos la validez del certificado SSL del DPA. Actualmente, EXIGIMOS el uso de OAuth2 para la autenticación mutua.
Descripción de la API
GTAF usa la clave del usuario, que identifica a un suscriptor del operador, cuando consulta la DPA del operador. Cuando GTAF consulta el DPA en nombre de las aplicaciones que tienen acceso al MSISDN, GTAF PUEDE usar el MSISDN. A grandes rasgos, la API del agente de planes de datos propuesta comprende los siguientes componentes:
- Es un mecanismo para consultar el estado del plan de datos del usuario.
- Mecanismo para consultar al DPA sobre las ofertas de planes de datos para el usuario.
- Mecanismo para realizar cambios en el plan de datos del usuario (p. ej., comprar un plan nuevo)
- Mecanismo para verificar si un usuario es apto para comprar un plan de datos en particular.
- Mecanismo para que el GTAF registre los MSISDN con la DPA.
- Es el mecanismo para que GTAF verifique si la DPA está en buen estado.
En el resto de este documento, se explica cada uno de estos componentes de la API. A menos que se indique explícitamente, todas las comunicaciones DEBEN realizarse a través de HTTPS (con un certificado SSL de DPA válido). Según las funciones reales que se admitan, un operador PUEDE optar por implementar todos los componentes de estas APIs o un subconjunto de ellos.
Consulta el estado del plan de datos
Interacción entre GTAF y DPA
Figura 4: Flujo de llamadas para solicitar y recibir información sobre el plan de datos del usuario.
En la figura 4, se ilustra el flujo de llamadas asociado con un cliente que consulta sobre el estado del plan de datos del usuario y otra información relacionada con el plan de datos. Este flujo de llamadas se comparte para las llamadas a la API que activa el cliente en el UE.
- El cliente solicita el estado del plan de datos o cualquier otra información llamando a una API privada de Google. El cliente incluye la clave de usuario en la solicitud a GTAF.
- La GTAF usa la clave del usuario y un identificador de cliente para consultar el DPA del operador. Los identificadores de cliente admitidos son mobiledataplan y youtube. Cuando el DPA recibe una llamada con uno de estos identificadores de cliente, DEBE responder con información del plan que el cliente pueda usar.
- GTAF devuelve la información solicitada al cliente, y GTAF almacena en caché la información del plan hasta la hora de vencimiento especificada por el DPA.
Los pasos 1 y 3 de la figura 4 son APIs privadas de Google y, por lo tanto, no se describen más. El paso 2 es una API pública que se describe a continuación. El DPA DEBE respetar el encabezado HTTP Cache-Control: no-cache cuando publique estas llamadas a la API desde GTAF.
Estado del plan
GTAF emite la siguiente solicitud HTTP para obtener el estado del plan:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
El cliente en nombre del cual GTAF se comunica con el DPA se identifica con CLIENT_ID. Según el acuerdo entre el cliente de Google y la empresa de transporte, el DPA puede personalizar la respuesta al GTAF. El formato de la respuesta es un objeto JSON que representa un PlanStatus.
{
"plans": [{
"planName": "ACME1",
"planId": "1",
"planCategory": "PREPAID",
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"planModules": [{
"moduleName": "Giga Plan", // req.
"trafficCategories": ["GENERIC"],
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"overUsagePolicy": "BLOCKED",
"maxRateKbps": "1500",
"description": "1GB for a month", // req.
"coarseBalanceLevel": "HIGH_QUOTA"
}]
}],
"languageCode": "en-US", // req.
"expireTime": "2018-06-14T08:41:27-07:00", // req.
"updateTime": "2018-06-07T07:41:22-07:00", // req.
"title": "Prepaid Plan"
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 256
}
}
}
}
La solicitud DEBE incluir un encabezado Accept-Language que indique el idioma en el que deben estar las cadenas legibles para el ser humano (p.ej., descripciones de planes).
En el caso de los planes pospagados, expirationTime DEBE ser la fecha de recurrencia del plan (es decir, cuando se actualiza o recarga el saldo de datos).
Cada módulo del plan puede contener varias categorías de tráfico del módulo del plan (PMTCs)para modelar el caso en el que un módulo del plan se comparte entre varias apps, p.ej., 500 MB para juegos y música Los siguientes PMTC están predefinidos: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Se espera que los operadores se comuniquen con los equipos individuales de Google para acordar el conjunto de categorías de tráfico y su semántica que son relevantes para las diferentes aplicaciones de Google.
Consulta de ofertas de planes
GTAF emite la siguiente solicitud HTTP para obtener ofertas de planes del operador:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
El cliente en nombre del cual GTAF se comunica con el DPA se identifica con CLIENT_ID. Según el acuerdo entre el cliente de Google y la empresa de transporte, el DPA puede personalizar la respuesta al GTAF. El parámetro de contexto opcional proporciona el contexto de la aplicación en el que se realiza la solicitud. Por lo general, es una cadena que la aplicación pasa al operador a través de GTAF.
El cuerpo de la respuesta contiene una instancia de PlanOffer.
{
"offers": [
{
"planName": "ACME Red", // req.
"planId": "turbulent1", // req.
"planDescription": "Unlimited Videos for 30 days.", // req.
"promoMessage": "Binge watch videos.",
"languageCode": "en_US", // req.
"overusagePolicy": "BLOCKED",
"cost": { // req.
"currencyCode": "INR",
"units": "300",
"nanos": 0
},
"duration": "2592000s",
"offerContext": "YouTube",
"trafficCategories": ["VIDEO"],
"quotaBytes": "9223372036850"
}
],
"expireTime": "2019-03-04T00:06:07Z" // req.
}
El orden de los planes de datos en el array offers PUEDE determinar el orden en el que se presentan los planes de datos a los usuarios. Además, si la aplicación solo puede presentar x planes debido a limitaciones de la IU o de otro tipo, y la respuesta contiene y > x planes, SOLO se presentarán los primeros x planes. GTAF comparte hasta 10 planes solo si la aplicación que consulta las ofertas es la IU del plan de datos móviles, que forma parte de los Servicios de Google Play. Esto es para garantizar una buena experiencia del usuario para los usuarios de los Servicios de Google Play.
Las cadenas de offerInfo tienen como objetivo permitir que el usuario lea más sobre la oferta y también incluyen una forma de inhabilitar la recepción de más ofertas desde las aplicaciones. El motivo por el que se incluyen estos campos es que algunos operadores no necesitan el consentimiento del usuario final para permitir las compras directas desde la app, sino que requieren un mecanismo para que los usuarios puedan inhabilitarlas. Ten en cuenta que el operador DEBE tener un mecanismo para completar una solicitud de compra de cualquier oferta que se extienda al usuario. El mecanismo a través del cual se le cobrará al usuario cualquier compra se puede comunicar con GTAF usando la opción formOfPayment en la respuesta.
La solicitud DEBE incluir un encabezado Accept-Language que indique el idioma en el que deben estar las cadenas legibles para el ser humano (p.ej., descripciones de planes).
Compra de datos
La API de planes de compra define cómo GTAF puede comprar planes a través del DPA. El GTAF inicia la transacción para comprar un plan de datos a la DPA. La solicitud DEBE incluir un identificador de transacción único (transactionId) para hacer un seguimiento de las solicitudes y evitar la ejecución de transacciones duplicadas. La APD DEBE responder con una respuesta de éxito o error.
Solicitud de transacción
Una vez que recibe una solicitud de un cliente, GTAF emite una solicitud POST a la DPA. La URL de la solicitud es la siguiente:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
donde userKey es CPID o MSISDN. El cuerpo de la solicitud es una instancia de TransactionRequest que incluye los siguientes campos:
{
"planId": string, // Id of plan to be purchased. Copied from
// offers.planId field returned from a
// Upsell Offer request,
// if available. (req.).
"transactionId": string, // Unique request identifier (req.)
"offerContext": string, // Copied from from the
// offers.offerContext, if available.
// (opt.)
"callbackUrl": string // URL that the DPA can call back with response once
// it has handled the request.
}
Respuesta de la transacción
En caso de error, la DPA DEBE devolver las causas de error comunes. Además, los siguientes códigos de error representan resultados de transacciones fallidas:
- El DPA devuelve un código de error 400 BAD REQUEST que indica al GTAF que el ID del plan comprado no es válido.
- El DPA devuelve un código de error 402 PAYMENT REQUIRED que indica al GTAF que el usuario no tiene saldo suficiente para completar la compra.
- El DPA devuelve un código de error 409 CONFLICT, que indica al GTAF que el plan que se comprará es incompatible con la combinación de productos actual del usuario. Por ejemplo, si la política del plan de datos del operador no permite combinar planes pospagados y prepagados, intentar comprar un plan prepagado para un usuario pospagado generará un error 409 CONFLICT.
- El DPA devuelve un código de error 403 FORBIDDEN que indica a GTAF que la transacción actual es un duplicado de una transacción emitida anteriormente. El DPA DEBE devolver las siguientes causas de error en la respuesta:
- Si la transacción anterior falló, causa del error que indica el motivo de la falla.
- Si la transacción anterior se realizó correctamente, se devuelve DUPLICATE_TRANSACTION.
- Si la transacción anterior aún está en la cola, se devuelve REQUEST_QUEUED.
El DPA DEBE generar una respuesta 200-OK solo para una transacción ejecutada correctamente o una transacción en cola. En el caso de una transacción en cola, el DPA solo debe completar el estado de la transacción y dejar vacíos los demás campos de la respuesta. El DPA DEBE llamar al GTAF con una respuesta una vez que se haya procesado una transacción en cola. El cuerpo de la respuesta es una instancia de TransactionResponse que incluye los siguientes detalles:
{
"transactionStatus": "SUCCESS",
"purchase": {
"planId": string, // copied from request. (req.)
"transactionId": string, // copied from request. (req.)
"transactionMessage": string, // status message. (opt.)
"confirmationCode": string, // DPA-generated confirmation code
// for successful transaction. (opt.)
"planActivationTime" : string, // Time when plan will be activated,
// in timestamp format. (opt.)
},
// walletInfo is populated with the balance left in the user's account.
"walletBalance": {
"currencyCode": string, // 3-letter currency code defined in ISO 4217.
"units": string, // Whole units of the currency amount.
"nanos": number // Number of nano units of the amount.
}
}
Si falta el parámetro planActivationTime, GTAF DEBE suponer que el plan se activó.
Consentimiento
Es posible que GTAF emita la siguiente solicitud para pasar la preferencia de consentimiento del usuario al operador.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
donde userKey es CPID o MSISDN. El cuerpo de la solicitud es una instancia de SetConsentStatusRequest.
Si se ejecuta correctamente, el cuerpo de la respuesta debe estar vacío.
Requisitos
Es posible que GTAF emita la siguiente solicitud de elegibilidad para verificar si un usuario es apto para comprar un plan.
GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}
Ten en cuenta que planId es el identificador único del plan que se puede usar para comprarlo en nombre del usuario (consulta Compra de datos).
Si no se especifica planId, el DPA DEBE devolver todos los planes que puede comprar ese usuario.
En caso de error, la DPA DEBE devolver las causas de error comunes. Además, la DPA DEBE devolver un error en los siguientes casos:
- El DPA devuelve un código de error 400 BAD REQUEST que indica al GTAF que
planIdno es válido. - La DPA devuelve un código de error 409 CONFLICT que indica que
planIdes incompatible con el plan de datos del usuario.
De lo contrario, la DPA DEBE devolver una respuesta 200-OK. El formato de una EligibilityResponse correcta es el siguiente:
{
"eligiblePlans":
[
{
"planId": string, // Plan identifier. Can be used to
// refer to the plan during
// offers, etc. (req.)
}
]
}
Cuando la solicitud incluye un planId, la respuesta solo incluye ese plan. De lo contrario, la lista incluye todos los planes que el usuario es apto para comprar. En el caso de que planId esté vacío y el DPA no admita la devolución de la lista de planes aptos, DEBE devolver un error 400 BAD REQUEST.
Extremo de registro del MSISDN
Para publicar aplicaciones que tienen acceso al MSISDN, GTAF registrará el MSISDN en la DPA. GTAF registra el MSISDN solo cuando hay aplicaciones que se publican a través de la API de Google Mobile Data Plan Sharing, en la que el DPA envía información a GTAF a través de las APIs de Google. Para registrar el MSISDN, GTAF realizará una solicitud POST al DPA:
POST DPA_URL/register
El cuerpo de la solicitud será una instancia de RegistrationRequest.
{
"msisdn": "<msisdn_string>"
}
Si el registro del MSISDN se realiza correctamente, la DPA DEBE devolver una respuesta 200 OK que incluya RegistrationResponse. El formato del objeto JSON es el siguiente:
{
// msisdn that was registered.
"msisdn": "<msisdn_string>",
// time after which DPA will not send updates to GTAF.
"expirationTime": string
}
Luego, el DPA DEBE enviar actualizaciones sobre el plan de datos del usuario al GTAF hasta que haya pasado expirationTime.
Si se produce un error, se debe devolver un ErrorResponse:
{
"error": "<error message>",
"cause": enum(ErrorCause)
}
La lista completa de los posibles valores de causa y los códigos de estado HTTP para las diferentes condiciones de error está disponible aquí. En particular, si se recibe una solicitud de registro de MSISDN para un usuario que está en itinerancia o que no aceptó compartir la información del plan de datos con Google, el DPA DEBE devolver el código de estado HTTP 403.
API de Monitoring
Algunos casos de uso requieren que GTAF supervise la DPA y detecte sus fallas. Para esos casos de uso, definimos una API de supervisión.
Definición de la API
La API de Monitoring debe estar disponible a través de una solicitud HTTP GET en la siguiente URL:
DPA_URL/dpaStatus
Si la DPA y todos sus backends funcionan correctamente, la DPA debe responder a esta consulta con el código de estado HTTP 200 y un cuerpo de respuesta que tenga una instancia de DpaStatus.
{
"status": enum(DpaStatusEnum),
"message": "<optional human-readable status description>"
}
Si el DPA o cualquiera de sus backends no funcionan correctamente, debe responder con el código de estado HTTP 500 y un cuerpo de respuesta que tenga una instancia de DpaStatus.
Comportamiento de la DPA
Cuando se detecta una falla, el DPA debe devolver el estado "UNAVAILABLE" para todas las consultas de dpaStatus. Además, debe dejar de enviar información sobre planes de datos con períodos de caché largos. Es posible que deje de enviar respuestas con períodos de almacenamiento en caché largos de una de las siguientes dos maneras:
- Comienza a establecer tiempos de vencimiento cortos para la caché.
- Dejar de enviar información sobre planes de datos por completo
Comportamiento de GTAF
GTAF consultará dpaStatus periódicamente. Cuando detecta una falla de DPA (según la respuesta "UNAVAILABLE"), borra su caché para el operador.
Casos de error
En caso de error, se espera que el DPA muestre un código de estado HTTP correspondiente a uno de los siguientes:
- Actualmente, el usuario está en roaming y la consulta de DPA está inhabilitada para este usuario. La DPA devuelve un error 403.
- El DPA devuelve un código de error 404 NOT_FOUND que indica al GTAF que la clave del usuario no es válida (es decir, no existe la clave del usuario).
- El DPA devuelve un código de error 410 GONE que indica a GTAF que el cliente debe obtener una nueva clave de usuario si key_type = CPID y el CPID venció.
- El DPA devuelve un código de error 501 NOT_IMPLEMENTED que indica que no admite esta llamada.
- El servicio no está disponible en este momento. El DPA devuelve un error 503 SERVICE UNAVAILABLE con el encabezado Retry-After que indica cuándo se puede intentar una nueva solicitud.
- El DPA devuelve un código de error 500 INTERNAL SERVER ERROR para todos los demás errores no especificados.
- El DPA devuelve un error 429 TOO_MANY_REQUESTS con el encabezado Retry-After que indica que GTAF está realizando demasiadas solicitudes al DPA.
- El DPA devuelve un error 409 CONFLICT que indica que no se puede completar la solicitud debido a un conflicto con el estado actual del DPA.
En todos los casos de error, el cuerpo de la respuesta HTTP DEBE incluir un objeto JSON con más información sobre el error. El cuerpo de la respuesta de error DEBE contener una instancia de ErrorResponse.
{
"error": string,
"cause": enum(ErrorCause)
}
Los valores de cause definidos actualmente se enumeran como parte de la referencia de la API de ErrorCause.
De lo contrario, la DPA devuelve un 200 OK. Observamos que estos valores de cause se usan para todas las respuestas.
Internacionalización
Las solicitudes de GTAF a la DPA incluyen un encabezado Accept-Language que indica el idioma en el que deben estar las cadenas legibles por humanos (p.ej., las descripciones de los planes). Además, las respuestas de la DPA (PlanStatus, PlanOffers) incluyen un campo languageCode obligatorio cuyo valor es el código de idioma BCP-47 (p.ej., "en-US") de la respuesta.
Si la DPA no admite el idioma que solicitó el usuario, puede usar un idioma predeterminado y el campo languageCode para indicar su elección.