Visão Geral A API Zuia permite acessar workspaces, integrações, dados de Radar e módulo de clientes programaticamente. Ideal para automações, dashboards externos e integrações com ERPs.
Base URL
https://zuia.com.br/apiFormato
JSON (application/json)Endpoints
24 endpoints documentadosRate Limits por Plano
Headers de resposta: X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset
Autenticação Dois métodos suportados. Para automações externas, prefira API Keys.
Método 1 — Bearer JWT
Para o frontend do Zuia (sessão do browser)
Authorization: Bearer eyJhbGciOi...Copiar Método 2 — X-API-Key
Para integrações externas, scripts e Postman
X-API-Key: zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCopiar 💡 API Keys são geradas em Configurações → API Keys e escopadas por workspace. O prefixo é zk_live_ para produção.
cURL Python Java Exemplos de código para todos os endpoints
Workspaces 4 endpoints GET /api/workspacesLista todos os workspaces do usuário autenticado com role e contagem de integrações. ▼
POST /api/workspacesCria novo workspace. Insere automaticamente o usuário como owner. ▼
PATCH /api/workspacesAtualiza campos de um workspace. Requer role owner ou admin. ▼
DELETE /api/workspaces?id={uuid}Exclui workspace e todos os dados associados (integrações, syncs, etc). Requer role owner. ▼
Integrações 6 endpoints GET /api/integrations?workspace_id={uuid}Lista integrações de um workspace. Nunca retorna credenciais. ▼
POST /api/integrations/testTesta credenciais de uma integração sem salvar. Útil para validar tokens antes de conectar. ▼
POST /api/integrationsConecta integração via token manual. Testa as credenciais antes de salvar. ▼
POST /api/integrations/syncDispara sync manual de uma integração. Retorna resultados ao terminar (operação síncrona). ▼
DELETE /api/integrations/:idDesconecta integração. Remove credenciais criptografadas do banco. ▼
GET /api/integrations/:id/logsHistórico de syncs de uma integração específica. ▼
API Keys 4 endpoints GET /api/api-keys?workspace_id={uuid}Lista API keys de um workspace. Nunca retorna o valor completo da key. ▼
POST /api/api-keysGera nova API key. O valor completo só é retornado uma vez — salve imediatamente. ▼
DELETE /api/api-keys?id={uuid}Revoga uma API key. Operação irreversível — a key para de funcionar imediatamente. ▼
GET /api/api-keys/:id/logsLogs de uso de uma API key específica (últimas 100 requisições). ▼
Radar 10 endpoints GET /api/radar/overviewKPIs consolidados de performance: receita, ROAS, CAC, CVR, score da loja e forecast. ▼
GET /api/radar/funnelFunil de conversão completo: consolidado, por canal e por device. ▼
GET /api/radar/channels/metaKPIs completos do Meta Ads: campanhas, conjuntos de anúncios, anúncios e frequência. ▼
GET /api/radar/channels/googleKPIs completos do Google Ads: campanhas, shopping, termos de busca e qualidade. ▼
GET /api/radar/regionsPerformance de vendas por estado brasileiro no mês especificado. ▼
GET /api/radar/productsProdutos com sessões, taxa de conversão, receita e tier de performance. ▼
GET /api/radar/recommendationsRecomendações geradas por IA baseadas nos dados do workspace. ▼
POST /api/radar/simulateSimulador de budget: projeta receita com base na distribuição de investimento por canal. ▼
GET /api/radar/metasMetas configuradas para o mês + progresso atual de cada KPI. ▼
POST /api/radar/metasSalva ou atualiza metas mensais para um workspace. ▼
Erros & Limites 400 Bad Request Body inválido ou campos obrigatórios faltando
401 Unauthorized Token ausente, inválido ou expirado
403 Forbidden Sem permissão (plano insuficiente ou role)
404 Not Found Recurso não encontrado
409 Conflict Recurso já existe (slug duplicado, integração já conectada)
429 Rate Limited Excedeu limite de requisições do plano
500 Internal Server Error Erro no servidor
502 Bad Gateway API externa (Shopify, Meta, etc.) indisponível
Formato de Erro
{
"error": {
"code": "PLAN_LIMIT_REACHED",
"message": "Seu plano Free permite até 1 empresa. Faça upgrade.",
"details": { "current": 1, "max": 1, "plan": "free" }
}
}Copiar Headers de Rate Limit
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1711843200Copiar