API do Zenit CRM

Para ligar um sistema de fora ao CRM — o checkout que cria o negócio na venda, a landing page que manda o lead, o painel que lê os números. Versão v1, endereço base:

https://crm.digitalzenit.com.br/api/v1

Autenticação

Gere a chave em Configurações → Chaves de API (só Dono e Admin). Ela começa com zk_ e aparece uma vez só: o CRM guarda apenas uma impressão (hash) dela. Mande em todo pedido:

curl https://crm.digitalzenit.com.br/api/v1/funis \
  -H "Authorization: Bearer zk_SuaChaveAqui..."

Limite de pedidos

60 pedidos por minuto por chave (minuto de relógio). Toda resposta traz:

Passou: 429 com Retry-After (segundos). Espere e repita o mesmo pedido.

Erros

Todo erro vem no mesmo formato; campo aparece quando o problema é num campo do corpo ou da URL:

{
  "erro": {
    "codigo": "validacao",
    "campo": "whatsapp",
    "mensagem": "WhatsApp inválido. Use DDD + número (ex.: 37999999999)."
  }
}
StatuscodigoQuando
400corpo_invalido · parametro_invalidocorpo que não é um objeto JSON; parâmetro da URL errado (limite, cursor, data)
401nao_autenticadosem chave, chave errada, revogada, vencida ou de quem não é mais Dono/Admin
403sem_permissaochave “Só leitura” num POST ou PATCH
404nao_encontradoo id não existe, é de outro workspace ou está na lixeira
409conflitoWhatsApp que já é de outro contato; mover negócio fechado sem reabrir; o mesmo externo_id sendo gravado agora por outro pedido
413corpo_grandecorpo acima de 64 KB
415tipo_de_conteudoPOST/PATCH sem Content-Type: application/json
422validacaocampo inválido ou desconhecido, id de funil/etapa/produto/responsável que não existe
429limite_excedidomais de 60 pedidos no minuto
500erro_internofalha do nosso lado: pode repetir

Campo que a API não conhece é erro (422), não silêncio: um erro de digitação aparece no primeiro teste.

Paginação

As listas vêm do mais novo para o mais antigo, 50 por página (?limite= de 1 a 100). A resposta é { "dados": [...], "proximo_cursor": "..." }; para a próxima página, repita o pedido com ?cursor=. Acabou quando proximo_cursor vem null. O cursor é opaco: use exatamente como veio.

# primeira página
curl "https://crm.digitalzenit.com.br/api/v1/contatos?limite=100" -H "Authorization: Bearer $CHAVE"
# { "dados": [ ... ], "proximo_cursor": "WyIyMDI2LTEwLTI3VDE0OjMw..." }

# próxima: o mesmo pedido com o cursor que veio — até "proximo_cursor": null
curl "https://crm.digitalzenit.com.br/api/v1/contatos?limite=100&cursor=WyIyMDI2LTEwLTI3VDE0OjMw..." -H "Authorization: Bearer $CHAVE"

Para sincronizar só o que mudou, use ?atualizado_desde=2026-10-27T00:00:00Z nas listas.

Contatos

O contato como a API devolve:

{
  "id": "6f1c…",
  "nome": "Ana Ribeiro",
  "whatsapp": "5537999999999",
  "email": "ana@exemplo.com.br",
  "email_consentimento_em": "2026-10-20T09:15:00.000Z",
  "email_suprimido": false,
  "instagram": "anaribeiro",
  "origem": "site",
  "responsavel_id": null,
  "tags": [{ "id": "a3e1…", "nome": "cliente" }],
  "ultima_interacao_em": "2026-10-27T13:02:11.000Z",
  "criado_em": "2026-10-20T09:15:00.000Z",
  "atualizado_em": "2026-10-27T14:30:00.000Z"
}

GET/api/v1/contatos

Lista. Filtros: busca (nome ou e-mail), whatsapp (exato; acha com e sem o nono dígito), email (exato), atualizado_desde, mais limite e cursor. Para saber “esse lead já existe?”: ?whatsapp=37999999999.

GET/api/v1/contatos/{id}

Um contato: { "dados": { ... } }.

POST/api/v1/contatos

Cria ou acha o contato — pode mandar o mesmo lead quantas vezes quiser, que não duplica. Campos: nome, whatsapp (com DDD, em qualquer formato), email, instagram, origem (padrão api), responsavel_id, tags (nomes; até 20; a que não existe é criada) e email_consentimento. Pelo menos nome, WhatsApp ou e-mail.

curl -X POST https://crm.digitalzenit.com.br/api/v1/contatos \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Ana Ribeiro",
    "whatsapp": "(37) 99999-9999",
    "email": "ana@exemplo.com.br",
    "origem": "site",
    "tags": ["cliente", "orcamento"],
    "email_consentimento": true
  }'

# 201 { "dados": { ...contato... }, "criado": true }    — contato novo
# 200 { "dados": { ...contato... }, "criado": false }   — já existia (achado pelo WhatsApp ou pelo e-mail)
  • email_consentimento: true declara que a pessoa pediu para receber e-mails da empresa (no checkout, no formulário): o contato fica com o consentimento registrado, com a origem “API, pela chave …”, e passa a entrar nas campanhas de e-mail. Vale só para o email do mesmo pedido (sem ele, 422) e nunca troca um consentimento que já existe; ausente ou false não muda nada (retirar é pela tela). Também vale no contato do POST de negócios e no PATCH.
  • O contato existente é achado pelo WhatsApp (com e sem o nono dígito) e, sem achar, pelo e-mail — o e-mail só casa com contato sem WhatsApp, ou quando o pedido não traz WhatsApp.
  • Achado, o POST só completa o que está vazio e põe as tags: nunca troca o nome, o e-mail ou o responsável que a equipe já tem. Para sobrescrever, use o PATCH.

PATCH/api/v1/contatos/{id}

Sobrescreve só os campos mandados; null apaga (o nome vira vazio). tags no PATCH só acrescenta — tirar tag é pela tela. WhatsApp que já é de outro contato: 409.

curl -X PATCH https://crm.digitalzenit.com.br/api/v1/contatos/6f1c… \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "email": "novo@exemplo.com.br", "instagram": null, "tags": ["vip"] }'

Negócios

O negócio como a API devolve (com os produtos):

{
  "id": "9b2d…",
  "codigo": 1287,
  "titulo": "Pacote Completo",
  "valor_centavos": 240000,
  "valor_manual": false,
  "status": "em_andamento",
  "funil_id": "c40a…",
  "etapa_id": "e7f2…",
  "etapa": "Novo lead",
  "contato_id": "6f1c…",
  "responsavel_id": null,
  "motivo_perda": null,
  "justificativa_perda": null,
  "externo_id": "PED-4815162342",
  "produtos": [{
    "produto_id": "p91a…", "nome": "Pacote Completo", "sku": "PCT-01",
    "quantidade": 1, "preco_unitario_centavos": 240000, "desconto_centavos": 0, "total_centavos": 240000
  }],
  "criado_em": "2026-10-27T14:30:00.000Z",
  "atualizado_em": "2026-10-27T14:30:00.000Z",
  "etapa_alterada_em": "2026-10-27T14:30:00.000Z",
  "fechado_em": null
}

GET/api/v1/negocios

Lista. Filtros: funil_id, etapa_id, contato_id, status (em_andamento, ganho, perdido), externo_id, atualizado_desde, mais limite e cursor.

GET/api/v1/negocios/{id}

Um negócio: { "dados": { ... } }.

POST/api/v1/negocios

Cria o negócio no fim da etapa (sem etapa_id, na primeira do funil). Campos: funil_id (obrigatório), etapa_id, contato_id ou contato (objeto com os campos do contato — vira o mesmo “cria ou acha” do POST de contatos), titulo, valor_centavos, responsavel_id, externo_id e produtos (até 20: produto_id, quantidade, preco_unitario_centavos e desconto_centavos, os dois últimos opcionais).

curl -X POST https://crm.digitalzenit.com.br/api/v1/negocios \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "funil_id": "c40a…",
    "etapa_id": "e7f2…",
    "externo_id": "PED-4815162342",
    "titulo": "Pacote Completo",
    "contato": { "nome": "Ana Ribeiro", "whatsapp": "37999999999", "email": "ana@exemplo.com.br" },
    "produtos": [{ "produto_id": "p91a…", "quantidade": 1 }]
  }'

# 201 { "dados": { ...negócio... }, "criado": true }
# mandou o mesmo externo_id de novo? 200 { "dados": { ...o mesmo negócio... }, "criado": false }
  • externo_id é o id do pedido no seu sistema: com ele, repetir o POST não duplica — volta o negócio que já existe (200, “criado”: false), sem mexer nele. Use sempre que o seu sistema reenvia avisos (checkouts reenviam). Dois pedidos iguais ao mesmo tempo também não duplicam: o segundo espera o primeiro (até uns 3 segundos) e devolve o negócio dele; se o primeiro demorar mais, o segundo recebe 409 — tente de novo.
  • Sem valor_centavos, o valor é a soma dos produtos (e acompanha se a equipe mexer nos produtos). Com valor_centavos e produtos, o valor fica o mandado (“definido à mão”).
  • Os ids de funil e etapa saem de GET /api/v1/funis; os de produto, de Configurações → Produtos.

PATCH/api/v1/negocios/{id}

Campos: titulo, valor_centavos, responsavel_id (null tira), etapa_id (mover, dentro do mesmo funil), status (ganho, perdido ou em_andamento para reabrir) e, só com “status”: “perdido”, motivo_perda e justificativa.

# mover de etapa (do mesmo funil)
curl -X PATCH https://crm.digitalzenit.com.br/api/v1/negocios/9b2d… -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{ "etapa_id": "a11b…" }'

# ganhar
curl -X PATCH https://crm.digitalzenit.com.br/api/v1/negocios/9b2d… -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{ "status": "ganho" }'

# perder (o motivo é o NOME cadastrado em Configurações → Motivos de perda)
curl -X PATCH https://crm.digitalzenit.com.br/api/v1/negocios/9b2d… -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{ "status": "perdido", "motivo_perda": "Preço", "justificativa": "Fechou com um concorrente mais barato" }'
  • Mandar o status que o negócio já tem não faz nada (o PATCH pode ser repetido). De ganho direto para perdido (o estorno) também vale: o CRM reabre e fecha de novo.
  • Negócio fechado só muda de etapa junto com “status”: “em_andamento” (senão 409).
  • As regras de etapa da tela (“campos obrigatórios para entrar na etapa”, atividade obrigatória) não barram a API: o pedido do checkout nunca se perde por um campo vazio.
  • Mover, ganhar e perder disparam os webhooks de saída e os fluxos do CRM, como na tela.

Funis

GET/api/v1/funis

Os funis ativos, cada um com as etapas na ordem do kanban — é daqui que saem os ids para criar e mover negócios.

{
  "dados": [{
    "id": "c40a…",
    "nome": "Vendas",
    "descricao": null,
    "etapas": [
      { "id": "e7f2…", "nome": "Novo lead", "cor": "#85857d", "ordem": 1 },
      { "id": "a11b…", "nome": "Proposta enviada", "cor": "#f5a524", "ordem": 2 }
    ]
  }]
}