API Reference

API REST para integração com agentes de IA, automações (n8n) e aplicativos externos.

https://crm.zark.com.br/api/v1Ver como JSON (para agentes)

Autenticação

Todas as requisições precisam de uma API Key no header Authorization.

Authorization: Bearer zk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gere sua chave em Configurações → API Keys no painel do Zark CRM.

📦 Espaços

GET/api/v1/spaces— Lista espaços acessíveis ao usuário

Exemplo

curl -H "Authorization: Bearer zk_SUA_KEY" \
  https://crm.zark.com.br/api/v1/spaces

Resposta

{
  "data": [
    {
      "id": "uuid",
      "name": "GERAIS",
      "color": "#ef4444",
      "status": "ativo",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

GET/api/v1/spaces/{spaceId}/members— Lista membros de um espaço

Exemplo

curl -H "Authorization: Bearer zk_SUA_KEY" \
  https://crm.zark.com.br/api/v1/spaces/UUID/members

Resposta

{
  "data": [
    {
      "user_id": "uuid",
      "role": "admin",
      "full_name": "Nome Completo",
      "email": "email@exemplo.com"
    }
  ]
}

✅ Tarefas

GET/api/v1/spaces/{spaceId}/tasks— Lista tarefas com filtros

Param	Tipo	Descrição / Valores
status	query	todo, doing, done
priority	query	urgent, high, medium, low
assignee_id	query	UUID do membro
include_done	query	true/false (default: false)

POST/api/v1/spaces/{spaceId}/tasks— Cria nova tarefa

Param	Tipo	Descrição / Valores
title	body ✅	Título da tarefa
description	body	Descrição detalhada
priority	body	urgent, high, medium (default), low
due_date	body	ISO 8601 (ex: 2026-03-15T23:59:59Z)
assignee_id	body	UUID do membro
folder_name	body	Nome da pasta (busca fuzzy)
list_name	body	Nome da lista (busca fuzzy)

Exemplo

curl -X POST \
  -H "Authorization: Bearer zk_SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Revisar contrato", "priority": "urgent"}' \
  https://crm.zark.com.br/api/v1/spaces/UUID/tasks

GET/api/v1/tasks/{taskId}— Ver detalhes completos da tarefa

PATCH/api/v1/tasks/{taskId}— Editar tarefa (somente campos enviados)

Param	Tipo	Descrição / Valores
title	body	Novo título
status	body	todo, doing, done
priority	body	urgent, high, medium, low
due_date	body	ISO 8601 ou null
assignee_id	body	UUID ou null

POST/api/v1/tasks/{taskId}/complete— Marca tarefa como concluída (sem body)

Exemplo

curl -X POST \
  -H "Authorization: Bearer zk_SUA_KEY" \
  https://crm.zark.com.br/api/v1/tasks/UUID/complete

💬 Comentários

GET/api/v1/tasks/{taskId}/comments— Lista comentários

POST/api/v1/tasks/{taskId}/comments— Adiciona comentário

Param	Tipo	Descrição / Valores
content	body ✅	Texto do comentário

Exemplo

curl -X POST \
  -H "Authorization: Bearer zk_SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Feito via comando de voz"}' \
  https://crm.zark.com.br/api/v1/tasks/UUID/comments

📅 Agenda / Calendário

Unifica em uma única visualização todos os eventos com data do sistema (tasks, leads, invoices, expenses, faturas de cartão, approvals) + eventos manuais (reuniões, lembretes, bloqueios). Endpoint canônico pra agentes IA responderem "o que tenho pra fazer hoje/semana/mês?"

GET/api/v1/calendar/events?from=ISO&to=ISO— Lista TODOS os eventos no range (cap 365 dias). Range obrigatório.

Param	Tipo	Descrição / Valores
from	query ✅	ISO 8601 (início)
to	query ✅	ISO 8601 (fim, > from, máx 365 dias)

Exemplo

curl -H "Authorization: Bearer zk_SUA_KEY" \
  "https://crm.zark.com.br/api/v1/calendar/events?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z"

Tipos de source retornados:

task — tasks.due_date

lead_followup — proximo_followup

followup_message — WhatsApp agendado

invoice — vencimento

expense — despesa vencendo

credit_card_invoice — fatura

approval_pending — arte cliente

manual:meeting / reminder / personal / ...

GET/api/v1/calendar/events/upcoming?limit=10&hours=24— 🤖 Atalho pra agentes IA — próximos N eventos a partir de agora (sem range)

Param	Tipo	Descrição / Valores
limit	query	1..50 (default 10)
hours	query	1..720h da janela (default 24)

Exemplo

curl -H "Authorization: Bearer zk_SUA_KEY" \
  "https://crm.zark.com.br/api/v1/calendar/events/upcoming?limit=5&hours=4"

POST/api/v1/calendar/events— Cria evento manual com reminders e recorrência opcional

Param	Tipo	Descrição / Valores
title	body ✅	Texto
start_at	body ✅	ISO 8601
end_at	body ✅	ISO 8601 (>= start_at)
all_day	body	boolean (default false)
category	body	meeting \| reminder \| personal \| blocked \| task \| other
visibility	body	private \| space \| org (default private)
space_id	body	uuid (obrigatório se visibility=space)
recurrence	body	none \| daily \| weekly \| monthly \| yearly \| custom
recurrence_until	body	YYYY-MM-DD (fim da recorrência)
related_lead_id / related_task_id / related_invoice_id	body	uuid (linkar entidade)
reminders	body	Array { offset_minutes: 0..43200, channel: in_app\|whatsapp\|both }

Exemplo — reunião com lead

curl -X POST \
  -H "Authorization: Bearer zk_SUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reunião com Acme",
    "start_at": "2026-05-21T18:00:00Z",
    "end_at": "2026-05-21T19:00:00Z",
    "category": "meeting",
    "related_lead_id": "uuid-do-lead",
    "reminders": [{"offset_minutes": 60}, {"offset_minutes": 0}]
  }' \
  https://crm.zark.com.br/api/v1/calendar/events

GET/api/v1/calendar/events/{eventId}— Obter evento manual (derivados só pelo GET com range)

PATCH/api/v1/calendar/events/{eventId}— Atualiza evento manual (subset dos campos de POST)

DELETE/api/v1/calendar/events/{eventId}— Exclui evento (cascade em reminders + exceptions)

POST/api/v1/calendar/events/{eventId}/reminders— Adiciona lembrete avulso ao evento

Param	Tipo	Descrição / Valores
offset_minutes	body ✅	0..43200 (até 30 dias antes); 0 = na hora
channel	body	in_app \| whatsapp \| both (default in_app)
occurrence_date	body	YYYY-MM-DD ou null — pra ocorrência específica (recorrente)

DELETE/api/v1/calendar/events/{eventId}/reminders/{reminderId}— Remove lembrete específico

Códigos de Erro

Código	Significado
200	Sucesso
201	Recurso criado
400	Campos obrigatórios faltando
401	API Key inválida ou ausente
403	Sem acesso ao recurso
404	Recurso não encontrado
500	Erro interno

🤖 Fluxo para Agentes de IA

1GET /spaces → Identificar o espaço pelo nome

2GET /spaces/{id}/members → Saber quem atribuir

3POST /spaces/{id}/tasks → Criar tarefa

4POST /tasks/{id}/complete → Concluir quando pedido

5POST /tasks/{id}/comments → Registrar observações

Endpoint de Documentação JSON

Agentes de IA podem consumir esta documentação programaticamente:

GET https://crm.zark.com.br/api/v1/docs