Ocorrências: GC ou GM

As ocorrências de uma empresa podem ser geridas em dois sistemas diferentes, conforme o que essa empresa contratou. A API é a mesma nos dois casos — mesmos caminhos, mesmos nomes de campos, mesma forma de resposta — mas o que cada um consegue guardar não é igual.

Tudo o resto — condomínios, frações, condóminos, fornecedores, contratos, correspondência, faturação e seguros — é idêntico nos dois casos. Esta página só diz respeito a ocorrências.

Descobrir qual

{
  "Occurrences": {
    "Source": "GC",
    "SupportedFilters": ["idBuilding", "status", "idTaskStatus", "idMaintenanceNature",
                         "idServiceType", "idPriority", "idFraction", "openedFrom", "openedTo"],
    "SupportedOperations": ["create", "claims", "assignment", "interventions", "update"]
  }
}

O ping diz-lhe a origem e, com ela, que filtros pode usar. Cada ocorrência traz também o seu Source.

Leia o ping no arranque

Se integra mais do que uma empresa, não presuma. Leia Source e SupportedFilters uma vez por empresa, e adapte-se — em vez de descobrir as diferenças por tentativa e erro em produção.

As diferenças

	GC	GM
Fração (IdFraction)	Sim	Não
Condómino (IdClient)	Sim	Não
Quem reportou, por nome (ReportedByName)	Não — é sempre alguém identificado	Sim
Natureza (IdMaintenanceNature)	Obrigatória	Obrigatória
Tipo de serviço (IdServiceType)	Obrigatório	Não existe
Localização (IdMaintenanceLocation)	Opcional	Obrigatória
Descrição normalizada (IdDescription)	Sim	Não
Visível para condóminos (IsVisibleToClients)	Sim	Não
Notificar (NotifyClient, Notify)	Sim	Não
Atribuir a	Fornecedor ou utilizador	Técnico
Sinistros	Sim	Sempre geridos no GC

Um campo que não se aplica é recusado, não ignorado: responde 400 UNSUPPORTED_FIELD, com field a dizer qual. É intencional — enviar uma fração e vê-la desaparecer em silêncio seria pior.

Abrir uma ocorrência

Em GC:

{
  "IdBuilding": 12,
  "IdFraction": 340,
  "IdClient": 87,
  "IdMaintenanceNature": 3,
  "IdServiceType": 7,
  "Description": "Infiltração no teto da garagem",
  "IsVisibleToClients": true,
  "NotifyClient": true
}

IdMaintenanceNature e IdServiceType são obrigatórios. ReportedByName é recusado: quem reporta é um condómino ou um utilizador identificado, indicado em IdClient.

Em GM:

{
  "IdBuilding": 12,
  "IdMaintenanceNature": 3,
  "IdMaintenanceLocation": 5,
  "Description": "Infiltração no teto da garagem",
  "ReportedByName": "Sr. Silva, do 3.º Dto."
}

IdMaintenanceLocation é obrigatório — sem ele a ocorrência fica registada mas não aparece nas listagens desse sistema. IdFraction, IdClient, IdServiceType, IdDescription, IsVisibleToClients e NotifyClient são recusados.

Quem reportou pode ir em ReportedByName, em texto livre. É a única forma de guardar essa informação aí, e não é um dado estruturado: não é pesquisável nem ligado a nenhum registo de pessoa.

Atribuir

POST /occurrences/{id}/assignment aceita um AssignedTo com Kind e Id. Quem pode receber depende da origem:

Origem	Kind aceites	Onde estão listados
GC	supplier, user	/suppliers e /assignees
GM	technician	/assignees

Chame sempre /assignees — devolve já o Kind correto para a empresa em causa, e é a forma de não ter esta tabela espalhada pelo seu código.

O que AssignedTo devolve numa leitura é exatamente o que se envia numa atribuição. Não tem de o converter.

Notificar

O campo Notify — na atribuição, na intervenção e na alteração de estado — só é aceite em GC. Em GM responde 400 UNSUPPORTED_FIELD. Envie-o a false, ou omita-o.

Sinistros

Os sinistros são sempre geridos no GC, mesmo nas empresas cujas ocorrências estão em GM. Os pontos /claims funcionam sempre da mesma maneira, com todos os campos, independentemente do Source que o ping indicar para as ocorrências.

Exige que a empresa tenha os sinistros configurados; se não tiver, responde 422 CLAIMS_NOT_CONFIGURED.

Identificadores não se misturam

Um identificador de ocorrência só tem significado dentro da sua origem. O mesmo vale para os cursores de sincronização. Se uma empresa mudar de sistema de ocorrências, recomece com uma leitura completa: os identificadores antigos não são reencontráveis.

Quando o sistema não responde

Nas empresas em GM, as ocorrências vivem num serviço separado. Se não responder, a API devolve 502 UPSTREAM_UNAVAILABLE em vez de uma lista vazia — que se leria como "esta empresa não tem ocorrências". Repita daqui a pouco.