API y acceso para agentes de Top Solution
Top Solution, nombre comercial de Rapid Services Enterprise, S.L., presta servicios de mantenimiento, reparación e instalación para el hogar y la empresa: oficios como electricidad, fontanería, cerrajería, desatascos o reformas y servicio técnico de electrodomésticos a domicilio, con páginas propias para 21 ubicaciones de España. Top Solution recibe el aviso por teléfono o por correo, da una horquilla de precio y una hora antes de que salga nadie, el técnico diagnostica en el domicilio y, si aparece algo que cambia el presupuesto, se para y se consulta. Después se ejecuta el trabajo y se factura, con la garantía correspondiente.
El contenido de topsolution.es también se puede consultar en formato legible por máquina, sin registro y en solo lectura: una API REST con contrato OpenAPI 3.1, un servidor MCP para asistentes y la versión en Markdown de cada página. No sirve para reservar, contratar ni pagar: para pedir un servicio hay que usar los datos de contacto.
Resumen
- API REST: https://topsolution.es/wp-json/agentes/v1/ (contrato: openapi.json, índice: /api)
- Servidor MCP (Streamable HTTP, POST):
https://topsolution.es/mcp· ficha: server-card.json - Instrucciones para agentes: agents.md · autenticación: auth.md · índice: llms.txt
- Cualquier página en Markdown: cabecera
Accept: text/markdowno.mdal final de la URL (la portada: /index.md) - Catálogos: api-catalog (RFC 9727) · ai-catalog.json
Operaciones
Todas son GET, sin autenticación, y devuelven JSON. Son las mismas que las herramientas del servidor MCP.
| Operación | Para qué | Ejemplo |
|---|---|---|
search_pages | Busca en las páginas publicadas de Top Solution por servicio, problema o ciudad y devuelve las URLs más relevantes con un extracto. Es el punto de entrada normal: pasa después la URL a read_page. Si hay más resultados, la respuesta trae next_cursor para pedir la página siguiente. | curl "https://topsolution.es/wp-json/agentes/v1/search_pages?query=cerrajero+Madrid&limit=3" |
read_page | Devuelve el texto completo de una página publicada de Top Solution, convertido a Markdown y sin menús ni pie. Acepta la URL completa, la ruta o el slug. | curl "https://topsolution.es/wp-json/agentes/v1/read_page?url=https%3A%2F%2Ftopsolution.es%2Fcontacto%2F" |
get_company_info | Marca, razón social, NIF, domicilio, contacto y horario de Top Solution, su modelo de servicio (quién hace, presupuesta, factura y garantiza el trabajo), impuestos, precios orientativos y la lista de servicios y ciudades con sus URLs. Úsalo para verificar quién está detrás del sitio o para decirle al usuario cómo pedir un servicio. Con section se pide solo una parte. | curl "https://topsolution.es/wp-json/agentes/v1/get_company_info?section=contact" |
Autenticación y cuota
Leer no exige credenciales: 60 peticiones por minuto por IP. El alta OAuth 2.0 (client_credentials, automática y gratuita) es opcional y solo sube la cuota a 600 por minuto; no abre ningún contenido nuevo. Detalles en auth.md.
curl -X POST https://topsolution.es/oauth/register -H "Content-Type: application/json" -d '{"client_name":"mi-agente"}'
curl -u CLIENT_ID:CLIENT_SECRET -X POST https://topsolution.es/oauth/token -d grant_type=client_credentialsCada respuesta trae las cabeceras RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset; un 429 añade Retry-After.
Errores
Siempre JSON, nunca HTML: {"code":"...","message":"...","data":{"status":404,"hint":"qué hacer"}}.
Versionado y retirada (deprecation and sunset policy)
Versión actual: v1, en la ruta (/wp-json/agentes/v1/) y en la cabecera API-Version: 1 de cada respuesta. El contrato OpenAPI 3.1 está en /openapi.json.
- Cambios compatibles (un campo nuevo, una operación nueva): se hacen dentro de v1, sin aviso previo. Un cliente debe ignorar los campos que no conozca.
- Cambios incompatibles: salen en una versión nueva (
/wp-json/agentes/v2/). La anterior sigue funcionando al menos 90 días después de anunciar su retirada. - Cómo se avisa: la versión en retirada responde con
Deprecation(RFC 9745) desde el día del anuncio y conSunset(RFC 8594) con la fecha exacta de apagado. Cada respuesta de la API lleva un enlacerel="deprecation"a este apartado. La política, en JSON: /api/versionado.
Hoy ninguna versión está en retirada, por eso las respuestas actuales no llevan Deprecation ni Sunset: si aparecen esas cabeceras, hay que migrar.
Pruebas
No hay entorno de pruebas aparte porque no hace falta: todo es de solo lectura y probar contra producción no crea, reserva ni cobra nada (/api/sandbox).
Getting started (English)
- Free: no paid plans and no trial that expires; reading needs no API key (60 requests per minute per IP).
- Self-serve API keys:
POST https://topsolution.es/oauth/registerreturns a client_id and client_secret instantly, with no human approval or sales contact; exchange them athttps://topsolution.es/oauth/token(client_credentials) for 600 requests per minute. - Sandbox: the API is read-only, so production is safe to test against and doubles as the sandbox (/api/sandbox).
- Deprecation and sunset policy: this is v1 (path and API-Version header). Breaking changes ship as v2; v1 keeps working for at least 90 days after a deprecation notice sent with the Deprecation (RFC 9745) and Sunset (RFC 8594) headers. No version is deprecated today.
- Errors: always JSON with code, message and data.hint, never HTML.
Empresa y contacto
Top Solution es una marca de Rapid Services Enterprise, S.L. (NIF B75807495), CL General TF65223 nº 23, esc. 1, pta. 1, 38631 Arona (Santa Cruz de Tenerife), España; es la sede administrativa y no atiende al público sin cita previa. Correo: info@rapidservicesenterprise.com · Teléfono: +34 682 048 793.