Desarrolladores

Documentación para agentes y API

Sententia expone los datos procesales de un despacho a través de un servidor MCP (Model Context Protocol) autenticado con OAuth 2.1 o token personal. Esta página describe cómo conectarse, qué herramientas hay disponibles y qué límites de uso se aplican.

1. Cuándo usar esta API

Esta API es la adecuada cuando la tarea trata sobre el trabajo procesal de un despacho de abogados español y hace falta acceder a datos reales del expediente: consultar los casos abiertos, leer el contenido de una evidencia, revisar los hechos y peticiones de una demanda, controlar plazos y vistas, o registrar anotaciones del abogado. También permite crear casos y actualizar sus campos.

No es la herramienta adecuada para asesoramiento jurídico genérico sin expediente, para jurisdicciones fuera de España, ni para consultas que no requieran datos de un despacho concreto.

2. Recursos

/openapi.json — especificación OpenAPI 3.1 de la superficie pública.
/llms.txt — índice del sitio legible por agentes.
/.well-known/oauth-authorization-server — descubrimiento del Authorization Server (RFC 8414).
/.well-known/oauth-protected-resource/mcp — metadatos del recurso protegido (RFC 9728).

3. Autenticación

El acceso usa OAuth 2.1 con authorization code + PKCE (método S256) y admite registro dinámico de clientes (RFC 7591), de modo que un agente puede darse de alta sin intervención manual. Los scopes disponibles son casos (datos procesales) y cendoj (jurisprudencia).

Los access token tienen una validez de 1 hora y los refresh token de 30 días. Usa siempre el host canónico https://www.sententia.studio: el endpoint de token no debe seguir redirecciones, por lo que un salto del dominio apex al canónico rompería el intercambio.

También puedes crear un token personal en Integraciones → Sententia Expedientes → Token de acceso / Desktop y enviarlo en la cabecera Authorization: Bearer <token>. Son los mismos tokens que CENDOJ: permiten acceder a los expedientes de tu cuenta hasta su revocación o regeneración. No los incluyas en URLs ni los compartas.

# 1. Registro dinámico del cliente
curl -X POST https://www.sententia.studio/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Mi agente","redirect_uris":["http://localhost:8765/callback"]}'

# 2. Autorización en el navegador (PKCE S256)
https://www.sententia.studio/oauth/authorize?response_type=code&client_id=...&redirect_uri=...
  &code_challenge=...&code_challenge_method=S256&scope=casos

# 3. Canje del código por un token
curl -X POST https://www.sententia.studio/oauth/token \
  -d grant_type=authorization_code -d code=... \
  -d redirect_uri=... -d client_id=... -d code_verifier=...

4. Endpoint MCP

El servidor MCP sententia-expedientes vive en https://www.sententia.studio/mcp y habla JSON-RPC 2.0 sobre HTTP POST. Requiere un token personal o un token OAuth con el scope casos. Soporta los métodos initialize, tools/list y tools/call.

curl -X POST https://www.sententia.studio/mcp \
  -H "Authorization: Bearer mcp_at_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_cases","arguments":{"limit":10}}}'

5. Herramientas disponibles

list_cases	Lista los casos de la organización, con filtros y paginación.
get_case	Devuelve el detalle completo de un caso por su UUID.
list_evidences	Lista las evidencias documentales asociadas a un caso.
read_evidence	Devuelve el contenido extraído de una evidencia.
list_claims	Lista los hechos y alegaciones de la demanda.
list_petitions	Lista las peticiones o súplicas dirigidas al juez.
list_legal_references	Lista la normativa y jurisprudencia citadas en el caso.
list_comments	Lista las anotaciones del abogado sobre las evidencias.
list_deadlines	Lista plazos procesales y eventos: vistas, notificaciones, citaciones.
add_comment	Añade una anotación del abogado a una evidencia.
create_deadline	Crea un plazo procesal o evento en un caso.
update_deadline	Actualiza un plazo: fecha, título o marcarlo completado.
update_case	Actualiza campos seguros de un caso.
create_case	Crea un nuevo caso en la organización del usuario.

6. Límites de uso

El endpoint MCP admite 120 peticiones por minuto y token. Todas las respuestas incluyen las cabeceras de la RFC 9331 para que el cliente pueda autorregularse sin llegar al rechazo:

RateLimit-Limit — peticiones permitidas en la ventana.
RateLimit-Remaining — peticiones restantes.
RateLimit-Reset — segundos hasta reiniciar la ventana.
Retry-After — enviada junto al 429, indica cuántos segundos esperar antes de reintentar.

7. Errores

Los errores se devuelven como objetos JSON-RPC con un campo error. Un 401 indica token ausente, inválido o revocado e incluye la cabecera WWW-Authenticate con la URL de los metadatos del recurso; un 403 significa que el token no tiene el scope casos; un 429 que se ha superado el límite de peticiones.

8. Acceso y pruebas

Sententia se contrata por suscripción y el acceso a la API va ligado a una cuenta activa del despacho. Los planes y sus condiciones están publicados en la página de inicio. Para solicitar acceso de evaluación, credenciales de prueba o resolver dudas de integración, escribe a info@sententia.studio.