Programadores

Os dados do condomínio, por API.

Uma chave, uma API REST só de leitura com documentação OpenAPI, um cliente TypeScript e um conector MCP para os assistentes de IA.

Uma chave em dois minutos

Entre no Condie como administrador da organização e abra Definições › Chaves API (/dashboard/api-keys).
Clique em Nova chave, dê-lhe um nome, escolha os âmbitos e, se quiser, uma validade (90 dias ou um ano; sem validade por omissão).
Copie a chave no momento: começa por cda_ e só é mostrada uma vez. Depois disso a página mostra o prefixo, os âmbitos, o limite por minuto e o último uso, e permite revogá-la.

A API está incluída no período de teste e no plano Corporativo. Uma chave deixa de responder no dia em que o plano deixa de a incluir, e uma organização só vê os seus edifícios.

Os dados dos condóminos passam para o programa ou assistente que ligar com a chave. A organização tem de ter base legal para isso e informar os condóminos, como prevê o acordo de tratamento de dados (DPA).

Âmbitos

buildings:read Edifícios (leitura): edifícios, frações, assembleias, ocorrências, prazos legais.
owners:read Proprietários (leitura): nomes, frações e saldos; devedores e totais.
owners:contact Contactos e NIF (leitura): NIF, email e telefone dos proprietários; só com Proprietários.
payments:read Pagamentos (leitura): recibos de um edifício.
expenses:read Despesas (leitura): despesas de um edifício.
financialDocuments:read Documentos financeiros (leitura): avisos, recibos, créditos e anulações, um a um.
documentLinks:read Ligações entre documentos (leitura): que recibo pagou que aviso.
* Acesso total: todos os âmbitos.

API REST

Base https://api.condie.pt/api/v1, autenticação por cabeçalho Authorization: Bearer cda_…, respostas em JSON. Todos os endpoints são de leitura. A documentação interativa está em api.condie.pt/api/docs e o ficheiro OpenAPI em openapi.json.

curl https://api.condie.pt/api/v1/buildings \
  -H "Authorization: Bearer cda_A_SUA_CHAVE"

Uma lista vem como { data: […], count }, um registo como { data }:

{
  "data": [
    { "id": "cmq…", "name": "Edifício Exemplo", "address": "Rua …", "nif": "…" }
  ],
  "count": 1
}

Endpoints

GET /api/v1/buildings Os edifícios da organização. (buildings:read)
GET /api/v1/buildings/{id} Um edifício. (buildings:read)
GET /api/v1/buildings/{id}/units As frações, com permilagem e titular. (buildings:read)
GET /api/v1/buildings/{id}/owners Os proprietários, com o saldo da conta corrente. (owners:read)
GET /api/v1/arrears Devedores em mora, por edifício, com a antiguidade. (owners:read)
GET /api/v1/balances/summary Totais da conta corrente por edifício. (owners:read)
GET /api/v1/buildings/{id}/payments Recibos de um edifício. (payments:read)
GET /api/v1/buildings/{id}/expenses Despesas de um edifício. (expenses:read)
GET /api/v1/buildings/{id}/issues Ocorrências de um edifício. (buildings:read)
GET /api/v1/buildings/{id}/financial-documents Documentos financeiros de um edifício. (financialDocuments:read)
GET /api/v1/financial-documents/{id} Um documento financeiro. (financialDocuments:read)
GET /api/v1/buildings/{id}/document-links As ligações entre documentos (que recibo pagou que aviso). (documentLinks:read)
GET /api/v1/docs A lista dos endpoints, os âmbitos e a ligação ao OpenAPI. (qualquer chave)

Os identificadores ({id}) são os que a lista de edifícios devolve. Os valores são em euros; um saldo positivo quer dizer que o proprietário deve ao condomínio.

Cliente TypeScript

O pacote @condie/sdk é um cliente tipado, gerado a partir do OpenAPI publicado, por isso acompanha sempre a API em produção. Ainda não está publicado no npm: vive em packages/sdk do repositório do Condie e usa-se a partir daí (ou copiando src/index.ts e os tipos gerados).

import { createCondieClient } from "@condie/sdk";

const condie = createCondieClient({
  baseUrl: "https://api.condie.pt",
  apiKey: process.env.CONDIE_API_KEY!,
});

// Os edifícios da organização da chave
const { data, error } = await condie.GET("/v1/buildings");
if (error) throw new Error(error.error); // a mensagem vem em português
for (const b of data.data) console.log(b.id, b.name);

// Um edifício
const one = await condie.GET("/v1/buildings/{id}", {
  params: { path: { id: data.data[0].id } },
});
console.log(one.data?.data.address);

Os tipos geram-se com npm run generate:prod dentro do pacote, que lê o openapi.json acima.

Conector MCP para assistentes de IA

O Condie tem um servidor MCP só de leitura em https://api.condie.pt/api/mcp (transporte Streamable HTTP, sem sessão). Autentica-se com a mesma chave API, no cabeçalho Authorization; o assistente só vê o que os âmbitos da chave permitem e nunca escreve. A ligação por OAuth, em vez de colar a chave, está no roteiro.

Crie uma chave com os âmbitos Edifícios (leitura) e Proprietários (leitura), ou Acesso total. Para o NIF, o email e o telefone dos proprietários, junte Contactos e NIF (leitura).
Em claude.ai ou no Claude Desktop: Definições › Conectores › Adicionar conector personalizado, com o endereço acima. Se o conector pedir uma autenticação que a chave não permite, use a configuração por ficheiro (claude_desktop_config.json):
```
{
  "mcpServers": {
    "condie": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.condie.pt/api/mcp",
        "--header",
        "Authorization: Bearer cda_A_SUA_CHAVE"
      ]
    }
  }
}
```

No Claude Code, um comando:

claude mcp add --transport http condie https://api.condie.pt/api/mcp \
  --header "Authorization: Bearer cda_A_SUA_CHAVE"

Ferramentas

O servidor expõe estas ferramentas; cada uma pede o âmbito do endpoint equivalente:

list_buildings
get_building
list_units
list_owners
owner_balance
arrears
balances_summary
list_assemblies
get_assembly
list_issues
upcoming_deadlines
search

Cada pergunta corre na conta do assistente; não há custo por pergunta no Condie. Cada chamada fica registada em Definições › Chaves API, como os pedidos da API.

Limites e erros

Limite de pedidos: por chave, 100 pedidos por minuto por omissão, numa janela de 60 segundos partilhada pela API e pelo MCP. Acima disso a resposta é 429:
```
{ "error": "Rate limit exceeded", "retryAfterMs": 42000 }
```
401: cabeçalho em falta, chave inválida, revogada ou expirada. 403: âmbito em falta (a mensagem diz qual e quais a chave tem) ou plano sem API. 404: o registo não existe ou não é da organização da chave.
Erros: sempre { "error": "…" }, com uma frase em português.
Listas: a lista de edifícios devolve até 500 registos; o OpenAPI indica o máximo de cada lista.
Versões: o prefixo /api/v1 é a versão; uma alteração incompatível teria um prefixo novo e o antigo ficaria a responder durante um período de transição.

A disponibilidade da API está na página de estado dos serviços. Dúvidas e pedidos de endpoints: apoio@condie.pt. Como o Condie é feito está em tecnologia.