Atividades

GET    {BASE_URL}/api-v1-activities      # lista
GET    {BASE_URL}/api-v1-activities/:id  # detalhe
POST   {BASE_URL}/api-v1-activities      # cria
PATCH  {BASE_URL}/api-v1-activities/:id  # atualiza

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/activities), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopos: activities:read para os GET; activities:write para a escrita.

Os campos de integração com agenda externa ficam fora do contrato público de propósito. Atividade não troca de dono de registro: PATCH não altera deal, contact, company nem lead.

Campos

Campo	Tipo	Escrita	Notas
`id`	uuid	somente leitura
`workspace_id`	uuid	somente leitura	Sempre o workspace da chave de API usada na chamada.
`deal_id`	uuid	criar: opcional, editar: não	Formato uuid; deve existir na ficha `deals`.
`contact_id`	uuid	criar: opcional, editar: não	Formato uuid; deve existir na ficha `contacts`.
`company_id`	uuid	criar: opcional, editar: não	Formato uuid; deve existir na ficha `companies`.
`lead_id`	uuid	criar: opcional, editar: não	Formato uuid.
`activity_type_id`	uuid	criar: obrigatório, editar: sim	Traduzível pela ficha `activity-types`. formato uuid; deve existir na ficha `activity-types`.
`owner_id`	uuid	criar: opcional, editar: sim	Formato uuid; deve existir na ficha `owners`.
`title`	string	criar: obrigatório, editar: sim	De 1 a 255 caracteres.
`description`	string	criar: opcional, editar: sim	Máximo 10000 caracteres.
`status`	string	criar: opcional, editar: sim	Leitura conhece 4 valores; a escrita não aceita 'encerrada' (só o CRM fecha assim). valores: `pendente`, `concluida`, `cancelada`.
`scheduled_at`	datetime	criar: obrigatório, editar: sim	Formato datetime.
`start_time`	datetime	criar: opcional, editar: sim	Omitido na criação, herda scheduled_at. formato datetime.
`end_time`	datetime	criar: opcional, editar: sim	Precisa ser maior ou igual ao início. formato datetime.
`completed_at`	datetime	criar: opcional, editar: sim	Só aceito quando o status efetivo é 'concluida'; nunca no futuro. formato datetime.
`is_online_meeting`	boolean	criar: opcional, editar: sim
`created_at`	datetime	somente leitura
`updated_at`	datetime	somente leitura

Listar atividades

GET {BASE_URL}/api-v1-activities

Parâmetro (query)	Tipo	Notas
`deal_id`	uuid
`lead_id`	uuid
`owner_id`	uuid
`activity_type_id`	uuid
`status`	string	Aceita os 4 valores do banco, inclusive 'encerrada'. Valores: `pendente`, `concluida`, `cancelada`, `encerrada`.
`since`	datetime	Só registros criados a partir desta data (ISO 8601). Compara: maior ou igual a.
`limit`	number	Tamanho da página. Padrão 50, máximo 200.
`cursor`	uuid	Próxima página — use o `meta.next_cursor` da resposta anterior.

Ordenação: id crescente. Paginação por cursor.

curl "{BASE_URL}/api-v1-activities?deal_id=8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ /* registros */ ],
  "meta": { "next_cursor": "8f3c...", "has_more": true }
}

Consultar um registro

GET {BASE_URL}/api-v1-activities/:id → o recurso completo, ou 404 not_found.

curl "{BASE_URL}/api-v1-activities/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui"

Criar

POST {BASE_URL}/api-v1-activities — escopo activities:write.

Campo	Tipo	Obrigatório	Notas
`deal_id`	uuid	Não	Formato uuid; deve existir na ficha `deals`.
`contact_id`	uuid	Não	Formato uuid; deve existir na ficha `contacts`.
`company_id`	uuid	Não	Formato uuid; deve existir na ficha `companies`.
`lead_id`	uuid	Não	Formato uuid.
`activity_type_id`	uuid	Sim	Traduzível pela ficha `activity-types`. formato uuid; deve existir na ficha `activity-types`.
`owner_id`	uuid	Não	Formato uuid; deve existir na ficha `owners`.
`title`	string	Sim	De 1 a 255 caracteres.
`description`	string	Não	Máximo 10000 caracteres.
`status`	string	Não	Leitura conhece 4 valores; a escrita não aceita 'encerrada' (só o CRM fecha assim). valores: `pendente`, `concluida`, `cancelada`.
`scheduled_at`	datetime	Sim	Formato datetime.
`start_time`	datetime	Não	Omitido na criação, herda scheduled_at. formato datetime.
`end_time`	datetime	Não	Precisa ser maior ou igual ao início. formato datetime.
`completed_at`	datetime	Não	Só aceito quando o status efetivo é 'concluida'; nunca no futuro. formato datetime.
`is_online_meeting`	boolean	Não

curl -X POST "{BASE_URL}/api-v1-activities" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "activity_type_id": "8f3c...", "title": "...", "scheduled_at": "2026-08-01T14:00:00Z" }'

Atualizar

PATCH {BASE_URL}/api-v1-activities/:id — escopo activities:write. Todos os campos são opcionais; só o que vier no corpo muda.

Campo	Tipo	Obrigatório	Notas
`activity_type_id`	uuid	Não	Traduzível pela ficha `activity-types`. formato uuid; deve existir na ficha `activity-types`.
`owner_id`	uuid	Não	Formato uuid; deve existir na ficha `owners`.
`title`	string	Não	De 1 a 255 caracteres.
`description`	string	Não	Máximo 10000 caracteres.
`status`	string	Não	Leitura conhece 4 valores; a escrita não aceita 'encerrada' (só o CRM fecha assim). valores: `pendente`, `concluida`, `cancelada`.
`scheduled_at`	datetime	Não	Formato datetime.
`start_time`	datetime	Não	Omitido na criação, herda scheduled_at. formato datetime.
`end_time`	datetime	Não	Precisa ser maior ou igual ao início. formato datetime.
`completed_at`	datetime	Não	Só aceito quando o status efetivo é 'concluida'; nunca no futuro. formato datetime.
`is_online_meeting`	boolean	Não

curl -X PATCH "{BASE_URL}/api-v1-activities/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "activity_type_id": "8f3c...", "owner_id": "8f3c...", "title": "..." }'

Webhooks desta ficha

activity.created
activity.overdue

Formato do envio, cabeçalhos e verificação da assinatura em Webhooks.

Erros

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	A chave não tem `activities:read` / `activities:write`.
`404`	`not_found`	O registro não existe neste cliente.
`422`	`validation_error`	Campo fora das regras da tabela acima.
`422`	`invalid_reference`	`deal_id`, `contact_id`, `company_id`, `activity_type_id`, `owner_id` aponta para fora deste cliente.
`422`	`invalid_cursor`	O `cursor` enviado não é válido.
`405`	`method_not_allowed`	Método não suportado neste endereço.
`500`	`internal_error`	Falha interna.

Catálogo completo em Erros.

Idempotência

Envie um header Idempotency-Key (1–255 caracteres, qualquer string única sua) para tornar o POST acima seguro de reenviar em caso de timeout de rede ou retry automático:

curl -X POST "{BASE_URL}/api-v1-activities" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-9f21" \
  -d '{ "deal_id": "8f3c...", "activity_type_id": "2b3c...", "title": "Ligação de qualificação", "scheduled_at": "2026-08-01T14:00:00Z" }'

Mesma chave, mesmo corpo: a segunda chamada não cria outra atividade — responde 200 OK com o corpo da resposta original (não 201).
Mesma chave, corpo diferente (ou reusada em outro recurso): 422 idempotency_conflict.
Mesma chave, requisição original ainda processando: 409 idempotency_in_progress — duas chamadas concorrentes com a mesma chave; espere e tente de novo.
Janela: a chave fica registrada por 24 horas; depois disso pode ser reusada como se fosse nova.
Sem o header: comportamento idêntico ao de hoje — cada POST cria uma atividade nova.

Erros específicos desta ficha

HTTP	`code`	Quando
`400`	`bad_request`	Corpo ausente/JSON inválido.
`422`	`no_owner_available`	Sem responsável ativo possível.
`400`	`invalid_idempotency_key`	`Idempotency-Key` fora de 1–255 caracteres.
`422`	`idempotency_conflict`	Mesma `Idempotency-Key` com corpo ou recurso diferente.
`409`	`idempotency_in_progress`	Mesma `Idempotency-Key` já em processamento (corrida).

Atividades

Nesta página