Antes de integrar
La cuenta determina la base de URL y los permisos del usuario determinan qué datos puede consultar o modificar.
Direcciones y autenticación
Cada organización usa https://{cuenta}.despacho.pe. La API vive bajo /api/ y el MCP en /api/mcp/rpc. El MCP acepta un token OAuth en Authorization: Bearer …, emitido por el servidor de la misma cuenta. Descubre las rutas de autorización en /.well-known/oauth-authorization-server y los metadatos del recurso en /.well-known/oauth-protected-resource.
El flujo implementado para MCP es código de autorización con PKCE S256, registro dinámico de cliente y tokens de renovación. La aplicación de la cuenta presenta el consentimiento al usuario. Para las rutas REST de expedientes, caja y bancos, agenda, ventas, compras, horas, contratos y documentos se usa un token de API personal de la misma cuenta en Authorization: Bearer TOKEN_PERSONAL. Actúa con los permisos del usuario que lo creó y solo en las operaciones publicadas en esta referencia: cualquier otra ruta responde 403. Se crea desde Perfil → Tokens de API en la aplicación y el valor se muestra una sola vez; guárdalo en tu cliente, no en este portal. Los tokens personales de API no acreditan los permisos mcp:read ni mcp:write.
Permisos
mcp:read permite intentar llamadas a herramientas de consulta; mcp:write permite intentar las tres herramientas que escriben. Cada herramienta aplica además los permisos del usuario. El token queda asociado a la cuenta que lo emitió y no autentica otra cuenta. Un scope OAuth no concede acceso a las demás rutas de /api/. El catálogo tools/list muestra las 12 herramientas aunque un token no tenga permiso para ejecutar todas.
Paginación y filtros
Las herramientas de listado aceptan pagina desde 1 y limite entre 1 y 50; el valor por defecto es 20. Responden con items, num_items, pagina y paginas. Algunas listas tienen un tope de resultados, por lo que conviene consultar páginas y filtros concretos. campos permite pedir un subconjunto de los campos publicados para cada herramienta. La respuesta puede incluir truncado: true y items_devueltos cuando se supera el presupuesto de tamaño. Los listados REST usan pg e items_x_pag en el cuerpo JSON: la página predeterminada es 1. El tamaño predeterminado es 50. El máximo es 50 para actuaciones procesales, 500 para expedientes y 200 para los demás listados aquí documentados. La respuesta devuelve items, num_items, pagina, item_desde, item_hasta, paginas e items_x_pag. Las operaciones OAuth documentadas no tienen paginación.
Errores
Las operaciones OAuth responden directamente con {"error":"…","error_description":"…"} en sus errores. La API puede devolver la envoltura general {"error":true,"data":null,"mensaje":"…","codigo":429,"otros":null} al limitar tráfico. Una llamada MCP sin token recibe HTTP 401 con WWW-Authenticate; las fallas JSON-RPC de método o parámetros usan HTTP 200 y un objeto error. Una herramienta sin scope suficiente devuelve isError: true en el resultado MCP. Las operaciones REST de los módulos responden con error, data, mensaje, codigo y otros; un error de negocio puede llegar con HTTP 200 y error: true, así que comprueba ambos datos.
Límites
El registro dinámico tiene un cupo adicional de cinco solicitudes por IP y hora. La API aplica límites por IP y, para solicitudes autenticadas, por usuario. El MCP tiene además un cupo configurable por usuario y cliente OAuth. Los umbrales configurables pueden variar entre instalaciones; una respuesta 429 puede incluir Retry-After: 60. Las respuestas MCP pueden recortar textos largos o truncarse; en ese caso incluyen truncado: true.