API e servidor MCP do Zlar

Autenticação

O URL base é https://zlar.app/api/v1. Crie uma chave de API da organização em Definições, Chaves de API, e envie-a em cada pedido como Authorization: Bearer <key>. As chaves pertencem a uma única organização e deixam de funcionar se a organização sair de um plano que inclua acesso à 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 condomínios
• GET /api/v1/condominiums/{id}: obter um condomínio
• GET /api/v1/condominiums/{id}/owners: listar os proprietários de um condomínio
• GET /api/v1/condominiums/{id}/units: listar as frações de um condomínio
• GET /api/v1/condominiums/{id}/fiscal-years: listar os exercícios de um condomínio
• GET /api/v1/condominiums/{id}/expenses: listar as despesas de um condomínio
• GET /api/v1/fiscal-years/{id}/quotas: listar as quotas de um exercício
• GET /api/v1/fiscal-years/{id}/payments: listar os pagamentos de um exercício

Os endpoints de listagem são paginados. Envie limit (de 1 a 100, por omissão 20) e, para a página seguinte, o cursor opaco devolvido em pagination.nextCursor. Quando pagination.hasMore é false, chegou à última página. Podem ser acrescentados novos campos às respostas a qualquer momento, por isso ignore os campos que não reconhece.

Erros

Cada erro é um objeto JSON com um code legível por máquinas, uma message legível por pessoas, uma hint sobre como o resolver e o requestId, que também é devolvido no cabeçalho X-Request-Id. Indique o identificador do pedido quando contactar o suporte.

{
  "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: o valor de cursor está mal formado
• 401 API_KEY_INVALID: a chave de API está em falta, é inválida, foi revogada ou expirou
• 403 FEATURE_NOT_AVAILABLE: o plano da organização não inclui acesso à API
• 404 CONDOMINIUM_NOT_FOUND, 404 FISCAL_YEAR_NOT_FOUND: o recurso não existe na organização da chave
• 404 NOT_FOUND: o endpoint não existe
• 405 METHOD_NOT_ALLOWED: o endpoint existe mas não aceita este método HTTP
• 429 RATE_LIMITED: demasiados pedidos; aguarde o tempo indicado no cabeçalho Retry-After
• 500 INTERNAL_ERROR: um erro inesperado do nosso lado; tente novamente mais tarde

Limites de pedidos

Cada chave de API pode fazer 120 pedidos por janela fixa de 60 segundos. As respostas dos endpoints de dados incluem um cabeçalho RateLimit-Policy que descreve a quota. Depois de um pedido ser contabilizado numa chave, a resposta inclui também um cabeçalho RateLimit com os pedidos restantes e os segundos até a janela reiniciar, segundo o rascunho do IETF para os cabeçalhos RateLimit. Uma resposta 429 acrescenta um cabeçalho Retry-After.

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

Versões e descontinuação

A versão da API faz parte do caminho do URL (/api/v1). Alterações aditivas, como novos campos ou novos endpoints, são lançadas sem mudança de versão. Alterações incompatíveis são lançadas num novo caminho, como /api/v2.

Nenhuma operação está descontinuada neste momento. Quando uma estiver, será marcada como tal no documento OpenAPI e responderá com um cabeçalho Deprecation (RFC 9745) e um cabeçalho Sunset (RFC 8594) pelo menos 6 meses antes de ser removida, por exemplo:

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

Servidor MCP

Os agentes de IA podem ligar-se ao servidor MCP do Zlar em https://zlar.app/api/mcp. Implementa a versão 2026-07-28 do protocolo MCP com OAuth 2.1: o cliente regista-se dinamicamente, o utilizador inicia sessão e dá consentimento, e o token resultante fica limitado à função e à organização desse utilizador. O servidor é só de leitura e reflete as leituras da API REST.