Condomínios

Os condomínios sob gestão da empresa. É por aqui que começa quase toda a integração: o identificador do condomínio é o que as frações, as ocorrências, os contratos, as apólices e a faturação pedem.

Listar condomínios

GET /buildings

Permissão · masterdata:read

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
includeInactive	booleano	false	Inclui os condomínios cuja gestão já terminou
limit	inteiro	500	Registos por página, no máximo 500
cursor	texto	—	Cursor da página seguinte. Ver Paginação

Pedido

curl "https://servidor.exemplo/api/integrations/v1/acme/buildings" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

{
  "Items": [
    {
      "Id": 12,
      "Code": "0012",
      "Name": "Edifício Girassol",
      "Address": "Rua das Flores, 120, R/C Esq.",
      "Place": "Lisboa",
      "ZipCode": "1200-195 Lisboa",
      "TaxId": "900123456",
      "Active": true
    }
  ],
  "Paging": {
    "Limit": 500,
    "NextCursor": null,
    "HasMore": false
  }
}

Campo	Tipo	Descrição
Id	inteiro	Identificador do condomínio. É o que os restantes pontos pedem
Code	texto	Código pelo qual a empresa o conhece. Estável, e é por ele que outros sistemas o referem
Name	texto	Designação do condomínio
Address	texto	Morada, já com a porta quando existe
Place	texto	Localidade
ZipCode	texto	Código postal com a localidade postal
TaxId	texto	Número de contribuinte do condomínio
Active	booleano	false quando a gestão do condomínio já terminou

O que não aparece nesta listagem

Condomínios ainda em angariação — que não estão sob gestão — nunca aparecem, nem com includeInactive=true. Por omissão também não aparecem os que já saíram de gestão: use includeInactive=true se precisar do histórico.

Erros

Estado	Código	Quando
400	INVALID_CURSOR	O cursor não foi emitido por esta API
401	INVALID_KEY · KEY_REVOKED · KEY_EXPIRED	Ver Autenticação
403	FORBIDDEN_SCOPE	A credencial não tem masterdata:read

---

Obter um condomínio

GET /buildings/{idBuilding}

Permissão · masterdata:read

Parâmetros

Parâmetro	Tipo	Descrição
idBuilding	inteiro	No caminho. O Id devolvido pela listagem

Pedido

curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

O mesmo objeto da listagem, sem envelope:

{
  "Id": 12,
  "Code": "0012",
  "Name": "Edifício Girassol",
  "Address": "Rua das Flores, 120, R/C Esq.",
  "Place": "Lisboa",
  "ZipCode": "1200-195 Lisboa",
  "TaxId": "900123456",
  "Active": true
}

Um condomínio cuja gestão terminou é devolvido por este ponto, com Active a false — ao contrário da listagem, que o omite por omissão. Quem já tem o identificador consegue sempre lê-lo.

Erros

Estado	Código	Quando
401	INVALID_KEY · KEY_REVOKED · KEY_EXPIRED	Ver Autenticação
403	FORBIDDEN_SCOPE	A credencial não tem masterdata:read
404	BUILDING_NOT_FOUND	Não existe condomínio com esse identificador nesta empresa

---

Traduzir um código em identificador

Se o seu sistema conhece os condomínios pelo código e não pelo identificador do GC, leia a listagem uma vez e construa a correspondência do seu lado:

const buildings = await readAll('/buildings?includeInactive=true')
const idByCode = new Map(buildings.map(building => [building.Code, building.Id]))

Vale a pena guardar essa correspondência: os condomínios mudam raramente, e relê-la a cada operação gasta o orçamento de pedidos no que já sabe.

Alguns pontos de escrita — abrir uma ocorrência, registar uma fatura — aceitam BuildingCode em vez de IdBuilding, precisamente para não obrigarem a esta tradução.