Agenda

Os calendários dos utilizadores da empresa e as suas marcações.

Listar calendários

GET /calendars

Permissão · calendar:read

Um calendário pertence a uma pessoa, não à empresa. Este ponto devolve os utilizadores cujos calendários podem ser lidos.

Pedido

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

Resposta · 200

[
  { "Id": 14, "Name": "Ana Costa" },
  { "Id": 15, "Name": "Rui Marques" }
]

---

Ler marcações

GET /calendars/{idCalendar}/entries    # de um utilizador
GET /calendar-entries                  # de toda a empresa

Permissão · calendar:read

Parâmetros

Parâmetro	Tipo	Descrição
from	data e hora	Obrigatório. Início do período
to	data e hora	Obrigatório. Fim do período

Pedido

# a agenda de uma pessoa
curl "https://servidor.exemplo/api/integrations/v1/acme/calendars/14/entries?from=2026-09-01&to=2026-09-30" \
  -H "ApiKey: $GC_API_KEY"

# a agenda da empresa toda
curl "https://servidor.exemplo/api/integrations/v1/acme/calendar-entries?from=2026-09-01&to=2026-09-30" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

Array simples, sem envelope — o período pedido é que limita o volume.

[
  {
    "Id": "E1204",
    "IdCalendar": 14,
    "Summary": "Visita ao Edifício Girassol",
    "Description": "Vistoria à garagem na sequência da infiltração.",
    "Start": "2026-09-25T10:00:00",
    "End": "2026-09-25T11:30:00",
    "Editable": true
  },
  {
    "Id": "R881",
    "IdCalendar": 14,
    "Summary": "Assembleia - Edifício Girassol",
    "Description": "",
    "Start": "2026-09-28T18:00:00",
    "End": "2026-09-28T20:00:00",
    "Editable": false
  }
]

Campo	Tipo	Descrição
Id	texto	Identificador da entrada. Ver o aviso abaixo
IdCalendar	inteiro	O calendário. 0 quando pediu o da empresa toda
Summary	texto	O que aparece na agenda
Description	texto	Detalhe
Start · End	data e hora	Início e fim
Editable	booleano	Se esta API pode alterá-la

Nem tudo o que está na agenda foi marcado nela

Um calendário mostra também assembleias, tarefas e datas de contratos, que vivem nos seus próprios registos. Essas vêm com Editable a false e não podem ser alteradas nem apagadas por aqui — corrigem-se no registo a que pertencem.

Só as entradas com Editable a true aceitam PATCH e DELETE.

O Id é texto, e não o número que o PATCH recebe

O Id da leitura traz um prefixo que diz de que tipo é a entrada — E1204, R881. Já o PATCH e o DELETE recebem o número, sem prefixo: 1204.

Numa entrada com Editable a true, tire o primeiro carácter para obter o identificador a usar nas escritas.

Erros

Estado	Código	Quando
400	MISSING_FIELD	Falta from ou to. field diz qual
400	INVALID_PERIOD	O período termina antes de começar
401 · 403		Ver Autenticação e Permissões

---

Criar uma marcação

POST /calendar-entries

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

Corpo

Campo	Tipo	Descrição
IdCalendar	inteiro	O calendário onde marcar
Summary	texto	Obrigatório. O que aparece na agenda
Description	texto	Detalhe
Start	data e hora	Início
End	data e hora	Fim

Pedido

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/calendar-entries" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "IdCalendar": 14,
        "Summary": "Visita ao Edifício Girassol",
        "Description": "Vistoria à garagem na sequência da infiltração.",
        "Start": "2026-09-25T10:00:00",
        "End": "2026-09-25T11:30:00"
      }'

Resposta · 201

{ "Id": 1204 }

Já o número, sem prefixo — é o que usa no PATCH e no DELETE.

Erros

Estado	Código	Quando
400	INVALID_BODY · MISSING_FIELD	Corpo inválido, ou sem Summary
400	INVALID_PERIOD	A marcação termina antes de começar
401 · 403		Ver Autenticação e Permissões
409	IDEMPOTENCY_KEY_REUSED	A chave já foi usada noutro pedido

---

Alterar uma marcação

PATCH /calendar-entries/{idEntry}

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

Pedido

curl -X PATCH "https://servidor.exemplo/api/integrations/v1/acme/calendar-entries/1204" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "Summary": "Visita ao Edifício Girassol (adiada)",
        "Description": "Reagendada a pedido do condómino.",
        "Start": "2026-09-26T10:00:00",
        "End": "2026-09-26T11:30:00"
      }'

O corpo é o mesmo da criação. Os campos enviados substituem os anteriores.

Resposta · 204

Sem corpo.

Erros

Estado	Código	Quando
400	INVALID_BODY · MISSING_FIELD · INVALID_PERIOD	Como na criação
401 · 403		Ver Autenticação e Permissões
404	ENTRY_NOT_FOUND	Não existe, ou existe mas não foi marcada aqui — as de editable: false
409	IDEMPOTENCY_KEY_REUSED	A chave já foi usada noutro pedido

---

Apagar uma marcação

DELETE /calendar-entries/{idEntry}

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

Pedido

curl -X DELETE "https://servidor.exemplo/api/integrations/v1/acme/calendar-entries/1204" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Resposta · 204

Sem corpo.

Erros

Estado	Código	Quando
401 · 403		Ver Autenticação e Permissões
404	ENTRY_NOT_FOUND	Não existe, ou não foi marcada aqui
409	IDEMPOTENCY_KEY_REUSED	A chave já foi usada noutro pedido

A chave de idempotência evita um falso erro

Sem ela, repetir uma eliminação por causa de um tempo esgotado responde 404 — e parece uma falha, quando a marcação está exatamente como queria. Com ela, a repetição devolve o 204 original.