Ocorrências

Abrir, consultar, atribuir e acompanhar ocorrências de um condomínio.

Leia primeiro onde estão as ocorrências desta empresa

O que uma ocorrência pode guardar depende do sistema que as gere nesta empresa. O ping diz qual é, e Ocorrências: GC ou GM diz o que muda. Vale meia hora de leitura e poupa-lhe descobrir as diferenças por tentativa e erro.

Listar ocorrências

GET /occurrences

Permissão · occurrences:read

Parâmetros

Parâmetro	Tipo	Por omissão	`GC`	`GM`
`idBuilding`	inteiro	todos	sim	sim
`status`	texto	`all`	sim	sim
`idTaskStatus`	inteiro	todos	sim	sim
`idPriority`	inteiro	todas	sim	sim
`openedFrom`	data	—	sim	sim
`openedTo`	data	—	sim	sim
`idMaintenanceNature`	inteiro	todas	sim	não
`idServiceType`	inteiro	todos	sim	não
`idFraction`	inteiro	todas	sim	não
`include`	texto	—	`interventions`	não
`limit`	inteiro	`100`	sim	sim
`cursor`	texto	—	sim	sim

status aceita open, closed ou all. É um atalho para "está por fechar ou já fechou", sem ter de saber que estados desta empresa contam como fechados.

Um filtro que a origem não suporta responde 400 UNSUPPORTED_FILTER em vez de ser ignorado. O SupportedFilters do ping diz-lhe quais são, para não ter de os descobrir assim.

Pedido

bash

# as que estão por fechar num condomínio
curl "https://servidor.exemplo/api/integrations/v1/acme/occurrences?idBuilding=12&status=open" \
  -H "ApiKey: $GC_API_KEY"

# com o histórico incluído (só em GC)
curl "https://servidor.exemplo/api/integrations/v1/acme/occurrences?idBuilding=12&include=interventions" \
  -H "ApiKey: $GC_API_KEY"

Resposta · `200`

json

{
  "Items": [
    {
      "Source": "GC",
      "Id": 501,
      "Reference": "2026/0501",
      "IdBuilding": 12,
      "BuildingCode": "0012",
      "OpeningDate": "2026-09-20T09:14:00",
      "ClosingDate": null,
      "Status": { "Id": 1, "Description": "Em aberto" },
      "Closed": false,
      "Priority": { "Id": 3, "Description": "Normal" },
      "Nature": { "Id": 4, "Description": "Infiltrações" },
      "ServiceType": { "Id": 7, "Description": "Canalização" },
      "Location": null,
      "IdFraction": 340,
      "FractionCode": "A",
      "IdClient": 87,
      "OpenedByName": null,
      "AssignedTo": { "Kind": "supplier", "Id": 88, "Name": "Canalizações Sul, Lda." },
      "Description": "Infiltração no teto da garagem, junto ao lugar 14.",
      "IsVisibleToClients": true,
      "HasAttachment": true,
      "LastActivityDate": "2026-09-22T16:03:00",
      "Interventions": null,
      "Notes": null
    }
  ],
  "Paging": { "Limit": 100, "NextCursor": "NTAx", "HasMore": true }
}

Campo	Tipo	Descrição
`Source`	texto	`GC` ou `GM`. Que sistema respondeu
`Id`	inteiro	Identificador. Só tem significado dentro da sua origem
`Reference`	texto	Referência que a aplicação mostra ao utilizador
`IdBuilding` · `BuildingCode`	inteiro · texto	O condomínio
`OpeningDate`	data e hora	Quando foi aberta
`ClosingDate`	data e hora	Quando fechou. `null` enquanto estiver aberta
`Status`	objeto	Estado. Ver `/reference/task-statuses`
`Closed`	booleano	Se o estado atual a dá por terminada
`Priority`	objeto	Prioridade. Ver `/reference/priorities`
`Nature`	objeto	Natureza
`ServiceType`	objeto	Tipo de serviço. `null` em `GM`
`Location`	texto	Local dentro do edifício. Preenchido em `GM`
`IdFraction` · `FractionCode`	inteiro · texto	A fração. `null` em `GM`
`IdClient`	inteiro	O condómino que a reportou. `null` em `GM`
`OpenedByName`	texto	Quem reportou, em texto livre. Só em `GM`
`AssignedTo`	objeto	A quem está entregue. `null` se a ninguém
`Description`	texto	Descrição
`IsVisibleToClients`	booleano	Visível no portal dos condóminos. `null` em `GM`
`HasAttachment`	booleano	Tem ficheiro anexo
`LastActivityDate`	data e hora	Data da última intervenção registada
`Interventions`	lista	O histórico, quando pedido com `include=interventions`. `null` caso contrário
`Notes`	texto	Nota livre da ocorrência. Só em `GM`

A ordem é da mais recente para a mais antiga.

Campos a null não significam "vazio"

Um campo que a origem desta empresa não tem vem sempre a null — ServiceType e IdFraction em GM, Location e OpenedByName em GC. A forma da resposta é a mesma nos dois casos, de propósito, para que o seu código não tenha de mudar de forma.

Erros

Estado	Código	Quando
`400`	`INVALID_STATUS`	O `status` não é `open`, `closed` nem `all`
`400`	`INVALID_CURSOR`	O `cursor` não foi emitido por esta API
`400`	`UNSUPPORTED_FILTER`	Um filtro que a origem desta empresa não suporta
`400`	`UNSUPPORTED_INCLUDE`	`include` desconhecido, ou `interventions` numa empresa em `GM`
`401`	`INVALID_KEY` · `KEY_REVOKED` · `KEY_EXPIRED`	Ver Autenticação
`403`	`FORBIDDEN_SCOPE`	A credencial não tem `occurrences:read`
`404`	`BUILDING_NOT_FOUND`	O `idBuilding` não existe
`502`	`UPSTREAM_UNAVAILABLE`	Numa empresa em `GM`, esse sistema não respondeu

Obter uma ocorrência

GET /occurrences/{idOccurrence}

Permissão · occurrences:read

Parâmetros

Parâmetro	Tipo	Descrição
`idOccurrence`	inteiro	No caminho
`include`	texto	`interventions` para trazer o histórico. Aqui funciona também em `GM`

Pedido

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/occurrences/501?include=interventions" \
  -H "ApiKey: $GC_API_KEY"

Resposta · `200`

O mesmo objeto da listagem, sem envelope, com interventions preenchido quando pedido:

json

{
  "Source": "GC",
  "Id": 501,
  "Reference": "2026/0501",
  "Interventions": [
    {
      "Id": 9012,
      "Date": "2026-09-22T16:03:00",
      "Description": "Contactado o fornecedor. Visita marcada para 25/09.",
      "CreatedBy": { "Kind": "user", "Id": 14, "Name": "Ana Costa" },
      "TransferredTo": { "Kind": "supplier", "Id": 88, "Name": "Canalizações Sul, Lda." },
      "HasAttachment": false
    }
  ]
}

Campo da intervenção	Tipo	Descrição
`Id`	inteiro	Identificador da intervenção
`Date`	data e hora	Quando foi registada
`Description`	texto	O que foi registado
`CreatedBy`	objeto	Quem a registou
`TransferredTo`	objeto	A quem a ocorrência passou nesse momento. `null` se não mudou de mãos
`HasAttachment`	booleano	A intervenção tem ficheiro anexo

O histórico numa listagem só existe em GC

Numa empresa em GM, include=interventions funciona neste ponto mas não na listagem: aí obrigaria a uma chamada por linha. Percorra a listagem sem histórico e peça-o nas ocorrências que lhe interessarem.

Erros

Estado	Código	Quando
`400`	`UNSUPPORTED_INCLUDE`	`include` diferente de `interventions`
`401`	`INVALID_KEY` · `KEY_REVOKED` · `KEY_EXPIRED`	Ver Autenticação
`403`	`FORBIDDEN_SCOPE`	A credencial não tem `occurrences:read`
`404`	`OCCURRENCE_NOT_FOUND`	Não existe, ou é um sinistro — esses leem-se em `/claims`
`502`	`UPSTREAM_UNAVAILABLE`	Numa empresa em `GM`, esse sistema não respondeu

Descarregar um anexo

GET /occurrences/{idOccurrence}/attachment
GET /occurrences/{idOccurrence}/interventions/{idIntervention}/attachment

Permissão · occurrences:read

Devolve o ficheiro em si, com o seu tipo e nome — não um JSON com base64. Viaja um terço mais leve e pode entregar o fluxo diretamente a quem o consome.

bash

curl "https://servidor.exemplo/api/integrations/v1/acme/occurrences/501/attachment" \
  -H "ApiKey: $GC_API_KEY" \
  -o anexo.pdf

Confirme primeiro HasAttachment na ocorrência ou na intervenção; poupa um 404.

Um anexo por ocorrência, um por intervenção

Não há coleções de ficheiros. Uma ocorrência tem no máximo um anexo, e cada intervenção o seu. Para juntar mais documentos a um processo, registe intervenções — cada uma leva o seu ficheiro.

Erros

Estado	Código	Quando
`401`	`INVALID_KEY` · `KEY_REVOKED` · `KEY_EXPIRED`	Ver Autenticação
`403`	`FORBIDDEN_SCOPE`	A credencial não tem `occurrences:read`
`404`	`ATTACHMENT_NOT_FOUND`	Não há anexo, ou está registado mas o ficheiro não está no arquivo

Abrir uma ocorrência

POST /occurrences

Permissão · occurrences:write · aceita Idempotency-Key

Corpo

Campo	Tipo	`GC`	`GM`
`IdBuilding` ou `BuildingCode`	inteiro / texto	obrigatório	obrigatório
`Description`	texto	obrigatório	obrigatório
`IdMaintenanceNature`	inteiro	obrigatório	obrigatório
`IdServiceType`	inteiro	obrigatório	recusado
`IdMaintenanceLocation`	inteiro	opcional	obrigatório
`IdFraction`	inteiro	opcional	recusado
`IdClient`	inteiro	opcional	recusado
`IdDescription`	inteiro	opcional	recusado
`IdPriority`	inteiro	opcional	opcional
`IsVisibleToClients`	booleano	opcional	recusado
`NotifyClient`	booleano	opcional	recusado
`ReportedByName`	texto	recusado	opcional
`AttachmentFileName`	texto	opcional	opcional
`AttachmentBase64`	texto	opcional	opcional

Pode dar o condomínio por IdBuilding ou por BuildingCode — o segundo evita ter de traduzir códigos do seu sistema para identificadores do GC.

Pedido

bash

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/occurrences" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{
        "BuildingCode": "0012",
        "IdFraction": 340,
        "IdClient": 87,
        "IdMaintenanceNature": 4,
        "IdServiceType": 7,
        "IdPriority": 3,
        "Description": "Infiltração no teto da garagem, junto ao lugar 14.",
        "IsVisibleToClients": true,
        "NotifyClient": true
      }'

Resposta · `201`

json

{ "Source": "GC", "Id": 501, "Reference": "2026/0501" }

Guarde o Id e o Source: é assim que volta a esta ocorrência.

Anexar um ficheiro na abertura

O anexo viaja em base64, por ser um campo entre outros do mesmo pedido:

json

{
  "BuildingCode": "0012",
  "IdMaintenanceNature": 4,
  "IdServiceType": 7,
  "Description": "Infiltração no teto da garagem.",
  "AttachmentFileName": "foto-infiltracao.jpg",
  "AttachmentBase64": "/9j/4AAQSkZJRgABAQ..."
}

Dê sempre AttachmentFileName com a extensão correta — é dela que sai o tipo do ficheiro na descarga.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY`	Corpo em falta ou JSON inválido
`400`	`MISSING_FIELD`	Falta um campo obrigatório. `field` diz qual
`400`	`UNSUPPORTED_FIELD`	Um campo que a origem desta empresa não tem. `field` diz qual
`400`	`INVALID_REFERENCE`	Um identificador de tabela de referência não existe
`401`	`INVALID_KEY` · `KEY_REVOKED` · `KEY_EXPIRED`	Ver Autenticação
`403`	`FORBIDDEN_SCOPE`	A credencial não tem `occurrences:write`
`404`	`BUILDING_NOT_FOUND` · `FRACTION_NOT_FOUND`	O condomínio ou a fração não existem
`409`	`IDEMPOTENCY_KEY_REUSED`	A chave já foi usada noutro pedido
`422`	`MAINTENANCE_NOT_LICENSED`	A empresa não tem o módulo de manutenção
`422`	`OCCURRENCE_NOT_CREATED`	Não chegou a ser criada. Reporte
`502`	`UPSTREAM_UNAVAILABLE`	Numa empresa em `GM`, esse sistema não respondeu

Atribuir uma ocorrência

POST /occurrences/{idOccurrence}/assignment

Permissão · occurrences:write · aceita Idempotency-Key

Entrega a ocorrência a quem a vai tratar, e regista no histórico a razão.

Corpo

Campo	Tipo	Descrição
`AssignedTo`	objeto	Obrigatório. `{ kind, id }`. Ver Destinatários
`Note`	texto	O que fica no histórico
`Notify`	booleano	Notificar. Recusado em `GM`
`AttachmentFileName`	texto	Nome do ficheiro a anexar
`AttachmentBase64`	texto	Conteúdo do ficheiro

Pedido

bash

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/occurrences/501/assignment" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "AssignedTo": { "Kind": "supplier", "Id": 88 },
        "Note": "Adjudicada a reparação conforme orçamento de 22/09.",
        "Notify": true
      }'

Resposta · `201`

json

{ "Id": 9013 }

O identificador da entrada criada no histórico.

Quem pode receber

Origem	`Kind` aceites
`GC`	`supplier` (de `/suppliers`) ou `user` (de `/assignees`)
`GM`	`technician` (de `/assignees`)

Um Kind que a origem não aceita responde 400 UNSUPPORTED_FIELD em AssignedTo.Kind.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY` · `MISSING_FIELD`	Corpo inválido, ou falta `AssignedTo`
`400`	`UNSUPPORTED_FIELD`	`Kind` não aceite nesta origem, ou `Notify` em `GM`
`401` · `403`		Ver Autenticação e Permissões
`404`	`OCCURRENCE_NOT_FOUND` · `SUPPLIER_NOT_FOUND`	A ocorrência ou o destinatário não existem
`409`	`IDEMPOTENCY_KEY_REUSED`	A chave já foi usada noutro pedido
`502`	`UPSTREAM_UNAVAILABLE`	Numa empresa em `GM`, esse sistema não respondeu

Registar uma intervenção

POST /occurrences/{idOccurrence}/interventions

Permissão · occurrences:write · aceita Idempotency-Key

Acrescenta uma entrada ao histórico. A ocorrência não muda de estado nem de responsável — é a forma de registar o que se passou sem mexer no processo.

Corpo

Campo	Tipo	Descrição
`Description`	texto	Obrigatório. O que fica registado
`Notify`	booleano	Notificar. Recusado em `GM`
`AttachmentFileName`	texto	Nome do ficheiro a anexar
`AttachmentBase64`	texto	Conteúdo do ficheiro

Pedido

bash

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/occurrences/501/interventions" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "Description": "Técnico no local. Identificada rutura na conduta do 2.º piso.",
        "Notify": false,
        "AttachmentFileName": "relatorio-visita.pdf",
        "AttachmentBase64": "JVBERi0xLjQKJ..."
      }'

Resposta · `201`

json

{ "Id": 9014 }

Não há notas internas

Tudo o que acrescenta ao histórico é matéria da ocorrência. Não existe distinção entre visível e reservado — se a nota não deve ser vista por ninguém de fora, não a registe aqui.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY` · `MISSING_DESCRIPTION`	Corpo inválido, ou sem descrição
`400`	`UNSUPPORTED_FIELD`	`Notify` numa empresa em `GM`
`401` · `403`		Ver Autenticação e Permissões
`404`	`OCCURRENCE_NOT_FOUND`	Não existe ocorrência com esse identificador
`409`	`IDEMPOTENCY_KEY_REUSED`	A chave já foi usada noutro pedido
`502`	`UPSTREAM_UNAVAILABLE`	Numa empresa em `GM`, esse sistema não respondeu

Alterar estado ou prioridade

PATCH /occurrences/{idOccurrence}

Permissão · occurrences:write · aceita Idempotency-Key

Corpo

Campo	Tipo	Descrição
`IdStatus`	inteiro	Novo estado. Ver `/reference/task-statuses`
`IdPriority`	inteiro	Nova prioridade. Ver `/reference/priorities`
`ClosedAt`	data e hora	Data de fecho. Só se aplica a um estado que fecha
`Note`	texto	Obrigatório. A razão, que fica no histórico
`Notify`	booleano	Notificar. Recusado em `GM`

Pelo menos um de IdStatus ou IdPriority é obrigatório. Os dois podem vir juntos — é uma única alteração, não duas.

Pedido

bash

# fechar
curl -X PATCH "https://servidor.exemplo/api/integrations/v1/acme/occurrences/501" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "IdStatus": 3,
        "ClosedAt": "2026-09-25T17:30:00",
        "Note": "Reparação concluída e confirmada pelo condómino.",
        "Notify": true
      }'

# subir a prioridade
curl -X PATCH "https://servidor.exemplo/api/integrations/v1/acme/occurrences/501" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "IdPriority": 1, "Note": "Agravamento: infiltração atingiu o quadro elétrico." }'

Resposta · `204`

Sem corpo.

Os identificadores de estado dependem da origem

Os valores de /reference/task-statuses de uma empresa em GC são recusados numa empresa em GM e vice-versa. Leia a tabela por empresa e não fixe números no código. Ver Tabelas de referência.

Erros

Estado	Código	Quando
`400`	`INVALID_BODY` · `MISSING_FIELD`	Corpo inválido, ou sem `IdStatus` nem `IdPriority`, ou sem `Note`
`400`	`INVALID_REFERENCE`	O estado ou a prioridade não existem nesta origem
`400`	`UNSUPPORTED_FIELD`	`Notify` numa empresa em `GM`
`401` · `403`		Ver Autenticação e Permissões
`404`	`OCCURRENCE_NOT_FOUND`	Não existe ocorrência com esse identificador
`409`	`IDEMPOTENCY_KEY_REUSED`	A chave já foi usada noutro pedido
`502`	`UPSTREAM_UNAVAILABLE`	Numa empresa em `GM`, esse sistema não respondeu

Acompanhar alterações

GET /occurrences/changes

Para manter uma cópia atualizada sem varrer tudo de cada vez. Ver Sincronização incremental, onde o fluxo completo está explicado.

Ocorrências ​

Listar ocorrências ​

Parâmetros ​

Pedido ​

Resposta · 200 ​

Erros ​

Obter uma ocorrência ​

Parâmetros ​

Pedido ​

Resposta · 200 ​

Erros ​

Descarregar um anexo ​

Erros ​

Abrir uma ocorrência ​

Corpo ​

Pedido ​

Resposta · 201 ​

Anexar um ficheiro na abertura ​

Erros ​

Atribuir uma ocorrência ​

Corpo ​

Pedido ​

Resposta · 201 ​

Quem pode receber ​

Erros ​

Registar uma intervenção ​

Corpo ​

Pedido ​

Resposta · 201 ​

Erros ​

Alterar estado ou prioridade ​

Corpo ​

Pedido ​

Resposta · 204 ​

Erros ​

Acompanhar alterações ​

Ocorrências

Listar ocorrências

Parâmetros

Pedido

Resposta · `200`

Erros

Obter uma ocorrência

Parâmetros

Pedido

Resposta · `200`

Erros

Descarregar um anexo

Erros

Abrir uma ocorrência

Corpo

Pedido

Resposta · `201`

Anexar um ficheiro na abertura

Erros

Atribuir uma ocorrência

Corpo

Pedido

Resposta · `201`

Quem pode receber

Erros

Registar uma intervenção

Corpo

Pedido

Resposta · `201`

Erros

Alterar estado ou prioridade

Corpo

Pedido

Resposta · `204`

Erros

Acompanhar alterações