Contratos de manutenção

Os contratos de manutenção de um condomínio, com o tipo de serviço, quem o presta e a periodicidade.

É o que diz a quem uma ocorrência de determinado tipo de serviço deve ser entregue — a aplicação usa o mesmo critério quando atribui automaticamente.

Listar os contratos de um condomínio

GET /buildings/{idBuilding}/maintenance-contracts

Permissão · masterdata:read

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
idBuilding	inteiro	—	No caminho. O condomínio
activeOn	data	todos	Só os contratos em vigor nessa data

Pedido

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

# os que estão em vigor hoje
curl "https://servidor.exemplo/api/integrations/v1/acme/buildings/12/maintenance-contracts?activeOn=2026-09-25" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

Array simples, sem envelope — um condomínio tem poucos contratos.

[
  {
    "Id": 55,
    "IdBuilding": 12,
    "BuildingCode": "0012",
    "ServiceType": { "Id": 7, "Description": "Elevadores" },
    "Description": { "Id": 3, "Description": "Manutenção preventiva mensal" },
    "AssignedTo": { "Kind": "supplier", "Id": 88, "Name": "Elevadores Norte, Lda." },
    "SporadicService": false,
    "BeginDate": "2024-01-01T00:00:00",
    "DurationMonths": 12,
    "EndDate": null,
    "SelfRenewing": true,
    "RenewalDays": 30,
    "TerminationAlertDays": 60,
    "Periodicity": { "Id": 2, "Description": "Mensal" },
    "DaysOfWeek": "2",
    "CreatesTasksAutomatically": true,
    "HasFile": true
  }
]

Campo	Tipo	Descrição
Id	inteiro	Identificador do contrato
IdBuilding · BuildingCode	inteiro · texto	O condomínio
ServiceType	objeto	Tipo de serviço. Ver /reference/service-types
Description	objeto	Designação do contrato. Pode vir a null
AssignedTo	objeto	Quem presta o serviço. Pode vir a null
SporadicService	booleano	true num contrato chamado quando é preciso, e não com periodicidade
BeginDate	data	Início
DurationMonths	inteiro	Duração em meses
EndDate	data	Fim. null num contrato sem termo definido
SelfRenewing	booleano	Renova-se automaticamente
RenewalDays	inteiro	Dias de antecedência da renovação. Pode vir a null
TerminationAlertDays	inteiro	Dias de antecedência do aviso de denúncia. Pode vir a null
Periodicity	objeto	Periodicidade das intervenções. Pode vir a null
DaysOfWeek	texto	Dias da semana das intervenções
CreatesTasksAutomatically	booleano	A aplicação abre as tarefas de manutenção sozinha
HasFile	booleano	Existe um ficheiro do contrato arquivado

Num contrato esporádico, a periodicidade não diz nada

Com SporadicService a true, os campos Periodicity e DaysOfWeek não têm significado — o contrato é chamado quando é necessário. Ignore-os nesse caso.

Quem presta o serviço

"AssignedTo": { "Kind": "supplier", "Id": 88, "Name": "Elevadores Norte, Lda." }

Kind	Significado	Onde está listado
supplier	Um fornecedor externo	/suppliers
user	Um utilizador da empresa	/assignees

Um contrato é de um ou de outro, nunca dos dois. Quando não tem nenhum atribuído, AssignedTo vem a null.

É a mesma forma usada nas ocorrências, de propósito: o que sai de um AssignedTo entra diretamente numa atribuição.

O ficheiro do contrato

HasFile diz que existe um ficheiro arquivado, mas a v1 não o serve. Só os anexos de ocorrências e de intervenções têm ponto de descarga.

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