LeyApp面向开发者
休息API以及一个用于预订西班牙各地经过认证的移民律师的MCP服务器。客户始终会在指定时间确认并付款。leyapp.es — 您的集成方案不会涉及资金。
概述
这API公开与律师相同的已验证数据leyapp.es搜索、公开资料、评价、房源情况和预订意向。匿名访问在低速率限制下有效；API密钥可提高限制并解锁密钥端点和使用情况分析。
不通过此方式付款API
预订意向是指15分钟的预订。客户确认并付款。leyapp.es — 您的集成永远不会处理资金或卡片数据。
匿名友好
读取端点和创建意图无需密钥，但每个 IP 地址的限制较为保守。密钥免费，可在您的控制面板中创建。
内置测试模式
leyk_test_ 键会运行完整的验证路径，但不会创建任何内容，也不会通知任何人。针对测试环境构建，并随生产环境一起发布。
设计上可追溯
每个响应都包含一个 X-Request-Id。请将此 ID 提供给技术支持，以便我们找到您具体的请求。
快速入门
从零到（测试）预订意向，只需四次请求。请先在“控制面板”→“开发者”中创建一个免费测试密钥。
# 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"}'验证
每次请求时都以 Bearer 令牌的形式发送您的密钥：
Authorization: Bearer leyk_...
- 密钥分为正式版 (leyk_) 和测试版 (leyk_test_) 两种变体，在创建时仅显示一次——将它们存储在密钥管理器中。
- 永远不要在客户端代码或公共代码库中发布密钥。轮换密钥的方式是：创建一个新密钥，部署它，然后撤销旧密钥（零停机时间）。
- 撤销操作立即生效。丢失的密钥无法恢复，只能更换。
- MCP 令牌（ley_...）用于在 /api/mcp 上验证 AI 助手，但在 REST 上无效。API 。
组织密钥
一家律师事务所LeyApp可以拥有API公司密钥直接与员工的个人密钥分开。公司密钥属于整个组织，因此不受人员变动的影响：即使创建密钥的人员更换职位或离职，密钥仍然有效，公司所有者和管理员会收到通知，以便他们能够主动更换密钥，而不是在系统出现故障时才发现问题。
所有者和管理员凭借其角色可以管理公司密钥。任何其他成员在被授予特定权限之前都无权访问：
- api:view — 列出公司的密钥、密钥前缀和上次使用时间。密钥创建后，绝不会再向任何人显示。
- api:manage — 创建、撤销、暂停和限制公司的密钥。
- api:webhooks — 管理公司的 webhook 端点。
公司密钥支持两种额外的控制功能：IP 地址白名单，用于拒绝来自名单之外任何地址的密钥；以及暂停功能，用于暂停密钥但不销毁它。公司设置的暂停功能可以由公司解除；LeyApp只能通过以下方式举起LeyApp。
速率限制
使用 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 标头设置请求速率限制（双窗口：每分钟突发流量限制 + 每日配额）。对于 429 端口，遵循 Retry-After 参数，并使用抖动指数退避算法进行重试。
| 层级 | 每分钟请求数 | 每日请求数 |
|---|---|---|
| free | 60 | 5,000 |
| partner | 300 | 50,000 |
| internal | 1,000 | ∞ |
新密钥从免费级别开始。合作伙伴级别由……授予。LeyApp团队——如果您的集成需要更多资源，请通过支持表单联系我们。匿名请求使用单独的、较低的每个 IP 地址的限制。
测试模式
测试密钥（leyk_test_）的行为与正式密钥完全相同——相同的端点、相同的验证、相同的响应形状——但实际上什么也没发生：没有存储预订意图，没有通知律师，任何内容都无法确认或支付。
测试流量会出现在控制面板的请求日志中（已标记），但不会包含在每日汇总数据中。正式发布时，只需将密钥替换为正式密钥即可，无需其他更改。
终点
/api/v1/lawyers/searchSearch verified lawyers
Same search engine as leyapp.es. Verified, publicly listed lawyers only. Scope: lawyers:read (anonymous allowed).
| 范围 | 类型 | 必需的 | 描述 |
|---|---|---|---|
| city | string | 不 | |
| practice_area | string | 不 | Slug from GET /practice-areas |
| language | string | 不 | |
| min_fee_eur | number | 不 | |
| max_fee_eur | number | 不 | |
| sort | string (rating | price_asc | price_desc | reviews) | 不 | |
| page | integer | 不 | |
| limit | integer | 不 |
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).
| 范围 | 类型 | 必需的 | 描述 |
|---|---|---|---|
| lawyerId | string | 是的 |
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).
| 范围 | 类型 | 必需的 | 描述 |
|---|---|---|---|
| lawyerId | string | 是的 | |
| start_date | string | 不 | Default: today |
| end_date | string | 不 | 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).
| 范围 | 类型 | 必需的 | 描述 |
|---|---|---|---|
| lawyerId | string | 是的 | |
| limit | integer | 不 |
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).
请求体
{
"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"}'文档中无法直接执行 POST 端点——请复制代码片段并使用测试密钥运行它。
/api/v1/booking-intents/{intentId}API需要密钥Poll a booking intent
Status of an intent CREATED BY YOUR KEY: pending | confirmed | expired. Requires an API key with bookings:read (not available anonymously).
| 范围 | 类型 | 必需的 | 描述 |
|---|---|---|---|
| intentId | string | 是的 |
curl "https://leyapp.es/api/v1/booking-intents/<intentId>" \ -H "Authorization: Bearer $LEYAPP_API_KEY"
网络钩子
订阅 HTTPS 端点（控制面板 → 开发者 → Webhooks）以接收使用您的密钥创建的预订意图的事件。请求传递遵循标准 Webhooks 规范，并会自动重试。
- 事件：booking_intent.confirmed / booking_intent.expired（意图阶段），以及完整的预订生命周期API-已发起的预订 — booking.approved、booking.cancelled、booking.completed。
- 使用在端点创建时显示的 whsec_ 签名密钥验证每个交付——官方的标准 Webhooks 库只需一次调用即可完成此操作。拒绝时间戳超过 ±5 分钟的请求。
- 至少发送一次：通过 webhook-id 标头（也是 payload ID）进行去重。payload 仅包含 ID 和状态——从 webhook-id 标头获取详细信息。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 和 AI 代理
比起写代码，你更喜欢聊天？LeyApp附带一个 MCP 服务器，包含 15 个工具——搜索、可用性、预订以及（经您同意）您自己的预订——适用于 Claude、ChatGPT、Cursor 和任何支持 MCP 的客户端。OAuth可设置细粒度的权限级别；可随时从控制面板 → 开发者撤销权限。
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.
更新日志
v1API仅进行新增操作：字段会被添加，不会重命名或删除。任何重大变更都会以新版本的形式发布，并在此处以及 Deprecation/Sunset 标头中公布 90 天的弃用窗口。
2026-07-22
Organization API keys & developer governance
- Law firms can now own API keys as an organization: keys survive staff changes, and firm admins manage them from Dashboard → Developer.
- Designated developers: firm admins can grant members view/manage/webhook access without making them org admins.
- Per-key IP allow-lists (exact IPs and CIDR ranges). Requests from other addresses get 403 ip_not_allowed.
- Org-visible audit trail of every key event (created, revoked, suspended, restrictions changed).
- Operational alerts (quota, error rate, webhook auto-disable) now go to firm admins for org keys.
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.
有任何疑问、需要提高限额或有合作意向？请通过支持表单联系我们——或者直接创建密钥并开始构建。