Integración de la API y Code Assist Toolkit

Usa el kit de herramientas de integración de APIs y Code Assist para acelerar tu migración a la API de Merchant y compilar integraciones nuevas con herramientas para desarrolladores potenciadas por IA.

Descripción general

Cuando migres de la Content API for Shopping a la API de Merchant o crees una integración nueva, deberás comprender las nuevas estructuras de servicio, los nombres de los recursos y los métodos. Las herramientas para desarrolladores potenciadas por IA son especialmente adecuadas para ayudar con las siguientes operaciones:

  • Traducción y migración de código: Te ayuda a comprender y convertir el código heredado de Content API for Shopping al nuevo formato de la API de Merchant. Esto incluye asignar atributos de producto a la nueva estructura y actualizar los archivos de administración de dependencias.
  • Experiencia en documentación de la API: Proporciona explicaciones claras de los recursos, los métodos, los campos, las cuotas y las prácticas recomendadas de la API de Merchant según el contexto autorizado de la documentación oficial de la API de Google.
  • Generación de código: Genera fragmentos de código para varias tareas de la API de Merchant en lenguajes como Python, Java, PHP y otros.
  • Solución de problemas: Ayuda a diagnosticar y corregir errores comunes de la API.

Elige la opción que mejor se adapte a tu entorno de desarrollo y caso de uso específico. Usa la integración de la API y el kit de herramientas de Code Assist para adaptar la configuración a tu flujo de trabajo preferido:

En el siguiente diagrama, se ilustran las opciones de configuración para una migración de código asistida por IA en los entornos de desarrollo integrado (IDE) de uso frecuente, como Antigravity, Visual Studio Code, Cursor o Copilot. Es posible configurar asistentes de programación, como Gemini, Claude, ChatGPT y Grok, y potenciarlos con el servidor de MCP de la documentación para desarrolladores de la API de Merchant o las habilidades de agente de la API de Merchant para que estén más fundamentados y, al mismo tiempo, aumenten la velocidad de integración.

Diagrama de asistencia de programación para la integración de IA (API de Merchant)

Servidor de MCP de documentación para desarrolladores de la API de Merchant

Obtén inteligencia contextual sobre la API de Merchant con el asistente de programación que prefieras. Dentro de tu IDE, ahora puedes acceder a la documentación para desarrolladores con el servicio del Protocolo de contexto del modelo (MCP). Este servicio alimenta a tu asistente de programación con información clave de la documentación oficial de las APIs de Google. Para obtener más información sobre el protocolo, consulta el estándar del Model Context Protocol.

Cómo funciona

Cuando le haces una pregunta sobre la API de Merchant al asistente de programación de tu IDE habilitado para MCP, el servicio recupera los fragmentos de texto y código más relevantes de los recursos oficiales y los devuelve como contexto a tu asistente de programación con un backend especializado de generación mejorada por recuperación (RAG). Un sistema de RAG es aquel que mejora la calidad de las respuestas de los LLM conectándolos a fuentes de conocimiento externas y actualizadas. Esto permite que tu asistente proporcione respuestas precisas y actualizadas sin que tengas que salir de tu entorno de desarrollo.

Ejemplo de flujo de trabajo:

  1. Haces una pregunta en tu asistente de programación o agente compatible con MCP (p.ej., una pregunta en lenguaje natural, una solicitud de una muestra de código o una traducción de código).
  2. Tu asistente de programación envía una solicitud de contexto al extremo de MCP.
  3. El servicio de MCP busca en su colección indexada de documentación, guías y muestras de código oficiales de la API de Merchant.
  4. El servicio devuelve fragmentos autorizados como contexto para tu asistente de programación.
  5. Tu asistente de programación aprovecha este contexto para generar una respuesta fundamentada o una tarea de traducción de código.

Cómo comenzar

Para integrar y usar MCP, sigue estos pasos:

1. Usa una herramienta compatible

Abre un IDE o un asistente de programación que admita el Protocolo de contexto del modelo con transporte HTTP transmisible.

2. Configura el extremo

Para conectar tu IDE o asistente de programación al MCP, usa los detalles del extremo remoto proporcionados, que pueden requerir que ingreses la URL directa del servicio o la definición del MCP, según la configuración de tu herramienta:

Configuraciones:

Antigravity

Sigue las instrucciones de la documentación de Antigravity.

"mcpServers": {
  "mapi-devdocs": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://merchantapi.googleapis.com/devdocs/mcp"
    ]
  }
}

Visual Studio Code

Sigue las instrucciones de la documentación de Visual Studio Code.

"servers": {
"mapi-devdocs": {
  "type": "http",
  "url": "https://merchantapi.googleapis.com/devdocs/mcp/"
  }
}

3. Agrega instrucciones para el agente (opcional)

Para permitir que tu agente traduzca código directamente con MCP, proporciónale las instrucciones del sistema: Protocolo de agente de integrador de comercios. Estas instrucciones guían al agente sobre cómo utilizar correctamente el MCP para la traducción de código. Según tu herramienta, puedes proporcionar estas instrucciones en la configuración de las instrucciones del sistema o como un archivo de contexto adicional para el agente.

Situaciones de uso de ejemplo

MCP puede acelerar tu flujo de trabajo en los siguientes casos de uso comunes:

Situación 1: Migra el código de products.insert

Puedes pedirle al agente que migre directamente un código de integración de Content API for Shopping products.insert a la API de Merchant.

Instrucción del usuario:

"Migra el código de products.insert a la API de Merchant"

Si proporcionas instrucciones del sistema y acceso a MCP a tu agente, este puede traducir el código de Content API for Shopping al código de la API de Merchant directamente en tu IDE. En este caso, identificará productInputs.insert como la llamada equivalente y asignará los atributos de producto del formato anterior al nuevo formato que requiere la API de Merchant. También puede actualizar las importaciones requeridas y el archivo de administración de dependencias (por ejemplo, requirements.txt, pom.xml o package.json). Puedes indicarle al agente que realice los cambios en el lugar o que cree una carpeta nueva.

Situación 2: Encuentra una funcionalidad equivalente

Tienes una aplicación existente que usa la Content API for Shopping y necesitas actualizarla. Puedes preguntar sobre un método heredado específico para obtener detalles sobre la implementación nueva y una muestra de código pertinente.

Instrucción del usuario:

"¿Cuál es el equivalente de la API de Merchant para el método accountstatuses.get en la Content API for Shopping?"

El servicio de MCP proporciona contexto de las guías de migración oficiales y la documentación de referencia, lo que permite que tu asistente responda con una respuesta detallada, incluido el nuevo nombre de la API, accounts.issues.

Situación 3: Busca una muestra de código

Estás implementando una función nueva y necesitas un ejemplo práctico para seguir.

Instrucción del usuario:

"Muéstrame una muestra de código de Python para agregar un nuevo servicio de envío con la API de Merchant".

El servicio de MCP recupera muestras de código relevantes de los repositorios oficiales de Google en GitHub y las guías para desarrolladores. Luego, tu asistente puede presentar un bloque de código completo y listo para adaptar.

Situación 4: Comprende los conceptos de las APIs

Encuentras un concepto nuevo o quieres comprender la estructura de un recurso o el patrón general de la API de Merchant.

Instrucción del usuario:

"¿Cómo actualizo el inventario de un producto con la API de Merchant?"

El servicio de MCP devuelve el contexto de la documentación de recursos de los productos y las guías pertinentes. Luego, el asistente puede explicar cómo usar el método accounts.productInputs.insert y proporcionar el recurso de producto parcial que contiene solo el productId y los campos relacionados con el inventario que necesitas actualizar.

"¿Cómo autorizo las llamadas de mi aplicación con la API de Merchant?"

El servicio de MCP recupera el contexto de las guías de autenticación oficiales, que abarcan diferentes métodos de autorización. Luego, tu asistente puede explicar las opciones principales disponibles, como usar una cuenta de servicio para las interacciones de servidor a servidor o un ID de cliente de OAuth 2.0 cuando se actúa en nombre de un usuario.

Situación 5: Adaptación a los cambios en la API

La API de Merchant presenta nuevos patrones, como las solicitudes por lotes, que difieren de Content API for Shopping. La Content API for Shopping usa métodos custombatch específicos, mientras que la API de Merchant usa una función de solicitud por lotes HTTP genérica integrada.

Instrucción del usuario:

"¿Cuál es la nueva forma de realizar un products.custombatch en la API de Merchant?"

El servicio de MCP recupera el contexto de Refactoriza el código para solicitudes simultáneas, en el que se explica que los métodos custombatch dedicados no existen en la API de Merchant. En su lugar, proporciona documentación sobre el uso de solicitudes por lotes HTTP con un Content-Type de multipart. Luego, tu asistente puede explicar cómo construir una sola solicitud HTTP que contenga varias llamadas a la API, enviada al extremo https://merchantapi.googleapis.com/batch/{sub-api}/v1, y proporcionar un ejemplo de cómo estructurar la solicitud de varias partes. Esto convierte una tarea de migración potencialmente confusa en un proceso guiado.

Situación 6: Traduce una consulta de informes

Puedes pedirle al agente que traduzca una consulta de informes de Content API for Shopping a la API de Merchant.

Instrucción del usuario:

"Migra esta consulta de informes de la API de Content a la API de Merchant: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

El servicio de MCP recupera la documentación de referencia de informes, las guías para desarrolladores y las guías de migración más recientes. Según esta información, transforma la consulta a la estructura nueva y actualiza los campos a sus nombres y valores nuevos.

Habilidades de agentes de la API de Merchant

La especificación de habilidades para agentes es un estándar abierto que se adopta en todas las herramientas de desarrollo de IA. Usa las habilidades de los agentes para mejorar tu experiencia de desarrollador y optimizar la migración desde la Content API for Shopping y la creación de integraciones nuevas. Los paquetes de habilidades de agentes de la API de Merchant empaquetan conocimientos y herramientas específicos del dominio para mejorar las capacidades de los agentes de IA y proporcionan asistencia de expertos a pedido para consultas de documentación, generación de código y solución de problemas.

Las habilidades de agente de la API de Merchant son compatibles con varias herramientas de línea de comandos y entornos de desarrollo integrado (IDE) potenciados por IA, como Antigravity y Claude Code.

Cómo funciona

Las habilidades de agente de la API de Merchant proporcionan un paquete de experiencia especializado que se basa en el estándar abierto de habilidades de agente. Nuestra habilidad de agente mapi-developer-assistant actúa como una capa inteligente entre tus herramientas para desarrolladores de IA y el servidor de MCP de la documentación para desarrolladores de la API de Merchant subyacente. Incorpora experiencia en el dominio y orientación procedimental, y tiene las siguientes propiedades:

  • Configuración cero: Administra automáticamente las conexiones del servidor de MCP, lo que elimina la necesidad de configurar extremos de forma manual.
  • Flujos de trabajo de expertos: Define mejor las instrucciones de los usuarios en consultas optimizadas para recuperar la información más pertinente de forma eficaz.
  • Administración de contexto y eficiencia de tokens: Usa la "divulgación progresiva" para cargar información a pedido y preservar la ventana de contexto de la IA.
  • Formato de salida mejorado: Proporciona instrucciones para dar formato y estructurar el resultado para obtener respuestas prácticas, legibles y coherentes.

Ejemplo de flujo de trabajo:

  1. Haces una pregunta sobre la API de Merchant en una herramienta para desarrolladores de IA.
  2. La habilidad del agente de la API de Merchant analiza tu intención, formula una consulta precisa y aplica su conocimiento de procedimientos a la solicitud.
  3. La habilidad del agente envía una solicitud de contexto al servidor de MCP de la documentación para desarrolladores de la API de Merchant, ubicado en merchantapi.googleapis.com/devdocs/mcp/.
  4. El servicio de MCP busca en su colección indexada de documentación, guías y muestras de código oficiales de la API de Merchant.
  5. Tu agente de IA aprovecha esta información para proporcionar una respuesta sintetizada y práctica.

Cómo comenzar

El archivo README de las habilidades del agente de la API de Merchant proporciona orientación paso a paso sobre lo siguiente:

  • Requisitos previos para herramientas como la herramienta de línea de comandos de Antigravity
  • Habilitar la compatibilidad con las habilidades del agente en la herramienta que elijas
  • Instalar la habilidad de mapi-developer-assistant desde el repositorio de GitHub como se indica en el archivo README
  • Verifica la instalación.
  • Comandos básicos de administración de habilidades

Para obtener instrucciones detalladas de instalación y configuración de varias herramientas de IA, incluidas la herramienta de línea de comandos de Antigravity, Claude Code y otras, sigue la guía del archivo README.

Ejemplos de instrucciones

Una vez que se instala y habilita en tus herramientas de desarrollo de IA, la habilidad de mapi-developer-assistant suele activarse automáticamente cuando haces preguntas relacionadas con la API de Merchant.

"¿Cómo inserto un producto con la API de Merchant en Python?"

"¿Cuál es el equivalente de la API de Merchant para el método accountstatuses.get de la Content API?"

"Muéstrame un ejemplo de Java para controlar la autenticación con la API de Merchant".

"Recibo un error '400 Solicitud incorrecta' con un error de validación cuando llamo a productInputs.insert. ¿Cómo puedo solucionarlo?".

"¿Cuál es la diferencia entre ProductInput y Product en la API de Merchant?"

Fuentes de la base de conocimiento

El servicio de MCP crea su base de conocimiento exclusivamente a partir de fuentes públicas y oficiales para garantizar que el contexto que proporciona sea preciso y confiable. El servicio indexa todo el contenido del sitio oficial para desarrolladores y el repositorio de muestras de código, lo que incluye lo siguiente: