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 nuevas integraciones con herramientas de desarrollo potenciadas por IA.

Descripción general

Cuando migres de Content API for Shopping a Merchant API o compiles una nueva integración, deberás comprender las nuevas estructuras de servicio, los nombres de recursos y los métodos. Las herramientas de desarrollo 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 la Content API for Shopping al nuevo formato de la API de Merchant. Esto incluye asignar atributos del producto a la nueva estructura y actualizar los archivos de administración de dependencias.
  • Experiencia en documentación de APIs: 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 el kit de herramientas de integración de APIs y 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 integrados (IDE) más utilizados, como Antigravity, Visual Studio Code, Cursor o Copilot. Es posible configurar asistentes de programación, como Gemini, Claude, ChatGPT, Grok y potenciarlos con el servidor de MCP de la documentación para desarrolladores de la API de Merchant o las habilidades del agente de la API de Merchant para que sean más fundamentados y, al mismo tiempo, aumentar la velocidad de integración.

(API de Merchant) Diagrama de Gemini Code Assist para la integración de IA

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

Obtén inteligencia contextual sobre la API de Merchant del asistente de programación que elijas. En tu IDE, ahora puedes acceder a la documentación para desarrolladores a través del servicio del Protocolo de contexto del modelo (MCP). Este servicio proporciona información clave de la documentación oficial de las APIs de Google a tu asistente de programación. Para obtener más información sobre el protocolo en sí, consulta el estándar del Protocolo de contexto del modelo.

Cómo funciona

Cuando le haces una pregunta a tu asistente de programación del IDE habilitado para MCP sobre la API de Merchant, 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 aumentada 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 o agente de programación 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 codificación envía una solicitud de contexto al endpoint 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 a MCP, usa los detalles del extremo remoto proporcionados, que pueden requerir que ingreses la URL del servicio directo o la definición de MCP, según la configuración de tu herramienta:

Configuración:

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 del agente 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 la herramienta que uses, puedes proporcionar estas instrucciones en la configuración de instrucciones del sistema o como un archivo de contexto adicional para el agente.

Ejemplos de situaciones de uso

El 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 a la API de Merchant.products.insert

Instrucción del usuario:

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

Si le proporcionas a tu agente instrucciones del sistema y acceso a MCP, este podrá traducir el código de Content API for Shopping al código de Merchant API directamente en tu IDE. En este caso, identificará productInputs.insert como la llamada equivalente y asignará los atributos del 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: Busca una funcionalidad equivalente

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

Instrucción del usuario:

"¿Cuál es el equivalente en la Merchant API del método accountstatuses.get de 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: Cómo encontrar 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 un ejemplo de código en Python para agregar un nuevo servicio de envío con la API de Merchant".

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

Situación 4: Comprender los conceptos de la API

Te encuentras con 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 contexto de la documentación de recursos de productos y de las guías pertinentes. Luego, tu asistente puede explicarte cómo usar el método accounts.productInputs.insert y proporcionar el recurso del 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 actúas en nombre de un usuario.

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

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

Instrucción del usuario:

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

El servicio de MCP recupera el contexto de Refactor code for concurrent requests, en el que se explica que no existen métodos custombatch dedicados en la API de Merchant. En cambio, proporciona documentación sobre el uso del procesamiento por lotes de HTTP con un Content-Type de multipart. Luego, tu asistente puede explicarte cómo crear una sola solicitud HTTP que contenga varias llamadas a la API, que se envían 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 Merchant API.

Instrucción del usuario:

"Migra esta consulta de informes de Content API a Merchant API: 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, las guías para desarrolladores y las guías de migración más recientes para la generación de informes. En función de esta información, transforma la búsqueda a la nueva estructura y actualiza los campos a sus nuevos nombres y valores.

Habilidades de agentes de la API de Merchant

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

Las habilidades del agente de la API de Merchant son compatibles con varias herramientas de IDE y de línea de comandos potenciadas por IA, como Gemini y Claude Code.

Cómo funciona

Las habilidades de agente de la API de Merchant proporcionan un paquete de experiencia especializada creado según el estándar abierto de habilidades de agente. Nuestra habilidad del agente mapi-developer-assistant actúa como una capa inteligente entre tus herramientas de desarrollo 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 manualmente los extremos.
  • Flujos de trabajo de expertos: Refina las instrucciones del usuario en consultas optimizadas para recuperar la información más pertinente de manera eficaz.
  • Administración del contexto y eficiencia de tokens: Usa la "divulgación progresiva" para cargar información a pedido y conservar la ventana de contexto de la IA.
  • Formato de salida mejorado: Proporciona instrucciones para dar formato y estructurar la salida de modo que las respuestas sean prácticas, legibles y coherentes.

Ejemplo de flujo de trabajo:

  1. Haces una pregunta sobre la API de Merchant en una herramienta de desarrollo de IA.
  2. La habilidad del agente de la API de Merchant analiza tu intención, formula una búsqueda precisa y aplica su conocimiento procedimental a la solicitud.
  3. La habilidad del agente envía una solicitud de contexto al servidor 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:

  • Son los requisitos previos para herramientas como la herramienta de línea de comandos de Gemini.
  • Habilitar la compatibilidad con Agent Skills en la herramienta que elegiste
  • Instala la habilidad mapi-developer-assistant desde el repositorio de GitHub según las instrucciones del 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 Gemini, Claude Code y otras, sigue las instrucciones 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 se activa 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 Content API?"

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

"Recibo un error '400 Bad Request' 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: