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

Escopos: activities:read para os GET; activities:write para POST e PATCH.

Toda atividade precisa de pelo menos um vínculo na criação: deal_id, contact_id, company_id ou lead_id. status e completed_at são aceitos, e são opcionais, em POST e PATCH — sem eles a atividade continua nascendo pendente, como antes. Servem para importar histórico de outro sistema sem que tudo vire tarefa em aberto: completed_at só é aceito quando o status é concluida, e nunca pode ser uma data futura.

O recurso Atividade

Listar atividades

GET {BASE_URL}/api-v1-activities

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

{
  "data": [ { "id": "5e6f...", "title": "Ligação de qualificação", "status": "pendente", "...": "..." } ],
  "meta": { "next_cursor": null, "has_more": false }
}

Consultar uma atividade

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

Criar uma atividade

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

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

Resposta 201 Created:

{ "id": "5e6f...", "owner_id": "3c2d...", "status": "pendente" }

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.

Atualizar uma atividade

PATCH {BASE_URL}/api-v1-activities/:id — escopo activities:write. Mesmos campos do POST, todos opcionais, exceto os vínculos deal_id, contact_id, company_id e lead_id (repassar a atividade para outro dono não é suportado). status e completed_at são aceitos aqui também (ver nota no topo). O mesmo limite de intervalo (end_time ≥ início) vale considerando o valor atual da atividade quando um dos dois campos não é enviado. Retorna a atividade completa atualizada (200 OK).

curl -X PATCH "{BASE_URL}/api-v1-activities/5e6f..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "end_time": "2026-08-01T15:00:00Z" }'

Erros possíveis