API y acceso para agentes de Top Service
Top Service es una marca de servicios profesionales para el hogar y el negocio y de servicio técnico de electrodomésticos, que presta cada trabajo con equipo propio y con profesionales colaboradores bajo su control, con guías por ciudad para 21 ciudades de España. Top Service trabaja en cuatro pasos: el cliente cuenta qué ocurre y dónde, se comprueba la disponibilidad para esa dirección, se le orienta sobre el oficio y, antes de empezar, se confirman el alcance y el coste del trabajo. Cada trabajo lo presta el equipo propio de Top Service o un profesional colaborador, en ambos casos bajo su control.
El contenido de topservice.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://topservice.es/wp-json/agentes/v1/ (contrato: openapi.json, índice: /api)
- Servidor MCP (Streamable HTTP, POST):
https://topservice.es/mcp· ficha: server-card.json - Instrucciones para agentes: agents.md · autenticación: auth.md
- 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 Service 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://topservice.es/wp-json/agentes/v1/search_pages?query=cerrajero+Sevilla&limit=3" |
read_page | Devuelve el texto completo de una página publicada de Top Service, convertido a Markdown y sin menús ni pie. Acepta la URL completa, la ruta o el slug. | curl "https://topservice.es/wp-json/agentes/v1/read_page?url=https%3A%2F%2Ftopservice.es%2Fcontacto%2F" |
get_company_info | Marca, razón social, NIF, domicilio, contacto y horario de Top Service, 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://topservice.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://topservice.es/oauth/register -H "Content-Type: application/json" -d '{"client_name":"mi-agente"}'
curl -u CLIENT_ID:CLIENT_SECRET -X POST https://topservice.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://topservice.es/oauth/registerreturns a client_id and client_secret instantly, with no human approval or sales contact; exchange them athttps://topservice.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 Service es una marca de Rapid Services Enterprise, S.L. (NIF B75807495), CL General TF65223, núm. 23, esc. 1, puerta 1, 38631 Arona (Santa Cruz de Tenerife), España; es el domicilio social y no una oficina de atención al público. Correo: info@rapidservicesenterprise.com.