API, les claus del desenvolupador

Què és el desenvolupador API?

LeyApp exposa un API REST públic sota /api/v1 que et permet cercar advocats, consultar la disponibilitat i iniciar reserves des del teu propi lloc web, aplicació o eina interna. L'accés de lectura bàsic funciona sense cap credencial, però una clau API augmenta els límits de velocitat, desbloqueja punts finals addicionals i et proporciona un tauler de control amb les teves claus i l'ús.

Qualsevol compte d'LeyApp pot crear claus API — no cal cap tipus de compte especial. Les reserves iniciades a través del API mai no es carreguen automàticament: el client sempre confirma i paga a leyapp.es, de manera que la vostra integració mai no gestiona diners ni detalls de la targeta.

Crear una clau API

Les claus es gestionen des del teu tauler de control:

1. Obre el tauler de control → Desenvolupador des de la barra lateral.
2. Feu clic a "Crea clau" i doneu-li un nom descriptiu, p. ex. "Giny del lloc web (producció)".
3. Tria el tipus de clau: Live per a sol·licituds reals, o Test per a experimentar amb seguretat.
4. Copieu la clau immediatament i deseu-la en un lloc segur, com ara un gestor de contrasenyes o l'emmagatzematge secret del vostre proveïdor d'allotjament.

Claus de prova vs claus en viu

Les claus de prova (leyk_test_...) es comporten exactament com les claus en viu — mateixos punts finals, mateixes respostes, mateixa validació — amb una diferència crucial: no passa res real. Una sol·licitud de reserva de prova es comprova completament amb la disponibilitat real, però no es crea cap intenció de reserva ni es notifica cap advocat.

Les claus en viu (leyk_...) creen intencions de reserva reals. Quan un client segueix l'enllaç de confirmació d'una intenció en viu, se l'envia al flux normal de pagament i confirmació de LeyApp.

Utilitzant la teva clau

Envia la clau a l'encapçalament Authorization de cada petició: "Authorization: Bearer leyk_...". Les peticions sense clau encara funcionen per a punts finals públics, però amb límits de velocitat anònims més baixos.

Cada resposta inclou un capçalera X-Request-Id. Si alguna cosa es comporta de manera inesperada, inclou aquest ID quan contactis amb el servei d'assistència — ens permet trobar la teva sol·licitud exacta en segons.

Límits de velocitat

Les noves clau comencen en el nivell gratuït: 60 sol·licituds per minut i 5.000 al dia. Cada resposta t'indica la teva situació mitjançant els encapçalaments X-RateLimit-Limit i X-RateLimit-Remaining; si superes el límit, reps una resposta 429 amb un encapçalament Retry-After que t'indica quan tornar-ho a provar.

Hi ha nivells superiors per a socis que són atorgats per l'equip d'LeyApp — poseu-vos en contacte amb nosaltres a través del formulari de suport si la vostra integració necessita més capacitat.

Com guardar les claus de manera segura

Una clau d'API és una contrasenya per a la teva integració. Tracta-la com a tal:

• No posis mai una clau en codi client, aplicacions mòbils o repositoris públics — qualsevol que la pugui llegir pot gastar el teu límit de velocitat i actuar dins dels àmbits de la clau.
• Utilitza una clau separada per a cada integració o entorn, de manera que puguis revocar-ne una sense afectar les altres.
• Revoca les claus que ja no utilitzes. La revocació és immediata: les sol·licituds amb una clau revocada fallen en la següent crida.
• Si una clau pot haver-se filtrat, revoca-la immediatament a Dashboard → Developer i crea-ne una de substitució. La rotació és sense temps d'inactivitat: crea primer la nova clau, implementa-la i després revoca l'antiga.

Resolució de problemes

Rebo un 401 "Clau API invàlida".

Comproveu que l'encapçalament sigui exactament "Authorization: Bearer leyk_..." sense espais addicionals i que la clau no hagi estat revocada. Tingueu en compte que els tokens MCP (ley_...) de Configuració → API Tokens són una credencial diferent i no són vàlids a la interfície REST API.

M'apareix un 429 "Rate limit exceeded".

Has assolit la finestra per minut o per dia del teu nivell. Honra l'encapçalament Retry-After i torna a provar amb retard exponencial. Si assoleixes regularment el límit diari, pregunta'ns per un nivell superior.

Les meves reserves de prova mai no apareixen enlloc.

Això és així per disseny: les claus de prova validen tot però no creen res. Canvia a una clau en viu per crear intencions de reserva reals.