Tabelas de referência

As listas de valores que a empresa configura: naturezas, tipos de serviço, prioridades, estados, tipos de tarefa, origens de contacto, tipos de fração e tipos de fornecedor.

São o que traduz os identificadores que as leituras devolvem, e a origem dos identificadores que as escritas exigem.

Listar as tabelas disponíveis

GET /reference

Permissão · masterdata:read

Pedido

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

Resposta · 200

[
  "contact-origins",
  "fraction-types",
  "maintenance-natures",
  "priorities",
  "service-types",
  "supplier-types",
  "task-statuses",
  "task-types"
]

---

Obter uma tabela

GET /reference/{nome}

Permissão · masterdata:read

Pedido

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

Resposta · 200

Um array simples, sem envelope — são conjuntos de poucas entradas e não há nada por onde paginar.

[
  { "Id": 1, "Description": "Em aberto", "Flags": { "Closed": false, "DefaultStatus": true } },
  { "Id": 2, "Description": "Em curso",  "Flags": { "Closed": false, "DefaultStatus": false } },
  { "Id": 3, "Description": "Resolvida", "Flags": { "Closed": true,  "DefaultStatus": false } }
]

Campo	Tipo	Descrição
Id	inteiro	Identificador. É o que se envia nas escritas e o que as leituras devolvem
Description	texto	Designação, definida pela empresa e alterável
Flags	objeto	Marcas que dizem o que a entrada significa

Nunca compare pela descrição

As descrições são texto livre que a empresa pode renomear a qualquer momento — "Em aberto" pode passar a "Aberta" sem aviso. Decida sempre pelo Id ou pelas Flags. Um if (Description === "Resolvida") parte-se na primeira vez que alguém edita a tabela.

As marcas de cada tabela

As Flags são o que permite interpretar uma entrada sem depender do texto:

Tabela	Marcas	O que dizem
task-statuses	Closed, DefaultStatus	Qual o estado que dá a ocorrência por terminada, e qual o inicial
priorities	Urgent, High, Normal, Low	Que grau cada prioridade representa
task-types	Occurrence, Deliberation, ContractRenovation, PreventiveMaintenance, Claim	Que natureza de tarefa a entrada representa. claim marca os sinistros
maintenance-natures	IsFraction	Se a natureza diz respeito a uma fração e não às partes comuns
fraction-types	Habitation	Se o tipo é de habitação
supplier-types	Insurance, IntermediaryInsurance, MaintenanceService, EnforcementOfficer, Lawyer, Solicitor	Os papéis do fornecedor
service-types	—	Sem marcas
contact-origins	Meeting, User, Supplier, Manager, Client, Phone, BuildingManager, Occurrence, Contract	De onde veio o contacto

Exemplo de como usar as marcas em vez do texto:

const statuses = await get('/reference/task-statuses')

const closedIds = new Set(statuses.filter(status => status.Flags.Closed)
                                  .map(status => status.Id))
const defaultStatus = statuses.find(status => status.Flags.DefaultStatus)

//assim isto continua certo mesmo que a empresa renomeie ou acrescente estados
const isFinished = closedIds.has(occurrence.Status.Id)

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	REFERENCE_NOT_FOUND	Não existe tabela com esse nome. Chame /reference para a lista

---

Estados e prioridades dependem de onde estão as ocorrências

Nas empresas cujas ocorrências são geridas em GM, task-statuses e priorities não vêm das tabelas desta empresa: vêm do sistema que as guarda, onde são valores fixos.

task-statuses

[
  { "Id": 1, "Description": "Ativo",      "Flags": { "Closed": false } },
  { "Id": 2, "Description": "Cancelado",  "Flags": { "Closed": true } },
  { "Id": 3, "Description": "Por Validar","Flags": { "Closed": false } },
  { "Id": 4, "Description": "Concluído",  "Flags": { "Closed": true } }
]

priorities

[
  { "Id": 1, "Description": "Baixa" },
  { "Id": 2, "Description": "Média" },
  { "Id": 3, "Description": "Alta" },
  { "Id": 4, "Description": "Urgente" }
]

Note que aí as prioridades não trazem marcas e os estados só trazem Closed — é a única que sobrevive à passagem entre sistemas.

Leia sempre estas duas tabelas por empresa

Não fixe identificadores de estado ou de prioridade no seu código. Os de uma empresa em GC são recusados numa empresa em GM e vice-versa. O ping diz-lhe qual é o caso antes de precisar de adivinhar. Ver Ocorrências: GC ou GM.

As restantes tabelas vêm sempre desta empresa, independentemente da origem das ocorrências.