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 coloque 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 esta asignación 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 fichas 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. Algunos ejemplos comunes incluyen los siguientes:
    • Agrupar todas las operaciones de lectura para métodos y recursos relacionados, como merchant-accounts-read-methods.
    • Agrupar todas las operaciones de escritura para métodos y recursos relacionados, como merchant-accounts-write-methods.

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

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

Excepción para el procesamiento por lotes de regiones dedicadas: Los métodos de procesamiento por lotes de regiones especializadas (batchCreate, batchUpdate, batchDelete) cuentan como una sola llamada a la API en el grupo de cuotas merchant_regions, independientemente de la cantidad de operaciones de región 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 deseas usar. Puedes encontrar estos detalles en el método de la 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 por día. Debes distribuir las llamadas de manera uniforme durante el día para cumplir con la cuota por minuto.
  • De forma predeterminada, solo puedes actualizar tus cuentas secundarias hasta dos veces por 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 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. UTC.
  • Límite por minuto (quotaMinuteLimit): Es la cantidad máxima de solicitudes permitidas por minuto, lo que controla la frecuencia de las solicitudes. Los límites de cuota por minuto usan una ventana móvil, en la que el período de aplicación comienza desde 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., la ventana de cuota por minuto para ese método se ejecuta hasta las 10:02:30 a.m..
  • Uso diario (quotaUsage): Es la cantidad de solicitudes que ya se realizaron y se descontaron del límite diario para el 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 quotas.list método.

Los límites diarios y por minuto específicos 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 realiza un seguimiento del uso de la cuota y la aplica:

En general, la cuota se cobra en función del usuario que realiza la solicitud a la API.

  • Cuentas independientes: Para las cuentas independientes que autentican una llamada a la API, esa solicitud se descuenta de la cuota de esa cuenta.
    • Ejemplo: Un comerciante Shoe Store 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 Shoe Store A's.
  • Cuentas avanzadas: La autenticación como una cuenta avanzada consume cuota del grupo de la cuenta avanzada, incluso cuando se segmenta una cuenta secundaria.
    • Ejemplo: Una agencia Retail Management Account (ID de cuenta avanzada: 12345) administra una cuenta secundaria Clothing Store B (ID de cuenta: 11111). La agencia se autentica con sus propias credenciales y llama a products.insert segmentando Clothing Store B (accounts/11111). La cuota se consume del grupo de la agencia principal (ID de cuenta avanzada: 12345), no del grupo de la cuenta secundaria.
  • Cuentas secundarias: Cuando las llamadas a la API se autentican con las credenciales de una cuenta secundaria, la cuota se cobra al grupo individual de esa cuenta secundaria. Esto funciona de la misma manera que una cuenta independiente, aunque la administre una cuenta avanzada principal.
    • Ejemplo: Con la misma configuración que antes, si Clothing Store B (ID de cuenta: 11111) se autentica con credenciales configuradas específicamente para su cuenta secundaria para llamar a products.insert segmentando su propia cuenta (accounts/11111), la cuota se consume del grupo de cuotas individual de Clothing Store B y no se modifica 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:

  • Accounts.list: La cuota de este método se cobra al usuario o la cuenta de servicio autenticados que realizan la llamada, no al ID de la cuenta de Merchant Center. Su uso de cuota no será visible en la página de diagnóstico estándar de la API de Merchant Center. Si tienes una cuenta avanzada, te recomendamos que uses el accounts.listSubaccounts método, que se incluye en la cuota de tus cuentas avanzadas.
  • Métodos de resolución de problemas: Estos métodos siempre se descuentan de la cuota de la cuenta cuyos problemas se solicitan, incluso si una cuenta diferente autentica la solicitud.

Jerarquía de asignación

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

    Ejemplos:

    • Un grupo de CSS llamado Europe Shopping Group (ID de cuenta: 10001) quiere 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 comerciante asociadas (accounts/30003) para asignar una etiqueta. La cuota se consume del grupo de cuotas de TopDeals CSS y 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 cuentas secundarias.

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 y subcuentas como el nivel más individual.

Ajuste automático de cuotas

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

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

Servicios de productos

  • Todos los grupos de cuotas de métodos relacionados con los recursos products y productInputs.
  • La cuota de llamadas diarias suele establecerse en 2 veces la cantidad de cuota de ofertas que tiene el comerciante. Esto supone que un comerciante podría necesitar actualizar cada uno de sus productos hasta dos veces por día.
  • Los productos individuales se pueden actualizar más de dos veces, pero tus llamadas diarias generales a la API no pueden exceder la cuota de llamadas diarias agregada.

Servicios de cuentas

  • Todos los grupos de cuotas de 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 veces de llamadas de lectura por cuenta secundaria 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.
  • La cuota de llamadas diarias suele establecerse en 2 veces la cantidad de cuentas secundarias que tiene la cuenta avanzada. Esto supone que un comerciante puede actualizar las fuentes de datos de cada una de sus cuentas secundarias hasta dos veces por día.

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

Qué sucede cuando se superan las cuotas

Una vez que se supera 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 cuota adicional para artículos, feeds o cuentas secundarias:

  • too_many_items: Se superó la cuota del comerciante.
  • too_many_subaccounts: Se alcanzó la cantidad máxima de cuentas secundarias.

Supervisión y visibilidad

Para verificar las cuotas y el uso de llamadas actuales 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: el token de autorización para realizar la llamada a la API

Si la solicitud se realiza correctamente, la API muestra una lista de quotaGroups recursos 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 cuota adicional, abre el formulario Comunicarse con el equipo de asistencia, selecciona Solicitud de aumento de cuota para 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 destino y la justificación comercial.

  • Para recursos con cuotas automáticas (products, accounts y datasources para cuentas avanzadas): Solo puedes solicitar un aumento temporal para situaciones especiales, como el lanzamiento en un mercado nuevo o durante las temporadas de compras de alto tráfico. No aceptamos aumentos de cuota permanentes 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 para cada grupo de métodos de la API.

Prácticas recomendadas

Implementar estas prácticas recomendadas ayuda a garantizar que tu integración se ejecute sin problemas, evita errores de cuota inesperados y utiliza 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 diarias a la API de manera uniforme durante el día para mantenerte dentro de 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 únicamente de los servidores de Google para rechazar el tráfico excesivo. Controla la frecuencia de solicitudes en la fuente.

Manejo correcto de errores

  • Maneja el error HTTP 429: Tu aplicación debe estar preparada para manejar los errores 429 Demasiadas solicitudes (quota/request_rate_too_high).
  • Retirada exponencial con jitter: Cuando reintentes las 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 vuelven a intentarlo 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 NOT_FOUND en el diagnóstico de la API de Merchant Center para detectar el seguimiento de estados obsoletos o el sondeo innecesario.
  • 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 get o list repetitivas para datos sin cambios.
  • Cuentas avanzadas y cuentas secundarias: Si tienes una cuenta avanzada, autentícate a nivel de la cuenta avanzada si quieres que las llamadas se descuenten del grupo compartido de cuentas avanzadas.
  • Usa listSubaccounts: Para las cuentas avanzadas, usa accounts.listSubaccounts en lugar de accounts.list. La cuota accounts.list se cobra al usuario que llama (no al ID de la MCA) y no es visible en el diagnóstico estándar. listSubaccounts se descuenta de tu cuota de la MCA.
Anterior
Overview
Siguiente
Merchant Center limits