API y agentes de IA: cómo conectarse a Mercatren
Lo que está abierto sin credenciales (catálogo, búsqueda, Markdown, servidor MCP), lo que lleva token de tienda (cobros por enlace y sincronización de catálogo) y cómo se pide el acceso.
En una línea
Leer el catálogo es público. Cobrar y sincronizar catálogos lleva un token de tienda que entrega el equipo. No hay servidor OAuth, y no se publica uno que no existe.
Lo público
| Qué | Dónde | Para qué |
|---|---|---|
| Catálogo por tandas | GET /datos/catalogo?pagina=1&todas=1 | Los productos publicados, 24 por tanda; con q= busca por palabras (con sinónimos). |
| Sugerencias | GET /datos/buscar?q= | Productos y comercios que calzan mientras se escribe. |
| Servidor MCP | POST /datos/mcp | JSON-RPC 2.0, Streamable HTTP: buscar_productos, ver_producto, listar_tiendas, ver_tienda. |
| Markdown para agentes | cualquier página con Accept: text/markdown | La ficha, la tienda, el artículo o la portada en Markdown, con x-markdown-tokens. |
| Salud | GET /datos/salud | ok y si la base contesta. |
| OpenAPI 3.1 | /datos/openapi.json | La especificación de todo lo anterior y de la API de socios. |
Cómo se descubre
- /.well-known/api-catalog — el catálogo de la API (RFC 9727).
- /.well-known/mcp/server-card.json — la tarjeta del servidor MCP.
- /.well-known/agent-skills/index.json — los skills: «comprar en Mercatren» y «cobrar por Mercatren», con su SHA-256.
- /.well-known/ai-catalog.json — el manifiesto ARD.
- /auth.md y /.well-known/oauth-protected-resource — cómo se consigue acceso y qué recurso está protegido.
- /llms.txt — el resumen para asistentes.
Probar el MCP en treinta segundos
Manda un POST a /datos/mcp con {"jsonrpc":"2.0","id":1,"method":"tools/list"} y recibes las cuatro herramientas. Después {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"buscar_productos","arguments":{"consulta":"bicicleta"}}} y recibes los resultados con título, precio, comercio y enlace.
La API de socios (con token)
Con Authorization: Bearer <token de la tienda>, un sistema crea cobros por enlace (POST /datos/socios/cobro), consulta su estado (GET /datos/socios/cobro?referencia=), los reactiva y los cancela, empuja su catálogo (POST /datos/socios/productos) y lee lo que cambió aquí (GET /datos/socios/cambios?desde=). El token lo entrega el equipo al vincular la tienda: escribe a hola@mercatren.com con el nombre de la tienda y para qué lo quieres. Una plataforma socia obtiene el token de cada tienda con su llave en POST /datos/socios/vincular.
Guárdalo bien
El token va en el servidor, nunca en el navegador ni en un repositorio público. Para rotarlo o revocarlo, escribe a hola@mercatren.com.