LeyApp Para desarrolladores
Un servicio REST API y un servidor MCP para reservar abogados especializados en inmigración acreditados en toda España. Los clientes siempre confirman y pagan en leyapp.es; tu integración nunca gestiona el dinero.
Resumen
La «API» muestra los mismos datos de abogados verificados que leyapp.es: búsquedas, perfiles públicos, reseñas, disponibilidad e intenciones de reserva. El acceso anónimo funciona con límites de uso reducidos; una clave de API aumenta los límites y desbloquea los puntos de conexión restringidos y los análisis de uso.
No se admiten pagos a través de la página web API
Una «intención de reserva» es una reserva de 15 minutos. El cliente confirma y paga en leyapp.es; tu integración nunca gestiona dinero ni datos de tarjetas.
Apto para usuarios anónimos
La lectura de puntos finales y la creación de intenciones funcionan sin necesidad de una clave, con límites conservadores por dirección IP. Las claves son gratuitas y se crean en tu panel de control.
Modo de prueba integrado
Las claves «leyk_test_» ejecutan todo el proceso de validación, pero no crean nada ni envían notificaciones a nadie. Se compilan con el entorno de pruebas y se distribuyen con el entorno de producción.
Trazabilidad integrada en el diseño
Cada respuesta incluye el campo «X-Request-Id». Indícalo al servicio de asistencia y podremos localizar tu solicitud concreta.
Inicio rápido
De cero a una intención de reserva (de prueba) en cuatro solicitudes. Primero, crea una clave de prueba gratuita en Dashboard → Developer.
# 1. Get a test key at leyapp.es/dashboard/developer
export LEYAPP_API_KEY="leyk_test_..."
# 2. Find a lawyer
curl "https://leyapp.es/api/v1/lawyers/search?city=Barcelona&practice_area=immigration" \
-H "Authorization: Bearer $LEYAPP_API_KEY"
# 3. Check availability (id from step 2)
curl "https://leyapp.es/api/v1/lawyers/<lawyer_id>/availability" \
-H "Authorization: Bearer $LEYAPP_API_KEY"
# 4. Create a (test) booking intent
curl -X POST "https://leyapp.es/api/v1/bookings/initiate" \
-H "Authorization: Bearer $LEYAPP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-1" \
-d '{"lawyer_id":"<lawyer_id>","date":"<date>","start_time":"09:00:00","end_time":"10:00:00"}'Autenticación
Envía tu clave como token «Bearer» en cada solicitud:
Authorization: Bearer leyk_...
- Las claves están disponibles en las variantes «live» (leyk_) y «test» (leyk_test_) y se muestran exactamente una vez al crearlas; guárdalas en un gestor de claves secretas.
- Nunca incluyas una clave en el código del lado del cliente ni en un repositorio público. Renueva la clave creando una nueva, implementándola y, a continuación, revocando la antigua (sin tiempo de inactividad).
- La revocación es inmediata. Las llaves perdidas no se pueden recuperar, solo se pueden sustituir.
- Los tokens MCP (ley_...) sirven para autenticar a los asistentes de IA en /api/mcp y no son válidos en el punto de API REST.
Límites de frecuencia
Las solicitudes con clave tienen límites por niveles (ventana dual: ráfaga por minuto + cuota diaria) con los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. En el código de estado 429, respeta el valor de Retry-After y vuelve a intentar la solicitud con un retroceso exponencial con fluctuación.
| Nivel | Solicitudes por minuto | Solicitudes al día |
|---|---|---|
| free | 60 | 5,000 |
| partner | 300 | 50,000 |
| internal | 1,000 | ∞ |
Las nuevas claves se activan en el nivel gratuito. Los niveles para socios los concede el equipo de LeyApp; ponte en contacto con nosotros a través del formulario de asistencia si tu integración necesita más capacidad. Las solicitudes anónimas tienen límites por IP distintos y más bajos.
Modo de prueba
Las claves de prueba (leyk_test_) se comportan exactamente igual que las claves activas —los mismos puntos finales, la misma validación, el mismo formato de respuesta—, pero no ocurre nada en la realidad: no se almacena ninguna solicitud de reserva, no se avisa a ningún abogado, no se puede confirmar ni pagar nada.
El tráfico de prueba aparece en el registro de solicitudes de tu panel de control (marcado), pero queda excluido de los totales diarios. Cambia la clave por una activa cuando lances la versión; no es necesario realizar ningún otro cambio.
Puntos finales
/api/v1/lawyers/searchSearch verified lawyers
Same search engine as leyapp.es. Verified, publicly listed lawyers only. Scope: lawyers:read (anonymous allowed).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| city | string | No | |
| practice_area | string | No | Slug from GET /practice-areas |
| language | string | No | |
| min_fee_eur | number | No | |
| max_fee_eur | number | No | |
| sort | string (rating | price_asc | price_desc | reviews) | No | |
| page | integer | No | |
| limit | integer | No |
curl "https://leyapp.es/api/v1/lawyers/search?city=Barcelona&practice_area=immigration&language=en" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
/api/v1/lawyers/{lawyerId}Public lawyer profile
Full public profile incl. bio and bar memberships. Bio is user-generated content wrapped in safety fencing for AI consumers. Scope: lawyers:read (anonymous allowed).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| lawyerId | string | Sí |
curl "https://leyapp.es/api/v1/lawyers/<lawyerId>" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
/api/v1/lawyers/{lawyerId}/availabilityAvailable consultation slots
Available slots for a date range (max 14 days). Scope: availability:read (anonymous allowed).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| lawyerId | string | Sí | |
| start_date | string | No | Default: today |
| end_date | string | No | Default: start_date + 13 days |
curl "https://leyapp.es/api/v1/lawyers/<lawyerId>/availability" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
/api/v1/lawyers/{lawyerId}/reviewsPublic reviews
Recent reviews from verified clients. Comments are UGC with AI-safety fencing. Scope: reviews:read (anonymous allowed).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| lawyerId | string | Sí | |
| limit | integer | No |
curl "https://leyapp.es/api/v1/lawyers/<lawyerId>/reviews" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
/api/v1/practice-areasPractice-area hierarchy
Reference data; cache-friendly (24h). Scope: reference:read (anonymous allowed).
curl "https://leyapp.es/api/v1/practice-areas" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
/api/v1/citiesSupported cities and provinces
Reference data; cache-friendly (24h). Scope: reference:read (anonymous allowed).
curl "https://leyapp.es/api/v1/cities" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
/api/v1/bookings/initiateCreate a booking intent
Creates a 15-minute booking intent for a free slot. The USER must open confirmation_url on leyapp.es to confirm and pay — the API never charges anyone. Supports Idempotency-Key (Stripe semantics: 24h replay, 422 on body mismatch). Test keys validate fully but create nothing. Scope: bookings:initiate (anonymous allowed at 5/hour).
Cuerpo de la solicitud
{
"lawyer_id": "<lawyer_id from search>",
"date": "2026-09-01",
"start_time": "09:00:00",
"end_time": "10:00:00",
"source": "api",
"agent_name": "MyIntegration"
}curl -X POST "https://leyapp.es/api/v1/bookings/initiate" \
-H "Authorization: Bearer $LEYAPP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"lawyer_id":"<lawyer_id from search>","date":"2026-09-01","start_time":"09:00:00","end_time":"10:00:00","source":"api","agent_name":"MyIntegration"}'Los puntos finales POST no se pueden ejecutar desde la documentación; copia el fragmento de código y ejecútalo con una clave de prueba.
/api/v1/booking-intents/{intentId}API Se requiere clavePoll a booking intent
Status of an intent CREATED BY YOUR KEY: pending | confirmed | expired. Requires an API key with bookings:read (not available anonymously).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| intentId | string | Sí |
curl "https://leyapp.es/api/v1/booking-intents/<intentId>" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
Webhooks
Suscríbete a un punto final HTTPS (Panel de control → Desarrollador → Webhooks) para recibir notificaciones de eventos relacionados con las intenciones de reserva creadas con tu clave. Las notificaciones se envían según la especificación estándar de webhooks y se reintentan automáticamente.
- Eventos: booking_intent.confirmed / booking_intent.expired (la fase de intención), además del ciclo de vida completo de las reservas originadas en API: booking.approved, booking.cancelled, booking.completed.
- Verifica cada entrega con el secreto de firma «whsec_» que se muestra una vez al crear el punto final; las bibliotecas oficiales de standardwebhooks lo hacen en una sola llamada. Rechaza las marcas de tiempo anteriores o posteriores a ±5 minutos.
- La entrega se realiza al menos una vez: se elimina la duplicación mediante el encabezado «webhook-id» (que también es el ID de la carga útil). Las cargas útiles solo contienen ID y estados; si necesitas más detalles, consúltalos en API.
# Delivery headers (Standard Webhooks — standardwebhooks.com):
# webhook-id: unique delivery id (dedup key — at-least-once delivery)
# webhook-timestamp: unix seconds (reject if older than ±5 minutes)
# webhook-signature: v1,<base64 HMAC-SHA256 of "{id}.{timestamp}.{body}">
#
# Payload: { "id": "...", "type": "booking_intent.confirmed",
# "created_at": "...", "data": { "booking_intent_id": "...", "status": "..." } }
# Events: booking_intent.confirmed | booking_intent.expired
# Retries: 1m / 5m / 30m / 2h / 12h, then dead. Endpoint auto-disabled
# after 20 consecutive failures.MCP y agentes de IA
¿Prefieres hablar en lugar de programar? LeyApp incluye un servidor MCP con 15 herramientas —búsqueda, disponibilidad, reservas y (con tu consentimiento) tus propias reservas— para Claude, ChatGPT, Cursor y cualquier cliente compatible con MCP. OAuth da tu consentimiento con niveles de permiso detallados; revócalo en cualquier momento desde el Panel de control → Desarrollador.
Settings → Connectors → Add custom connector Name: LeyApp URL: https://leyapp.es/api/mcp/mcp Claude opens the LeyApp consent screen — sign in, pick a permission level, and you're connected.
Registro de cambios
La versión 1 de API es exclusivamente aditiva: se añaden campos, pero nunca se renombran ni se eliminan. Los cambios que impliquen incompatibilidad se publicarían como una nueva versión con un plazo de obsolescencia de 90 días, que se anunciaría aquí y a través de los encabezados «Deprecation» y «Sunset».
2026-07-22
Reliability, webhook coverage, and key controls
- Idempotency-Key is now exactly-once even under concurrent retries (a duplicate in-flight request gets 409, then replays the original result).
- Webhook events expanded to the full booking lifecycle: booking.approved, booking.cancelled, booking.completed (for API-originated bookings).
- API keys can be created with an optional expiration (30/90/365 days).
- Owners are emailed when a key nears its daily quota or shows a high error rate, and when a webhook endpoint is auto-disabled.
2026-07-22
Search, profiles, reviews, reference data, intent polling, usage analytics
- New endpoints: GET /lawyers/search, GET /lawyers/{id}, GET /lawyers/{id}/reviews, GET /practice-areas, GET /cities.
- New: GET /booking-intents/{id} — poll intents created by your key (bookings:read scope, key-only).
- Booking intents are now persisted end-to-end; POST /bookings/initiate returns real confirmable intents.
- Usage analytics in Dashboard → Developer: 30-day aggregates and a live request log per key.
- Machine-readable spec published at /api/v1/openapi.json.
2026-07-16
API keys, tiered rate limits, idempotency, test mode
- API keys (leyk_ live / leyk_test_ test) with one-time reveal, managed in Dashboard → Developer.
- Tiered rate limits with X-RateLimit-* headers; RFC 9457 problem+json errors with X-Request-Id.
- Idempotency-Key support on POST /bookings/initiate (24h replay, 422 on body mismatch).
- Test mode: full validation, zero side effects, no lawyer notifications.
2026-03-21
Initial public beta
- GET /lawyers/{id}/availability and POST /bookings/initiate (anonymous, per-IP limits).
- MCP server with 15 tools at /api/mcp; OAuth 2.1 + PKCE for AI clients.
¿Tienes alguna pregunta, quieres límites más altos o te gustaría proponer una colaboración? Ponte en contacto con nosotros a través del formulario de asistencia, o simplemente crea una clave y empieza a desarrollar.