A API REST v1 na prática: chaves pessoais, curl e erros reais
Já escrevemos sobre por que documentamos todas as APIs. Este é o lado prático: um passeio pela API REST v1 do zerosoft com comandos curl prontos para copiar e colar, para o Link e para o CRM, mais os erros que você vai encontrar de verdade.
Tudo aqui foi conferido contra os handlers em app/api/v1, não só contra a página de docs. A URL base é https://zerosoft.ai/api/v1 no zerosoft Cloud, ou https://seu-host/api/v1 se você faz self-host.
Pegue uma chave
Vá em Dashboard → Settings → API keys, dê um nome à chave ("CI deploy", "substituto-do-zapier", o que for) e crie.
Três coisas para saber:
- Ela aparece uma única vez. A chave é
zs_seguido de 32 caracteres aleatórios. Guardamos só o hash SHA-256 dela e os 10 primeiros caracteres como prefixo visível. Perdeu? Crie outra. - Ela age como o workspace. O que você cria pela API cai no mesmo workspace que você vê no dashboard. Admins veem todas as chaves do workspace; members, só as que eles mesmos criaram. A lista mostra quando cada chave foi usada pela última vez, e revogar vale a partir da próxima request.
- 100 requests por minuto, por chave. Mais sobre isso abaixo.
Coloque numa variável de ambiente e esqueça:
export ZS_KEY="zs_..."
export ZS="https://zerosoft.ai/api/v1"
Links
Crie um link curto. Só url é obrigatório; slug (até 32 caracteres), title, tags (até 5) e domain (um domínio próprio que você verificou) são opcionais.
curl -X POST "$ZS/links" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/spring-launch", "slug": "spring", "tags": ["launch"]}'
Você recebe um 201 com id, slug, domain, short_url, url, title, tags e created_at.
Liste, com paginação (pageSize vai até 50):
curl "$ZS/links?page=1&pageSize=50" -H "Authorization: Bearer $ZS_KEY"
A resposta é { "links": [...], "total": n }, arquivados incluídos, cada um com sua contagem de cliques.
Cliques por dia nos últimos 30 dias:
curl "$ZS/links/LINK_ID/stats" -H "Authorization: Bearer $ZS_KEY"
# { "slug": "spring", "total": 312, "byDay": [{ "date": "...", "count": 41 }, ...] }
Isso basta para montar um relatório semanal num cron sem nunca abrir o dashboard.
CRM: contatos
Busque e pagine (pageSize até 100):
curl "$ZS/crm/contacts?q=ana&page=1&pageSize=25" -H "Authorization: Bearer $ZS_KEY"
Crie um. Atenção: os bodies das requests usam nomes de campo em camelCase, e as respostas devolvem a linha salva com colunas em snake_case:
curl -X POST "$ZS/crm/contacts" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"firstName": "Ana", "lastName": "Garcia", "email": "ana@example.com", "lifecycleStage": "lead", "source": "event"}'
# 201 → { "id": "...", "first_name": "Ana", "last_name": "Garcia", "lifecycle_stage": "lead", ... }
Atualize com PATCH: todos os campos são opcionais:
curl -X PATCH "$ZS/crm/contacts/CONTACT_ID" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"jobTitle": "Head of Ops", "city": "Montevideo"}'
Empresas funcionam do mesmo jeito em /crm/companies e /crm/companies/:id.
CRM: deals e tarefas
Um deal precisa de pipeline e etapa, então peça isso primeiro:
curl "$ZS/crm/pipelines" -H "Authorization: Bearer $ZS_KEY"
Cada pipeline vem com suas etapas (id, name, probability, isWon, isLost). Depois:
curl -X POST "$ZS/crm/deals" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"pipelineId": "PIPELINE_ID", "stageId": "STAGE_ID", "name": "Acme renewal", "amount": 4800, "currency": "USD", "contactIds": ["CONTACT_ID"]}'
GET /crm/deals lista os deals de ?pipelineId=…, ou do seu primeiro pipeline se você omitir.
Tarefas ficam penduradas em contatos, empresas ou deals:
curl -X POST "$ZS/crm/tasks" \
-H "Authorization: Bearer $ZS_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "Send renewal proposal", "dueAt": "2026-08-20 15:00", "dealId": "DEAL_ID"}'
curl "$ZS/crm/tasks?bucket=overdue" -H "Authorization: Bearer $ZS_KEY"
bucket aceita overdue, today, upcoming ou done. Datas vão como YYYY-MM-DD, opcionalmente com horário.
Também há endpoints do Cal (tipos de evento, agendamentos, cancelamento) em /calendar: estão nas docs.
Erros: um formato para tudo
Todo erro da v1 tem o mesmo body:
{ "error": { "code": "slug_taken", "message": "That slug is already taken." } }
Decida com base no code, mostre a message para humanos. Os que você vai encontrar:
| Status | Code | Quando |
|---|---|---|
| 401 | invalid_key |
Falta o header Authorization: Bearer …, ou a chave está errada ou revogada. |
| 429 | rate_limited |
Mais de 100 requests no minuto atual para essa chave. |
| 400 | invalid_url, invalid_slug, slug_taken, invalid_domain |
Problemas ao criar o link. |
| 400 | invalid_input, invalid_email, missing_name |
O body do CRM não passou na validação. |
| 400 | invalid_pipeline, invalid_stage |
O pipeline não existe, ou a etapa não é dele. |
| 404 | not_found |
O registro não existe no seu workspace. |
Sobre esse rate limit
O limite é uma janela fixa de um minuto por chave, contada no banco de dados (escrevemos um post inteiro sobre isso). Dois detalhes que valem saber:
- A contagem acontece antes de validar a chave. Testar chaves na força bruta gasta o mesmo orçamento. Além disso, chaves inválidas têm um teto de 20 tentativas por minuto por IP.
- O 429 não traz header
Retry-After. As janelas se alinham ao minuto do relógio, então o cliente correto mais simples dorme até o próximo minuto começar e tenta de novo.
# ingênuo, mas correto
until curl -fsS "$ZS/links" -H "Authorization: Bearer $ZS_KEY"; do sleep 15; done
Para importações em massa, fique bem abaixo de 100 por minuto e você nunca verá um 429.
O que (ainda) não existe
Sendo honestos sobre as bordas: ainda não há API para Track, Chat ou Docs, o CRM não emite eventos de webhook, e não há OAuth para apps de terceiros, as chaves são pessoais. Se o dashboard faz algo que a API não faz, isso é uma lacuna, não uma decisão de design. Abra uma issue.