Cliente Python moderno e completo para integração com a API v2 do ClickUp.
- ✅ 100% Bilíngue (PT/EN) - Use parâmetros em português ou inglês!
- ✅ 100% compatível com Python 3.13
- ✅ Datas em linguagem natural (português e inglês)
- ✅ Tradução automática PT → EN antes de enviar à API
- ✅ Output formatado com Rich
- ✅ Type hints completos
- ✅ Exception handling robusto
- ✅ Sem dependências problemáticas (sem Pendulum)
- ✅ Retry Automático - Backoff exponencial para rate limits (429)
- ✅ Paginação Automática - Busca TODAS as páginas automaticamente
- ✅ Rate Limiting Inteligente - Handling de 100+ req/min
- ✅ 32+ métodos avançados - Custom Fields, Time Tracking, Goals, Webhooks e mais!
- ✅ Helpers especializados - Cálculos de tempo, formatação, análises
- ✅ Autenticação e Validação - Token management e user info
- ✅ Workspaces/Teams - Gerenciamento de workspaces
- ✅ Spaces - Organização de spaces
- ✅ Folders - Estrutura de folders
- ✅ Lists - Gerenciamento de lists
- ✅ Tasks - CRUD completo de tasks
- ✅ Comments - Comentários em tasks
- ✅ A. Custom Fields - 16 tipos de campos personalizados
- ✅ B. Time Tracking - Timers e registros manuais de tempo
- ✅ C. Attachments - Upload de arquivos (até 1GB)
- ✅ D. Checklists - Listas de verificação em tasks
- ✅ E. Goals - Objetivos e metas quantitativas
- ✅ F. Members - Gerenciamento de membros e assignees
- ✅ G. Webhooks - Eventos em tempo real com HMAC SHA256
- ✅ H. Views - Visualizações customizadas (list, board, calendar, gantt)
- ✅ Alertas de Contas a Pagar - Notificações 7/3/1 dia antes + vencidos
- ✅ Lembretes de Reuniões - 24h e 1h antes via email + in-app
- ✅ Relatórios Semanais - Task automática toda segunda-feira
- ✅ 100% Nativo - Sem código, sem custos adicionais
- ✅ R$ 0/mês - Incluído no plano atual do ClickUp
# Clone o repositório
git clone https://github.com/Danizk/clickup-client.git
cd clickup-client
# Instale as dependências
pip install -r requirements.txt- Crie um arquivo
.envna raiz do projeto:
CLICKUP_TOKEN=pk_SEU_TOKEN_AQUI
CLICKUP_TEAM_ID=SEU_TEAM_ID
CLICKUP_BASE_URL=https://api.clickup.com/api/v2- Obtenha seu token em: ClickUp Settings → Apps → API Token
from src.clickup_api.client import KaloiClickUpClient
# Inicializar cliente
client = KaloiClickUpClient()
# Validar autenticação
client.validate_auth()
# Obter informações do usuário
client.get_user_info()O cliente aceita parâmetros 100% em PORTUGUÊS ou INGLÊS!
A tradução é feita automaticamente antes de enviar à API.
# Use português naturalmente!
task = client.create_task(
list_id="123456789",
nome="Reunião importante", # ← português!
descrição="Discutir projeto Q1", # ← português!
prioridade="alta", # ← português!
status="em progresso", # ← português!
data_vencimento="próxima segunda" # ← português + linguagem natural!
)
# Atualizar task em português
client.update_task(
"task_id",
status="concluído",
prioridade="baixa"
)
# Buscar tasks com filtros em português
tasks = client.get_tasks(
"list_id",
arquivada=False,
página=0
)# English works too!
task = client.create_task(
list_id="123456789",
name="Important meeting",
description="Discuss Q1 project",
priority="high", # or priority=2
status="in progress",
due_date="next monday" # natural language!
)
# Update task in English
client.update_task(
"task_id",
status="complete",
priority="low"
)
# Get tasks with English filters
tasks = client.get_tasks(
"list_id",
archived=False,
page=0
)| Português | Inglês | Valor API |
|---|---|---|
| Prioridade | ||
| urgente | urgent | 1 |
| alta | high | 2 |
| normal | normal | 3 |
| baixa | low | 4 |
| Status | ||
| fazer | to do | "to do" |
| em progresso | in progress | "in progress" |
| em revisão | in review | "in review" |
| concluído | complete | "complete" |
| Parâmetros | ||
| nome | name | name |
| descrição | description | description |
| prioridade | priority | priority |
| data_vencimento | due_date | due_date |
| data_inicio | start_date | start_date |
| responsáveis | assignees | assignees |
| etiquetas | tags | tags |
# Criar task com data em linguagem natural
task = client.create_task(
list_id="123456789",
name="Reunião importante",
description="Discutir o projeto X",
due_date="amanhã", # Suporta PT e EN!
priority=3
)
# Buscar task
task = client.get_task("task_id")
# Atualizar task
client.update_task(
"task_id",
name="Novo nome",
status="em progresso"
)
# Deletar task
client.delete_task("task_id")
# Listar tasks de uma lista
tasks = client.get_tasks("list_id")
# 🆕 Paginação automática - buscar TODAS as tasks
all_tasks = client.get_tasks("list_id", paginate=True)
print(f"Total: {len(all_tasks)} tasks encontradas")O cliente agora busca automaticamente todas as páginas quando solicitado:
# Buscar apenas primeira página (padrão - 100 tasks)
tasks_page_1 = client.get_tasks("list_id")
# Buscar TODAS as tasks automaticamente
all_tasks = client.get_tasks("list_id", paginate=True)
# Com filtros
active_tasks = client.get_tasks(
"list_id",
paginate=True, # Busca todas as páginas
arquivada=False,
incluir_fechadas=False
)
print(f"Total de tasks ativas: {len(active_tasks)}")Vantagens:
- ✅ Suporta listas com 100+ tasks
- ✅ Automático - não precisa controlar páginas manualmente
- ✅ Funciona com todos os filtros
O cliente possui retry automático com backoff exponencial:
- 5 tentativas máximas
- Backoff: 0.5s → 1s → 2s → 4s → 8s
- Status codes: 429, 500, 502, 503, 504
# Não precisa fazer nada! O retry é automático
client = KaloiClickUpClient()
# Se a API retornar 429 (rate limit), o cliente:
# 1. Aguarda 0.5s
# 2. Tenta novamente
# 3. Se falhar, aguarda 1s
# 4. Tenta novamente... até 5 vezes
task = client.get_task("task_id") # Retry automático!Vantagens:
- ✅ Previne falhas por rate limiting
- ✅ Não precisa implementar retry manual
- ✅ Backoff exponencial evita sobrecarregar a API
O cliente suporta datas naturais em português e inglês:
# Português
client.create_task(
list_id="123",
name="Task 1",
due_date="amanhã" # Tomorrow
)
client.create_task(
list_id="123",
name="Task 2",
due_date="próxima semana" # Next week
)
client.create_task(
list_id="123",
name="Task 3",
due_date="1 de dezembro" # December 1st
)
# Inglês
client.create_task(
list_id="123",
name="Task 4",
due_date="tomorrow"
)
client.create_task(
list_id="123",
name="Task 5",
due_date="next week"
)
client.create_task(
list_id="123",
name="Task 6",
due_date="december 1st"
)
# Formatos tradicionais também funcionam
client.create_task(
list_id="123",
name="Task 7",
due_date="2024-12-25" # ISO 8601
)
client.create_task(
list_id="123",
name="Task 8",
due_date=1735095600000 # Unix timestamp (ms)
)# Listar workspaces
teams = client.get_teams()
# Listar spaces
spaces = client.get_spaces(team_id="123")
# Buscar space específico
space = client.get_space("space_id")
# Listar folders
folders = client.get_folders("space_id")
# Buscar folder
folder = client.get_folder("folder_id")# Listar lists de um folder
lists = client.get_lists("folder_id")
# Listar lists sem folder (folderless)
lists = client.get_folderless_lists("space_id")
# Buscar list específica
list_data = client.get_list("list_id")# Listar comentários de uma task
comments = client.get_task_comments("task_id")
# Criar comentário
comment = client.create_task_comment(
"task_id",
"Ótimo progresso no projeto!"
)validate_auth()- Valida token e lista workspacesget_user_info()- Informações do usuário autenticado
get_teams()- Lista todos os workspaces
get_spaces(team_id)- Lista spaces de um workspaceget_space(space_id)- Busca space específico
get_folders(space_id)- Lista folders de um spaceget_folder(folder_id)- Busca folder específico
get_lists(folder_id)- Lista lists de um folderget_folderless_lists(space_id)- Lists sem folderget_list(list_id)- Busca list específica
get_task(task_id)- Busca task específicaget_tasks(list_id, **filters)- Lista tasks com filtroscreate_task(list_id, name, **kwargs)- Cria nova taskupdate_task(task_id, **updates)- Atualiza taskdelete_task(task_id)- Deleta task
get_task_comments(task_id)- Lista comentárioscreate_task_comment(task_id, text)- Cria comentário
get_custom_fields(list_id)- Lista custom fields de uma listset_custom_field(task_id, field_id, value, **kwargs)- Define valor de um custom fieldset_multiple_custom_fields(task_id, fields)- Define múltiplos custom fields de uma vez
create_time_entry(team_id, duration, task_id, **kwargs)- Cria registro manual de tempostart_timer(team_id, task_id, **kwargs)- Inicia timer em tempo realstop_timer(team_id)- Para timer ativoget_running_timer(team_id)- Busca timer ativo atualget_time_entries(team_id, **filters)- Lista time entries com filtrosupdate_time_entry(team_id, entry_id, **updates)- Atualiza time entry existentedelete_time_entry(team_id, entry_id)- Deleta time entry
upload_attachment(task_id, file_path)- Faz upload de arquivo para task
create_checklist(task_id, name)- Cria checklist em uma taskadd_checklist_item(checklist_id, name, **kwargs)- Adiciona item ao checklistcomplete_checklist_item(checklist_id, item_id)- Marca item como concluídodelete_checklist(checklist_id)- Deleta checklist
create_goal(name, due_date, **kwargs)- Cria novo goalget_goals(team_id, **filters)- Lista goals do workspaceget_goal(goal_id)- Busca goal específico
get_list_members(list_id)- Lista membros de uma listget_task_members(task_id)- Lista membros de uma taskadd_assignees(task_id, assignees)- Adiciona assignees a uma taskremove_assignees(task_id, assignees)- Remove assignees de uma task
create_webhook(endpoint_url, events, **kwargs)- Cria webhookget_webhooks(team_id)- Lista webhooks ativosdelete_webhook(webhook_id)- Deleta webhook
get_list_views(list_id)- Lista views de uma listget_view(view_id)- Busca view específicaget_view_tasks(view_id, **filters)- Lista tasks de uma viewupdate_view(view_id, **updates)- Atualiza configurações de uma view
# Listar custom fields disponíveis
fields = client.get_custom_fields("list_id")
# Setar um custom field
client.set_custom_field(
"task_id",
"field_id",
"Valor do campo"
)
# Setar múltiplos custom fields de uma vez
client.set_multiple_custom_fields("task_id", {
"field_id_1": "Valor 1",
"field_id_2": 42,
"field_id_3": True
})# Criar registro manual de tempo (2 horas)
client.create_time_entry(
duration=7200000, # 2 horas em milissegundos
task_id="task_id",
description="Desenvolvimento de feature",
billable=True
)
# Iniciar timer em tempo real
client.start_timer("task_id", description="Trabalhando na task")
# Verificar timer ativo
timer = client.get_running_timer()
# Parar timer
client.stop_timer()
# Buscar time entries com filtros
entries = client.get_time_entries(
start_date=1704067200000, # Unix timestamp ms
end_date=1735689600000,
assignee="user_id"
)# Criar checklist
checklist = client.create_checklist("task_id", "Deploy Process")
# Adicionar items
client.add_checklist_item(
checklist["checklist"]["id"],
"Rodar testes",
assignee=123456
)
# Marcar item como concluído
client.complete_checklist_item(checklist_id, item_id)# Criar goal com data de vencimento
goal = client.create_goal(
name="Aumentar Vendas Q1",
due_date=1735689600000, # Unix timestamp ms
description="Meta trimestral de vendas",
multiple_owners=True,
owners=[123456, 789012]
)
# Listar goals
goals = client.get_goals(include_completed=False)# Criar webhook para receber eventos
webhook = client.create_webhook(
endpoint_url="https://meu-servidor.com/webhook",
events=["taskCreated", "taskUpdated", "taskDeleted"],
space_id="space_id"
)
# Listar webhooks ativos
webhooks = client.get_webhooks()
# Deletar webhook
client.delete_webhook("webhook_id")Execute os scripts de teste incluídos:
# Teste de autenticação
python main.py
# Teste de datas em linguagem natural
python test_fuzzy_dates.py
# Teste completo de todas as funcionalidades (A-H)
python dkbot-client/examples/test_all_features.pyLinguagem Natural (PT):
- "amanhã", "hoje", "ontem"
- "próxima semana", "próximo mês"
- "em 3 dias", "em 2 semanas"
- "1 de dezembro", "25 de dezembro de 2024"
Linguagem Natural (EN):
- "tomorrow", "today", "yesterday"
- "next week", "next month"
- "in 3 days", "in 2 weeks"
- "december 1st", "december 25th 2024"
Formatos Tradicionais:
- ISO 8601:
"2024-12-25T00:00:00Z" - Unix timestamp (ms):
1735095600000 - Unix timestamp (s):
1735095600
O helper fuzzy_time_to_seconds() converte durações:
from src.clickup_api.helpers.date_utils import fuzzy_time_to_seconds
# Português
fuzzy_time_to_seconds("2 horas") # 7200
fuzzy_time_to_seconds("30 minutos") # 1800
fuzzy_time_to_seconds("1 dia") # 86400
# Inglês
fuzzy_time_to_seconds("2 hours") # 7200
fuzzy_time_to_seconds("30 minutes") # 1800
fuzzy_time_to_seconds("1 day") # 86400- Python 3.13+
- requests - HTTP client
- python-dotenv - Variáveis de ambiente
- rich - Output formatado
- dateparser - Parsing de datas naturais
Decisão Final: Usar 100% automações nativas do ClickUp (sem código, R$ 0/mês)
Interface: ClickUp Automations (nativo) Custo: R$ 0
- 7 dias antes: Tag
vencendo-em-breve+ comentário + notificação - 3 dias antes: Tag
urgente+ prioridade alta + notificação - 1 dia antes: Tag
muito-urgente+ prioridade urgente + notificação - Vencido: Tag
atrasado+ criar subtask de revisão
Interface: ClickUp Automations (nativo) Custo: R$ 0
- 24h antes: Tag
lembrete-24h+ comentário + notificação email - 1h antes: Tag
lembrete-1h+ comentário urgente + notificação
Interface: ClickUp Automations (nativo) Custo: R$ 0
- Toda segunda-feira 9h: Criar task "Relatório Semanal" com checklist
| Item | Custo Mensal |
|---|---|
| ClickUp Automations | R$ 0 (incluído no plano) |
| TOTAL | R$ 0 |
| Aspecto | Nativo ClickUp | Python + WhatsApp |
|---|---|---|
| Custo | R$ 0 | R$ 123-173 |
| Setup | 30 min | 3-5 dias |
| Código | 0 linhas | 1.100 linhas |
| Pré-requisitos | Nenhum | MEI + Interakt |
| Manutenção | Zero | Média |
Passo a passo visual:
- Abra a List desejada (ex: "Contas a Pagar")
- Clique em "Automate" (ícone de raio, canto superior direito)
- Clique em "+ Add Automation"
- Configure trigger e actions (veja guia completo)
- Ative a automação
- AUTOMACOES_CLICKUP_NATIVAS.md - Guia passo a passo completo (30 min)
clickup-client/
├── .env # Credenciais (não versionado)
├── .env.example # Template de configuração
├── .gitignore # Arquivos ignorados
├── README.md # Esta documentação
├── requirements.txt # Dependências Python
├── main.py # Script de teste principal
├── test_fuzzy_dates.py # Teste de datas naturais
├── demo_bilingual.py # Demonstração bilíngue (PT/EN)
│
├── src/
│ ├── clickup_api/
│ │ ├── __init__.py
│ │ ├── client.py # Cliente principal (bilíngue) - 1200+ linhas
│ │ └── helpers/
│ │ ├── __init__.py
│ │ ├── date_utils.py # Parsing de datas naturais
│ │ └── translation.py # Tradução PT ↔ EN
│ │
│ └── integrations/ # 🆕 Integrações externas
│ └── whatsapp_client.py # 🆕 Cliente WhatsApp via Interakt
│
├── automation/ # 🆕 Sistema de automações
│ ├── daily_alerts.py # 🆕 Alertas de contas a pagar
│ ├── commercial_reminders.py # 🆕 Lembretes WhatsApp
│ └── weekly_reports.py # 🆕 Relatórios semanais
│
├── .github/
│ └── workflows/ # 🆕 GitHub Actions
│ ├── daily-alerts.yml # 🆕 Workflow diário
│ ├── commercial-reminders.yml # 🆕 Workflow horário
│ └── weekly-reports.yml # 🆕 Workflow semanal
│
├── dkbot-client/ # Novo pacote com funcionalidades A-H
│ ├── src/
│ │ └── dkbot/
│ │ ├── client.py # Cliente estendido com funcionalidades A-H
│ │ ├── templates/ # Templates para automação
│ │ ├── validators/# Validadores de dados
│ │ └── helpers/
│ │ ├── custom_fields.py # Helpers de Custom Fields
│ │ ├── time_tracking.py # Helpers de Time Tracking
│ │ ├── date_utils.py # Parsing de datas
│ │ └── translation.py # Tradução PT ↔ EN
│ ├── docs/ # Documentação das funcionalidades
│ └── examples/
│ └── test_all_features.py # Teste completo A-H
│
└── docs/ # Documentação técnica detalhada
├── README.md # Índice de documentação
├── SETUP_AUTOMACOES.md # 🆕 Setup completo de automações
├── RESUMO_IMPLEMENTACAO_FINAL.md # 🆕 Resumo executivo
├── CUSTOM_FIELDS_SUMMARY.md # A. Custom Fields
├── CUSTOM_FIELDS_RESEARCH.md
├── CUSTOM_FIELDS_EXAMPLES.md
├── TIME_TRACKING_SUMMARY.md # B. Time Tracking
├── TIME_TRACKING_RESEARCH.md
├── TIME_TRACKING_EXAMPLES.md
├── ADVANCED_FEATURES_SUMMARY.md # C-H. Funcionalidades Avançadas
└── ADVANCED_FEATURES_RESEARCH.md
Contribuições são bem-vindas! Por favor:
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/NovaFuncionalidade) - Commit suas mudanças (
git commit -m 'Adiciona nova funcionalidade') - Push para a branch (
git push origin feature/NovaFuncionalidade) - Abra um Pull Request
Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
- Dani Kaloi - @Danizk
- Sistema Kaloi - Arquitetura híbrida de IAs
O projeto inclui documentação técnica detalhada sobre funcionalidades avançadas:
- docs/README.md - Índice geral de documentação
- docs/CUSTOM_FIELDS_SUMMARY.md - Resumo executivo sobre Custom Fields
- docs/CUSTOM_FIELDS_RESEARCH.md - Pesquisa técnica completa
- docs/CUSTOM_FIELDS_EXAMPLES.md - Exemplos práticos de uso
| Funcionalidade | Status | Documentação |
|---|---|---|
| Custom Fields | ✅ Concluída | Ver docs |
| Time Tracking | ✅ Concluída | Ver docs |
| Avançadas (C-H) | ✅ Concluída | Ver docs |
Funcionalidades Avançadas incluem:
- C. Attachments (Upload de arquivos)
- D. Checklists (Listas de verificação)
- E. Goals (Metas e objetivos)
- F. Members (Gerenciamento de membros)
- G. Webhooks (Eventos em tempo real)
- H. Views (Visualizações customizadas)
Este cliente não é afiliado oficialmente ao ClickUp. É um projeto independente criado pela comunidade.
Desenvolvido com ❤️ pelo Sistema Kaloi