Agenda

Compromissos (meeting) e lembretes (reminder).

Compromissos (meeting) e lembretes (reminder).

{
  "id": "8a4c2e6f-1d3b-4a5c-9e7f-2b4d6a8c0e2f",
  "title": "Apresentar proposta — Acme",
  "description": null,
  "start_at": "2026-08-05T14:00",
  "end_at": "2026-08-05T15:00",
  "type": "meeting",
  "location": "Google Meet",
  "contact_id": "9f1e4b7a-…",
  "deal_id": "6d2c9f4e-…",
  "company_id": null,
  "owner_id": "1b7c9d2e-…",
  "external_id": null,
  "created_at": "2026-08-01T10:00:00.000Z",
  "updated_at": "2026-08-01T10:00:00.000Z"
}

start_at e end_at são texto local, SEM fuso horário — AAAA-MM-DD (dia inteiro) ou AAAA-MM-DDTHH:mm (com hora). Não converta para UTC. Mandar um ISO com Z ou com deslocamento (2026-08-05T14:00:00.000Z) é rejeitado. É o mesmo formato que a tela grava.

Método Escopo Descrição
GET/api/agenda agenda:read Lista. ?from= e ?to= obrigatórios (AAAA-MM-DD, janela de no máximo 1 ano). Filtros: ?type=, ?contact_id=, ?company_id=, ?deal_id=, ?external_id=
GET/api/agenda/{id} agenda:read Um compromisso
POST/api/agenda agenda:write Cria (201)
PATCH/api/agenda/{id} agenda:write Edição parcial
DELETE/api/agenda/{id} agenda:write Exclui (204)
Campo Criar Editar Regras
title obrigatório opcional 2–120
description opcional opcional até 1000
type obrigatório opcional meeting ou reminder
start_at obrigatório opcional data/hora que exista de verdade
end_at opcional opcional precisa ser depois de start_at
location opcional opcional até 200
contact_id / company_id / deal_id opcional opcional precisam existir na conta
owner_id opcional opcional pessoa ativa. Sem valor na criação, o responsável pela chave (§2) vira o responsável do registro
external_id opcional opcional* até 255 — ver §27
created_at / updated_at ⛔ só com import:write não aceito data/hora ISO original, para quem migra de outro CRM — ver §24

* só DEFINE quando o compromisso ainda não tem external_id; trocar um já gravado é 409 — ver §27.

Esta é a única listagem que ordena por start_at crescente — um calendário começa pelo primeiro compromisso da janela pedida. A janela from/to inclui os dois dias (o compromisso que começa no dia to entra).

"Só o dele" na Agenda: a chave enxerga os compromissos do responsável pela chave e os sem responsável que ele mesmo criou — aqui não existe balcão. Criar um compromisso com owner_id de outra pessoa, ou passar um compromisso para outra pessoa no PATCH, devolve 403 forbidden_module.

Criar dispara event.created, editar dispara event.updated e excluir dispara event.canceled (§21).