API del agente de planes de datos

Motivación

Como se mencionó en la descripción general, según los casos prácticos que el operador desee admitir, la APD debe implementar una combinación de la API de uso compartido del plan de datos móviles de Google y la API del agente del plan de datos. En este documento, se describe la API del Agente de plan de datos que Google usará para identificar los planes de datos móviles del usuario, recuperar información sobre estos planes y adquirir planes de datos.

Autenticación

Antes de que GTAF pueda llamar, la APD debe autenticar a GTAF. Como parte del proceso de integración de operadores, verificaremos la validez del certificado SSL de DPA. Actualmente, REQUIERES el uso de OAuth2 para la autenticación mutua.

Descripción de la API

GTAF usa la clave del usuario, que identifica al suscriptor, cuando se consulta la APD del operador. Cuando GTAF consulta la APD en nombre de las aplicaciones que tienen acceso al MSISDN, GTAF PUEDE usar el MSISDN. En un nivel superior, la API del agente de planes de datos propuesta consta de los siguientes componentes:

  1. Mecanismo para consultar el estado del plan de datos del usuario.
  2. Mecanismo para consultar al DPA sobre las ofertas de planes de datos para el usuario.
  3. Mecanismo para realizar cambios en el plan de datos del usuario (p.ej., comprar un plan nuevo).
  4. Mecanismo a fin de verificar si un usuario es apto para comprar un plan de datos en particular.
  5. Mecanismo para que la GTAF registre los MSISDN con la APD.
  6. Mecanismo para que el GTAF verifique si el APD está en buen estado.

El resto de este documento explica cada uno de estos componentes de API. A menos que se indique explícitamente, todas las comunicaciones DEBEN realizarse por HTTPS (con un certificado SSL de DPA válido). Según las características reales que se admitan, un operador PUEDE implementar todos o algunos de estos componentes de API.

Consulta el estado del plan de datos

Interacción GTAF-DPA

Interacción GTAF-DPA

Figura 4: Flujo de llamadas para solicitar y recibir información del plan de datos del usuario

En la figura 4, se ilustra el flujo de llamadas asociado con un cliente que consulta el estado del plan de datos del usuario y otra información del plan de datos. Este flujo de llamadas se comparte para las llamadas a la API que activa el cliente en la UE.

  1. El cliente solicita el estado del plan de datos o demás información mediante una llamada a una API de Google privada. El cliente incluye la clave del usuario en la solicitud para GTAF.
  2. GTAF usa la clave del usuario y un identificador de cliente para consultar el APD del operador. Los identificadores de cliente admitidos son mobiledataplan y youtube. Cuando la APD recibe una llamada con uno de estos identificadores de cliente, DEBE responder con información del plan que el cliente pueda usar.
  3. GTAF muestra la información solicitada al cliente, y la GTAF almacena en caché la información del plan hasta la fecha de vencimiento que especifica el APD.

Los pasos 1 y 3 de la figura 4 son API privadas de Google y, por lo tanto, no se describen con más detalle. El paso 2 es una API pública que se describe a continuación. La APD DEBE respetar el encabezado HTTP Cache-Control: no-cache cuando entrega 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 la APD se identifica mediante CLIENT_ID. Según el acuerdo entre el cliente de Google y el proveedor, la APD puede personalizar la respuesta a 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 lenguaje en el que deberían estar las strings legibles (p.ej., las descripciones del plan).

Para los planes pospagos, expirationTime DEBE ser la fecha de recurrencia del plan (es decir, cuando se actualiza o se vuelve a cargar 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 equipos de Google individuales a fin de acordar el conjunto de categorías de tráfico y su semántica que son relevantes para las diferentes aplicaciones de Google.

Consulta ofertas del plan

GTAF emite la siguiente solicitud HTTP para obtener ofertas del plan 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 la APD se identifica mediante CLIENT_ID. Según el acuerdo entre el cliente de Google y el proveedor, la APD puede personalizar la respuesta a GTAF. El parámetro de contexto opcional proporciona el contexto de la aplicación en la que se realiza la solicitud. Por lo general, es una string que la aplicación le 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 arreglo offers PUEDE determinar el orden en el que los planes de datos se presentan a los usuarios. Además, si la aplicación puede presentar solo x planes debido a la IU o a otras limitaciones, y la respuesta contiene y > x planes, solo se presentarán los primeros x planes. El GTAF comparte solo hasta 10 planes si la aplicación que busca ofertas es la IU del plan de datos móviles, que forma parte de los Servicios de Google Play. De esta manera, se garantiza una buena experiencia del usuario para los Servicios de Google Play.

Las strings en offerInfo están diseñadas para permitir que el usuario lea más sobre la oferta y, además, incluyen una manera de inhabilitar la recepción de más ofertas de aplicaciones internas. El motivo de tener estos campos es que algunos operadores no necesitan el consentimiento del usuario final para permitir compras directas desde la aplicación, sino que requieren un mecanismo de inhabilitación. Ten en cuenta que el operador DEBE tener un mecanismo para cumplir con una solicitud de compra de cualquier oferta que se extienda al usuario. El mecanismo a través del cual se le cobrará al usuario por cualquier compra se puede comunicar con GTAF mediante la opción formOfPayment en la respuesta.

La solicitud DEBE incluir un encabezado Accept-Language que indique el lenguaje en el que deberían estar las strings legibles (p.ej., las descripciones del plan).

Compra de datos

La API del plan de compra define cómo la GTAF puede comprar planes a través de la APD. El GTAF inicia la transacción para comprar un plan de datos a la APD. La solicitud SHALL incluye 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 falla.

Solicitud de transacción

Una vez que recibe una solicitud de un cliente, el GTAF envía una solicitud POST a la APD. La URL de la solicitud es la siguiente:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

En el ejemplo anterior, 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

La APD mostrará los errores comunes en caso de error. Además, los siguientes códigos de error representan los resultados de transacciones fallidas:

  • La APD muestra un código de error 400 BAD REQUEST que le indica a GTAF que el ID del plan comprado no es válido.
  • La APD muestra un código de error 402 PAYMENT REQUIRED que indica a GTAF que el usuario no tiene saldo suficiente para completar la compra.
  • La APD muestra un código de error 409 CONFLICT que indica a GTAF que el plan que se comprará no es compatible 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 pospagos y prepagos, intentar comprar un plan prepagado para un usuario pospago generará un error 409 CONFLICT.
  • La APD muestra un código de error 403 FORBIDDEN que indica a GTAF que la transacción actual es un duplicado de una transacción emitida con anterioridad. El ADP debería mostrar los siguientes errores como respuesta:
    • Si la transacción anterior fue un error, la causa del error indica el motivo del error.
    • Si la transacción anterior se realizó correctamente, DUPLICATE_TRANSACTION.
    • Si la transacción anterior sigue en cola, REQUEST_QUEUED.

La APD generará una respuesta 200-OK solo para una transacción ejecutada con éxito o una transacción en cola. En el caso de una transacción en cola, el APD solo completará el estado de la transacción y dejará otros campos en la respuesta vacíos. La APD DEBE llamar a GTAF con una respuesta una vez que se haya manejado 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 planActivationTime, GTAF ASUMIRÁ que el plan se activó.

GTAF PUEDE emitir la siguiente solicitud para pasar la preferencia de consentimiento del usuario al proveedor.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

En el ejemplo anterior, userKey es CPID o MSISDN. El cuerpo de la solicitud es una instancia de SetConsentStatusRequest.

Si se ejecuta correctamente, el cuerpo de la respuesta debería estar vacío.

Elegibilidad

GTAF PUEDE emitir la siguiente solicitud de elegibilidad a fin de 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 comprar el plan en nombre del usuario (consulta Compra de datos). Si no se especifica planId, el APD DEBE mostrar todos los planes que pueda comprar ese usuario.

La APD mostrará los errores comunes en caso de error. Además, la APD mostrará un error en los siguientes casos:

  • La APD muestra un código de error 400 BAD REQUEST para indicarle al GTAF que planId no es válido.
  • La APD muestra un código de error 409 CONFLICT que indica que planId no es compatible con el plan de datos del usuario.

De lo contrario, la APD mostrará una respuesta 200-OK. El formato de una ElegibilidadResponse exitosa 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 puede comprar. En los casos en que planId esté vacío y el DPA no admita que se muestre la lista de planes aptos, DEBE mostrar un error 400 BAD REQUEST.

Extremo de registro de MSISDN

Para entregar aplicaciones que tienen acceso a MSISDN, GTAF registrará el MSISDN con el DPA. El GTAF solo registra el MSISDN cuando hay aplicaciones entregadas por la API de uso compartido de planes de datos móviles de Google, en las que la APD envía información a la GTAF mediante las API de Google. Para registrar el MSISDN, GTAF realizará una solicitud POST al APD:

POST DPA_URL/registro

El cuerpo de la solicitud será una instancia de RegistrationRequest.

{
  "msisdn": "<msisdn_string>"
}

Si el registro del MSISDN se ejecuta correctamente, el APD debe mostrar una respuesta 200 OK que incluya RegistrationResponse. El formato de JSON es el siguiente:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

La APD DEBE enviar actualizaciones sobre el plan de datos del usuario a GTAF hasta que pase el expirationTime.

Si se produce un error, se debería mostrar ErrorResponse:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

La lista completa de los posibles valores de causa y códigos de estado HTTP para diferentes condiciones de error está disponible aquí. En particular, si se recibe una solicitud de registro de MSISDN para un usuario que está en roaming o que no optó por compartir información del plan de datos con Google, el DEP debe mostrar el código de estado HTTP 403.

API de Monitoring

Algunos casos de uso requieren GTAF para supervisar la DPA y detectar fallas. Para esos casos de uso, definimos una API de supervisión.

Definición de API

La API de supervisión debe estar disponible a través de la solicitud GET de HTTP en la siguiente URL:

DPA_URL/dpaStatus

Si el DPA y todos sus backends funcionan de forma correcta, deben responder a esta consulta con un 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 alguno de sus backends no funcionan de forma correcta, debe responder con el código de estado HTTP 500 y un cuerpo de respuesta que tenga una instancia de DpaStatus.

Comportamiento de la APD

Cuando se detecta una falla, el DPA debe mostrar el estado "UNAVAILABLE" para todas las consultas dpaStatus. Además, debe dejar de enviar información del plan de datos con períodos de caché largos. Puede dejar de enviar respuestas con largos períodos de caché de una de las siguientes maneras:

  1. Comienza a establecer tiempos de caducidad cortos de la caché.
  2. Deje de enviar por completo la información del plan de datos.

Comportamiento de GTAF

GTAF sondeará dpaStatus periódicamente. Cuando detecta una falla de DPA (según la respuesta “UNAVAILABLE”), borrará 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 valores:

  • Actualmente, el usuario está en roaming y la búsqueda de APD está inhabilitada para este usuario. La APD muestra un error 403.
  • La APD muestra un código de error 404 NOT_FOUND que indica a GTAF que la clave del usuario no es válida (es decir, la clave del usuario no existente).
  • El DPA muestra un código de error 410 GONE que le indica a GTAF que el cliente debe obtener una clave de usuario nueva si key_type = CPID y el CPID venció.
  • La APD muestra un código de error 501 NOT_IMPLEMENTED que indica que no admite esta llamada.
  • El servicio no está disponible en este momento. La APD muestra un 503 SERVICE UNAVAILABLE, con el encabezado Retry-After que indica cuándo se puede intentar una nueva solicitud.
  • La APD muestra un código de error 500 INTERNAL SERVER ERROR para todos los demás errores no especificados.
  • La APD muestra un error 429 TOO_MANY_REQUESTS con el encabezado Retry-After que indica que GTAF realiza demasiadas solicitudes a la APD.
  • La APD muestra un error 409 CONFLICT que indica que la solicitud no se puede completar debido a un conflicto con el estado actual de la APD.

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 cause definidos actualmente se enumeran como parte de la referencia de la API ErrorCause.

De lo contrario, la APD muestra un 200 OK. Notamos que estos valores de cause se usan para todas las respuestas.

Internacionalización

Las solicitudes de GTAF a la APD incluyen un encabezado Accept-Language que indica el idioma en el que deberían estar las strings legibles (p.ej., las descripciones de los planes). Además, las respuestas de DPA (PlanStatus, PlanOffers) incluyen un campo de languageCode obligatorio cuyo valor es el código de idioma BCP-47 (p.ej., &en “EE.UU.” de la respuesta.

Si la APD no admite el idioma que solicitó el usuario, puede usar un idioma predeterminado y el campo languageCode para indicar su elección.