Cuotas

En este documento, se enumeran las cuotas que se aplican a la API de Merchant.

La API de Merchant usa cuotas para garantizar un entorno estable y justo para todos los usuarios. Las cuotas evitan que un solo usuario de la API genere una carga excesiva en el sistema, lo que garantiza un alto rendimiento. Comprender estas cuotas es clave para administrar tus datos de productos y expandir tu empresa en Google.

Conceptos generales

Las cuotas de la API de Merchant se administran a través de grupos de cuotas.

Los métodos de la API se asignan a grupos de cuotas. La estructura de este mapeo puede variar:

  • Un solo método por grupo: Algunos grupos de cuotas se aplican a un solo método de la API. Por ejemplo, el método de fuentes de datos de la ficha accounts.dataSources.list tiene su propio grupo de cuotas dedicado.
  • Varios métodos por grupo (agrupación): A menudo, los métodos relacionados se agrupan en un solo grupo de cuotas. Todos los métodos dentro de ese grupo comparten los mismos límites diarios y por minuto. Estos son algunos ejemplos comunes:
    • Agrupa todas las operaciones de lectura para los métodos y recursos relacionados, como merchant-accounts-read-methods.
    • Agrupa todas las operaciones de escritura para los métodos y recursos relacionados, como merchant-accounts-write-methods.

Cada llamada de método se cuenta una vez, independientemente de su tipo. Una solicitud list de 250 elementos se cuenta solo una vez, no como 250 solicitudes get.

El procesamiento por lotes de HTTP integrado no influye en la cuota. Cada solicitud individual dentro de un lote de solicitudes cuenta como una para la cuota. Por ejemplo, una solicitud por lotes que contiene 500 solicitudes del método insert se cobra como 500 solicitudes individuales del método insert.

Excepción para el procesamiento por lotes de regiones dedicadas: Los métodos especializados de procesamiento por lotes de regiones (batchCreate, batchUpdate, batchDelete) se consideran una sola llamada a la API en el grupo de cuotas de merchant_regions, independientemente de la cantidad de operaciones regionales que contenga la carga útil.

Para administrar tu integración de manera eficaz, debes revisar el grupo de cuotas específico asociado con cada método de la API que planeas usar. Puedes encontrar estos detalles en el método de lista de cuotas. Para obtener más información, consulta Supervisión y visibilidad.

Actualizar política

La API de Merchant aplica las siguientes políticas en términos de actualizaciones:

  • De forma predeterminada, puedes actualizar tus productos hasta dos veces al día. Debes distribuir las llamadas de manera uniforme a lo largo del día para cumplir con la cuota por minuto.
  • De forma predeterminada, solo puedes actualizar tus cuentas secundarias hasta dos veces al día. Tu cuota diaria de actualización de cuentas secundarias es un límite agregado basado en el total de cuentas secundarias permitidas.
  • De forma predeterminada, solo puedes llamar a los métodos de la fuente de datos para tus cuentas secundarias, como list o create, hasta dos veces por cuenta secundaria por día.

Cuotas de frecuencia

Cada grupo de cuotas tiene dos tipos de límites (y uso diario):

  • Límite diario (quotaLimit): Es la cantidad máxima de solicitudes permitidas por día. Los límites de cuota diarios se restablecen a las 12:00 p.m. (mediodía) UTC.
  • Límite por minuto (quotaMinuteLimit): Es la cantidad máxima de solicitudes permitidas por minuto, que controla la tasa de solicitudes. Los límites de cuota por minuto usan una ventana continua, en la que el período de aplicación comienza en el momento en que se realiza la primera llamada a la API para ese método y recurso. Por ejemplo, si realizas una llamada a las 10:01:30 a.m., el período de cuota por minuto para ese método se ejecutará hasta las 10:02:30 a.m..
  • Uso diario (quotaUsage): Es la cantidad de solicitudes que ya se realizaron y se contabilizaron en el límite diario del día actual. Si falta el campo, significa que aún no se consumió ninguna cuota para este grupo.

Puedes encontrar los tres campos descritos anteriormente (quotaLimit, quotaMinuteLimit y quotaUsage) en la respuesta del método quotas.list.

Los límites específicos diarios y por minuto varían significativamente entre los diferentes grupos de cuotas. Las operaciones con un volumen esperado más alto o un costo del sistema más bajo, como la lectura de datos de productos, suelen tener límites más altos. Por el contrario, las operaciones más intensivas o sensibles, como las modificaciones de la cuenta, pueden tener límites más bajos.

Asignación y jerarquía de cuotas

En esta sección, se explica en nombre de quién la API de Merchant hace un seguimiento del uso de la cuota y la aplica:

En general, la cuota se cobra según el usuario que realiza la solicitud a la API.

  • Cuentas independientes: En el caso de las cuentas independientes que autentican una llamada a la API, esa solicitud se descuenta de la cuota de la cuenta.
    • Ejemplo: Un comercio Zapatería A (ID de cuenta: 12345) se autentica con su propia cuenta de servicio para llamar a products.insert y segmentar su propia cuenta (accounts/12345). La cuota se consume del grupo de cuotas de Zapatería A.
  • Cuentas avanzadas: La autenticación como una cuenta avanzada consume cuota del grupo de la cuenta avanzada, incluso cuando se segmenta para una cuenta secundaria.
    • Ejemplo: Una agencia Cuenta de administración de comercio minorista (ID de cuenta avanzada: 12345) administra una subcuenta Tienda de ropa B (ID de cuenta: 11111). La agencia se autentica con sus propias credenciales y llama a la segmentación de products.insert Tienda de ropa B (accounts/11111). La cuota se consume del grupo de la agencia principal (ID de cuenta avanzada: 12345), no del grupo de la subcuenta.
  • Cuentas secundarias: Cuando las llamadas a la API se autentican con las credenciales de una cuenta secundaria, la cuota se cobra del grupo individual de esa cuenta secundaria. Funciona de la misma manera que una cuenta independiente, aunque la administre una cuenta avanzada parental.
    • Ejemplo: Con la misma configuración que antes, si Tienda de ropa B (ID de cuenta: 11111) se autentica con las credenciales configuradas específicamente para su cuenta secundaria para llamar a products.insert segmentado para su propia cuenta (accounts/11111), la cuota se consume del grupo de cuotas individuales de Tienda de ropa B, lo que deja intacto el grupo de la agencia principal.

Excepciones a las reglas generales

Existen algunas excepciones específicas que se aplican a las reglas generales de asignación de cuotas:

Jerarquía de asignación

  • Servicios de comparación de productos (CSS): Los CSS son sitios web que agregan ofertas de productos y dirigen a los usuarios a los sitios web de los minoristas para que realicen compras. Cuando se realizan llamadas a la API, las cuotas se aplican al grupo de CSS, al dominio de CSS, a la cuenta o a la cuenta secundaria específicos con los que te autenticas.

    Ejemplos:

    • Un grupo de CSS llamado Europe Shopping Group (ID de cuenta: 10001) desea mostrar sus dominios de CSS asociados. Cuando se autentica con sus propias credenciales para realizar esta llamada a la API, la cuota se consume directamente del grupo de cuotas de Europe Shopping Group.
    • Un dominio de CSS TopDeals CSS (ID de cuenta: 20002) se autentica para llamar a un método que segmenta una de sus cuentas de comercio asociadas (accounts/30003) para asignar una etiqueta. La cuota se consume del grupo de cuotas del CSS de TopDeals, no del grupo de la cuenta de comerciante.

  • Mercados: Los mercados son plataformas en línea que alojan a varios comercios individuales. Funcionan como cuentas avanzadas especiales que te permiten crear cuentas secundarias individuales para cada uno de tus vendedores.

En el siguiente diagrama, se muestra la jerarquía de los grupos de CSS, los CSS, los mercados, las cuentas avanzadas, las cuentas independientes y las subcuentas.

Un grupo de CSS es el nivel de autenticación general, con la posibilidad de tener CSS individuales dentro de él, cuentas dentro de esos CSS y subcuentas como el nivel más individual.

Ajuste automático de cuota

La API de Merchant tiene un sistema automático de administración de cuotas para servicios específicos, que ajusta los límites de cuotas para los comercios en crecimiento según tu uso, tu oferta y el tamaño de tu cuenta. La API de Merchant vuelve a calcular estas cuotas a diario.

Los grupos de cuotas incluidos en los ajustes automáticos de cuotas son los siguientes:

Servicios de productos

  • Son todos los grupos de cuotas de los métodos relacionados con los recursos products y productInputs.
  • Por lo general, la cuota de llamadas diarias se establece en 2 veces la cuota de ofertas que tiene el comercio. Esto supone que un comercio podría necesitar actualizar cada uno de sus productos hasta dos veces al día.
  • Los productos individuales se pueden actualizar más de dos veces, pero las llamadas a la API diarias generales no pueden exceder la cuota de llamadas diarias agregada.

Servicios de cuentas

  • Son todos los grupos de cuotas de los métodos relacionados con los diversos recursos detallados relacionados con la cuenta en la API de Merchant.
  • La cuota de llamadas diarias se establece en la cantidad máxima de cuentas secundarias permitidas para esa cuenta. Esto permite hasta dos llamadas de lectura por cuenta secundaria y por día.

Servicios de fuentes de datos

  • Todos los grupos de cuotas de métodos relacionados con los recursos relacionados con la fuente de datos en la API de Merchant, como list o create, que una cuenta avanzada realiza en sus cuentas secundarias.
  • Por lo general, la cuota de llamadas diarias se establece en 2 veces la cantidad de cuentas secundarias que tiene la cuenta avanzada. Esto supone que un comercio puede actualizar las fuentes de datos de cada una de sus cuentas secundarias hasta dos veces al día.

Solo los servicios descritos anteriormente tienen ajustes automáticos de las cuotas. Otros servicios tienen una cuota predeterminada, y cualquier aumento se debe solicitar de forma manual. Para obtener más información, consulta la sección sobre el proceso de aumento de la cuota.

Qué sucede cuando se superan las cuotas

Después de que se exceda una cuota, aparecerán errores en las respuestas de la API y en la página de diagnóstico de tu cuenta de Merchant Center:

  • Por minuto: quota/request_rate_too_high
{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}
  • Por día: quota/daily_limit_exceeded
{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

Los siguientes errores son límites de Merchant Center y no están relacionados con las cuotas de la API de Merchant. Puedes intentar solicitar una cuota adicional de artículos, feeds o cuentas secundarias:

  • too_many_items: Se excedió la cuota del comercio
  • too_many_subaccounts: Se alcanzó la cantidad máxima de cuentas secundarias

Supervisión y visibilidad

Para verificar las cuotas y el uso actuales de las llamadas de una cuenta, llama a quotas.list con el nombre de la cuenta.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Reemplaza lo siguiente:

  • ACCOUNT_ID: Tu ID de Merchant Center
  • ACCESS_TOKEN: Es el token de autorización para realizar la llamada a la API.

Cuando la solicitud se realiza correctamente, la API devuelve una lista de recursos quotaGroups que contienen el recurso name del grupo de cuotas, las diferentes cuotas y los métodos a los que se aplica la cuota del grupo.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

Proceso de aumento de cuota

Para solicitar una cuota adicional, abre el formulario de contacto con el equipo de asistencia, selecciona Solicitud de aumento de cuota en el campo obligatorio "¿Cuál es el problema o la pregunta?" y completa todos los campos obligatorios, incluidos tu ID de Merchant Center, los métodos de segmentación y la justificación comercial.

  • Para los recursos con cuotas automáticas (products, accounts y datasources para las cuentas avanzadas): Solo puedes solicitar un aumento temporal para situaciones especiales, como el lanzamiento en un mercado nuevo o durante las temporadas de compras con mucho tráfico. No aceptamos aumentos permanentes de cuota para estos tipos de recursos.
  • Para todos los demás recursos sin cuotas automáticas: Solicita aumentos de cuota según sea necesario.

Te recomendamos que revises tus cuotas periódicamente para asegurarte de tener suficiente cuota para tu implementación y ver cómo se ajusta automáticamente. Usa el método quotas.list para ver tu límite de cuota diario actual, el límite por minuto y el uso diario actual de cada grupo de métodos de la API.

Prácticas recomendadas

Implementar estas prácticas recomendadas te ayudará a garantizar que tu integración se ejecute sin problemas, evitar errores inesperados de cuota y utilizar los recursos de Merchant Center de manera eficiente.

Optimiza la distribución de solicitudes

  • Distribuye las solicitudes de manera uniforme: Evita enviar grandes ráfagas de solicitudes. Distribuye tus llamadas a la API diarias de manera uniforme a lo largo del día para no superar los límites de cuota por minuto (quotaMinuteLimit).
  • Limitación proactiva: Implementa la limitación de frecuencia del cliente (limitación) en tu aplicación. No dependas solo de los servidores de Google para rechazar el exceso de tráfico. Controla tu porcentaje de solicitudes en la fuente.

Manejo de errores ordenado

  • Controla el error HTTP 429: Tu aplicación debe estar preparada para controlar los errores 429 Too Many Requests (quota/request_rate_too_high).
  • Retirada exponencial con jitter: Cuando reintentes solicitudes fallidas (en especial, después de un error 429), usa la retirada exponencial (aumenta los tiempos de espera) y agrega "jitter" (retraso aleatorio). El jitter evita las "tormentas de reintentos", en las que varias instancias del cliente reintentan la solicitud exactamente al mismo tiempo, lo que vuelve a sobrecargar el servidor.
  • Respeta las sugerencias de reintento: Si la respuesta de la API contiene detalles o encabezados de reintento, úsalos para determinar cuándo reanudar las llamadas.

Minimiza las llamadas redundantes

  • Evita las llamadas obsoletas (404 NOT_FOUND): Evita solicitar o borrar recursos que ya no existen. Incluso las llamadas fallidas consumen cuota de la API. Supervisa los errores de NOT_FOUND en el Diagnóstico de la API de Merchant Center para detectar el seguimiento de estados obsoletos o las verificaciones innecesarias.
  • Verifica antes de actualizar: Antes de enviar una solicitud de actualización, verifica si los datos realmente cambiaron. Evita enviar actualizaciones que escriban los mismos valores.
  • Usa el almacenamiento en caché: Almacena en caché las respuestas de lectura (p.ej., detalles del producto, configuración) de forma local cuando sea apropiado para evitar llamadas repetitivas de get o list para datos sin cambios.
  • Cuentas avanzadas y subcuentas: Si tienes una cuenta avanzada, autentícate a nivel de la cuenta avanzada si quieres que las llamadas se contabilicen en el grupo compartido de cuentas avanzadas.
  • Usa listSubaccounts: En el caso de las cuentas avanzadas, usa accounts.listSubaccounts en lugar de accounts.list. La cuota de accounts.list se cobra al usuario que realiza la llamada (no al ID de MC) y no se ve en los diagnósticos estándar. listSubaccounts se incluye en tu cuota de la MCA.
Anterior
Overview
Siguiente
Merchant Center limits