Pessoas

Os condóminos e demais pessoas ligadas a uma fração, e a procura de uma pessoa pelos seus contactos.

Dados pessoais

Esta área devolve nomes, moradas de correio, telefones e números de contribuinte de pessoas singulares. Requer people:read, que é concedido caso a caso, e traz consigo as obrigações de tratamento de dados pessoais que o seu sistema tem de cumprir.

Pessoas de uma fração

GET /fractions/{idFraction}/clients

Permissão · people:read

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
idFraction	inteiro	—	No caminho. A fração
currentOnly	booleano	true	Apenas as ligações em vigor. false traz também as que terminaram

Pedido

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

Resposta · 200

Array simples, sem envelope — uma fração tem poucas pessoas ligadas.

[
  {
    "IdFraction": 340,
    "IdClient": 87,
    "Code": "C0087",
    "Name": "Maria Silva",
    "SecondName": "",
    "Relation": "proprietary",
    "BeginDate": "2019-03-01T00:00:00",
    "EndDate": null,
    "Percentage": 100.0,
    "EMails": ["maria.silva@exemplo.pt"],
    "Phones": ["213456789"],
    "MobilePhones": ["912345678"],
    "Authorisations": {
      "EMail": true,
      "SMS": true,
      "Phone": false,
      "SharePhone": false
    }
  }
]

Campo	Tipo	Descrição
IdFraction	inteiro	A fração
IdClient	inteiro	A pessoa. É o IdClient que abrir uma ocorrência aceita
Code	texto	Código da pessoa na empresa
Name	texto	Nome
SecondName	texto	Segundo titular, quando a posição é partilhada
Relation	texto	O papel. Ver a tabela abaixo
BeginDate	data	Início da ligação à fração
EndDate	data	Fim da ligação. null enquanto estiver em vigor
Percentage	decimal	Quota-parte na propriedade. null no arrendamento
emails	lista de texto	Endereços de correio
Phones	lista de texto	Telefones fixos
MobilePhones	lista de texto	Telemóveis
Authorisations	objeto	O que a pessoa autorizou. Ver abaixo

Os papéis

Relation	Significado
proprietary	Proprietário
usufructuary	Usufrutuário
proxy	Procurador
renter	Locatário, na ficha de propriedade
tenant	Arrendatário, do registo de arrendamento, com datas próprias

Uma fração pode ter várias pessoas em simultâneo, com papéis diferentes — e mais do que uma no mesmo papel, quando a propriedade é partilhada. O Percentage diz a quota-parte de cada uma.

Autorizações de contacto

"Authorisations": { "EMail": true, "SMS": true, "Phone": false, "SharePhone": false }

Campo	O que autoriza
email	Ser contactada por correio eletrónico
SMS	Ser contactada por SMS
Phone	Ser contactada por telefone
SharePhone	O seu telefone ser partilhado com terceiros

Respeite as autorizações

São o registo do que a pessoa consentiu. Enviar uma mensagem a quem tem email a false, ou entregar o telefone de quem tem SharePhone a false a um fornecedor, é responsabilidade de quem o faz. A API entrega os contactos; a decisão de os usar é sua.

Erros

Estado	Código	Quando
401	INVALID_KEY · KEY_REVOKED · KEY_EXPIRED	Ver Autenticação
403	FORBIDDEN_SCOPE	A credencial não tem people:read
404	FRACTION_NOT_FOUND	Não existe fração com esse identificador

---

Procurar uma pessoa

GET /clients/search

Permissão · people:read

Encontra uma pessoa pelo contacto, e devolve todas as frações a que está ligada, em todos os condomínios. É o que permite identificar quem está do outro lado de um telefonema ou de uma mensagem.

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
email	texto	—	Endereço de correio
phone	texto	—	Telefone ou telemóvel
taxId	texto	—	Número de contribuinte
limit	inteiro	50	Registos por página, no máximo 500
cursor	texto	—	Cursor da página seguinte

Pelo menos um de email, phone ou taxId é obrigatório. Podem ser combinados.

Pedido

curl "https://servidor.exemplo/api/integrations/v1/acme/clients/search?phone=912345678" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

{
  "Items": [
    {
      "Id": 87,
      "Code": "C0087",
      "Name": "Maria Silva",
      "SecondName": "",
      "TaxId": "123456789",
      "EMails": ["maria.silva@exemplo.pt"],
      "MobilePhones": ["912345678"],
      "Authorisations": { "EMail": true, "SMS": true, "Phone": false, "SharePhone": false },
      "Fractions": [
        {
          "IdFraction": 340,
          "FractionCode": "A",
          "IdBuilding": 12,
          "BuildingCode": "0012",
          "BuildingName": "Edifício Girassol",
          "Relation": "proprietary",
          "Current": true
        }
      ]
    }
  ],
  "Paging": { "Limit": 50, "NextCursor": null, "HasMore": false }
}

Cada entrada de Fractions traz o condomínio já identificado, para não ter de o ir buscar, e Current diz se a ligação está em vigor.

Como funciona cada critério

Por telefone — a comparação é feita sobre os últimos 9 dígitos, depois de retirados espaços, traços e indicativos. +351 912 345 678, 912345678 e 912-345-678 encontram a mesma pessoa.

A procura por telefone é aproximada

Os números são escritos à mão na aplicação, sem formato imposto. A comparação pelos últimos dígitos é o que dá melhores resultados, mas pode devolver mais do que uma pessoa, ou nenhuma quando o número está registado de forma invulgar. Não a use como identificação segura de alguém.

Por correio — um condómino pode ter vários endereços registados no mesmo campo. A procura percorre todos.

Por contribuinte — tem de ser numérico; caso contrário responde INVALID_TAX_ID.

Erros

Estado	Código	Quando
400	MISSING_CRITERIA	Não foi dado nenhum de email, phone ou taxId
400	INVALID_TAX_ID	O taxId não é numérico
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 people:read

O MISSING_CRITERIA existe porque uma procura sem critérios devolveria todos os condóminos da empresa de uma vez — o que não é uma procura.