API y servidor MCP de Zlar

Autenticación

La URL base es https://zlar.app/api/v1. Crea una clave de API de la organización en Ajustes, Claves de API, y envíala en cada petición como Authorization: Bearer <key>. Las claves pertenecen a una sola organización y dejan de funcionar si la organización abandona un plan que incluya acceso a la API.

curl https://zlar.app/api/v1/condominiums?limit=20 \
  -H "Authorization: Bearer $ZLAR_API_KEY"

{
  "data": [
    {
      "id": "01J9Z3K8M2X4V6B8N0Q2R4T6W8",
      "name": "Edifício Atlântico",
      "address": "Rua das Flores 12",
      "city": "Lisboa",
      "country": "PT",
      "totalUnits": 24,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

Endpoints

• GET /api/v1/condominiums: listar comunidades
• GET /api/v1/condominiums/{id}: obtener una comunidad
• GET /api/v1/condominiums/{id}/owners: listar los propietarios de una comunidad
• GET /api/v1/condominiums/{id}/units: listar las unidades de una comunidad
• GET /api/v1/condominiums/{id}/fiscal-years: listar los ejercicios de una comunidad
• GET /api/v1/condominiums/{id}/expenses: listar los gastos de una comunidad
• GET /api/v1/fiscal-years/{id}/quotas: listar las cuotas de un ejercicio
• GET /api/v1/fiscal-years/{id}/payments: listar los pagos de un ejercicio

Los endpoints de listado están paginados. Envía limit (de 1 a 100, por defecto 20) y, para la página siguiente, el cursor opaco devuelto en pagination.nextCursor. Cuando pagination.hasMore es false, has llegado a la última página. Se pueden añadir campos nuevos a las respuestas en cualquier momento, así que ignora los campos que no reconozcas.

Errores

Cada error es un objeto JSON con un code legible por máquinas, un message legible por personas, una hint sobre cómo resolverlo y el requestId, que también se devuelve en la cabecera X-Request-Id. Indica el identificador de la petición cuando contactes con soporte.

{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid or missing API key.",
    "hint": "Send an organization API key as 'Authorization: Bearer <key>'. Create or rotate keys in Settings > API keys.",
    "requestId": "01J9Z3K8M2X4V6B8N0Q2R4T6W8"
  }
}

• 400 INVALID_CURSOR: el cursor de paginación está mal formado
• 401 API_KEY_INVALID: la clave de API falta, no es válida, se ha revocado o ha caducado
• 403 FEATURE_NOT_AVAILABLE: el plan de la organización no incluye acceso a la API
• 404 CONDOMINIUM_NOT_FOUND, 404 FISCAL_YEAR_NOT_FOUND: el recurso no existe en la organización de la clave
• 404 NOT_FOUND: el endpoint no existe
• 405 METHOD_NOT_ALLOWED: el endpoint existe pero no acepta este método HTTP
• 429 RATE_LIMITED: demasiadas peticiones; espera el tiempo indicado en la cabecera Retry-After
• 500 INTERNAL_ERROR: un error inesperado por nuestra parte; vuelve a intentarlo más tarde

Límites de peticiones

Cada clave de API puede hacer 120 peticiones por ventana fija de 60 segundos. Las respuestas de los endpoints de datos incluyen una cabecera RateLimit-Policy que describe la cuota. Una vez que una petición se contabiliza en una clave, la respuesta incluye además una cabecera RateLimit con las peticiones restantes y los segundos hasta que se reinicia la ventana, según el borrador del IETF para las cabeceras RateLimit. Una respuesta 429 añade una cabecera Retry-After.

RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=119;t=42

Versiones y obsolescencia

La versión de la API forma parte de la ruta de la URL (/api/v1). Los cambios aditivos, como campos o endpoints nuevos, se publican sin cambio de versión. Los cambios incompatibles se publican en una ruta nueva, como /api/v2.

Ninguna operación está obsoleta actualmente. Cuando lo esté, se marcará como tal en el documento OpenAPI y responderá con una cabecera Deprecation (RFC 9745) y una cabecera Sunset (RFC 8594) al menos 6 meses antes de eliminarse, por ejemplo:

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT

Servidor MCP

Los agentes de IA pueden conectarse al servidor MCP de Zlar en https://zlar.app/api/mcp. Implementa la versión 2026-07-28 del protocolo MCP con OAuth 2.1: el cliente se registra dinámicamente, el usuario inicia sesión y da su consentimiento, y el token resultante queda limitado al rol y la organización de ese usuario. El servidor es de solo lectura y refleja las lecturas de la API REST.