A API da zerosoft.
REST e JSON.

Link, CRM, Cal, Track, Docs, Chat, Agents e a maioria dos outros apps têm API REST com respostas JSON e chaves pessoais.

Baixar a spec OpenAPI 3.1 Conectar o Claude e a CLI

Base URL

https://zerosoft.ai/api/v1

Autenticação

Cada requisição precisa de uma API key, enviada como Bearer token. Para sessões de navegador, o fluxo OAuth do Google cria o cookie de sessão.

Authorization: Bearer zs_live_9f3k...

Crie as chaves em Dashboard → Settings → API keys. A chave é exibida uma única vez: copie e guarde como uma senha. Cada chave permite 100 requisições por minuto.

Cada chave tem escopos, escolhidos ao criá-la. Os de escrita incluem leitura. Chaves criadas antes dos escopos têm todos. Uma requisição sem o escopo necessário recebe 403 insufficient_scope.

EscopoDescrição
crm:readLer contatos, empresas, negócios, atividades, tarefas, pipelines, produtos, cotações, tags, templates, sequências e formulários.
crm:writeCriar, editar e excluir registros do CRM, inscrever em sequências e aplicar tags (inclui crm:read).
links:readListar links e ler suas estatísticas.
links:writeCriar, editar e excluir links curtos (inclui links:read).
cal:readListar tipos de evento e reservas.
cal:writeCriar e cancelar reservas (inclui cal:read).
agents:runEnviar mensagens para os seus agentes de IA.
robots:runListar e executar robôs, e ler suas execuções e lotes.
chat:readListar as conversas do Chat e ler as mensagens.
chat:writeResponder, atribuir, resolver e reabrir conversas do Chat (inclui chat:read).
groups:readLer chats, mensagens e tickets de WhatsApp no Lines.
groups:writeEnviar mensagens de WhatsApp e criar tickets no Lines.
voice:readLer ditados, reuniões e transcrições do Voice.
voice:writeDitar e enviar áudio de reuniões para o Voice.
track:readLer issues e pedidos de clientes do Track.
track:writeCriar issues do Track a partir de pedidos de clientes (e-mail, formulários, Flow).
docs:readLer páginas, bancos, linhas e comentários do Docs, e buscar.
docs:writeCriar e editar páginas, linhas e comentários do Docs (inclui docs:read).
talk:readLer canais e mensagens do Talk dos quais você é membro.
talk:writePublicar mensagens e criar canais no Talk.
boards:readLer quadros, o resumo e buscar dentro.
boards:writeCriar quadros, adicionar post-its e formas, renomear, mover e mandar para a lixeira.
design:readLer designs do Design e suas páginas.
shop:readLer produtos e pedidos do Shop.
shop:writeCriar produtos do Shop.
hiring:readLer as vagas do Hiring e os candidatos que quem criou a chave vê.
sign:readLer os envelopes do Sign que a pessoa dona da key vê (sem arquivos).
analytics:readLer projetos, eventos e pessoas do Pulse e rodar consultas.
analytics:writeMudar projetos, insights, painéis, coortes e flags do Pulse.
bi:readLer perguntas, painéis e coleções do Analytics e rodar consultas.
bi:writeCriar e mudar perguntas, painéis, coleções e assinaturas do Analytics.
social:readLer publicações do Social das contas que você vê.
social:writeCriar rascunhos e publicações agendadas no Social (com aprovação se você precisar).
people:readLer o diretório do People: só campos públicos do perfil, nunca salário nem dados pessoais.
books:readLer faturas do Books (com o papel no Books de quem criou a key).
books:writeCriar faturas em rascunho no Books.
forms:readLer os formulários do Forms e suas respostas, só os que o dono da key pode ver.
send:readLer os documentos que a pessoa vê, com seus links e visitas.
calls:readLer as chamadas que a pessoa vê, com transcrições e análise.
calls:writeCriar e editar chamadas, comentários e clipes, e mandar o notetaker para uma reunião.
notes:readLer as notas que quem criou a chave pode ver, e suas tarefas.
notes:writeCriar e editar as notas de quem criou a chave.

Uma chave age como a pessoa que a criou: se o seu workspace limita os membros aos próprios registros do CRM (ou aos da equipe), a API devolve só esses registros.

Login com Google

GET/api/auth/signin/google

Redirecione o usuário para iniciar o fluxo OAuth do Google. Após o sucesso ele retorna ao app com o cookie de sessão.

curl -X GET "https://zerosoft.ai/api/auth/signin/google" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Contatos

Pessoas e leads.

Listar contatos

GET/api/v1/crm/contacts

Lista contatos. Filtros: q, page, pageSize (máx 100).

Escopo crm:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
lifecyclestringNãoEtapa do ciclo de vida (lead, sql, opportunity, customer).
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/contacts" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "contacts": [
    {
      "id": "b1f47ac2-…",
      "first_name": "Ana",
      "last_name": "Garcia",
      "email": "ana@kallpa.co",
      "lifecycle_stage": "sql",
      "company_id": null,
      "created_at": "2026-07-18 10:04:11"
    }
  ],
  "total": 142,
  "page": 1,
  "pageSize": 25
}

Criar um contato

POST/api/v1/crm/contacts

Cria um contato novo.

Escopo crm:write

NomeTipoObrigatórioDescrição
firstNamestringNãoNome.
lastNamestringNãoSobrenome.
emailstringNãoEndereço de email.
lifecycleStagestringNãoEtapa do ciclo de vida (lead, sql, opportunity, customer).
companyIdstringNãoId da empresa vinculada.
curl -X POST "https://zerosoft.ai/api/v1/crm/contacts" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Ana",
  "lastName": "Garcia",
  "email": "ana@kallpa.co",
  "lifecycleStage": "sql"
}'

Requisição

{
  "firstName": "Ana",
  "lastName": "Garcia",
  "email": "ana@kallpa.co",
  "lifecycleStage": "sql"
}

Resposta · 201

{
  "id": "b1f47ac2-…",
  "first_name": "Ana",
  "last_name": "Garcia",
  "email": "ana@kallpa.co",
  "lifecycle_stage": "sql",
  "created_at": "2026-07-18 10:04:11"
}

Ler um contato

GET/api/v1/crm/contacts/{id}

Lê um contato por id.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/contacts/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Atualizar um contato

PATCH/api/v1/crm/contacts/{id}

Atualize qualquer propriedade de um contato.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
firstNamestringNãoNome.
lifecycleStagestringNãoEtapa do ciclo de vida (lead, sql, opportunity, customer).
companyIdstring | nullNãoId da empresa principal. É associada se necessário; a principal anterior continua associada. null remove a principal.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/contacts/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "lifecycleStage": "opportunity"
}'

Requisição

{
  "lifecycleStage": "opportunity"
}

Excluir um contato

DELETE/api/v1/crm/contacts/{id}

Exclui o contato definitivamente. As atividades ficam, sem vínculo.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/contacts/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Empresas

Organizações e contas.

Listar empresas

GET/api/v1/crm/companies

Lista empresas. Filtros: q, page, pageSize.

Escopo crm:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/companies" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "companies": [
    {
      "id": "c7a1…",
      "name": "Norte Labs",
      "domain": "nortelabs.co",
      "industry": "Software"
    }
  ],
  "total": 40,
  "page": 1,
  "pageSize": 25
}

Criar uma empresa

POST/api/v1/crm/companies

Cria uma empresa nova.

Escopo crm:write

NomeTipoObrigatórioDescrição
namestringSimNome da empresa.
domainstringNãoNome de domínio.
industrystringNãoIndústria.
parentCompanyIdstring | nullNãoId da empresa matriz (hierarquia). null a deixa no nível superior. Uma empresa não pode ser ancestral de si mesma.
curl -X POST "https://zerosoft.ai/api/v1/crm/companies" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Norte Labs",
  "domain": "nortelabs.co",
  "industry": "Software"
}'

Requisição

{
  "name": "Norte Labs",
  "domain": "nortelabs.co",
  "industry": "Software"
}

Ler uma empresa

GET/api/v1/crm/companies/{id}

Lê uma empresa por id.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/companies/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Atualizar uma empresa

PATCH/api/v1/crm/companies/{id}

Atualize qualquer propriedade de uma empresa.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
namestringNãoNome da empresa.
domainstringNãoNome de domínio.
industrystringNãoIndústria.
parentCompanyIdstring | nullNãoId da empresa matriz (hierarquia). null a deixa no nível superior. Uma empresa não pode ser ancestral de si mesma.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/companies/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "industry": "Cloud infrastructure",
  "parentCompanyId": "{company_id}"
}'

Requisição

{
  "industry": "Cloud infrastructure",
  "parentCompanyId": "{company_id}"
}

Excluir uma empresa

DELETE/api/v1/crm/companies/{id}

Exclui a empresa definitivamente. Os contatos continuam existindo sem empresa.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/companies/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Deals

Oportunidades e pipelines.

Listar deals

GET/api/v1/crm/deals

Lista deals. Filtro: pipelineId.

Escopo crm:read

NomeTipoObrigatórioDescrição
pipelineIdstringNãoId do pipeline.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/deals" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "deals": [
    {
      "id": "d9e2…",
      "name": "Norte Labs — New business",
      "amount": 24000,
      "currency": "USD",
      "stage_id": "{stage_id}"
    }
  ],
  "total": 36,
  "page": 1,
  "pageSize": 25
}

Criar um deal

POST/api/v1/crm/deals

Cria um deal em uma etapa do pipeline.

Escopo crm:write

NomeTipoObrigatórioDescrição
pipelineIdstringSimId do pipeline.
stageIdstringSimId da etapa.
namestringNãoNome do deal.
amountnumberNãoValor do deal.
currencystringNãoCódigo da moeda.
contactIdsstring[]NãoIDs dos contatos a inscrever (1–500).
companyIdstringNãoEmpresa principal do deal.
companyIdsstring[]NãoOutras empresas para associar ao deal.
curl -X POST "https://zerosoft.ai/api/v1/crm/deals" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "pipelineId": "{pipeline_id}",
  "stageId": "{stage_id}",
  "name": "Norte Labs — New business",
  "amount": 24000,
  "currency": "USD",
  "contactIds": [
    "{contact_id}"
  ],
  "companyId": "{company_id}"
}'

Requisição

{
  "pipelineId": "{pipeline_id}",
  "stageId": "{stage_id}",
  "name": "Norte Labs — New business",
  "amount": 24000,
  "currency": "USD",
  "contactIds": [
    "{contact_id}"
  ],
  "companyId": "{company_id}"
}

Ler um deal

GET/api/v1/crm/deals/{id}

Lê um deal por id.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/deals/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Atualizar um deal

PATCH/api/v1/crm/deals/{id}

Atualize valor, etapa ou datas.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
namestringNãoNome do deal.
amountnumberNãoValor do deal.
addContactIdsstring[]NãoIDs dos contatos a inscrever (1–500).
companyIdstringNãoEmpresa principal do deal.
amountOverridebooleanNãotrue mantém um valor manual mesmo com line items; false o recalcula a partir dos line items. Editar o valor de um deal com line items o ativa.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/deals/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "amount": 28000,
  "closeDate": "2026-11-30",
  "amountOverride": true
}'

Requisição

{
  "amount": 28000,
  "closeDate": "2026-11-30",
  "amountOverride": true
}

Mover um negócio de etapa

POST/api/v1/crm/deals/{id}/move

Move o negócio para outra etapa do pipeline. Etapas de ganho/perda o fecham; perda exige lostReason. Se a etapa pede propriedades que o negócio não tem, responde 422 missing_required com a lista; envie-as em fields para preencher e mover numa chamada só. Dispara deal.stage_changed (e deal.won / deal.lost).

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
stageIdstringSimId da etapa.
lostReasonstringNãoPor que foi perdido (obrigatório em etapas de perda).
fieldsobjectNãoPropriedades que a etapa pede, salvas antes de mover: amount, closeDate, ownerId, priority, source, description e custom (valores de custom fields por nome).
curl -X POST "https://zerosoft.ai/api/v1/crm/deals/{id}/move" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "stageId": "{stage_id}"
}'

Requisição

{
  "stageId": "{stage_id}"
}

Excluir um negócio

DELETE/api/v1/crm/deals/{id}

Exclui o negócio definitivamente.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/deals/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Atividades

A timeline de um contato, empresa ou negócio: notas, ligações, reuniões, emails e tarefas. Reuniões agendadas no Cal aparecem aqui automaticamente.

Listar a timeline de um registro

GET/api/v1/crm/activities

Mais recentes primeiro. Passe só um entre contactId, companyId ou dealId.

Escopo crm:read

NomeTipoObrigatórioDescrição
contactId | companyId | dealIdstringSimO registro cuja timeline você quer.
typenote | task | call | meeting | emailNãoTipo de atividade.
limitintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/activities" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "activities": [
    {
      "id": "a12…",
      "type": "meeting",
      "subject": "Intro call",
      "due_at": "2026-11-03 13:00:00",
      "duration_min": 30,
      "contact_id": "{contact_id}"
    }
  ]
}

Registrar uma atividade

POST/api/v1/crm/activities

Registre uma nota, ligação, reunião ou email em um registro. Tarefas têm endpoint próprio.

Escopo crm:write

NomeTipoObrigatórioDescrição
typenote | call | meeting | emailSimTipo de atividade.
subjectstringNãoAssunto da tarefa.
bodystringNãoTexto livre: notas, resumo da ligação, corpo do email.
contactIdstringNãoId do contato vinculado.
dealIdstringNãoId do deal vinculado.
curl -X POST "https://zerosoft.ai/api/v1/crm/activities" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "type": "call",
  "subject": "Discovery call",
  "body": "Budget approved for Q1.",
  "durationMin": 25,
  "contactId": "{contact_id}"
}'

Requisição

{
  "type": "call",
  "subject": "Discovery call",
  "body": "Budget approved for Q1.",
  "durationMin": 25,
  "contactId": "{contact_id}"
}

CRM · Tarefas

Atividades e acompanhamentos.

Listar tarefas

GET/api/v1/crm/tasks

Lista tarefas. bucket: overdue, today, upcoming, done.

Escopo crm:read

NomeTipoObrigatórioDescrição
bucketoverdue | today | upcoming | doneNãoBucket de filtro: overdue, today, upcoming, done.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/tasks" \
  -H "Authorization: Bearer zs_live_9f3k..."

Criar uma tarefa

POST/api/v1/crm/tasks

Cria uma tarefa, opcionalmente ligada a um registro.

Escopo crm:write

NomeTipoObrigatórioDescrição
subjectstringSimAssunto da tarefa.
dueAtstring (ISO 8601)NãoData de vencimento em formato ISO.
contactIdstringNãoId do contato vinculado.
companyIdstringNãoId da empresa vinculada.
dealIdstringNãoId do deal vinculado.
curl -X POST "https://zerosoft.ai/api/v1/crm/tasks" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Follow-up call",
  "dueAt": "2026-07-25T15:00:00Z",
  "dealId": "{deal_id}"
}'

Requisição

{
  "subject": "Follow-up call",
  "dueAt": "2026-07-25T15:00:00Z",
  "dealId": "{deal_id}"
}

Atualizar uma tarefa

PATCH/api/v1/crm/tasks/{id}

Edite ou conclua uma tarefa.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
subjectstringNãoAssunto da tarefa.
donebooleanNãoMarcar como concluída.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/tasks/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "done": true
}'

Requisição

{
  "done": true
}

CRM · Pipelines e etapas

Pipelines de vendas e suas etapas.

Listar pipelines

GET/api/v1/crm/pipelines

Lista pipelines com suas etapas.

Escopo crm:read

curl -X GET "https://zerosoft.ai/api/v1/crm/pipelines" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "pipelines": [
    {
      "id": "{pipeline_id}",
      "name": "Sales",
      "position": 0,
      "stages": [
        {
          "id": "{stage_id}",
          "name": "Qualified",
          "position": 0,
          "probability": 20,
          "isWon": false,
          "isLost": false
        },
        {
          "id": "{stage_id}",
          "name": "Won",
          "position": 5,
          "probability": 100,
          "isWon": true,
          "isLost": false
        }
      ]
    }
  ]
}

CRM · Produtos e line items

Catálogo de produtos e os line items de cada deal. Enquanto um deal tiver line items, o valor dele é a soma dos líquidos (depois do desconto, antes dos impostos), a menos que amountOverride esteja ativo.

Listar produtos

GET/api/v1/crm/products

Produtos do catálogo, ativos primeiro, ordenados por nome.

Escopo crm:read

NomeTipoObrigatórioDescrição
qstringNãoBuscar por nome ou SKU.
activebooleanNãotrue = só ativos, false = só arquivados.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/products" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "products": [
    {
      "id": "{product_id}",
      "name": "Pro plan",
      "sku": "PRO-Y",
      "description": "",
      "price": 1200,
      "currency": "USD",
      "recurring": "yearly",
      "tax_pct": 21,
      "active": 1,
      "created_at": "2026-10-13 12:00:00",
      "updated_at": "2026-10-13 12:00:00"
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 25
}

Criar um produto

POST/api/v1/crm/products

Adiciona um produto ao catálogo. Sem moeda, usa a moeda base do workspace.

Escopo crm:write

NomeTipoObrigatórioDescrição
namestringSimNome do produto.
skustringNãoSKU ou código interno.
descriptionstringNãoDescrição exibida em line items e orçamentos.
pricenumberNãoPreço unitário.
currencystringNãoCódigo de moeda ISO (por padrão, a moeda base do workspace).
recurringnone | monthly | yearlyNãoCobrança: none, monthly ou yearly.
taxPctnumberNãoPercentual de imposto (0-100).
activebooleanNãofalse arquiva o produto (some dos seletores).
curl -X POST "https://zerosoft.ai/api/v1/crm/products" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Pro plan",
  "sku": "PRO-Y",
  "price": 1200,
  "currency": "USD",
  "recurring": "yearly",
  "taxPct": 21
}'

Requisição

{
  "name": "Pro plan",
  "sku": "PRO-Y",
  "price": 1200,
  "currency": "USD",
  "recurring": "yearly",
  "taxPct": 21
}

Resposta · 201

{
  "id": "{product_id}",
  "name": "Pro plan",
  "sku": "PRO-Y",
  "description": "",
  "price": 1200,
  "currency": "USD",
  "recurring": "yearly",
  "tax_pct": 21,
  "active": 1,
  "created_at": "2026-10-13 12:00:00",
  "updated_at": "2026-10-13 12:00:00"
}

Obter um produto

GET/api/v1/crm/products/{id}

Retorna um produto.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/products/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{product_id}",
  "name": "Pro plan",
  "sku": "PRO-Y",
  "description": "",
  "price": 1200,
  "currency": "USD",
  "recurring": "yearly",
  "tax_pct": 21,
  "active": 1,
  "created_at": "2026-10-13 12:00:00",
  "updated_at": "2026-10-13 12:00:00"
}

Atualizar um produto

PATCH/api/v1/crm/products/{id}

Atualiza os campos enviados. Line items que já estão em deals não mudam.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
pricenumberNãoPreço unitário.
activebooleanNãofalse arquiva o produto (some dos seletores).
curl -X PATCH "https://zerosoft.ai/api/v1/crm/products/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "price": 1320,
  "active": true
}'

Requisição

{
  "price": 1320,
  "active": true
}

Excluir um produto

DELETE/api/v1/crm/products/{id}

Exclui o produto. Os line items que o usavam ficam nos deals como itens personalizados.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/products/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Listar os line items de um deal

GET/api/v1/crm/deals/{id}/line-items

Line items com subtotal, desconto, líquido, imposto e total calculados, mais os totais do deal. Os valores são arredondados por linha na moeda do deal.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do deal.
curl -X GET "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "currency": "USD",
  "items": [
    {
      "id": "{line_item_id}",
      "deal_id": "{deal_id}",
      "product_id": "{product_id}",
      "name": "Pro plan",
      "sku": "PRO-Y",
      "description": "",
      "quantity": 2,
      "unit_price": 1200,
      "discount_pct": 10,
      "tax_pct": 21,
      "recurring": "yearly",
      "position": 0,
      "subtotal": 2400,
      "discount": 240,
      "net": 2160,
      "tax": 453.6,
      "total": 2613.6,
      "created_at": "2026-10-13 12:00:00",
      "updated_at": "2026-10-13 12:00:00"
    }
  ],
  "totals": {
    "subtotal": 2400,
    "discount": 240,
    "net": 2160,
    "tax": 453.6,
    "total": 2613.6
  },
  "amountOverride": false
}

Adicionar um line item

POST/api/v1/crm/deals/{id}/line-items

A partir de um produto (copia nome, preço, imposto e recorrência; o preço é convertido para a moeda do deal se houver taxa de câmbio) ou personalizado (nome e unitPrice). Recalcula o valor do deal.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do deal.
productIdstringNãoId do produto do catálogo. Omita para um line item personalizado.
namestringNãoNome do line item (obrigatório em itens personalizados).
quantitynumberNãoQuantidade (pode ter decimais).
unitPricenumberNãoPreço unitário na moeda do deal.
discountPctnumberNãoPercentual de desconto (0-100).
taxPctnumberNãoPercentual de imposto (0-100).
curl -X POST "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "productId": "{product_id}",
  "quantity": 2,
  "discountPct": 10
}'

Requisição

{
  "productId": "{product_id}",
  "quantity": 2,
  "discountPct": 10
}

Resposta · 201

{
  "id": "{line_item_id}",
  "deal_id": "{deal_id}",
  "product_id": "{product_id}",
  "name": "Pro plan",
  "sku": "PRO-Y",
  "description": "",
  "quantity": 2,
  "unit_price": 1200,
  "discount_pct": 10,
  "tax_pct": 21,
  "recurring": "yearly",
  "position": 0,
  "subtotal": 2400,
  "discount": 240,
  "net": 2160,
  "tax": 453.6,
  "total": 2613.6,
  "created_at": "2026-10-13 12:00:00",
  "updated_at": "2026-10-13 12:00:00"
}

Atualizar um line item

PATCH/api/v1/crm/deals/{id}/line-items/{itemId}

Atualiza quantidade, preço, desconto, imposto ou texto e recalcula o valor do deal.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do deal.
itemIdstringSimId do line item.
quantitynumberNãoQuantidade (pode ter decimais).
discountPctnumberNãoPercentual de desconto (0-100).
curl -X PATCH "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items/{itemId}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 3,
  "discountPct": 15
}'

Requisição

{
  "quantity": 3,
  "discountPct": 15
}

Excluir um line item

DELETE/api/v1/crm/deals/{id}/line-items/{itemId}

Remove o line item e recalcula o valor do deal.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do deal.
itemIdstringSimId do line item.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items/{itemId}" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Orçamentos

Orçamentos criados a partir dos line items de um deal. Cada um guarda uma cópia dos itens e tem uma página pública (public_url) onde o cliente aceita ou recusa. Ao aceitar, dispara o evento do Flow quote.accepted e o gatilho de workflow quote_accepted.

Listar orçamentos

GET/api/v1/crm/quotes

Orçamentos do workspace, do mais novo ao mais antigo. Os enviados que passaram do vencimento voltam como expired.

Escopo crm:read

NomeTipoObrigatórioDescrição
dealIdstringNãoSó os orçamentos deste deal.
statusdraft | sent | accepted | declined | expiredNãoFiltrar por status.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/quotes" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "quotes": [
    {
      "id": "{quote_id}",
      "deal_id": "{deal_id}",
      "deal_name": "Norte Labs — New business",
      "number": "Q-2026-0003",
      "title": "Norte Labs — Pro plan",
      "status": "draft",
      "currency": "USD",
      "items": [
        {
          "name": "Pro plan",
          "sku": "PRO-Y",
          "description": "",
          "quantity": 2,
          "unit_price": 1200,
          "discount_pct": 10,
          "tax_pct": 21,
          "recurring": "yearly",
          "subtotal": 2400,
          "discount": 240,
          "net": 2160,
          "tax": 453.6,
          "total": 2613.6
        }
      ],
      "subtotal": 2400,
      "discount_total": 240,
      "tax_total": 453.6,
      "total": 2613.6,
      "expires_at": "2026-11-30",
      "terms": "Payment within 30 days of acceptance.",
      "notes": "",
      "sender_name": "Lucía Pérez",
      "sender_email": "lucia@zerosoft.ai",
      "sender_company": "Zerosoft",
      "recipient_name": "Ana Garcia",
      "recipient_email": "ana@nortelabs.co",
      "recipient_company": "Norte Labs",
      "sent_at": null,
      "accepted_at": null,
      "declined_at": null,
      "signer_name": "",
      "public_url": "https://zerosoft.ai/q/7Jx2kQ…",
      "created_at": "2026-10-13 12:00:00"
    }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 25
}

Criar um orçamento

POST/api/v1/crm/quotes

Cria um orçamento em rascunho com os line items atuais do deal (precisa de pelo menos um). Por padrão vence em 30 dias e o destinatário é o primeiro contato e a empresa principal do deal.

Escopo crm:write

NomeTipoObrigatórioDescrição
dealIdstringSimDeal cujos line items formam o orçamento.
titlestringNãoTítulo do orçamento (por padrão, o nome do deal).
expiresAtstringNãoData de vencimento, YYYY-MM-DD.
termsstringNãoTermos e condições.
notesstringNãoObservações para o cliente.
senderNamestringNãoDados do remetente exibidos no orçamento.
senderEmailstringNãoDados do remetente exibidos no orçamento.
senderCompanystringNãoDados do remetente exibidos no orçamento.
recipientNamestringNãoDados do destinatário (padrão: primeiro contato e empresa principal do deal).
recipientEmailstringNãoDados do destinatário (padrão: primeiro contato e empresa principal do deal).
recipientCompanystringNãoDados do destinatário (padrão: primeiro contato e empresa principal do deal).
curl -X POST "https://zerosoft.ai/api/v1/crm/quotes" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "dealId": "{deal_id}",
  "title": "Norte Labs — Pro plan",
  "expiresAt": "2026-11-30",
  "terms": "Payment within 30 days of acceptance.",
  "senderName": "Lucía Pérez",
  "senderEmail": "lucia@zerosoft.ai",
  "senderCompany": "Zerosoft"
}'

Requisição

{
  "dealId": "{deal_id}",
  "title": "Norte Labs — Pro plan",
  "expiresAt": "2026-11-30",
  "terms": "Payment within 30 days of acceptance.",
  "senderName": "Lucía Pérez",
  "senderEmail": "lucia@zerosoft.ai",
  "senderCompany": "Zerosoft"
}

Resposta · 201

{
  "id": "{quote_id}",
  "deal_id": "{deal_id}",
  "deal_name": "Norte Labs — New business",
  "number": "Q-2026-0003",
  "title": "Norte Labs — Pro plan",
  "status": "draft",
  "currency": "USD",
  "items": [
    {
      "name": "Pro plan",
      "sku": "PRO-Y",
      "description": "",
      "quantity": 2,
      "unit_price": 1200,
      "discount_pct": 10,
      "tax_pct": 21,
      "recurring": "yearly",
      "subtotal": 2400,
      "discount": 240,
      "net": 2160,
      "tax": 453.6,
      "total": 2613.6
    }
  ],
  "subtotal": 2400,
  "discount_total": 240,
  "tax_total": 453.6,
  "total": 2613.6,
  "expires_at": "2026-11-30",
  "terms": "Payment within 30 days of acceptance.",
  "notes": "",
  "sender_name": "Lucía Pérez",
  "sender_email": "lucia@zerosoft.ai",
  "sender_company": "Zerosoft",
  "recipient_name": "Ana Garcia",
  "recipient_email": "ana@nortelabs.co",
  "recipient_company": "Norte Labs",
  "sent_at": null,
  "accepted_at": null,
  "declined_at": null,
  "signer_name": "",
  "public_url": "https://zerosoft.ai/q/7Jx2kQ…",
  "created_at": "2026-10-13 12:00:00"
}

Obter um orçamento

GET/api/v1/crm/quotes/{id}

Retorna o orçamento com os itens e o public_url.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/quotes/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{quote_id}",
  "deal_id": "{deal_id}",
  "deal_name": "Norte Labs — New business",
  "number": "Q-2026-0003",
  "title": "Norte Labs — Pro plan",
  "status": "draft",
  "currency": "USD",
  "items": [
    {
      "name": "Pro plan",
      "sku": "PRO-Y",
      "description": "",
      "quantity": 2,
      "unit_price": 1200,
      "discount_pct": 10,
      "tax_pct": 21,
      "recurring": "yearly",
      "subtotal": 2400,
      "discount": 240,
      "net": 2160,
      "tax": 453.6,
      "total": 2613.6
    }
  ],
  "subtotal": 2400,
  "discount_total": 240,
  "tax_total": 453.6,
  "total": 2613.6,
  "expires_at": "2026-11-30",
  "terms": "Payment within 30 days of acceptance.",
  "notes": "",
  "sender_name": "Lucía Pérez",
  "sender_email": "lucia@zerosoft.ai",
  "sender_company": "Zerosoft",
  "recipient_name": "Ana Garcia",
  "recipient_email": "ana@nortelabs.co",
  "recipient_company": "Norte Labs",
  "sent_at": null,
  "accepted_at": null,
  "declined_at": null,
  "signer_name": "",
  "public_url": "https://zerosoft.ai/q/7Jx2kQ…",
  "created_at": "2026-10-13 12:00:00"
}

Editar ou enviar um orçamento

PATCH/api/v1/crm/quotes/{id}

Edita um rascunho. status: "sent" publica o link público (draft → sent). Aceitar e recusar acontece na página pública. Se não for rascunho, responde 409 not_draft.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
statusstringNão"sent" publica o orçamento.
refreshItemsbooleanNãoCopia de novo os line items atuais do deal (só rascunhos).
expiresAtstringNãoData de vencimento, YYYY-MM-DD.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/quotes/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "refreshItems": true,
  "status": "sent"
}'

Requisição

{
  "refreshItems": true,
  "status": "sent"
}

CRM · Leads

Leads são prospects antes de virarem negócio: responsável, etapa do pipeline de leads, contato e empresa. Converter um lead cria um negócio pelo app. Campos personalizados de leads vão em custom; os que a key não pode editar retornam 403 field_readonly e os ocultos ficam fora das respostas.

Listar leads

GET/api/v1/crm/leads

Os leads que a key vê, mais novos primeiro.

Escopo crm:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
statusopen | qualified | disqualifiedNãoSó leads em etapas deste tipo.
stageIdstringNãoEtapa do pipeline de leads.
contactIdstringNãoContato associado.
companyIdstringNãoEmpresa associada.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/leads" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "leads": [
    {
      "id": "f1c2…",
      "owner_id": "usr_…",
      "name": "Ana Gómez",
      "stage_id": "stg_…",
      "stage_name": "Connected",
      "stage_kind": "open",
      "contact_id": "c7a1…",
      "company_id": "co_…",
      "source": "form",
      "disqualify_reason": "",
      "deal_id": null,
      "converted_at": null,
      "custom": "{}",
      "created_at": "2026-10-24 12:00:00",
      "updated_at": "2026-10-24 12:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

Criar um lead

POST/api/v1/crm/leads

Precisa de nome, contato ou empresa. Sem nome, usa o do contato (ou o da empresa). Sem stageId, começa na primeira etapa aberta.

Escopo crm:write

NomeTipoObrigatórioDescrição
namestringNãoNome do lead.
contactIdstringNãoContato associado.
companyIdstringNãoEmpresa associada.
stageIdstringNãoEtapa do pipeline de leads.
ownerIdstringNãoPessoa do workspace responsável. Por padrão, quem criou a key.
sourcestringNãoOrigem (organic, referral, ads, social, email, event, form, other).
customobjectNãoCampos personalizados de leads.
curl -X POST "https://zerosoft.ai/api/v1/crm/leads" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "{contact_id}",
  "source": "form"
}'

Requisição

{
  "contactId": "{contact_id}",
  "source": "form"
}

Resposta · 201

{
  "id": "f1c2…",
  "owner_id": "usr_…",
  "name": "Ana Gómez",
  "stage_id": "stg_…",
  "stage_name": "Connected",
  "stage_kind": "open",
  "contact_id": "c7a1…",
  "company_id": "co_…",
  "source": "form",
  "disqualify_reason": "",
  "deal_id": null,
  "converted_at": null,
  "custom": "{}",
  "created_at": "2026-10-24 12:00:00",
  "updated_at": "2026-10-24 12:00:00"
}

Ver um lead

GET/api/v1/crm/leads/{id}

Um lead com etapa, contato, empresa e negócio.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/leads/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "f1c2…",
  "owner_id": "usr_…",
  "name": "Ana Gómez",
  "stage_id": "stg_…",
  "stage_name": "Connected",
  "stage_kind": "open",
  "contact_id": "c7a1…",
  "company_id": "co_…",
  "source": "form",
  "disqualify_reason": "",
  "deal_id": null,
  "converted_at": null,
  "custom": "{}",
  "created_at": "2026-10-24 12:00:00",
  "updated_at": "2026-10-24 12:00:00"
}

Editar um lead

PATCH/api/v1/crm/leads/{id}

Muda etapa, responsável, contato, empresa, origem, motivo da desqualificação ou campos personalizados.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
stageIdstringNãoEtapa do pipeline de leads.
disqualifyReasonstringNãoPor que o lead foi desqualificado.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/leads/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "stageId": "{stage_id}"
}'

Requisição

{
  "stageId": "{stage_id}"
}

Resposta · 200

{
  "id": "f1c2…",
  "owner_id": "usr_…",
  "name": "Ana Gómez",
  "stage_id": "stg_…",
  "stage_name": "Connected",
  "stage_kind": "open",
  "contact_id": "c7a1…",
  "company_id": "co_…",
  "source": "form",
  "disqualify_reason": "",
  "deal_id": null,
  "converted_at": null,
  "custom": "{}",
  "created_at": "2026-10-24 12:00:00",
  "updated_at": "2026-10-24 12:00:00"
}

Excluir um lead

DELETE/api/v1/crm/leads/{id}

Exclui o lead com suas notas e tarefas. O contato, a empresa e o negócio continuam.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/leads/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Objetos personalizados

Registros dos objetos personalizados que um admin definiu (por exemplo veículos ou imóveis). Cada registro tem nome (a propriedade principal), responsável e suas propriedades em custom. As permissões por campo valem como em contatos.

Listar objetos personalizados

GET/api/v1/crm/objects

Os objetos do workspace com as propriedades que a key vê.

Escopo crm:read

curl -X GET "https://zerosoft.ai/api/v1/crm/objects" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "objects": [
    {
      "id": "obj_…",
      "slug": "vehicles",
      "singular": "Vehicle",
      "plural": "Vehicles",
      "primary_label": "Plate",
      "properties": [
        {
          "name": "model",
          "label": "Model",
          "type": "text",
          "options": [],
          "readOnly": false
        }
      ]
    }
  ]
}

Listar registros

GET/api/v1/crm/objects/{slug}/records

Os registros de um objeto, mais novos primeiro.

Escopo crm:read

NomeTipoObrigatórioDescrição
slugstringSimSlug do objeto (de Listar objetos personalizados).
qstringNãoQuery de busca.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/objects/{slug}/records" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "records": [
    {
      "id": "rec_…",
      "object_id": "obj_…",
      "owner_id": "usr_…",
      "name": "AB 123 CD",
      "custom": "{\"model\":\"Hilux\",\"year\":2023}",
      "created_at": "2026-10-24 12:00:00",
      "updated_at": "2026-10-24 12:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

Criar um registro

POST/api/v1/crm/objects/{slug}/records

Os valores de custom são validados com o tipo de cada propriedade; propriedades que não existem são ignoradas.

Escopo crm:write

NomeTipoObrigatórioDescrição
slugstringSimSlug do objeto (de Listar objetos personalizados).
namestringSimValor da propriedade principal.
ownerIdstringNãoPessoa do workspace responsável. Por padrão, quem criou a key.
customobjectNãoValores das propriedades por nome.
curl -X POST "https://zerosoft.ai/api/v1/crm/objects/{slug}/records" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "AB 123 CD",
  "custom": {
    "model": "Hilux",
    "year": 2023
  }
}'

Requisição

{
  "name": "AB 123 CD",
  "custom": {
    "model": "Hilux",
    "year": 2023
  }
}

Resposta · 201

{
  "id": "rec_…",
  "object_id": "obj_…",
  "owner_id": "usr_…",
  "name": "AB 123 CD",
  "custom": "{\"model\":\"Hilux\",\"year\":2023}",
  "created_at": "2026-10-24 12:00:00",
  "updated_at": "2026-10-24 12:00:00"
}

Ver um registro

GET/api/v1/crm/objects/{slug}/records/{id}

O registro com os ids dos contatos, empresas e negócios associados.

Escopo crm:read

NomeTipoObrigatórioDescrição
slugstringSimSlug do objeto (de Listar objetos personalizados).
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/objects/{slug}/records/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "rec_…",
  "object_id": "obj_…",
  "owner_id": "usr_…",
  "name": "AB 123 CD",
  "custom": "{\"model\":\"Hilux\",\"year\":2023}",
  "created_at": "2026-10-24 12:00:00",
  "updated_at": "2026-10-24 12:00:00",
  "associations": {
    "contacts": [
      "c7a1…"
    ],
    "companies": [],
    "deals": []
  }
}

Editar um registro

PATCH/api/v1/crm/objects/{slug}/records/{id}

Muda nome, responsável ou propriedades.

Escopo crm:write

NomeTipoObrigatórioDescrição
slugstringSimSlug do objeto (de Listar objetos personalizados).
idstringSimId do registro.
customobjectNãoValores das propriedades por nome.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/objects/{slug}/records/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "custom": {
    "model": "Hilux",
    "year": 2024
  }
}'

Requisição

{
  "custom": {
    "model": "Hilux",
    "year": 2024
  }
}

Resposta · 200

{
  "id": "rec_…",
  "object_id": "obj_…",
  "owner_id": "usr_…",
  "name": "AB 123 CD",
  "custom": "{\"model\":\"Hilux\",\"year\":2023}",
  "created_at": "2026-10-24 12:00:00",
  "updated_at": "2026-10-24 12:00:00"
}

Excluir um registro

DELETE/api/v1/crm/objects/{slug}/records/{id}

Exclui o registro com suas notas e tarefas.

Escopo crm:write

NomeTipoObrigatórioDescrição
slugstringSimSlug do objeto (de Listar objetos personalizados).
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/objects/{slug}/records/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Associações

Vínculos muitos-para-muitos entre contatos, empresas e deals. Um contato ou deal pode ter várias empresas; uma delas é a principal. contact.company_id sempre reflete a empresa principal.

Listar associações

GET/api/v1/crm/associations

Todos os registros vinculados a um contato, empresa ou deal. Empresas também retornam a empresa matriz e as filiais.

Escopo crm:read

NomeTipoObrigatórioDescrição
typecontact | company | dealSimTipo de registro: contact, company ou deal.
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/associations" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "companies": [
    {
      "id": "{company_id}",
      "name": "Norte Labs",
      "domain": "nortelabs.co",
      "is_primary": true,
      "label": "decision_maker"
    },
    {
      "id": "{company_id}",
      "name": "Norte Holding",
      "domain": "norte.com",
      "is_primary": false,
      "label": "billing"
    }
  ],
  "deals": [
    {
      "id": "{deal_id}",
      "name": "Norte Labs — New business",
      "amount": 24000,
      "currency": "USD"
    }
  ]
}

Associar dois registros

POST/api/v1/crm/associations

Vincula contato ↔ empresa, deal ↔ empresa ou deal ↔ contato (em qualquer ordem). primary torna a empresa a principal; label só vale para contato ↔ empresa. Se a associação já existir, atualiza principal e label.

Escopo crm:write

NomeTipoObrigatórioDescrição
fromTypecontact | company | dealSimTipo do primeiro registro.
fromIdstringSimId do primeiro registro.
toTypecontact | company | dealSimTipo do segundo registro.
toIdstringSimId do segundo registro.
primarybooleanNãoTorna esta a empresa principal do contato ou deal.
labelstringNãoLabel de contato ↔ empresa: employee, decision_maker, billing, champion, influencer, former_employee (ou vazio).
curl -X POST "https://zerosoft.ai/api/v1/crm/associations" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "fromType": "contact",
  "fromId": "{contact_id}",
  "toType": "company",
  "toId": "{company_id}",
  "primary": true,
  "label": "decision_maker"
}'

Requisição

{
  "fromType": "contact",
  "fromId": "{contact_id}",
  "toType": "company",
  "toId": "{company_id}",
  "primary": true,
  "label": "decision_maker"
}

Resposta · 201

{
  "ok": true
}

Remover uma associação

DELETE/api/v1/crm/associations

Desvincula dois registros (parâmetros na query). Se você remover a empresa principal, a mais antiga que sobrar vira principal.

Escopo crm:write

NomeTipoObrigatórioDescrição
fromTypecontact | company | dealSimTipo do primeiro registro.
fromIdstringSimId do primeiro registro.
toTypecontact | company | dealSimTipo do segundo registro.
toIdstringSimId do segundo registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/associations" \
  -H "Authorization: Bearer zs_live_9f3k..."

CRM · Tags

Tags do workspace para contatos, empresas e deals.

Listar tags

GET/api/v1/crm/tags

Tags com quantos contatos, empresas e deals usam cada uma.

Escopo crm:read

curl -X GET "https://zerosoft.ai/api/v1/crm/tags" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "tags": [
    {
      "id": "{tag_id}",
      "name": "Enterprise",
      "color": "crm",
      "created_at": "2026-10-13 12:00:00",
      "contacts": 18,
      "companies": 4,
      "deals": 7
    }
  ]
}

Criar uma tag

POST/api/v1/crm/tags

O nome é único por workspace (sem diferenciar maiúsculas). Se repetir, responde 409 duplicate_tag.

Escopo crm:write

NomeTipoObrigatórioDescrição
namestringSimNome da tag (até 60 caracteres).
colorstringNãoCor: crm, link, cal, track, chat, docs, flow, agents, notes, board ou robots.
curl -X POST "https://zerosoft.ai/api/v1/crm/tags" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Enterprise",
  "color": "crm"
}'

Requisição

{
  "name": "Enterprise",
  "color": "crm"
}

Resposta · 201

{
  "id": "{tag_id}",
  "name": "Enterprise",
  "color": "crm",
  "created_at": "2026-10-13 12:00:00"
}

Atualizar uma tag

PATCH/api/v1/crm/tags/{id}

Muda o nome ou a cor da tag.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
namestringNãoNome da tag (até 60 caracteres).
colorstringNãoCor: crm, link, cal, track, chat, docs, flow, agents, notes, board ou robots.
curl -X PATCH "https://zerosoft.ai/api/v1/crm/tags/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "color": "cal"
}'

Requisição

{
  "color": "cal"
}

Excluir uma tag

DELETE/api/v1/crm/tags/{id}

Exclui a tag e a remove de todos os registros.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X DELETE "https://zerosoft.ai/api/v1/crm/tags/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Adicionar ou remover uma tag de registros

POST/api/v1/crm/tags/{id}/records

Adiciona ou remove a tag em até 1000 registros. Ids de outros workspaces são ignorados. Retorna quantos registros mudaram.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
entitycontact | company | dealSimTipo de registro: contact, company ou deal.
idsstring[]SimIds dos registros.
actionadd | removeSimadd ou remove.
curl -X POST "https://zerosoft.ai/api/v1/crm/tags/{id}/records" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "entity": "contact",
  "ids": [
    "{contact_id}"
  ],
  "action": "add"
}'

Requisição

{
  "entity": "contact",
  "ids": [
    "{contact_id}"
  ],
  "action": "add"
}

Resposta · 200

{
  "changed": 1
}

CRM · Formulários

Formulários de captura de leads e seus envios. Cada envio também cria ou atualiza um contato e registra uma atividade "Form submitted".

Listar formulários

GET/api/v1/crm/forms

Formulários do mais novo ao mais antigo, com status, quantidade de respostas e parciais, última resposta e quem pode abri-los.

Escopo crm:read

curl -X GET "https://zerosoft.ai/api/v1/crm/forms" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "forms": [
    {
      "id": "{form_id}",
      "name": "Contact us",
      "key": "contact-us",
      "slug": "contact-us",
      "token": "a1b2c3d4e5f6a7b8c9d0",
      "status": "active",
      "fields": [
        {
          "id": "email",
          "type": "email",
          "label": "Email",
          "property": "email",
          "required": true
        }
      ],
      "submission_count": 42
    }
  ]
}

Listar envios de um formulário

GET/api/v1/crm/forms/{id}/submissions

Envios de um formulário, os mais recentes primeiro, com os valores, os parâmetros UTM e o contato vinculado.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/crm/forms/{id}/submissions" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "submissions": [
    {
      "id": "{submission_id}",
      "formId": "{form_id}",
      "contactId": "{contact_id}",
      "contactCreated": true,
      "values": {
        "email": "ana@kallpa.co",
        "first_name": "Ana"
      },
      "utm": {
        "utm_source": "google",
        "utm_campaign": "spring"
      },
      "pageUrl": "https://kallpa.co/pricing?utm_source=google",
      "referrer": "",
      "createdAt": "2026-10-13 14:02:11"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25
}

CRM · Templates de email e sequências

Templates e snippets de email compartilhados, e sequências de vendas com várias etapas. Os emails das sequências saem do Gmail conectado de quem envia; as etapas rodam no agendador de hora em hora.

Listar templates de email

GET/api/v1/crm/email-templates

Templates e snippets compartilhados no workspace. As variáveis ficam entre chaves duplas (contact.first_name, contact.company, deal.name, owner.first_name, contact.custom.x), com um valor padrão opcional depois de uma barra vertical.

Escopo crm:read

NomeTipoObrigatórioDescrição
kindtemplate | snippetNãoFiltrar por tipo: template ou snippet.
curl -X GET "https://zerosoft.ai/api/v1/crm/email-templates" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "templates": [
    {
      "id": "{template_id}",
      "kind": "template",
      "name": "Intro",
      "subject": "Quick question, {{contact.first_name}}",
      "body": "Hi {{contact.first_name | there}}, I saw {{contact.company}} is hiring…",
      "created_by": "u_123",
      "created_at": "2026-10-13 12:00:00",
      "updated_at": "2026-10-13 12:00:00"
    }
  ]
}

Obter um template de email

GET/api/v1/crm/email-templates/{id}

Retorna um template ou snippet.

Escopo crm:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/crm/email-templates/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Listar sequências

GET/api/v1/crm/sequences

Sequências com o número de etapas e inscrições.

Escopo crm:read

curl -X GET "https://zerosoft.ai/api/v1/crm/sequences" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "sequences": [
    {
      "id": "{sequence_id}",
      "name": "Outbound — 3 touches",
      "timezone": "America/Argentina/Buenos_Aires",
      "window_start": "09:00",
      "window_end": "17:00",
      "business_days": 1,
      "step_count": 4,
      "active_count": 12,
      "total_count": 40
    }
  ]
}

Inscrever contatos em uma sequência

POST/api/v1/crm/sequences/{id}/enroll

Inscreve até 500 contatos. Os que já estão inscritos, cancelaram a inscrição ou não têm email voltam em skipped. Quem envia precisa do Gmail conectado com permissão de envio.

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
contactIdsstring[]SimIDs dos contatos a inscrever (1–500).
senderIdstringNãoMembro do workspace cujo Gmail envia os emails. Por padrão, o owner do contato e depois quem criou a sequência.
curl -X POST "https://zerosoft.ai/api/v1/crm/sequences/{id}/enroll" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "contactIds": [
    "{contact_id}"
  ]
}'

Requisição

{
  "contactIds": [
    "{contact_id}"
  ]
}

Resposta · 201

{
  "enrolled": [
    "{contact_id}"
  ],
  "skipped": []
}

Remover um contato de uma sequência

POST/api/v1/crm/sequences/{id}/unenroll

Remove o contato da sequência (status exited, motivo manual).

Escopo crm:write

NomeTipoObrigatórioDescrição
idstringSimId do registro.
contactIdstringSimId do contato vinculado.
curl -X POST "https://zerosoft.ai/api/v1/crm/sequences/{id}/unenroll" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "{contact_id}"
}'

Requisição

{
  "contactId": "{contact_id}"
}

Resposta · 200

{
  "exited": 1
}

Painel do contato de um email

GET/api/v1/crm/extension/sidebar

O que a extensão do Gmail mostra ao lado de um email: o contato com esse endereço, sua empresa, negócios e tarefas abertas. contact é null se ninguém que você vê no CRM tem esse endereço.

Escopo crm:read

NomeTipoObrigatórioDescrição
emailstringSimEndereço de email.
curl -X GET "https://zerosoft.ai/api/v1/crm/extension/sidebar" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "email": "ana@acme.com",
  "contact": {
    "id": "{contact_id}",
    "name": "Ana Pérez",
    "email": "ana@acme.com",
    "url": "/app/crm/contacts/{contact_id}"
  },
  "company": {
    "id": "{company_id}",
    "name": "Acme",
    "domain": "acme.com",
    "url": "/app/crm/companies/{company_id}"
  },
  "deals": [
    {
      "id": "{deal_id}",
      "name": "Acme renewal",
      "amount": 12000,
      "currency": "USD",
      "stage": "Proposal",
      "closed": false
    }
  ],
  "tasks": [
    {
      "id": "{task_id}",
      "subject": "Send proposal",
      "dueAt": "2026-07-25 15:00:00"
    }
  ],
  "emailsLogged": 3
}

Registrar um email do Gmail

POST/api/v1/crm/extension/log-email

Salva um email na linha do tempo dos contatos que participam. Enviar o mesmo messageId de novo não duplica (200 com duplicate: true). 404 no_contact se nenhum participante for contato.

Escopo crm:write

NomeTipoObrigatórioDescrição
messageIdstringSimId da mensagem no Gmail (data-legacy-message-id)
fromstringSimRemetente, como "Ana <ana@acme.com>"
tostringNãoDestinatários, separados por vírgulas
subjectstringNãoAssunto do email
bodystringNãoCorpo em texto simples
curl -X POST "https://zerosoft.ai/api/v1/crm/extension/log-email" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "messageId": "18c2f0a1b2c3d4e5",
  "from": "Ana <ana@acme.com>",
  "to": "you@yourco.com",
  "subject": "Pricing",
  "body": "Hi…"
}'

Requisição

{
  "messageId": "18c2f0a1b2c3d4e5",
  "from": "Ana <ana@acme.com>",
  "to": "you@yourco.com",
  "subject": "Pricing",
  "body": "Hi…"
}

Resposta · 201

{
  "ok": true,
  "emailId": "{email_id}",
  "contactIds": [
    "{contact_id}"
  ],
  "duplicate": false
}

Registrar e rastrear um email antes de enviar

POST/api/v1/crm/extension/track

Salva o email de saída e devolve o pixel de aberturas para adicionar ao corpo. Se nenhum destinatário for contato, o primeiro é criado como contato.

Escopo crm:write

NomeTipoObrigatórioDescrição
tostringSimDestinatários, separados por vírgulas
subjectstringNãoAssunto do email
bodystringNãoCorpo em texto simples
curl -X POST "https://zerosoft.ai/api/v1/crm/extension/track" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "to": "ana@acme.com",
  "subject": "Proposal",
  "body": "Hi Ana…"
}'

Requisição

{
  "to": "ana@acme.com",
  "subject": "Proposal",
  "body": "Hi Ana…"
}

Resposta · 201

{
  "ok": true,
  "emailId": "{email_id}",
  "pixelUrl": "https://zerosoft.ai/api/crm/t/o/{token}.gif",
  "contactIds": [
    "{contact_id}"
  ],
  "createdContact": false
}

Cal

Tipos de evento e reservas. Reservas criadas pela API seguem as mesmas regras da página pública (disponibilidade, intervalos, ocupado no Google Calendar) e enviam os mesmos emails.

Listar tipos de evento

GET/api/v1/calendar/event-types

Seus tipos de evento com a URL pública de agendamento.

Escopo cal:read

curl -X GET "https://zerosoft.ai/api/v1/calendar/event-types" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "eventTypes": [
    {
      "id": "et_42",
      "slug": "intro",
      "title": "Intro call",
      "durationMin": 30,
      "active": true,
      "url": "https://zerosoft.ai/en/book/ana/intro"
    }
  ]
}

Listar reservas

GET/api/v1/calendar/bookings

Reservas dos seus tipos de evento, mais novas primeiro. Filtre por status e período.

Escopo cal:read

NomeTipoObrigatórioDescrição
statusconfirmed | cancelled | no_show | pendingNãoSó reservas com este status.
qstringNãoBusca no nome ou no email do convidado.
fromISO 8601NãoInício a partir de (inclusive).
toISO 8601NãoInício até (inclusive).
curl -X GET "https://zerosoft.ai/api/v1/calendar/bookings" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "bookings": [
    {
      "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
      "status": "confirmed",
      "startsAt": "2026-11-03T13:00:00.000Z",
      "endsAt": "2026-11-03T13:30:00.000Z",
      "timezone": "America/Argentina/Buenos_Aires",
      "invitee": {
        "name": "Ana",
        "email": "ana@example.com"
      },
      "answers": {},
      "hostUserId": "u_123",
      "meetingUrl": "https://meet.google.com/abc-defg-hij",
      "rescheduledFrom": null,
      "cancelReason": null,
      "eventType": {
        "id": "et_42",
        "slug": "intro",
        "title": "Intro call"
      }
    }
  ]
}

Criar uma reserva

POST/api/v1/calendar/bookings

Reserva um horário para um convidado. Retorna 409 slot_unavailable se o horário não for mais oferecido.

Escopo cal:write

NomeTipoObrigatórioDescrição
eventTypeIdstringSimId do tipo de evento (de Listar tipos de evento).
startISO 8601SimInício do horário; precisa coincidir com um oferecido.
namestringSimNome do convidado.
emailstringSimEmail do convidado: recebe a confirmação e o convite de calendário.
timezoneIANANãoFuso do convidado para os emails. Padrão UTC.
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "eventTypeId": "et_42",
  "start": "2026-11-03T13:00:00.000Z",
  "name": "Ana",
  "email": "ana@example.com",
  "timezone": "America/Argentina/Buenos_Aires"
}'

Requisição

{
  "eventTypeId": "et_42",
  "start": "2026-11-03T13:00:00.000Z",
  "name": "Ana",
  "email": "ana@example.com",
  "timezone": "America/Argentina/Buenos_Aires"
}

Resposta · 201

{
  "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
  "status": "confirmed",
  "startsAt": "2026-11-03T13:00:00.000Z",
  "endsAt": "2026-11-03T13:30:00.000Z",
  "timezone": "America/Argentina/Buenos_Aires",
  "invitee": {
    "name": "Ana",
    "email": "ana@example.com"
  },
  "answers": {},
  "hostUserId": "u_123",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "rescheduledFrom": null,
  "cancelReason": null,
  "eventType": {
    "id": "et_42",
    "slug": "intro",
    "title": "Intro call"
  }
}

Obter uma reserva

GET/api/v1/calendar/bookings/:id

Uma reserva por id (dono do tipo de evento ou host atribuído).

Escopo cal:read

curl -X GET "https://zerosoft.ai/api/v1/calendar/bookings/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
  "status": "confirmed",
  "startsAt": "2026-11-03T13:00:00.000Z",
  "endsAt": "2026-11-03T13:30:00.000Z",
  "timezone": "America/Argentina/Buenos_Aires",
  "invitee": {
    "name": "Ana",
    "email": "ana@example.com"
  },
  "answers": {},
  "hostUserId": "u_123",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "rescheduledFrom": null,
  "cancelReason": null,
  "eventType": {
    "id": "et_42",
    "slug": "intro",
    "title": "Intro call"
  }
}

Cancelar uma reserva

POST/api/v1/calendar/bookings/:id/cancel

Cancela uma reserva confirmada, envia ao convidado o cancelamento com .ics, remove o evento do Google Calendar e emite booking.cancelled.

Escopo cal:write

NomeTipoObrigatórioDescrição
reasonstringNãoMostrado ao convidado no email de cancelamento.
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings/:id/cancel" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer asked to move it to next month"
}'

Requisição

{
  "reason": "Customer asked to move it to next month"
}

Resposta · 200

{
  "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
  "status": "cancelled",
  "startsAt": "2026-11-03T13:00:00.000Z",
  "endsAt": "2026-11-03T13:30:00.000Z",
  "timezone": "America/Argentina/Buenos_Aires",
  "invitee": {
    "name": "Ana",
    "email": "ana@example.com"
  },
  "answers": {},
  "hostUserId": "u_123",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "rescheduledFrom": null,
  "cancelReason": "Customer asked to move it to next month",
  "eventType": {
    "id": "et_42",
    "slug": "intro",
    "title": "Intro call"
  }
}

Reagendar uma reserva

POST/api/v1/calendar/bookings/:id/reschedule

Move uma reserva confirmada para outro horário oferecido, envia ao convidado o .ics atualizado e emite booking.rescheduled. Retorna 409 slot_unavailable se o horário não é oferecido.

Escopo cal:write

NomeTipoObrigatórioDescrição
startISO 8601SimInício do horário; precisa coincidir com um oferecido.
timezoneIANANãoFuso do convidado para os emails. Padrão UTC.
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings/:id/reschedule" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "start": "2026-11-04T14:00:00.000Z"
}'

Requisição

{
  "start": "2026-11-04T14:00:00.000Z"
}

Resposta · 200

{
  "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
  "status": "confirmed",
  "startsAt": "2026-11-04T14:00:00.000Z",
  "endsAt": "2026-11-04T14:30:00.000Z",
  "timezone": "America/Argentina/Buenos_Aires",
  "invitee": {
    "name": "Ana",
    "email": "ana@example.com"
  },
  "answers": {},
  "hostUserId": "u_123",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "rescheduledFrom": null,
  "cancelReason": null,
  "eventType": {
    "id": "et_42",
    "slug": "intro",
    "title": "Intro call"
  }
}

Marcar ausência

POST/api/v1/calendar/bookings/:id/no-show

Marca que o convidado não apareceu. Só para reservas confirmadas.

Escopo cal:write

curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings/:id/no-show" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
  "status": "no_show",
  "startsAt": "2026-11-03T13:00:00.000Z",
  "endsAt": "2026-11-03T13:30:00.000Z",
  "timezone": "America/Argentina/Buenos_Aires",
  "invitee": {
    "name": "Ana",
    "email": "ana@example.com"
  },
  "answers": {},
  "hostUserId": "u_123",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "rescheduledFrom": null,
  "cancelReason": null,
  "eventType": {
    "id": "et_42",
    "slug": "intro",
    "title": "Intro call"
  }
}

Agents

Converse com seus agentes de AI a partir do seu próprio app. O agente usa as mesmas instruções, conhecimento e ferramentas do Chat e da página pública; cada resposta conta para a cota de AI do workspace.

Enviar uma mensagem a um agente

POST/api/v1/agents/:id/messages

Retorna a resposta do agente e as ferramentas que usou. Envie o conversationId retornado para continuar a mesma conversa. Erros: 404 not_found, 403 agent_disabled, 429 rate_limited, 503 ai_disabled.

Escopo agents:run

NomeTipoObrigatórioDescrição
messagestringSimO que o usuário diz (até 4000 caracteres).
conversationIdstringNãoContinua uma conversa de API existente. Omita para começar uma nova.
curl -X POST "https://zerosoft.ai/api/v1/agents/:id/messages" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "message": "Do you ship to Brazil?"
}'

Requisição

{
  "message": "Do you ship to Brazil?"
}

Resposta · 200

{
  "conversationId": "6b0f8f7e-2a43-4d0c-9a51-3f3c1f1b8e21",
  "message": {
    "id": "b7e1…",
    "role": "assistant",
    "content": "Yes! We ship to Brazil in 5–7 business days.",
    "createdAt": "2026-11-01T18:00:00.000Z"
  },
  "status": "replied",
  "handoff": false,
  "toolCalls": [
    {
      "tool": "search_knowledge",
      "input": {
        "query": "shipping Brazil"
      },
      "output": {
        "results": []
      },
      "error": null
    }
  ]
}

Chat

Leia e responda as conversas do inbox do Chat a partir do seu app ou helpdesk. Precisa do scope chat:read para ler e chat:write para responder, atribuir e resolver. As respostas saem em nome de quem criou a key.

Listar conversas

GET/api/v1/chat/conversations

Conversas dos widgets do workspace, as atualizadas mais recentemente primeiro.

Escopo chat:read

NomeTipoObrigatórioDescrição
statusopen | pending | snoozed | resolvedNãoSó conversas com este status.
assignedTostringNãoSó conversas atribuídas a este id de usuário, ou unassigned.
widgetIdstringNãoSó conversas deste widget.
limitintegerNãoQuantas devolver (de 1 a 200, 50 por padrão).
offsetintegerNãoQuantas pular, para paginar.
curl -X GET "https://zerosoft.ai/api/v1/chat/conversations" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "conversations": [
    {
      "id": "{conversation_id}",
      "widgetId": "{widget_id}",
      "status": "open",
      "priority": "medium",
      "subject": null,
      "assignedTo": "{user_id}",
      "visitor": {
        "id": "{visitor_id}",
        "name": "Ana",
        "email": "ana@example.com"
      },
      "firstResponseAt": "2026-11-01T18:02:00.000Z",
      "resolvedAt": null,
      "createdAt": "2026-11-01T18:00:00.000Z",
      "updatedAt": "2026-11-01T18:02:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Ver uma conversa

GET/api/v1/chat/conversations/{id}

A conversa e todas as suas mensagens, da mais antiga para a mais nova. As notas internas vêm com isNote: true.

Escopo chat:read

NomeTipoObrigatórioDescrição
idstringSimId do registro.
curl -X GET "https://zerosoft.ai/api/v1/chat/conversations/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "conversation": {
    "id": "{conversation_id}",
    "widgetId": "{widget_id}",
    "status": "open",
    "priority": "medium",
    "subject": null,
    "assignedTo": "{user_id}",
    "visitor": {
      "id": "{visitor_id}",
      "name": "Ana",
      "email": "ana@example.com"
    },
    "firstResponseAt": "2026-11-01T18:02:00.000Z",
    "resolvedAt": null,
    "createdAt": "2026-11-01T18:00:00.000Z",
    "updatedAt": "2026-11-01T18:02:00.000Z"
  },
  "messages": [
    {
      "id": "{message_id}",
      "conversationId": "{conversation_id}",
      "senderType": "user",
      "userId": "{user_id}",
      "body": "Hi Ana, the order ships tomorrow.",
      "isNote": false,
      "attachments": [],
      "createdAt": "2026-11-01T18:02:00.000Z"
    }
  ]
}

Responder

POST/api/v1/chat/conversations/{id}/messages

Envia uma mensagem ao visitante (ou uma nota interna com note: true). Como uma resposta do inbox, conta como primeira resposta para o SLA e reabre a conversa se estava resolvida. Dispara chat.message.created.

Escopo chat:write

NomeTipoObrigatórioDescrição
bodystringSimTexto da mensagem (até 5000 caracteres).
notebooleanNãotrue para deixar uma nota interna que o visitante não vê.
curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/messages" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "body": "Hi Ana, the order ships tomorrow."
}'

Requisição

{
  "body": "Hi Ana, the order ships tomorrow."
}

Resposta · 201

{
  "id": "{message_id}",
  "conversationId": "{conversation_id}",
  "senderType": "user",
  "userId": "{user_id}",
  "body": "Hi Ana, the order ships tomorrow.",
  "isNote": false,
  "attachments": [],
  "createdAt": "2026-11-01T18:02:00.000Z"
}

Atribuir

POST/api/v1/chat/conversations/{id}/assign

Atribui a conversa a um agente do widget, ou a deixa sem atribuição com null. Dispara chat.conversation.assigned. Erros: 400 invalid_assignee.

Escopo chat:write

NomeTipoObrigatórioDescrição
assignedTostringSimId de usuário do agente, ou null para tirar a atribuição.
curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/assign" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "assignedTo": "{user_id}"
}'

Requisição

{
  "assignedTo": "{user_id}"
}

Resposta · 200

{
  "id": "{conversation_id}",
  "widgetId": "{widget_id}",
  "status": "open",
  "priority": "medium",
  "subject": null,
  "assignedTo": "{user_id}",
  "visitor": {
    "id": "{visitor_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "firstResponseAt": "2026-11-01T18:02:00.000Z",
  "resolvedAt": null,
  "createdAt": "2026-11-01T18:00:00.000Z",
  "updatedAt": "2026-11-01T18:02:00.000Z"
}

Resolver

POST/api/v1/chat/conversations/{id}/resolve

Marca a conversa como resolvida. Se o widget tem atributos obrigatórios vazios, responde 400 missing_attributes. Dispara chat.conversation.resolved.

Escopo chat:write

curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/resolve" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{conversation_id}",
  "widgetId": "{widget_id}",
  "status": "resolved",
  "priority": "medium",
  "subject": null,
  "assignedTo": "{user_id}",
  "visitor": {
    "id": "{visitor_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "firstResponseAt": "2026-11-01T18:02:00.000Z",
  "resolvedAt": "2026-11-01T18:10:00.000Z",
  "createdAt": "2026-11-01T18:00:00.000Z",
  "updatedAt": "2026-11-01T18:02:00.000Z"
}

Reabrir

POST/api/v1/chat/conversations/{id}/reopen

Abre de novo uma conversa resolvida ou adiada.

Escopo chat:write

curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/reopen" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{conversation_id}",
  "widgetId": "{widget_id}",
  "status": "open",
  "priority": "medium",
  "subject": null,
  "assignedTo": "{user_id}",
  "visitor": {
    "id": "{visitor_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "firstResponseAt": "2026-11-01T18:02:00.000Z",
  "resolvedAt": null,
  "createdAt": "2026-11-01T18:00:00.000Z",
  "updatedAt": "2026-11-01T18:02:00.000Z"
}

Robots

Execute seus robôs de navegador a partir do seu próprio app, um de cada vez ou sobre muitas entradas. As execuções passam pela mesma fila do app (uma por vez por workspace) e contam para os minutos mensais de robôs. Para executar é preciso uma key criada por um admin do workspace.

Listar robôs

GET/api/v1/robots

Retorna os robôs do workspace com suas entradas, para saber o que enviar ao executá-los.

Escopo robots:run

curl -X GET "https://zerosoft.ai/api/v1/robots" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "robots": [
    {
      "id": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
      "name": "Price check",
      "description": "",
      "enabled": true,
      "inputs": [
        {
          "name": "url",
          "label": "Product URL",
          "kind": "text",
          "default": "",
          "required": true
        }
      ],
      "updatedAt": "2026-11-01T18:00:00.000Z"
    }
  ]
}

Executar um robô

POST/api/v1/robots/:id/runs

Coloca uma execução na fila e responde 202 com a execução; consulte GET /api/v1/robots/runs/:id até que status seja success ou failed. Com "wait": true a resposta espera o resultado (200) se não houver outra execução na frente. O robô precisa ter as execuções automáticas ativadas. Erros: 404 not_found, 400 missing_input ou disabled, 409 busy, 429 rate_limited ou quota_exceeded, 503 runner_unavailable.

Escopo robots:run

NomeTipoObrigatórioDescrição
inputsobjectNãoEntradas do robô por nome. Entradas do tipo lista recebem um array de textos.
waitbooleanNãoEsperar o resultado na mesma resposta (até o timeout do robô). Padrão false.
curl -X POST "https://zerosoft.ai/api/v1/robots/:id/runs" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
  }
}'

Requisição

{
  "inputs": {
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
  }
}

Resposta · 202

{
  "run": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "robotId": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
    "status": "queued",
    "trigger": "api",
    "input": {
      "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
    },
    "output": {},
    "error": null,
    "warnings": 0,
    "changed": null,
    "batchId": null,
    "createdAt": "2026-11-01T18:00:00.000Z",
    "startedAt": null,
    "finishedAt": null,
    "durationMs": null
  }
}

Ver uma execução

GET/api/v1/robots/runs/:id

Status, entradas e dados extraídos de uma execução. changed diz se os dados diferem da execução bem-sucedida anterior com as mesmas entradas (null se não havia com o que comparar).

Escopo robots:run

curl -X GET "https://zerosoft.ai/api/v1/robots/runs/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "run": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "robotId": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
    "status": "success",
    "trigger": "api",
    "input": {
      "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
    },
    "output": {
      "title": "A Light in the Attic",
      "price": "£51.77"
    },
    "error": null,
    "warnings": 0,
    "changed": false,
    "batchId": null,
    "createdAt": "2026-11-01T18:00:00.000Z",
    "startedAt": "2026-11-01T18:00:01.000Z",
    "finishedAt": "2026-11-01T18:00:06.000Z",
    "durationMs": 5000
  }
}

Executar um robô sobre muitas entradas

POST/api/v1/robots/:id/bulk

Coloca na fila uma execução por item de inputs (até 1.000 por pedido) sob um id de lote. Para chegar a 50.000, envie partes com o mesmo batchId, o offset da primeira linha de cada parte e total: nenhuma execução começa até todas as linhas chegarem, e reenviar uma parte não a duplica. As execuções seguem o ajuste de execuções simultâneas do workspace; cada entrada do pedido é validada antes de algo entrar na fila. Erros: 400 missing_input (com o índice do item), 409 busy, 429 rate_limited.

Escopo robots:run

NomeTipoObrigatórioDescrição
inputsobject[]SimUm objeto de entradas por execução, de 1 a 1.000 por pedido.
curl -X POST "https://zerosoft.ai/api/v1/robots/:id/bulk" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "inputs": [
    {
      "url": "https://example.com/a"
    },
    {
      "url": "https://example.com/b"
    }
  ]
}'

Requisição

{
  "inputs": [
    {
      "url": "https://example.com/a"
    },
    {
      "url": "https://example.com/b"
    }
  ]
}

Resposta · 202

{
  "batchId": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
  "total": 2,
  "runs": [
    {
      "id": "1f2e3d4c-…",
      "status": "queued",
      "input": {
        "url": "https://example.com/a"
      }
    },
    {
      "id": "5b6a7c8d-…",
      "status": "queued",
      "input": {
        "url": "https://example.com/b"
      }
    }
  ]
}

Ver um lote

GET/api/v1/robots/batches/:id

Contagens por status, done quando todas terminaram e uma página de execuções na ordem em que você enviou: ?limit= (até 1.000, o padrão) e ?offset=. nextOffset é o offset da próxima página, ou null na última.

Escopo robots:run

curl -X GET "https://zerosoft.ai/api/v1/robots/batches/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "batchId": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
  "robotId": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
  "total": 2,
  "counts": {
    "queued": 0,
    "running": 1,
    "success": 1,
    "failed": 0
  },
  "done": false,
  "nextOffset": null,
  "runs": [
    {
      "id": "1f2e3d4c-…",
      "status": "success",
      "input": {
        "url": "https://example.com/a"
      },
      "output": {
        "title": "A"
      },
      "error": null
    },
    {
      "id": "5b6a7c8d-…",
      "status": "running",
      "input": {
        "url": "https://example.com/b"
      },
      "output": {},
      "error": null
    }
  ]
}

Lines (WhatsApp)

Leia chats e grupos de WhatsApp, envie mensagens e crie tickets a partir dos seus sistemas. As mensagens saem do número ao qual o chat pertence.

Listar chats e grupos

GET/api/v1/groups/chats

Chats e grupos abertos, os mais recentes primeiro, com etiquetas, responsável e se esperam resposta.

Escopo groups:read

NomeTipoObrigatórioDescrição
filterstringNãoall, unread, unanswered, flagged, mine, unassigned ou closed
qstringNãoQuery de busca.
kindstringNãogroup ou dm
curl -X GET "https://zerosoft.ai/api/v1/groups/chats" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "gc_1",
      "kind": "group",
      "name": "Acme · Support",
      "memberCount": 12,
      "assignedTo": null,
      "labels": [
        {
          "id": "gl_1",
          "name": "Enterprise",
          "color": "blue"
        }
      ],
      "unread": 2,
      "lastMessageAt": "2026-11-01T18:00:00.000Z",
      "awaitingSince": "2026-11-01T18:00:00.000Z",
      "flagged": false
    }
  ],
  "total": 1
}

Listar mensagens

GET/api/v1/groups/chats/:id/messages

Mensagens e notas internas de um chat, da mais antiga para a mais nova.

Escopo groups:read

NomeTipoObrigatórioDescrição
afterstringNãoSó mensagens depois desta data ISO
curl -X GET "https://zerosoft.ai/api/v1/groups/chats/:id/messages" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "gm_1",
      "direction": "in",
      "senderName": "Ana",
      "senderPhone": "5491155550000",
      "body": "The October invoice did not arrive",
      "status": "received",
      "createdAt": "2026-11-01T18:00:00.000Z"
    }
  ]
}

Enviar uma mensagem

POST/api/v1/groups/chats/:id/messages

Envia um WhatsApp para o chat ou grupo, ou salva uma nota interna com note: true.

Escopo groups:write

NomeTipoObrigatórioDescrição
bodystringSimTexto da mensagem (até 4096 caracteres)
notebooleanNãoSalvar como nota interna em vez de enviar
pollobjectNãoObjeto com question, options (2 a 12) e multi, no lugar de body. Só WAHA e Evolution
mediaobjectNãoObjeto com url (https pública), mimetype e filename
curl -X POST "https://zerosoft.ai/api/v1/groups/chats/:id/messages" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "body": "Hi Ana, resending it now."
}'

Requisição

{
  "body": "Hi Ana, resending it now."
}

Resposta · 201

{
  "data": {
    "id": "gm_2",
    "direction": "out",
    "body": "Hi Ana, resending it now.",
    "status": "sent",
    "createdAt": "2026-11-01T18:01:00.000Z"
  }
}

Listar tickets

GET/api/v1/groups/tickets

Tickets criados a partir de mensagens de WhatsApp, com o status de SLA.

Escopo groups:read

NomeTipoObrigatórioDescrição
statusstringNãoactive (padrão), all, open, in_progress, resolved ou closed
curl -X GET "https://zerosoft.ai/api/v1/groups/tickets" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "gt_1",
      "number": 12,
      "title": "Invoice did not arrive",
      "status": "open",
      "priority": "high",
      "source": "reaction",
      "dueAt": "2026-11-02T18:00:00.000Z",
      "breached": false
    }
  ]
}

Criar um ticket

POST/api/v1/groups/tickets

Cria um ticket em um chat. Com messageId, uma mensagem tem no máximo um ticket: repetir devolve o existente.

Escopo groups:write

NomeTipoObrigatórioDescrição
chatIdstringSimId do chat ou grupo
titlestringNãoTítulo do ticket (padrão: a primeira linha da mensagem)
prioritystringNãolow, medium, high ou urgent
curl -X POST "https://zerosoft.ai/api/v1/groups/tickets" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "gc_1",
  "title": "Invoice did not arrive",
  "priority": "high"
}'

Requisição

{
  "chatId": "gc_1",
  "title": "Invoice did not arrive",
  "priority": "high"
}

Resposta · 201

{
  "data": {
    "id": "gt_1",
    "number": 12,
    "title": "Invoice did not arrive",
    "status": "open",
    "priority": "high",
    "source": "api"
  }
}

Ver um chat

GET/api/v1/groups/chats/:id

Um chat ou grupo com etiquetas, responsável e membros.

Escopo groups:read

curl -X GET "https://zerosoft.ai/api/v1/groups/chats/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "gc_1",
    "kind": "group",
    "name": "Acme · Support",
    "memberCount": 12,
    "status": "open",
    "labels": [],
    "members": [
      {
        "phone": "5491155550000",
        "name": "Ana",
        "role": "admin"
      }
    ]
  }
}

Atualizar um chat

PATCH/api/v1/groups/chats/:id

Atribuir, fechar ou reabrir, trocar etiquetas, renomear (também no WhatsApp se for grupo) ou definir propriedades. As mudanças ficam na auditoria.

Escopo groups:write

NomeTipoObrigatórioDescrição
assignedTostringNãoId de uma pessoa do workspace, ou null para tirar
statusopen | closedNãoopen ou closed
labelIdsstring[]NãoIds de etiquetas (substituem as atuais)
namestringNãoNome
curl -X PATCH "https://zerosoft.ai/api/v1/groups/chats/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "assignedTo": "u_1",
  "labelIds": [
    "gl_1"
  ]
}'

Requisição

{
  "assignedTo": "u_1",
  "labelIds": [
    "gl_1"
  ]
}

Resposta · 200

{
  "data": {
    "id": "gc_1",
    "assignedTo": "u_1",
    "status": "open",
    "labels": [
      {
        "id": "gl_1",
        "name": "Enterprise",
        "color": "blue"
      }
    ]
  }
}

Listar membros de um grupo

GET/api/v1/groups/chats/:id/members

Membros de um grupo com o papel (member, admin ou superadmin).

Escopo groups:read

curl -X GET "https://zerosoft.ai/api/v1/groups/chats/:id/members" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "phone": "5491155550000",
      "name": "Ana",
      "role": "admin"
    }
  ]
}

Adicionar, remover ou promover membros

POST/api/v1/groups/chats/:id/members

Muda membros no WhatsApp (números WAHA ou Evolution). Com action invite devolve o link de convite; revoke: true gera um novo.

Escopo groups:write

NomeTipoObrigatórioDescrição
actionadd | remove | promote | demote | inviteSimO que fazer com os telefones
phonesstring[]NãoTelefones em formato internacional
curl -X POST "https://zerosoft.ai/api/v1/groups/chats/:id/members" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "action": "add",
  "phones": [
    "+5491155550001"
  ]
}'

Requisição

{
  "action": "add",
  "phones": [
    "+5491155550001"
  ]
}

Resposta · 200

{
  "data": {
    "results": [
      {
        "phone": "5491155550001",
        "ok": true
      }
    ],
    "members": []
  }
}

Criar grupos

POST/api/v1/groups/groups

Cria um grupo de WhatsApp, ou até 50 com groups: [...]. Os telefones que o WhatsApp não deixou adicionar voltam em notAdded.

Escopo groups:write

NomeTipoObrigatórioDescrição
numberIdstringSimNúmero que cria o grupo (WAHA ou Evolution)
namestringSimNome
phonesstring[]NãoTelefones em formato internacional
curl -X POST "https://zerosoft.ai/api/v1/groups/groups" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "numberId": "gn_1",
  "name": "Acme · Onboarding",
  "phones": [
    "+5491155550001"
  ]
}'

Requisição

{
  "numberId": "gn_1",
  "name": "Acme · Onboarding",
  "phones": [
    "+5491155550001"
  ]
}

Resposta · 201

{
  "data": [
    {
      "name": "Acme · Onboarding",
      "ok": true,
      "chatId": "gc_2",
      "notAdded": []
    }
  ]
}

Listar números

GET/api/v1/groups/numbers

Números de WhatsApp conectados com provedor, status e recursos. As credenciais nunca são devolvidas.

Escopo groups:read

curl -X GET "https://zerosoft.ai/api/v1/groups/numbers" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "gn_1",
      "name": "Support line",
      "provider": "waha",
      "phone": "5491155550000",
      "status": "connected"
    }
  ]
}

Listar etiquetas

GET/api/v1/groups/labels

Etiquetas do workspace com quantos chats tem cada uma.

Escopo groups:read

curl -X GET "https://zerosoft.ai/api/v1/groups/labels" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "gl_1",
      "name": "Enterprise",
      "color": "blue",
      "count": 4
    }
  ]
}

Criar uma etiqueta

POST/api/v1/groups/labels

Cores: gray, red, orange, yellow, green, teal, blue, purple ou pink.

Escopo groups:write

NomeTipoObrigatórioDescrição
namestringSimNome
curl -X POST "https://zerosoft.ai/api/v1/groups/labels" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Enterprise",
  "color": "blue"
}'

Requisição

{
  "name": "Enterprise",
  "color": "blue"
}

Resposta · 201

{
  "data": {
    "id": "gl_1",
    "name": "Enterprise",
    "color": "blue"
  }
}

Ver um ticket

GET/api/v1/groups/tickets/:id

O ticket com os tickets vinculados no Freshdesk ou Zoho Desk, se houver.

Escopo groups:read

curl -X GET "https://zerosoft.ai/api/v1/groups/tickets/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "gt_1",
    "number": 12,
    "title": "Invoice did not arrive",
    "status": "open",
    "links": [
      {
        "kind": "freshdesk",
        "remoteId": "1042",
        "remoteUrl": "https://acme.freshdesk.com/a/tickets/1042"
      }
    ]
  }
}

Atualizar um ticket

PATCH/api/v1/groups/tickets/:id

Status, prioridade, responsável ou título. O novo status vai para os tickets vinculados do Freshdesk ou Zoho Desk.

Escopo groups:write

NomeTipoObrigatórioDescrição
statusstringNãoactive (padrão), all, open, in_progress, resolved ou closed
prioritystringNãolow, medium, high ou urgent
assigneeIdstringNãoId de uma pessoa do workspace, ou null para tirar
curl -X PATCH "https://zerosoft.ai/api/v1/groups/tickets/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "status": "resolved"
}'

Requisição

{
  "status": "resolved"
}

Resposta · 200

{
  "data": {
    "id": "gt_1",
    "number": 12,
    "status": "resolved"
  }
}

Fazer um envio em massa

POST/api/v1/groups/broadcasts

Envia uma mensagem ou enquete para muitos chats e grupos de um número, no ritmo escolhido (perMinute). Com scheduledAt sai depois.

Escopo groups:write

NomeTipoObrigatórioDescrição
chatIdsstring[]SimIds de chats e grupos
bodystringNãoTexto da mensagem (até 4096 caracteres)
pollobjectNãoObjeto com question, options (2 a 12) e multi, no lugar de body. Só WAHA e Evolution
scheduledAtstringNãoData ISO para enviar depois
curl -X POST "https://zerosoft.ai/api/v1/groups/broadcasts" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "chatIds": [
    "gc_1",
    "gc_2"
  ],
  "body": "Hi {{first_name}}, the new release is live.",
  "perMinute": 20
}'

Requisição

{
  "chatIds": [
    "gc_1",
    "gc_2"
  ],
  "body": "Hi {{first_name}}, the new release is live.",
  "perMinute": 20
}

Resposta · 201

{
  "data": {
    "id": "gb_1",
    "status": "scheduled",
    "total": 2
  }
}

Criar uma mensagem recorrente

POST/api/v1/groups/recurring

Repete uma mensagem ou enquete todo dia, toda semana, todo mês ou com uma expressão cron. GET na mesma rota lista com a próxima execução.

Escopo groups:write

NomeTipoObrigatórioDescrição
chatIdsstring[]SimIds de chats e grupos
ruleobjectSimObjeto com freq (daily, weekly, monthly ou cron), time (HH:MM), days (0 a 6), dayOfMonth ou cron
timezonestringNãoFuso horário IANA (padrão UTC)
endsAtstringNãoData ISO de fim, opcional
curl -X POST "https://zerosoft.ai/api/v1/groups/recurring" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "chatIds": [
    "gc_1"
  ],
  "body": "Weekly check-in: anything blocking you?",
  "rule": {
    "freq": "weekly",
    "days": [
      1
    ],
    "time": "09:00"
  },
  "timezone": "America/Argentina/Buenos_Aires"
}'

Requisição

{
  "chatIds": [
    "gc_1"
  ],
  "body": "Weekly check-in: anything blocking you?",
  "rule": {
    "freq": "weekly",
    "days": [
      1
    ],
    "time": "09:00"
  },
  "timezone": "America/Argentina/Buenos_Aires"
}

Resposta · 201

{
  "data": {
    "id": "gr_1",
    "status": "active",
    "nextRunAt": "2026-11-02T12:00:00.000Z"
  }
}

Servidor MCP

POST/api/v1/groups/mcp

Model Context Protocol por streamable HTTP (JSON-RPC). Métodos: initialize, tools/list, tools/call. Ferramentas: list_chats, get_messages, send_message, send_poll, update_chat, list_labels, create_ticket, list_tickets, update_ticket. As que escrevem pedem groups:write.

Escopo groups:read

curl -X POST "https://zerosoft.ai/api/v1/groups/mcp" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_chats",
    "arguments": {
      "filter": "unanswered"
    }
  }
}'

Requisição

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_chats",
    "arguments": {
      "filter": "unanswered"
    }
  }
}

Resposta · 200

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"total\":1,\"chats\":[...]}"
      }
    ],
    "isError": false
  }
}

Voice

Ditado e transcrições de reuniões. O app desktop usa estes endpoints com uma chave com voice:read e voice:write. O áudio é transcrito e descartado.

Ditar

POST/api/v1/voice/dictate

Envia um áudio em multipart. Devolve a transcrição limpa com o dicionário e o estilo da pessoa e salva no histórico de ditados.

Escopo voice:write

curl -X POST "https://zerosoft.ai/api/v1/voice/dictate" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "audio": "(multipart file, webm/ogg/wav/m4a/mp3, up to 4 MB)",
  "context": "email",
  "sourceApp": "Mail",
  "durationMs": 5200
}'

Requisição

{
  "audio": "(multipart file, webm/ogg/wav/m4a/mp3, up to 4 MB)",
  "context": "email",
  "sourceApp": "Mail",
  "durationMs": 5200
}

Resposta · 201

{
  "data": {
    "id": "vs_1",
    "text": "The launch is on Tuesday.",
    "raw": "um the launch is on monday, no, I mean tuesday",
    "ai": true
  }
}

Listar sessões

GET/api/v1/voice/sessions

Ditados e reuniões de quem criou a chave, da mais nova para a mais antiga.

Escopo voice:read

NomeTipoObrigatórioDescrição
kindstringNãomeeting ou dictation.
qstringNãoQuery de busca.
curl -X GET "https://zerosoft.ai/api/v1/voice/sessions" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "vs_2",
      "kind": "meeting",
      "title": "Acme pricing call",
      "status": "done",
      "durationMs": 1820000,
      "startedAt": "2026-11-02T15:00:00.000Z"
    }
  ]
}

Criar uma reunião

POST/api/v1/voice/sessions

Inicia uma reunião para enviar trechos de áudio.

Escopo voice:write

curl -X POST "https://zerosoft.ai/api/v1/voice/sessions" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "title": "Acme pricing call"
}'

Requisição

{
  "title": "Acme pricing call"
}

Resposta · 201

{
  "data": {
    "id": "vs_2",
    "title": "Acme pricing call",
    "status": "recording",
    "startedAt": "2026-11-02T15:00:00.000Z"
  }
}

Enviar um trecho de áudio

POST/api/v1/voice/sessions/:id/chunks

Transcreve um trecho da reunião. source é me (microfone), them (áudio do sistema) ou mixed. Idempotente por source e seq.

Escopo voice:write

curl -X POST "https://zerosoft.ai/api/v1/voice/sessions/:id/chunks" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "audio": "(multipart file, up to 4 MB)",
  "source": "them",
  "seq": 200,
  "offsetMs": 20000,
  "durationMs": 20000
}'

Requisição

{
  "audio": "(multipart file, up to 4 MB)",
  "source": "them",
  "seq": 200,
  "offsetMs": 20000,
  "durationMs": 20000
}

Resposta · 201

{
  "data": {
    "duplicate": false,
    "segments": [
      {
        "id": "sg_1",
        "source": "them",
        "speaker": "0",
        "startMs": 20400,
        "endMs": 24100,
        "text": "Twenty dollars works for us."
      }
    ]
  }
}

Ver uma sessão

GET/api/v1/voice/sessions/:id

A sessão com a transcrição, as notas e a nota com IA.

Escopo voice:read

curl -X GET "https://zerosoft.ai/api/v1/voice/sessions/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "vs_2",
    "title": "Acme pricing call",
    "segments": [],
    "myNotes": "",
    "enhanced": null
  }
}

Atualizar uma sessão

PATCH/api/v1/voice/sessions/:id

Mudar o título, ou definir status como done ao terminar a gravação.

Escopo voice:write

curl -X PATCH "https://zerosoft.ai/api/v1/voice/sessions/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "status": "done"
}'

Requisição

{
  "status": "done"
}

Resposta · 200

{
  "data": {
    "id": "vs_2",
    "title": "Acme pricing call",
    "status": "done",
    "durationMs": 1820000
  }
}

Dicionário e ajustes

GET/api/v1/voice/dictionary

Palavras, substituições, snippets e ajustes de ditado da pessoa, para sincronizar o app desktop.

Escopo voice:read

curl -X GET "https://zerosoft.ai/api/v1/voice/dictionary" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "entries": [
      {
        "id": "vd_1",
        "kind": "replace",
        "phrase": "zero soft",
        "replacement": "zerosoft"
      }
    ],
    "settings": {
      "language": "auto",
      "shortcut": "Alt+Space"
    }
  }
}

Track

Issues, comentários, equipes, cycles, status, labels e pessoas do Track. Use uma key com track:read ou track:write. Os issues criados pela API vão para triage se a equipe tiver ativo, e cada mudança deixa atividade, avisos, webhooks e uma entrada de audit como o app. As equipes antes se chamavam projetos: /api/v1/track/projects e projectId continuam funcionando.

Listar issues

GET/api/v1/track/issues

Issues que a key vê, os editados mais recentes primeiro, com filtros.

Escopo track:read

NomeTipoObrigatórioDescrição
teamIdstringNãoId ou chave da equipe (WEB). projectId também funciona.
statusCategorybacklog | todo | in_progress | done | cancelledNãoCategoria do status.
assigneeIdstringNãoId da pessoa atribuída.
priorityurgent | high | medium | lowNãoPrioridade.
qstringNãoQuery de busca.
updatedSincestringNãoSó issues editados desde esta data ISO.
pageintegerNãoNúmero da página.
pageSizeintegerNãoItems por página (máx 100).
curl -X GET "https://zerosoft.ai/api/v1/track/issues" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{issue_id}",
      "identifier": "WEB-12",
      "title": "Checkout button does nothing on Safari",
      "description": "Steps: open /pricing, press Buy.",
      "url": "https://zerosoft.ai/app/track/issues/{issue_id}",
      "projectId": "{team_id}",
      "teamId": "{team_id}",
      "planId": null,
      "status": {
        "id": "{status_id}",
        "name": "In Progress",
        "category": "in_progress",
        "color": "#000000"
      },
      "priority": "high",
      "assignee": {
        "id": "{user_id}",
        "name": "Ana",
        "email": "ana@example.com"
      },
      "creatorId": "{user_id}",
      "cycle": {
        "id": "{cycle_id}",
        "name": "Cycle 4"
      },
      "milestoneId": null,
      "parentId": null,
      "estimate": 3,
      "labels": [
        {
          "id": "{label_id}",
          "name": "bug",
          "color": "#d14343"
        }
      ],
      "startDate": null,
      "dueDate": "2026-11-04",
      "triage": false,
      "source": "api",
      "createdAt": "2026-10-25T14:02:11.000Z",
      "updatedAt": "2026-10-25T15:10:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "hasMore": false
}

Criar um issue

POST/api/v1/track/issues

teamId aceita o id ou a chave (WEB); projectId é o nome anterior. status aceita o nome do status ou uma categoria. Os links do Sentry, Zendesk, Intercom ou Figma ficam vinculados ao issue.

Escopo track:write

NomeTipoObrigatórioDescrição
teamIdstringSimId ou chave da equipe (WEB). projectId também funciona.
titlestringSimTítulo do issue.
descriptionstringNãoDescrição em markdown.
statusstringNãoNome do status ("In Progress") ou categoria (in_progress).
priorityurgent | high | medium | lowNãoPrioridade.
assigneeEmailstringNãoEmail de um membro da equipe.
labelsstring[]NãoNomes de labels; os que não existem são criados.
dueDatestringNãoPrazo, YYYY-MM-DD.
linksstring[]NãoURLs do Sentry, Zendesk, Intercom ou Figma para vincular.
curl -X POST "https://zerosoft.ai/api/v1/track/issues" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "teamId": "WEB",
  "title": "Checkout button does nothing on Safari",
  "description": "Steps: open /pricing, press Buy.",
  "priority": "high",
  "labels": [
    "bug"
  ],
  "links": [
    "https://acme.zendesk.com/agent/tickets/4812"
  ]
}'

Requisição

{
  "teamId": "WEB",
  "title": "Checkout button does nothing on Safari",
  "description": "Steps: open /pricing, press Buy.",
  "priority": "high",
  "labels": [
    "bug"
  ],
  "links": [
    "https://acme.zendesk.com/agent/tickets/4812"
  ]
}

Resposta · 201

{
  "id": "{issue_id}",
  "identifier": "WEB-12",
  "title": "Checkout button does nothing on Safari",
  "description": "Steps: open /pricing, press Buy.",
  "url": "https://zerosoft.ai/app/track/issues/{issue_id}",
  "projectId": "{team_id}",
  "teamId": "{team_id}",
  "planId": null,
  "status": {
    "id": "{status_id}",
    "name": "In Progress",
    "category": "in_progress",
    "color": "#000000"
  },
  "priority": "high",
  "assignee": {
    "id": "{user_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "creatorId": "{user_id}",
  "cycle": {
    "id": "{cycle_id}",
    "name": "Cycle 4"
  },
  "milestoneId": null,
  "parentId": null,
  "estimate": 3,
  "labels": [
    {
      "id": "{label_id}",
      "name": "bug",
      "color": "#d14343"
    }
  ],
  "startDate": null,
  "dueDate": "2026-11-04",
  "triage": false,
  "source": "api",
  "createdAt": "2026-10-25T14:02:11.000Z",
  "updatedAt": "2026-10-25T15:10:00.000Z"
}

Ver um issue

GET/api/v1/track/issues/{id}

Por id ou identificador (WEB-12).

Escopo track:read

NomeTipoObrigatórioDescrição
idstringSimId ou identificador do issue (WEB-12).
curl -X GET "https://zerosoft.ai/api/v1/track/issues/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{issue_id}",
  "identifier": "WEB-12",
  "title": "Checkout button does nothing on Safari",
  "description": "Steps: open /pricing, press Buy.",
  "url": "https://zerosoft.ai/app/track/issues/{issue_id}",
  "projectId": "{team_id}",
  "teamId": "{team_id}",
  "planId": null,
  "status": {
    "id": "{status_id}",
    "name": "In Progress",
    "category": "in_progress",
    "color": "#000000"
  },
  "priority": "high",
  "assignee": {
    "id": "{user_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "creatorId": "{user_id}",
  "cycle": {
    "id": "{cycle_id}",
    "name": "Cycle 4"
  },
  "milestoneId": null,
  "parentId": null,
  "estimate": 3,
  "labels": [
    {
      "id": "{label_id}",
      "name": "bug",
      "color": "#d14343"
    }
  ],
  "startDate": null,
  "dueDate": "2026-11-04",
  "triage": false,
  "source": "api",
  "createdAt": "2026-10-25T14:02:11.000Z",
  "updatedAt": "2026-10-25T15:10:00.000Z"
}

Editar um issue

PATCH/api/v1/track/issues/{id}

Envie só o que muda. Mudar status ou responsável aceita um issue que está em triage.

Escopo track:write

NomeTipoObrigatórioDescrição
idstringSimId ou identificador do issue (WEB-12).
statusstringNãoNome do status ("In Progress") ou categoria (in_progress).
assigneeEmailstringNãoEmail de um membro da equipe.
priorityurgent | high | medium | lowNãoPrioridade.
curl -X PATCH "https://zerosoft.ai/api/v1/track/issues/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "status": "Done"
}'

Requisição

{
  "status": "Done"
}

Resposta · 200

{
  "id": "{issue_id}",
  "identifier": "WEB-12",
  "title": "Checkout button does nothing on Safari",
  "description": "Steps: open /pricing, press Buy.",
  "url": "https://zerosoft.ai/app/track/issues/{issue_id}",
  "projectId": "{team_id}",
  "teamId": "{team_id}",
  "planId": null,
  "status": {
    "id": "{status_id}",
    "name": "Done",
    "category": "done",
    "color": "#000000"
  },
  "priority": "high",
  "assignee": {
    "id": "{user_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "creatorId": "{user_id}",
  "cycle": {
    "id": "{cycle_id}",
    "name": "Cycle 4"
  },
  "milestoneId": null,
  "parentId": null,
  "estimate": 3,
  "labels": [
    {
      "id": "{label_id}",
      "name": "bug",
      "color": "#d14343"
    }
  ],
  "startDate": null,
  "dueDate": "2026-11-04",
  "triage": false,
  "source": "api",
  "createdAt": "2026-10-25T14:02:11.000Z",
  "updatedAt": "2026-10-25T15:10:00.000Z"
}

Excluir um issue

DELETE/api/v1/track/issues/{id}

Exclui o issue e os sub-issues.

Escopo track:write

NomeTipoObrigatórioDescrição
idstringSimId ou identificador do issue (WEB-12).
curl -X DELETE "https://zerosoft.ai/api/v1/track/issues/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{issue_id}",
  "deleted": true
}

Listar comentários

GET/api/v1/track/issues/{id}/comments

Comentários de um issue, os mais antigos primeiro.

Escopo track:read

NomeTipoObrigatórioDescrição
idstringSimId ou identificador do issue (WEB-12).
curl -X GET "https://zerosoft.ai/api/v1/track/issues/{id}/comments" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{comment_id}",
      "issueId": "{issue_id}",
      "body": "Reproduced on Safari 18.",
      "author": {
        "id": "{user_id}",
        "name": "Ana",
        "email": "ana@example.com"
      },
      "createdAt": "2026-10-25T15:00:00.000Z",
      "updatedAt": "2026-10-25T15:00:00.000Z"
    }
  ]
}

Comentar

POST/api/v1/track/issues/{id}/comments

Comenta como o dono da key em markdown e avisa inscritos e menções.

Escopo track:write

NomeTipoObrigatórioDescrição
idstringSimId ou identificador do issue (WEB-12).
bodystringSimComentário em markdown.
curl -X POST "https://zerosoft.ai/api/v1/track/issues/{id}/comments" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "body": "Deployed the fix to staging."
}'

Requisição

{
  "body": "Deployed the fix to staging."
}

Resposta · 201

{
  "id": "{comment_id}",
  "issueId": "{issue_id}",
  "body": "Deployed the fix to staging.",
  "author": {
    "id": "{user_id}",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "createdAt": "2026-10-25T16:00:00.000Z",
  "updatedAt": "2026-10-25T16:00:00.000Z"
}

Listar equipes

GET/api/v1/track/teams

Equipes ativas que a key vê. includeArchived=true inclui as arquivadas.

Escopo track:read

curl -X GET "https://zerosoft.ai/api/v1/track/teams" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{team_id}",
      "name": "Web",
      "key": "WEB",
      "description": "",
      "icon": null,
      "color": "#000000",
      "status": "active",
      "visibility": "workspace",
      "triageEnabled": true,
      "url": "https://zerosoft.ai/app/track/team/WEB",
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-10-20T10:00:00.000Z"
    }
  ]
}

Criar uma equipe

POST/api/v1/track/teams

Só admins. Cria os status padrão. key é o prefixo dos identificadores.

Escopo track:write

NomeTipoObrigatórioDescrição
namestringSimNome
keystringNãoPrefixo dos identificadores, letras e números (WEB).
descriptionstringNãoDescrição
curl -X POST "https://zerosoft.ai/api/v1/track/teams" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Web",
  "key": "WEB"
}'

Requisição

{
  "name": "Web",
  "key": "WEB"
}

Resposta · 201

{
  "id": "{team_id}",
  "name": "Web",
  "key": "WEB",
  "description": "",
  "icon": null,
  "color": "#000000",
  "status": "active",
  "visibility": "workspace",
  "triageEnabled": true,
  "url": "https://zerosoft.ai/app/track/team/WEB",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-10-20T10:00:00.000Z"
}

Ver uma equipe

GET/api/v1/track/teams/{id}

Por id ou chave, com os status.

Escopo track:read

NomeTipoObrigatórioDescrição
idstringSimId ou chave da equipe (WEB). projectId também funciona.
curl -X GET "https://zerosoft.ai/api/v1/track/teams/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "id": "{team_id}",
  "name": "Web",
  "key": "WEB",
  "description": "",
  "icon": null,
  "color": "#000000",
  "status": "active",
  "visibility": "workspace",
  "triageEnabled": true,
  "url": "https://zerosoft.ai/app/track/team/WEB",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-10-20T10:00:00.000Z",
  "statuses": [
    {
      "id": "{status_id}",
      "projectId": "{project_id}",
      "name": "Todo",
      "category": "todo",
      "color": "#000000",
      "position": 1
    }
  ]
}

Editar uma equipe

PATCH/api/v1/track/teams/{id}

Nome, descrição, cor e ícone. Arquivar e triage pedem uma key de admin.

Escopo track:write

NomeTipoObrigatórioDescrição
idstringSimId ou chave da equipe (WEB). projectId também funciona.
statusactive | archivedNãoactive ou archived.
curl -X PATCH "https://zerosoft.ai/api/v1/track/teams/{id}" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "description": "Marketing site and checkout"
}'

Requisição

{
  "description": "Marketing site and checkout"
}

Resposta · 200

{
  "id": "{team_id}",
  "name": "Web",
  "key": "WEB",
  "description": "",
  "icon": null,
  "color": "#000000",
  "status": "active",
  "visibility": "workspace",
  "triageEnabled": true,
  "url": "https://zerosoft.ai/app/track/team/WEB",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-10-20T10:00:00.000Z"
}

Listar cycles

GET/api/v1/track/teams/{id}/cycles

Cycles de uma equipe.

Escopo track:read

NomeTipoObrigatórioDescrição
idstringSimId ou chave da equipe (WEB). projectId também funciona.
curl -X GET "https://zerosoft.ai/api/v1/track/teams/{id}/cycles" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{cycle_id}",
      "projectId": "{project_id}",
      "name": "Cycle 4",
      "startAt": "2026-10-20",
      "endAt": "2026-11-02",
      "completedAt": null
    }
  ]
}

Criar um cycle

POST/api/v1/track/teams/{id}/cycles

Datas em YYYY-MM-DD.

Escopo track:write

NomeTipoObrigatórioDescrição
namestringSimNome
startAtstringSimData, YYYY-MM-DD.
endAtstringSimData, YYYY-MM-DD.
curl -X POST "https://zerosoft.ai/api/v1/track/teams/{id}/cycles" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Cycle 5",
  "startAt": "2026-11-03",
  "endAt": "2026-11-16"
}'

Requisição

{
  "name": "Cycle 5",
  "startAt": "2026-11-03",
  "endAt": "2026-11-16"
}

Resposta · 201

{
  "id": "{cycle_id}",
  "projectId": "{project_id}",
  "name": "Cycle 5",
  "startAt": "2026-11-03",
  "endAt": "2026-11-16",
  "completedAt": null
}

Listar status

GET/api/v1/track/teams/{id}/statuses

Status do workflow de uma equipe em ordem, com a categoria.

Escopo track:read

NomeTipoObrigatórioDescrição
idstringSimId ou chave da equipe (WEB). projectId também funciona.
curl -X GET "https://zerosoft.ai/api/v1/track/teams/{id}/statuses" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{status_id}",
      "projectId": "{project_id}",
      "name": "In Progress",
      "category": "in_progress",
      "color": "#000000",
      "position": 2
    }
  ]
}

Listar labels

GET/api/v1/track/labels

Labels do workspace. POST com name e teamId cria um.

Escopo track:read

curl -X GET "https://zerosoft.ai/api/v1/track/labels" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{label_id}",
      "name": "bug",
      "color": "#d14343",
      "workspaceId": "{workspace_id}"
    }
  ]
}

Listar pessoas

GET/api/v1/track/users

Pessoas que podem ser atribuídas, de uma equipe ou de todas.

Escopo track:read

NomeTipoObrigatórioDescrição
teamIdstringNãoId ou chave da equipe (WEB). projectId também funciona.
curl -X GET "https://zerosoft.ai/api/v1/track/users" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "{user_id}",
      "name": "Ana",
      "email": "ana@example.com",
      "role": "member"
    }
  ]
}

Servidor MCP do Track

Model Context Protocol via Streamable HTTP em /api/mcp/track (só leitura em /api/mcp/track/readonly). Autenticação com uma API key como Bearer. Ferramentas: search_issues, get_issue, create_issue, update_issue, add_comment, list_teams, get_team, list_cycles, list_labels, list_users.

Chamar uma ferramenta

POST/api/mcp/track

JSON-RPC 2.0: initialize, tools/list e tools/call. As ferramentas que escrevem pedem track:write.

Escopo track:read

curl -X POST "https://zerosoft.ai/api/mcp/track" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_issues",
    "arguments": {
      "query": "checkout",
      "statusCategory": "in_progress"
    }
  }
}'

Requisição

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_issues",
    "arguments": {
      "query": "checkout",
      "statusCategory": "in_progress"
    }
  }
}

Resposta · 200

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"total\": 1, \"issues\": [ … ] }"
      }
    ],
    "isError": false
  }
}

Docs

Leia e escreva páginas, blocos, bancos, linhas e comentários do Docs. O conteúdo entra e sai em Markdown (ou em blocos do Docs). Uma key age como a pessoa que a criou: só vê e edita as páginas que essa pessoa pode abrir. Bancos sincronizados são somente leitura.

Listar páginas

GET/api/v1/docs/pages

Páginas que a key pode ler, mais novas primeiro. Com q procura em títulos e conteúdo.

Escopo docs:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
parentstringNãoSó páginas dentro deste id (root para as do topo).
limitnumberNãoQuantos retornar (1 a 100, padrão 50).
offsetnumberNãoQuantos pular, para paginar.
curl -X GET "https://zerosoft.ai/api/v1/docs/pages" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "pg_1",
      "title": "Launch plan",
      "icon": null,
      "parentId": null,
      "url": "/app/docs/pg_1",
      "createdAt": "2026-11-01T12:00:00.000Z",
      "updatedAt": "2026-11-02T09:30:00.000Z",
      "archived": false
    }
  ],
  "hasMore": false
}

Criar uma página

POST/api/v1/docs/pages

Cria uma página a partir de Markdown ou blocos, dentro de outra (parentId) ou de um modelo (id de modelo do workspace ou builtin:<key>). As {{variáveis}} do modelo são preenchidas com vars.

Escopo docs:write

NomeTipoObrigatórioDescrição
titlestringNãoTítulo da página.
markdownstringNãoConteúdo em Markdown (títulos, listas, to-dos, citações, código, tabelas).
parentIdstringNãoCriar como subpágina desta página.
templateIdstringNãoId de modelo do workspace ou builtin:<key>.
curl -X POST "https://zerosoft.ai/api/v1/docs/pages" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "title": "Launch plan",
  "parentId": "pg_root",
  "markdown": "## Goals\n\n- [ ] Ship the beta"
}'

Requisição

{
  "title": "Launch plan",
  "parentId": "pg_root",
  "markdown": "## Goals\n\n- [ ] Ship the beta"
}

Resposta · 201

{
  "data": {
    "id": "pg_1",
    "title": "Launch plan",
    "icon": null,
    "parentId": null,
    "url": "/app/docs/pg_1",
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z",
    "archived": false,
    "access": "owner",
    "markdown": "## Goals\n\n- [ ] Ship the beta",
    "databases": []
  }
}

Ler uma página

GET/api/v1/docs/pages/:id

A página com o conteúdo em Markdown e seus bancos. Com format=blocks traz também os blocos.

Escopo docs:read

NomeTipoObrigatórioDescrição
formatstringNãoblocks para trazer também os blocos.
curl -X GET "https://zerosoft.ai/api/v1/docs/pages/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "pg_1",
    "title": "Launch plan",
    "icon": null,
    "parentId": null,
    "url": "/app/docs/pg_1",
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z",
    "archived": false,
    "access": "edit",
    "markdown": "## Goals\n\n- [ ] Ship the beta",
    "databases": [
      {
        "blockId": "b_1",
        "title": "Tasks",
        "rows": 12,
        "synced": false
      }
    ]
  }
}

Atualizar uma página

PATCH/api/v1/docs/pages/:id

Muda o título ou o ícone, substitui o conteúdo (os bancos da página são mantidos) ou manda para a lixeira e tira de lá (archived).

Escopo docs:write

NomeTipoObrigatórioDescrição
titlestringNãoTítulo da página.
markdownstringNãoSubstitui todo o conteúdo (os bancos são mantidos).
archivedbooleanNãotrue manda para a lixeira, false restaura.
curl -X PATCH "https://zerosoft.ai/api/v1/docs/pages/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "title": "Launch plan (Q4)"
}'

Requisição

{
  "title": "Launch plan (Q4)"
}

Resposta · 200

{
  "data": {
    "id": "pg_1",
    "title": "Launch plan (Q4)",
    "icon": null,
    "parentId": null,
    "url": "/app/docs/pg_1",
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z",
    "archived": false,
    "access": "owner",
    "markdown": "",
    "databases": []
  }
}

Mandar uma página para a lixeira

DELETE/api/v1/docs/pages/:id

Manda a página e suas subpáginas para a lixeira. Restaure com PATCH archived: false.

Escopo docs:write

curl -X DELETE "https://zerosoft.ai/api/v1/docs/pages/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Listar blocos

GET/api/v1/docs/pages/:id/blocks

Os blocos de uma página no formato do Docs (tipo, conteúdo em HTML-lite, aninhamento com indent).

Escopo docs:read

curl -X GET "https://zerosoft.ai/api/v1/docs/pages/:id/blocks" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "b_1",
      "type": "heading",
      "level": 2,
      "content": "Goals"
    },
    {
      "id": "b_2",
      "type": "todo",
      "content": "Ship the beta",
      "checked": false
    }
  ]
}

Adicionar blocos

POST/api/v1/docs/pages/:id/blocks

Adiciona Markdown ou blocos no fim da página, ou abaixo do bloco em after. Quem está com a página aberta vê mesclado no editor.

Escopo docs:write

NomeTipoObrigatórioDescrição
markdownstringNãoConteúdo em Markdown (títulos, listas, to-dos, citações, código, tabelas).
blocksobject[]NãoBlocos no formato do Docs (em vez de Markdown).
afterstringNãoInserir abaixo deste id de bloco.
curl -X POST "https://zerosoft.ai/api/v1/docs/pages/:id/blocks" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "markdown": "- [ ] Write the release notes"
}'

Requisição

{
  "markdown": "- [ ] Write the release notes"
}

Resposta · 201

{
  "data": {
    "id": "pg_1",
    "title": "Launch plan",
    "icon": null,
    "parentId": null,
    "url": "/app/docs/pg_1",
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z",
    "archived": false,
    "access": "owner",
    "markdown": "- [ ] Write the release notes",
    "databases": []
  }
}

Listar comentários

GET/api/v1/docs/pages/:id/comments

Comentários e conversas de uma página.

Escopo docs:read

curl -X GET "https://zerosoft.ai/api/v1/docs/pages/:id/comments" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "cm_1",
      "pageId": "pg_1",
      "blockId": null,
      "parentId": null,
      "text": "Can we ship this in May?",
      "resolved": false,
      "author": {
        "id": "u_1",
        "name": "Ada",
        "email": "ada@example.com"
      },
      "createdAt": "2026-11-02T10:00:00.000Z"
    }
  ]
}

Comentar

POST/api/v1/docs/pages/:id/comments

Comenta a página ou um bloco, ou responde uma conversa, como a pessoa que criou a key.

Escopo docs:write

NomeTipoObrigatórioDescrição
textstringSimTexto do comentário.
blockIdstringNãoComentar este bloco.
parentIdstringNãoResponder na conversa deste comentário.
curl -X POST "https://zerosoft.ai/api/v1/docs/pages/:id/comments" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "text": "Done, the beta is live."
}'

Requisição

{
  "text": "Done, the beta is live."
}

Resposta · 201

{
  "data": {
    "id": "cm_2",
    "pageId": "pg_1",
    "blockId": null,
    "parentId": null,
    "text": "Done, the beta is live.",
    "resolved": false,
    "author": {
      "id": "u_1",
      "name": "Ada",
      "email": "ada@example.com"
    },
    "createdAt": "2026-11-02T11:00:00.000Z"
  }
}

Listar bancos

GET/api/v1/docs/databases

Bancos das páginas que a key pode ler, com propriedades e opções.

Escopo docs:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
curl -X GET "https://zerosoft.ai/api/v1/docs/databases" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "pageId": "pg_1",
      "blockId": "b_1",
      "title": "Tasks",
      "page": {
        "id": "pg_1",
        "title": "Launch plan"
      },
      "synced": null,
      "properties": [
        {
          "id": "title",
          "name": "Name",
          "type": "title"
        },
        {
          "id": "status",
          "name": "Status",
          "type": "status",
          "options": [
            "Not started",
            "In progress",
            "Done"
          ]
        }
      ],
      "rowCount": 12
    }
  ]
}

Ler um banco

GET/api/v1/docs/databases/:pageId/:blockId

Propriedades de um banco e, se for sincronizado, de onde vem.

Escopo docs:read

curl -X GET "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "pageId": "pg_1",
    "blockId": "b_1",
    "title": "Issues",
    "page": {
      "id": "pg_1",
      "title": "Engineering"
    },
    "synced": {
      "provider": "github",
      "label": "acme/web · Issues",
      "syncedAt": "2026-11-02T10:15:00.000Z"
    },
    "properties": [
      {
        "id": "title",
        "name": "Title",
        "type": "title"
      }
    ],
    "rowCount": 40
  }
}

Consultar linhas

GET/api/v1/docs/databases/:pageId/:blockId/rows

Linhas de um banco com propriedades em texto (properties) e valores brutos (values). filter[Propriedade]=texto mantém as linhas cujo valor contém o texto.

Escopo docs:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
filter[Property]stringNãoMantém as linhas cuja Propriedade contém o texto.
limitnumberNãoQuantos retornar (1 a 100, padrão 50).
offsetnumberNãoQuantos pular, para paginar.
curl -X GET "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "r_1",
      "title": "Website refresh",
      "url": "/app/docs/pg_1?row=r_1",
      "properties": {
        "Status": "In progress",
        "Owner": "Ada"
      },
      "values": {
        "Status": "opt_2",
        "Owner": [
          "u_1"
        ]
      },
      "createdAt": "2026-11-01T12:00:00.000Z",
      "updatedAt": "2026-11-02T09:00:00.000Z"
    }
  ],
  "total": 1,
  "hasMore": false
}

Adicionar uma linha

POST/api/v1/docs/databases/:pageId/:blockId/rows

Adiciona uma linha. properties vai do nome (ou id) da propriedade ao valor: opções de select são criadas se faltarem, pessoas por email e datas como AAAA-MM-DD. As automações do banco rodam como sempre.

Escopo docs:write

NomeTipoObrigatórioDescrição
titlestringNãoTítulo da linha.
propertiesobjectNãoNome ou id da propriedade → valor.
markdownstringNãoConteúdo da linha em Markdown.
templatestringNãoModelo de linha do banco (id ou nome).
curl -X POST "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "title": "Website refresh",
  "properties": {
    "Status": "In progress",
    "Owner": "ada@example.com",
    "Tags": [
      "web",
      "q4"
    ]
  }
}'

Requisição

{
  "title": "Website refresh",
  "properties": {
    "Status": "In progress",
    "Owner": "ada@example.com",
    "Tags": [
      "web",
      "q4"
    ]
  }
}

Resposta · 201

{
  "data": {
    "id": "r_2",
    "title": "Website refresh",
    "url": "/app/docs/pg_1?row=r_2",
    "properties": {
      "Status": "In progress",
      "Owner": "Ada",
      "Tags": "web, q4"
    },
    "values": {},
    "createdAt": "2026-11-02T12:00:00.000Z",
    "updatedAt": "2026-11-02T12:00:00.000Z"
  }
}

Ler uma linha

GET/api/v1/docs/databases/:pageId/:blockId/rows/:rowId

Uma linha com propriedades e conteúdo em Markdown.

Escopo docs:read

curl -X GET "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows/:rowId" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "r_1",
    "title": "Website refresh",
    "url": "/app/docs/pg_1?row=r_1",
    "properties": {
      "Status": "In progress"
    },
    "values": {},
    "markdown": "Brief and links.",
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:00:00.000Z"
  }
}

Atualizar uma linha

PATCH/api/v1/docs/databases/:pageId/:blockId/rows/:rowId

Muda propriedades, o título ou o conteúdo de uma linha.

Escopo docs:write

NomeTipoObrigatórioDescrição
propertiesobjectNãoNome ou id da propriedade → valor.
titlestringNãoTítulo da linha.
appendMarkdownstringNãoMarkdown para adicionar no fim do conteúdo da linha.
curl -X PATCH "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows/:rowId" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "properties": {
    "Status": "Done"
  }
}'

Requisição

{
  "properties": {
    "Status": "Done"
  }
}

Resposta · 200

{
  "data": {
    "id": "r_1",
    "title": "Website refresh",
    "url": "/app/docs/pg_1?row=r_1",
    "properties": {
      "Status": "Done"
    },
    "values": {},
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T13:00:00.000Z"
  }
}

Apagar uma linha

DELETE/api/v1/docs/databases/:pageId/:blockId/rows/:rowId

Apaga a linha. Ela fica no histórico da página.

Escopo docs:write

curl -X DELETE "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows/:rowId" \
  -H "Authorization: Bearer zs_live_9f3k..."

Servidor MCP

POST/api/v1/docs/mcp

Model Context Protocol sobre HTTP (JSON-RPC). Métodos: initialize, tools/list, tools/call. Ferramentas: search, fetch_page, create_page, update_page, list_databases, get_database, query_database, get_row, create_row, update_row, list_comments, add_comment. As que escrevem pedem docs:write.

Escopo docs:read

curl -X POST "https://zerosoft.ai/api/v1/docs/mcp" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "launch plan"
    }
  }
}'

Requisição

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "launch plan"
    }
  }
}

Resposta · 200

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"results\":[...]}"
      }
    ],
    "isError": false
  }
}

Notes

Leia e escreva suas notas. Uma chave age como a pessoa que a criou e só vê as notas dela. Notas bloqueadas não retornam conteúdo.

Listar notas

GET/api/v1/notes

Suas notas, as mais recentes primeiro. q aceita os mesmos operadores do app (tag:, notebook:, intitle:, todo:).

Escopo notes:read

curl -X GET "https://zerosoft.ai/api/v1/notes" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "note_1",
      "title": "Weekly review",
      "snippet": "Send the report",
      "notebookId": null,
      "tags": [
        "work"
      ],
      "pinned": false,
      "trashed": false,
      "locked": false,
      "sourceUrl": null,
      "createdAt": "2026-11-01T12:00:00.000Z",
      "updatedAt": "2026-11-02T09:30:00.000Z"
    }
  ],
  "hasMore": false
}

Criar uma nota

POST/api/v1/notes

Cria uma nota a partir de Markdown ou blocos.

Escopo notes:write

curl -X POST "https://zerosoft.ai/api/v1/notes" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "title": "Weekly review",
  "markdown": "- [ ] Send the report",
  "tags": [
    "work"
  ]
}'

Requisição

{
  "title": "Weekly review",
  "markdown": "- [ ] Send the report",
  "tags": [
    "work"
  ]
}

Resposta · 201

{
  "data": {
    "id": "note_1",
    "title": "Weekly review",
    "snippet": "Send the report",
    "notebookId": null,
    "tags": [
      "work"
    ],
    "pinned": false,
    "trashed": false,
    "locked": false,
    "sourceUrl": null,
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z",
    "markdown": "- [ ] Send the report"
  }
}

Ler uma nota

GET/api/v1/notes/:id

Uma nota com o conteúdo em Markdown e blocos.

Escopo notes:read

curl -X GET "https://zerosoft.ai/api/v1/notes/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "note_1",
    "title": "Weekly review",
    "snippet": "Send the report",
    "notebookId": null,
    "tags": [
      "work"
    ],
    "pinned": false,
    "trashed": false,
    "locked": false,
    "sourceUrl": null,
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z",
    "markdown": "- [ ] Send the report"
  }
}

Editar uma nota

PATCH/api/v1/notes/:id

Muda título, etiquetas, caderno, fixação ou conteúdo.

Escopo notes:write

curl -X PATCH "https://zerosoft.ai/api/v1/notes/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "title": "Weekly review (done)",
  "pinned": true
}'

Requisição

{
  "title": "Weekly review (done)",
  "pinned": true
}

Resposta · 200

{
  "data": {
    "id": "note_1",
    "title": "Weekly review",
    "snippet": "Send the report",
    "notebookId": null,
    "tags": [
      "work"
    ],
    "pinned": true,
    "trashed": false,
    "locked": false,
    "sourceUrl": null,
    "createdAt": "2026-11-01T12:00:00.000Z",
    "updatedAt": "2026-11-02T09:30:00.000Z"
  }
}

Enviar para a lixeira

DELETE/api/v1/notes/:id

Move a nota para a lixeira.

Escopo notes:write

curl -X DELETE "https://zerosoft.ai/api/v1/notes/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "note_1",
    "trashed": true
  }
}

Listar cadernos

GET/api/v1/notes/notebooks

Seus cadernos com a contagem de notas.

Escopo notes:read

curl -X GET "https://zerosoft.ai/api/v1/notes/notebooks" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "nb_1",
      "name": "Work",
      "count": 12,
      "stack": null
    }
  ]
}

Servidor MCP

POST/api/v1/notes/mcp

Endpoint do Model Context Protocol. Ferramentas: search_notes, read_note, list_notebooks, list_tasks, create_note e update_note.

Escopo notes:read

curl -X POST "https://zerosoft.ai/api/v1/notes/mcp" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "query": "tag:work"
    }
  }
}'

Requisição

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "query": "tag:work"
    }
  }
}

Resposta · 200

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"notes\":[...]}"
      }
    ],
    "isError": false
  }
}

Talk

Mensagens de equipe. A key age como a pessoa que a criou: vê os canais que essa pessoa vê e publica onde ela é membro (em um canal público entra ao publicar). As mensagens diretas não estão na API. Escopos talk:read e talk:write.

Listar canais

GET/api/v1/talk/channels

Os canais em que a pessoa da key está, ou com scope=all os públicos e os privados em que ela está.

Escopo talk:read

NomeTipoObrigatórioDescrição
scopestringNãomember (padrão) ou all
qstringNãoQuery de busca.
curl -X GET "https://zerosoft.ai/api/v1/talk/channels" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "tc_1",
      "name": "general",
      "kind": "public",
      "topic": "Company news",
      "description": "",
      "archived": false,
      "member_count": 8,
      "is_member": true,
      "created_at": "2026-10-25T12:00:00.000Z"
    }
  ]
}

Criar um canal

POST/api/v1/talk/channels

Cria um canal público ou privado. O nome é salvo como no Slack: em minúsculas e com hífens no lugar de espaços.

Escopo talk:write

NomeTipoObrigatórioDescrição
namestringSimNome do canal
kindstringNãopublic (padrão) ou private
topicstringNãoTema do canal
curl -X POST "https://zerosoft.ai/api/v1/talk/channels" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "launch-q4",
  "kind": "public",
  "topic": "Q4 launch"
}'

Requisição

{
  "name": "launch-q4",
  "kind": "public",
  "topic": "Q4 launch"
}

Resposta · 201

{
  "data": {
    "id": "tc_2",
    "name": "launch-q4",
    "kind": "public",
    "topic": "Q4 launch",
    "description": "",
    "archived": false,
    "member_count": 1,
    "is_member": true,
    "created_at": "2026-10-25T12:00:00.000Z"
  }
}

Listar mensagens

GET/api/v1/talk/messages

As mensagens do canal, da mais antiga para a mais nova. As menções vêm como tokens com o id da pessoa, mais os de canal e aqui.

Escopo talk:read

NomeTipoObrigatórioDescrição
channelstringSimId ou nome do canal (general ou #general)
beforestringNãoData ISO: as mensagens anteriores (para paginar)
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/v1/talk/messages" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "tm_1",
      "channel_id": "tc_1",
      "thread_id": null,
      "user_id": "u_1",
      "bot_name": null,
      "text": "Deploy done <@u_2>",
      "files": [],
      "reactions": [
        {
          "emoji": "🎉",
          "count": 2,
          "users": [
            "u_2",
            "u_3"
          ]
        }
      ],
      "reply_count": 1,
      "edited_at": null,
      "pinned": false,
      "created_at": "2026-10-25T12:05:00.000Z"
    }
  ],
  "has_more": false
}

Enviar uma mensagem

POST/api/v1/talk/messages

Publica em um canal ou responde em um fio. Menções, avisos, prévias de links, Flow e webhooks rodam como se fosse pelo app.

Escopo talk:write

NomeTipoObrigatórioDescrição
channelstringSimId ou nome do canal (general ou #general)
textstringSimTexto da mensagem, com a mesma formatação do app (*negrito*, _itálico_, `código`, links, :emoji:)
thread_idstringNãoId da mensagem raiz para responder no fio
also_in_channelbooleanNãoCom thread_id, mostrar a resposta também no canal
curl -X POST "https://zerosoft.ai/api/v1/talk/messages" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "channel": "general",
  "text": "Release *2.4* is live :tada:"
}'

Requisição

{
  "channel": "general",
  "text": "Release *2.4* is live :tada:"
}

Resposta · 201

{
  "data": {
    "id": "tm_2",
    "channel_id": "tc_1",
    "thread_id": null,
    "user_id": "u_1",
    "bot_name": null,
    "text": "Release *2.4* is live :tada:",
    "files": [],
    "reactions": [],
    "reply_count": 0,
    "edited_at": null,
    "pinned": false,
    "created_at": "2026-10-25T12:06:00.000Z"
  }
}

Webhook de entrada

POST/api/talk/hooks/:token

Sem API key: crie a URL em um canal (Detalhes, Integrações) e envie um POST com um JSON com text. Publica como bot com o nome do webhook. 60 pedidos por minuto por webhook.

NomeTipoObrigatórioDescrição
textstringSimTexto da mensagem, com a mesma formatação do app (*negrito*, _itálico_, `código`, links, :emoji:)
usernamestringNãoNome do bot na mensagem (por padrão, o do webhook)
thread_idstringNãoId da mensagem raiz para responder no fio
curl -X POST "https://zerosoft.ai/api/talk/hooks/:token" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "text": "Build *green* on main",
  "username": "CI"
}'

Requisição

{
  "text": "Build *green* on main",
  "username": "CI"
}

Resposta · 200

{
  "ok": true,
  "id": "tm_3"
}

Board

Quadros: listar e buscar (também pelo texto de dentro), ler um resumo, criar a partir de um modelo, adicionar post-its, formas e setas, renomear, mover para uma pasta ou mandar para a lixeira. A key age como a pessoa que a criou: vê e edita os quadros que essa pessoa pode abrir. Quem está com o quadro aberto vê as mudanças ao vivo. Scopes boards:read e boards:write.

Listar quadros

GET/api/v1/boards

Quadros que a pessoa da key pode abrir, o editado mais recente primeiro. Com q busca também em post-its, rótulos e nomes de frames, e devolve a linha que coincidiu em match.

Escopo boards:read

NomeTipoObrigatórioDescrição
qstringNãoBusca no nome e no texto de dentro.
folderstringNãoId da pasta.
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/v1/boards" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "b_1",
      "name": "Q4 retro",
      "folderId": null,
      "access": "workspace",
      "version": 12,
      "updatedAt": "2026-10-28T12:00:00.000Z",
      "createdAt": "2026-10-20T09:00:00.000Z",
      "updatedBy": "Ana"
    }
  ]
}

Criar um quadro

POST/api/v1/boards

Vazio ou a partir de um modelo: retro, brainstorm, userFlow, kanban, roadmap, swot, mindMap, priorityMatrix, journey ou leanCanvas.

Escopo boards:write

NomeTipoObrigatórioDescrição
namestringNãoNome do quadro.
templatestringNãoChave do modelo.
folderIdstringNãoId da pasta.
curl -X POST "https://zerosoft.ai/api/v1/boards" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q4 retro",
  "template": "retro",
  "locale": "en"
}'

Requisição

{
  "name": "Q4 retro",
  "template": "retro",
  "locale": "en"
}

Resposta · 201

{
  "data": {
    "id": "b_1",
    "name": "Q4 retro",
    "folderId": null,
    "access": "workspace",
    "version": 12,
    "updatedAt": "2026-10-28T12:00:00.000Z",
    "createdAt": "2026-10-20T09:00:00.000Z",
    "updatedBy": "Ana"
  }
}

Ler um quadro

GET/api/v1/boards/:id

O quadro com um resumo: frames em ordem de leitura, post-its com texto e etiquetas, textos soltos. Com scene=1, também a cena do Excalidraw.

Escopo boards:read

NomeTipoObrigatórioDescrição
scenestringNão1 para incluir a cena do Excalidraw.
curl -X GET "https://zerosoft.ai/api/v1/boards/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": {
    "id": "b_1",
    "name": "Q4 retro",
    "folderId": null,
    "access": "workspace",
    "version": 12,
    "updatedAt": "2026-10-28T12:00:00.000Z",
    "createdAt": "2026-10-20T09:00:00.000Z",
    "updatedBy": "Ana",
    "myAccess": "edit",
    "outline": {
      "frames": [
        {
          "id": "f_1",
          "name": "Agenda"
        }
      ],
      "stickies": [
        {
          "id": "s_1",
          "text": "Ship the beta",
          "tags": [
            "launch"
          ],
          "frameId": null
        }
      ],
      "texts": [],
      "elementCount": 14
    }
  }
}

Alterar um quadro

PATCH/api/v1/boards/:id

Renomeia ou move para uma pasta (folderId null tira da pasta).

Escopo boards:write

NomeTipoObrigatórioDescrição
namestringNãoNome do quadro.
folderIdstringNãoId da pasta.
curl -X PATCH "https://zerosoft.ai/api/v1/boards/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q4 retro (final)"
}'

Requisição

{
  "name": "Q4 retro (final)"
}

Resposta · 200

{
  "data": {
    "id": "b_1",
    "name": "Q4 retro (final)",
    "folderId": null,
    "access": "workspace",
    "version": 12,
    "updatedAt": "2026-10-28T12:00:00.000Z",
    "createdAt": "2026-10-20T09:00:00.000Z",
    "updatedBy": "Ana"
  }
}

Apagar um quadro

DELETE/api/v1/boards/:id

Manda para a lixeira. Pode ser restaurado pelo app por 30 dias.

Escopo boards:write

curl -X DELETE "https://zerosoft.ai/api/v1/boards/:id" \
  -H "Authorization: Bearer zs_live_9f3k..."

Adicionar post-its e formas

POST/api/v1/boards/:id/elements

Adiciona post-its, textos e formas, e setas entre eles por índice. Sem x e y ficam ao lado do conteúdo. Não muda nada do que já existe.

Escopo boards:write

NomeTipoObrigatórioDescrição
stickiesarrayNãoPost-its: { text, color?, tags? }. Cores: yellow, green, blue, pink, violet, orange.
elementsarrayNãoFormas e textos: { kind, text?, x?, y?, width?, height?, fill? } com kind sticky, text, rectangle, ellipse ou diamond.
connectarrayNãoSetas entre elementos por índice: { from, to }.
curl -X POST "https://zerosoft.ai/api/v1/boards/:id/elements" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "elements": [
    {
      "kind": "ellipse",
      "text": "Start"
    },
    {
      "kind": "rectangle",
      "text": "Sign up"
    }
  ],
  "connect": [
    {
      "from": 0,
      "to": 1
    }
  ]
}'

Requisição

{
  "elements": [
    {
      "kind": "ellipse",
      "text": "Start"
    },
    {
      "kind": "rectangle",
      "text": "Sign up"
    }
  ],
  "connect": [
    {
      "from": 0,
      "to": 1
    }
  ]
}

Resposta · 201

{
  "data": {
    "version": 13,
    "added": [
      {
        "id": "e_1",
        "type": "ellipse"
      },
      {
        "id": "e_2",
        "type": "rectangle"
      },
      {
        "id": "e_3",
        "type": "arrow"
      }
    ]
  }
}

Servidor MCP

POST/api/v1/boards/mcp

Model Context Protocol (streamable HTTP, respostas JSON) para agentes de IA. Ferramentas: list_boards, get_board, create_board, add_stickies, add_diagram, update_board e trash_board.

Escopo boards:read

curl -X POST "https://zerosoft.ai/api/v1/boards/mcp" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_stickies",
    "arguments": {
      "board_id": "b_1",
      "stickies": [
        {
          "text": "Ship the beta",
          "color": "green"
        }
      ]
    }
  }
}'

Requisição

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_stickies",
    "arguments": {
      "board_id": "b_1",
      "stickies": [
        {
          "text": "Ship the beta",
          "color": "green"
        }
      ]
    }
  }
}

Resposta · 200

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"version\":13,\"added\":[...]}"
      }
    ],
    "isError": false
  }
}

Design

Leia os designs que a pessoa da chave vê: nomes, tamanhos, páginas e, com id, o JSON completo das páginas.

Listar ou ler designs

GET/api/v1/design

Sem id, os designs que a pessoa vê (os mais recentes primeiro). Com id, esse design com suas páginas em JSON.

Escopo design:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
viewstringNãorecent (padrão), mine, shared, starred ou templates
idstringNãoId de um design: devolve esse design com suas páginas
curl -X GET "https://zerosoft.ai/api/v1/design" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "d_1",
      "name": "Summer sale",
      "width": 1080,
      "height": 1080,
      "pages": 1,
      "owner": "Ana",
      "access": "owner",
      "starred": false,
      "template": false,
      "updated_at": "2026-10-29T12:00:00.000Z",
      "url": "https://zerosoft.ai/en/app/design/d_1"
    }
  ]
}

Shop

O catálogo e os pedidos da sua loja. Scopes shop:read e shop:write. Os dados de clientes só ficam disponíveis para keys de pessoas com o app Shop.

Listar produtos

GET/api/v1/shop/products

Produtos com status, faixa de preço, número de variantes e estoque. Um POST no mesmo path cria um produto com o mesmo corpo que o app usa.

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/v1/shop/products" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "prod_1",
      "handle": "blue-mug",
      "title": "Blue mug",
      "status": "active",
      "variants": 2,
      "stock": 14,
      "tracked": true,
      "minPriceCents": 1900,
      "maxPriceCents": 2100
    }
  ],
  "total": 1
}

Listar pedidos

GET/api/v1/shop/orders

Pedidos do mais novo ao mais antigo, com status (pending, paid, fulfilled, cancelled, refunded) e total em centavos.

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/v1/shop/orders" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "ord_1",
      "number": 1001,
      "status": "paid",
      "email": "ana@example.com",
      "name": "Ana Pérez",
      "totalCents": 4100,
      "currency": "USD",
      "paymentMethod": "stripe",
      "items": 2,
      "createdAt": "2026-10-29 15:00:00"
    }
  ],
  "total": 1
}

Pulse

Analytics de produto. Os endpoints de ingestão (/api/ingest/*) usam a key do projeto, não uma API key: a pública (zsp_…) no corpo vinda do navegador, ou a key secreta do projeto como Bearer zss_… vinda de um servidor. As consultas aceitam uma sessão iniciada ou uma API key com analytics:read.

Capturar eventos

POST/api/ingest/e

Um evento ou um lote de até 200, 512 KB por pedido. Com a key secreta como Bearer não há checagem de origem. Eventos com uuid repetido são ignorados. Tem limite por projeto.

NomeTipoObrigatórioDescrição
api_keystringNãoKey pública do projeto (zsp_…). Também aceita como token.
batcharraySimEventos: event, distinct_id, properties, timestamp e um uuid opcional. Um evento só pode ir no primeiro nível.
sent_atstringNãoQuando o cliente enviou o lote; serve para corrigir o relógio dele.
curl -X POST "https://zerosoft.ai/api/ingest/e" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "zsp_…",
  "batch": [
    {
      "event": "signed_up",
      "distinct_id": "user_42",
      "properties": {
        "plan": "team"
      },
      "timestamp": "2026-10-29T12:00:00.000Z"
    }
  ]
}'

Requisição

{
  "api_key": "zsp_…",
  "batch": [
    {
      "event": "signed_up",
      "distinct_id": "user_42",
      "properties": {
        "plan": "team"
      },
      "timestamp": "2026-10-29T12:00:00.000Z"
    }
  ]
}

Resposta · 200

{
  "status": 1,
  "stored": 1,
  "dropped": 0
}

Feature flags de uma pessoa

POST/api/ingest/decide

Valores das flags ativas para um distinct_id (true, false ou a chave da variante) e os ajustes do snippet. person_properties se soma ao que a pessoa já tem.

NomeTipoObrigatórioDescrição
api_keystringSimKey pública do projeto (zsp_…). Também aceita como token.
distinct_idstringSimO id da pessoa no seu produto.
person_propertiesobjectNãoPropriedades extras da pessoa para esta avaliação.
curl -X POST "https://zerosoft.ai/api/ingest/decide" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "zsp_…",
  "distinct_id": "user_42"
}'

Requisição

{
  "api_key": "zsp_…",
  "distinct_id": "user_42"
}

Resposta · 200

{
  "featureFlags": {
    "new-checkout": true,
    "pricing-test": "variant-b"
  },
  "config": {
    "autocapture": true,
    "respectDnt": true
  }
}

Apagar uma pessoa

POST/api/ingest/delete

Apaga a pessoa de um distinct_id com todos os seus eventos e sessões. Pede a key secreta do projeto como Bearer zss_….

NomeTipoObrigatórioDescrição
distinct_idstringSimO id da pessoa no seu produto.
curl -X POST "https://zerosoft.ai/api/ingest/delete" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "distinct_id": "user_42"
}'

Requisição

{
  "distinct_id": "user_42"
}

Resposta · 200

{
  "deleted": true,
  "events": 128
}

Rodar uma consulta

POST/api/analytics/query

kind é trends, funnel, retention, paths, sql ou web. O SQL é somente leitura sobre as tabelas do projeto events, persons, person_distinct_ids e sessions, até 1.000 linhas.

Escopo analytics:read

NomeTipoObrigatórioDescrição
projectIdstringSimId do projeto (ap_…).
queryobjectSimA definição da consulta, a mesma que o app salva num insight.
curl -X POST "https://zerosoft.ai/api/analytics/query" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "ap_…",
  "query": {
    "kind": "trends",
    "series": [
      {
        "event": "$pageview",
        "math": "unique"
      }
    ],
    "interval": "day",
    "dateRange": {
      "from": "-7d"
    }
  }
}'

Requisição

{
  "projectId": "ap_…",
  "query": {
    "kind": "trends",
    "series": [
      {
        "event": "$pageview",
        "math": "unique"
      }
    ],
    "interval": "day",
    "dateRange": {
      "from": "-7d"
    }
  }
}

Resposta · 200

{
  "result": {
    "kind": "trends",
    "buckets": [
      "2026-10-23",
      "2026-10-24"
    ],
    "series": [
      {
        "label": "$pageview (unique users)",
        "breakdownValue": null,
        "data": [
          120,
          134
        ],
        "total": 231
      }
    ],
    "usedRollup": true
  }
}

Listar eventos

GET/api/analytics/events

Últimos eventos de um projeto, os mais novos primeiro. Passe after com o último id que você viu para trazer só os novos.

Escopo analytics:read

NomeTipoObrigatórioDescrição
projectstringSimId do projeto (ap_…).
eventstringNãoSó este nome de evento.
afternumberNãoSó eventos com id maior.
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/analytics/events" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "events": [
    {
      "id": 981,
      "event": "$pageview",
      "distinctId": "user_42",
      "ts": 1761739200000,
      "url": "https://example.com/pricing",
      "pathname": "/pricing",
      "browser": "Chrome",
      "os": "macOS",
      "device": "desktop",
      "country": "AR",
      "properties": {}
    }
  ]
}

Listar pessoas

GET/api/analytics/persons

Pessoas de um projeto com suas propriedades e distinct ids, as vistas mais recentemente primeiro.

Escopo analytics:read

NomeTipoObrigatórioDescrição
projectstringSimId do projeto (ap_…).
qstringNãoQuery de busca.
cohortstringNãoSó pessoas deste id de coorte.
curl -X GET "https://zerosoft.ai/api/analytics/persons" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "persons": [
    {
      "id": "p_3f…",
      "distinctIds": [
        "user_42"
      ],
      "properties": {
        "email": "ana@example.com"
      },
      "isIdentified": true,
      "createdAt": 1761000000000,
      "lastSeen": 1761739200000
    }
  ],
  "hasMore": false
}

Social

Publicações em redes sociais. A chave age como a pessoa que a criou: vê e publica nas contas dessa pessoa, e quem precisa de aprovação envia as publicações para aprovação. Scopes social:read e social:write.

Listar publicações

GET/api/v1/social/posts

As publicações que a chave vê, da mais nova para a mais antiga, com o status de cada conta e o link para o que foi publicado.

NomeTipoObrigatórioDescrição
statusstringNãodraft, pending_approval, scheduled, published, partial ou failed.
fromstringNãoA partir desta data (ISO 8601).
tostringNãoAté esta data (ISO 8601).
curl -X GET "https://zerosoft.ai/api/v1/social/posts" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "sp_1",
      "text": "Launch day #launch",
      "status": "published",
      "scheduled_at": "2026-11-03T13:00:00.000Z",
      "published_at": "2026-11-03T13:00:12.000Z",
      "targets": [
        {
          "account_id": "sa_1",
          "network": "linkedin",
          "status": "published",
          "url": "https://www.linkedin.com/feed/update/urn:li:share:1",
          "error": null
        }
      ],
      "created_at": "2026-11-01T10:00:00.000Z"
    }
  ]
}

Criar uma publicação

POST/api/v1/social/posts

Salva um rascunho, agenda, adiciona à fila ou publica na hora. Cada rede checa tamanho e arquivos antes; os erros voltam por conta.

NomeTipoObrigatórioDescrição
textstringSimTexto da publicação.
accountIdsstring[]SimIds das contas conectadas onde publicar.
overridesobjectNãoTexto próprio por conta: { accountId: texto }.
actionstringNãodraft, schedule, queue ou now. Padrão draft.
scheduledAtstringNãoData e hora de publicação (ISO 8601), com action schedule.
curl -X POST "https://zerosoft.ai/api/v1/social/posts" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "text": "Launch day #launch",
  "accountIds": [
    "sa_1"
  ],
  "action": "schedule",
  "scheduledAt": "2026-11-03T13:00:00.000Z"
}'

Requisição

{
  "text": "Launch day #launch",
  "accountIds": [
    "sa_1"
  ],
  "action": "schedule",
  "scheduledAt": "2026-11-03T13:00:00.000Z"
}

Resposta · 201

{
  "data": {
    "id": "sp_2",
    "text": "Launch day #launch",
    "status": "scheduled",
    "scheduled_at": "2026-11-03T13:00:00.000Z",
    "published_at": null,
    "targets": [
      {
        "account_id": "sa_1",
        "network": "linkedin",
        "status": "pending",
        "url": null,
        "error": null
      }
    ],
    "created_at": "2026-11-01T10:00:00.000Z"
  }
}

Books

Faturas do Books. A key age como a pessoa que a criou, com o papel dela no Books. Valores são inteiros na unidade mínima da moeda (centavos). Scopes books:read e books:write.

Listar faturas

GET/api/v1/books/invoices

Faturas, das mais novas para as mais antigas, com status, número, cliente, total e saldo.

NomeTipoObrigatórioDescrição
statusstringNãodraft, sent, partial, paid, overdue, void ou open (tudo que tem saldo).
qstringNãoQuery de busca.
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/v1/books/invoices" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "inv_1",
      "docType": "invoice",
      "status": "sent",
      "numberLabel": "B 00001-00000012",
      "reference": "PO 778",
      "contactId": "con_1",
      "contactName": "Acme SA",
      "issueDate": "2026-11-01",
      "dueDate": "2026-12-01",
      "currency": "ARS",
      "total": 12100000,
      "amountDue": 12100000,
      "sentAt": "2026-11-01 12:00:00",
      "updatedAt": "2026-11-01 12:00:00"
    }
  ],
  "total": 1
}

Criar uma fatura em rascunho

POST/api/v1/books/invoices

Salva um rascunho com o mesmo corpo que o app usa. Alguém aprova no app, que atribui o número e gera o lançamento.

NomeTipoObrigatórioDescrição
contactIdstringNãoId do contato do Books (o cliente).
linesobject[]SimLinhas: description, quantity, unitPrice (unidades mínimas inteiras, ou um texto decimal com ponto como separador decimal, por exemplo "1500.50", seja qual for a moeda), discountBps, taxRateId, itemId.
currencystringNãoCódigo de moeda ISO; a moeda base se omitido.
fxRatestringNãoCâmbio manual (moeda base por 1 unidade) quando a moeda não é a base.
referencestringNãoSua referência (pedido de compra, projeto).
curl -X POST "https://zerosoft.ai/api/v1/books/invoices" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "con_1",
  "reference": "PO 778",
  "lines": [
    {
      "description": "Consulting",
      "quantity": 10,
      "unitPrice": "1000.00",
      "taxRateId": "tax_iva21"
    }
  ]
}'

Requisição

{
  "contactId": "con_1",
  "reference": "PO 778",
  "lines": [
    {
      "description": "Consulting",
      "quantity": 10,
      "unitPrice": "1000.00",
      "taxRateId": "tax_iva21"
    }
  ]
}

Resposta · 201

{
  "data": {
    "id": "inv_2",
    "docType": "invoice",
    "status": "draft",
    "numberLabel": "",
    "total": 1210000,
    "currency": "ARS",
    "lines": [
      {
        "description": "Consulting",
        "quantity": 10,
        "unitPrice": 100000,
        "taxBps": 2100,
        "net": 1000000,
        "tax": 210000,
        "total": 1210000
      }
    ]
  }
}

Forms

Formulários e suas respostas. A key age como a pessoa que a criou e só vê os formulários que ela pode abrir. Scope forms:read.

Listar formulários

GET/api/v1/forms/forms

Formulários do mais novo ao mais antigo, com status, quantidade de respostas e parciais, última resposta e quem pode abri-los.

Escopo forms:read

NomeTipoObrigatórioDescrição
qstringNãoQuery de busca.
statusstringNãoFiltre os formulários por status, por exemplo published.
curl -X GET "https://zerosoft.ai/api/v1/forms/forms" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "fm_1",
      "name": "NPS survey",
      "slug": "nps-survey-a1b2c3",
      "status": "published",
      "responseCount": 42,
      "partialCount": 3,
      "lastResponseAt": "2026-11-03T13:00:00.000Z",
      "updatedAt": "2026-11-03T13:00:00.000Z",
      "sharing": "workspace",
      "open": true
    }
  ]
}

Listar respostas

GET/api/v1/forms/responses

Respostas de um formulário, da mais nova à mais antiga. As respostas são indexadas pelo id da pergunta. As de arquivo devolvem uma referência, não o arquivo.

Escopo forms:read

NomeTipoObrigatórioDescrição
formstringSimId do formulário.
statusstringNãocompleted (padrão) ou partial.
fromstringNãoSó respostas enviadas a partir desta data (YYYY-MM-DD).
tostringNãoSó respostas enviadas até esta data (YYYY-MM-DD).
pageintegerNãoNúmero da página.
limitnumberNãoQuantidade máxima de resultados.
curl -X GET "https://zerosoft.ai/api/v1/forms/responses" \
  -H "Authorization: Bearer zs_live_9f3k..."

Resposta · 200

{
  "data": [
    {
      "id": "rs_1",
      "status": "completed",
      "answers": {
        "q_1": 9,
        "q_2": "Fast and clear"
      },
      "hidden": {
        "source": "newsletter"
      },
      "vars": {
        "score": 0
      },
      "endingId": "end_1",
      "lang": "en",
      "contactId": "con_1",
      "consent": true,
      "createdAt": "2026-11-03T12:58:00.000Z",
      "submittedAt": "2026-11-03T13:00:00.000Z"
    }
  ],
  "total": 42
}

Webhooks

Adicione endpoints em Dashboard → Configurações → Webhooks. Eventos: booking.created, booking.rescheduled, booking.cancelled, booking.no_show, booking.requested, link.created, link.clicked, link.updated, link.deleted, contact.created, contact.updated, deal.created, deal.updated, deal.stage_changed, deal.won, deal.lost, robot.run.finished, robot.run.failed, robot.output.changed, chat.message.created, chat.conversation.created, chat.conversation.assigned, chat.conversation.tagged, chat.conversation.resolved, chat.csat.submitted. Os eventos de links podem ser limitados a alguns links, tags ou domínios. link.updated traz o link e a lista de campos alterados; link.deleted, o link como estava. Cada request traz Zerosoft-Signature: t=TIMESTAMP,v1=HEX, onde v1 = HMAC-SHA256(secret, "TIMESTAMP.BODY_CRU"). Rejeite timestamps antigos. Entregas com falha são reenviadas com backoff por ~15 horas.

Payload do evento

POSThttps://your-app.example/webhooks/zerosoft

O que seu endpoint recebe. Responda 2xx em até 8 segundos.

curl -X POST "https://your-app.example/webhooks/zerosoft" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_1",
  "type": "booking.created",
  "createdAt": "2026-11-01T18:00:00.000Z",
  "data": {
    "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
    "status": "confirmed",
    "startsAt": "2026-11-03T13:00:00.000Z",
    "endsAt": "2026-11-03T13:30:00.000Z",
    "timezone": "America/Argentina/Buenos_Aires",
    "invitee": {
      "name": "Ana",
      "email": "ana@example.com"
    },
    "answers": {},
    "hostUserId": "u_123",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "rescheduledFrom": null,
    "cancelReason": null,
    "eventType": {
      "id": "et_42",
      "slug": "intro",
      "title": "Intro call"
    }
  }
}'

Requisição

{
  "id": "evt_1",
  "type": "booking.created",
  "createdAt": "2026-11-01T18:00:00.000Z",
  "data": {
    "id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
    "status": "confirmed",
    "startsAt": "2026-11-03T13:00:00.000Z",
    "endsAt": "2026-11-03T13:30:00.000Z",
    "timezone": "America/Argentina/Buenos_Aires",
    "invitee": {
      "name": "Ana",
      "email": "ana@example.com"
    },
    "answers": {},
    "hostUserId": "u_123",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "rescheduledFrom": null,
    "cancelReason": null,
    "eventType": {
      "id": "et_42",
      "slug": "intro",
      "title": "Intro call"
    }
  }
}

Payload dos eventos do Chat

POSThttps://your-app.example/webhooks/zerosoft

Os eventos do Chat trazem a conversa. chat.message.created soma a mensagem (do visitante, da equipe ou do bot; as notas internas não são enviadas) e chat.conversation.assigned soma previousAssignedTo.

curl -X POST "https://your-app.example/webhooks/zerosoft" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_2",
  "type": "chat.message.created",
  "createdAt": "2026-11-01T18:02:00.000Z",
  "data": {
    "conversation": {
      "id": "{conversation_id}",
      "widgetId": "{widget_id}",
      "status": "open",
      "priority": "medium",
      "subject": null,
      "assignedTo": "{user_id}",
      "visitor": {
        "id": "{visitor_id}",
        "name": "Ana",
        "email": "ana@example.com"
      },
      "firstResponseAt": "2026-11-01T18:02:00.000Z",
      "resolvedAt": null,
      "createdAt": "2026-11-01T18:00:00.000Z",
      "updatedAt": "2026-11-01T18:02:00.000Z"
    },
    "message": {
      "id": "{message_id}",
      "conversationId": "{conversation_id}",
      "senderType": "user",
      "userId": "{user_id}",
      "body": "Hi Ana, the order ships tomorrow.",
      "isNote": false,
      "attachments": [],
      "createdAt": "2026-11-01T18:02:00.000Z"
    }
  }
}'

Requisição

{
  "id": "evt_2",
  "type": "chat.message.created",
  "createdAt": "2026-11-01T18:02:00.000Z",
  "data": {
    "conversation": {
      "id": "{conversation_id}",
      "widgetId": "{widget_id}",
      "status": "open",
      "priority": "medium",
      "subject": null,
      "assignedTo": "{user_id}",
      "visitor": {
        "id": "{visitor_id}",
        "name": "Ana",
        "email": "ana@example.com"
      },
      "firstResponseAt": "2026-11-01T18:02:00.000Z",
      "resolvedAt": null,
      "createdAt": "2026-11-01T18:00:00.000Z",
      "updatedAt": "2026-11-01T18:02:00.000Z"
    },
    "message": {
      "id": "{message_id}",
      "conversationId": "{conversation_id}",
      "senderType": "user",
      "userId": "{user_id}",
      "body": "Hi Ana, the order ships tomorrow.",
      "isNote": false,
      "attachments": [],
      "createdAt": "2026-11-01T18:02:00.000Z"
    }
  }
}

Payload de eventos do Track

POSThttps://your-app.example/webhooks/zerosoft

Os eventos issue.* trazem o issue e a equipe (project no payload); issue.status_changed inclui from e to, comment.created o comentário e project.* a equipe.

curl -X POST "https://your-app.example/webhooks/zerosoft" \
  -H "Authorization: Bearer zs_live_9f3k..."
  -H "Content-Type: application/json" \
  -d '{
  "id": "evt_3",
  "type": "issue.status_changed",
  "createdAt": "2026-10-25T15:10:00.000Z",
  "data": {
    "issue": {
      "id": "{issue_id}",
      "identifier": "WEB-12",
      "title": "Checkout button does nothing on Safari",
      "priority": "high",
      "status": "Done",
      "assigneeId": "{user_id}"
    },
    "project": {
      "id": "{project_id}",
      "name": "Web"
    },
    "changes": [
      "statusId"
    ],
    "from": "In Progress",
    "to": "Done"
  }
}'

Requisição

{
  "id": "evt_3",
  "type": "issue.status_changed",
  "createdAt": "2026-10-25T15:10:00.000Z",
  "data": {
    "issue": {
      "id": "{issue_id}",
      "identifier": "WEB-12",
      "title": "Checkout button does nothing on Safari",
      "priority": "high",
      "status": "Done",
      "assigneeId": "{user_id}"
    },
    "project": {
      "id": "{project_id}",
      "name": "Web"
    },
    "changes": [
      "statusId"
    ],
    "from": "In Progress",
    "to": "Done"
  }
}