API e server MCP di Zlar

Autenticazione

L'URL di base è https://zlar.app/api/v1. Crea una chiave API dell'organizzazione in Impostazioni, Chiavi API, e inviala a ogni richiesta come Authorization: Bearer <key>. Le chiavi appartengono a una sola organizzazione e smettono di funzionare se l'organizzazione lascia un piano che include l'accesso all'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 }
}

Endpoint

• GET /api/v1/condominiums: elencare i condomini
• GET /api/v1/condominiums/{id}: ottenere un condominio
• GET /api/v1/condominiums/{id}/owners: elencare i proprietari di un condominio
• GET /api/v1/condominiums/{id}/units: elencare le unità di un condominio
• GET /api/v1/condominiums/{id}/fiscal-years: elencare gli esercizi di un condominio
• GET /api/v1/condominiums/{id}/expenses: elencare le spese di un condominio
• GET /api/v1/fiscal-years/{id}/quotas: elencare le quote di un esercizio
• GET /api/v1/fiscal-years/{id}/payments: elencare i pagamenti di un esercizio

Gli endpoint di elenco sono paginati. Passa limit (da 1 a 100, predefinito 20) e, per la pagina successiva, il cursor opaco restituito in pagination.nextCursor. Quando pagination.hasMore è false hai raggiunto l'ultima pagina. Nuovi campi possono essere aggiunti alle risposte in qualsiasi momento, quindi ignora i campi che non riconosci.

Errori

Ogni errore è un oggetto JSON con un code leggibile dalle macchine, un message leggibile dalle persone, un hint su come risolverlo e il requestId, restituito anche nell'intestazione X-Request-Id. Indica l'identificativo della richiesta quando contatti l'assistenza.

{
  "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: il cursore di paginazione non è valido
• 401 API_KEY_INVALID: la chiave API manca, non è valida, è stata revocata o è scaduta
• 403 FEATURE_NOT_AVAILABLE: il piano dell'organizzazione non include l'accesso all'API
• 404 CONDOMINIUM_NOT_FOUND, 404 FISCAL_YEAR_NOT_FOUND: la risorsa non esiste nell'organizzazione della chiave
• 404 NOT_FOUND: l'endpoint non esiste
• 405 METHOD_NOT_ALLOWED: l'endpoint esiste ma non accetta questo metodo HTTP
• 429 RATE_LIMITED: troppe richieste; attendi il tempo indicato nell'intestazione Retry-After
• 500 INTERNAL_ERROR: un errore imprevisto da parte nostra; riprova più tardi

Limiti di richieste

Ogni chiave API può effettuare 120 richieste per finestra fissa di 60 secondi. Le risposte degli endpoint di dati includono un'intestazione RateLimit-Policy che descrive la quota. Dopo che una richiesta è stata conteggiata su una chiave, la risposta include anche un'intestazione RateLimit con le richieste rimanenti e i secondi al ripristino della finestra, secondo la bozza IETF per le intestazioni RateLimit. Una risposta 429 aggiunge un'intestazione Retry-After.

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

Versioni e deprecazione

La versione dell'API fa parte del percorso dell'URL (/api/v1). Le modifiche additive, come nuovi campi o nuovi endpoint, vengono rilasciate senza cambio di versione. Le modifiche incompatibili vengono rilasciate su un nuovo percorso, come /api/v2.

Al momento nessuna operazione è deprecata. Quando lo sarà, verrà contrassegnata come tale nel documento OpenAPI e risponderà con un'intestazione Deprecation (RFC 9745) e un'intestazione Sunset (RFC 8594) almeno 6 mesi prima della rimozione, ad esempio:

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

Server MCP

Gli agenti IA possono collegarsi al server MCP di Zlar all'indirizzo https://zlar.app/api/mcp. Implementa la versione 2026-07-28 del protocollo MCP con OAuth 2.1: il client si registra dinamicamente, l'utente accede e dà il consenso, e il token risultante è limitato al ruolo e all'organizzazione di quell'utente. Il server è di sola lettura e rispecchia le letture dell'API REST.