Introdução

A API de Integração do GC permite a um sistema externo ler e escrever dados de gestão de condomínios: condomínios e frações, condóminos e contactos, fornecedores, contratos de manutenção, apólices de seguro, ocorrências e sinistros, correspondência, faturação e pagamentos a fornecedores, e agenda.

É REST sobre HTTPS, com JSON nos dois sentidos, e autenticada por uma credencial emitida ao integrador.

Endereço

Todos os caminhos seguem o mesmo padrão:

https://<servidor>/api/integrations/v1/{company}/<recurso>

<servidor> e {company} são-lhe indicados quando a credencial é emitida. O {company} identifica a empresa de condomínios em cuja informação vai trabalhar — uma credencial serve uma empresa e só essa.

O servidor varia

Algumas empresas são alojadas por nós e outras têm servidor próprio. Não assuma um endereço fixo no seu código: torne-o configurável, ou ficará preso à primeira empresa que integrar.

Primeiro pedido

O ping confirma que a credencial funciona, que a empresa existe e que o servidor é o certo. É o único ponto que não exige nenhuma permissão em particular — negá-lo por falta de permissão retirava-lhe a utilidade.

curl https://servidor.exemplo/api/integrations/v1/acme/ping \
  -H "ApiKey: gcik_XXXXXXXXXXXXXXXXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"

{
  "Company": "acme",
  "CompanyName": "Administração Exemplo, Lda.",
  "ApiVersion": "v1",
  "Scopes": ["masterdata:read", "occurrences:read", "occurrences:write"],
  "ServerTime": "2026-09-25T15:42:11.4821376",
  "Occurrences": {
    "Source": "GC",
    "SupportedFilters": ["idBuilding", "status", "idTaskStatus", "idMaintenanceNature",
                         "idServiceType", "idPriority", "idFraction", "openedFrom", "openedTo"],
    "SupportedOperations": ["create", "claims", "assignment", "interventions", "update"]
  },
  "EMail": {
    "MaxAttachments": 3,
    "RecordedOnlyWithFraction": true
  }
}

Vale a pena chamá-lo no arranque da sua integração: diz-lhe que permissões tem, e diz-lhe onde estão as ocorrências desta empresa — o que muda o que pode fazer com elas. Ver Ocorrências: GC ou GM.

Convenções

Formato. Pedidos e respostas em JSON. Os nomes dos campos começam por maiúscula — Id, IdBuilding, BuildingCode — tanto nas respostas como nos corpos dos pedidos.

Nos pedidos, a capitalização é indiferente: deliveryPointCode e DeliveryPointCode são lidos da mesma forma, tal como os parâmetros de query string. Nas respostas, o que recebe é sempre a forma com maiúscula inicial, e é por ela que deve ler os campos.

Datas. ISO 8601 sem fuso horário, em hora local de Portugal — 2026-09-25T15:42:11. Quando um campo é só data, a hora vem a zeros.

Use um leitor de ISO 8601 e não um formato fixo: consoante a origem do valor, a hora pode trazer fração de segundo (2026-09-25T15:42:11.123) ou não. Um yyyy-MM-ddTHH:mm:ss rígido falha no primeiro caso. A enviar, qualquer das formas é aceite.

Valores monetários. Números decimais, em euros, sem separador de milhares.

Identificadores. Números inteiros atribuídos pelo GC. Guarde-os: são a forma estável de voltar a referir o mesmo registo. Códigos e descrições podem ser alterados por quem gere a aplicação.

Ausência. Um campo sem valor vem a null. Um campo que não se aplica àquela empresa vem a null em vez de ser omitido, para que a forma da resposta seja sempre a mesma.

HTTPS obrigatório. A credencial viaja no cabeçalho e não há acesso em claro.

Mapa da API

Área	O que lá está	Permissão
Dados base	Condomínios, frações, fornecedores, contratos de manutenção, apólices, tabelas de referência, contas de despesa e de pagamento	masterdata:read
Pessoas	Condóminos de uma fração, procura por email ou telefone	people:read
Ocorrências	Listagem, detalhe, histórico, anexos, sinistros, sincronização incremental	occurrences:read
Ocorrências (escrita)	Abrir, atribuir, registar intervenção, alterar estado e prioridade	occurrences:write
Financeiro	Faturas de fornecedor e pagamentos	finance:read
Financeiro (escrita)	Registar faturas e pagamentos, incluindo consumos	finance:write
Despesas	Registar despesas pagas em caixa ou pelo banco, sem fatura de fornecedor	expenses:write
Correspondência	Correspondência de uma fração	correspondence:read
Correspondência (envio)	Enviar mensagens em nome da empresa	correspondence:send
Agenda	Calendários e marcações	calendar:read / calendar:write
Comercial	Submeter propostas	commercial:write

O que a API não faz

Vale a pena saber já, para não desenhar em cima do que não existe:

• Não há ligação entre uma mensagem enviada e uma ocorrência. A correspondência pertence a uma fração, não a uma ocorrência.
• Não há ligação entre uma fatura de fornecedor e uma ocorrência. Se precisa de relacionar custo com ocorrência, terá de o manter do seu lado.
• Uma mensagem endereçada a um fornecedor é enviada mas não fica registada. Só uma mensagem dirigida a uma fração se torna correspondência consultável.
• Não há notas internas numa ocorrência. Tudo o que acrescenta ao histórico é matéria da ocorrência, sem distinção entre visível e reservado.
• As coberturas de uma apólice não estão estruturadas. A apólice traz seguradora, mediador, capital e datas; as coberturas existem apenas como texto livre nas observações.
• Uma fração não tem estado ativo ou inativo. O que termina é a ligação do proprietário à fração, que traz data de fim.

Suporte

Dúvidas sobre a integração, pedidos de credencial ou de alargamento de permissões: fale com o seu contacto habitual na SolidSoft.