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- JSON nos dois sentidos, com nomes em
snake_case(os mesmos dos webhooks de saída). - Dinheiro sempre em centavos inteiros: R$ 1.997,00 =
199700. - Datas em ISO 8601, em UTC (
2026-10-27T14:30:00.000Z). - Contato e negócio na lixeira não existem para a API (404), e nenhum pedido os traz de volta — restaurar é pela tela.
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..."- A chave age em nome de quem a gerou: o que ela cria aparece na linha do tempo como feito por essa pessoa (“… pela API”). Se a pessoa sair do workspace ou deixar de ser Dono/Admin, a chave para de funcionar.
- Leitura e escrita faz tudo desta página; Só leitura recebe
403emPOSTePATCH. - Sem a chave, com a chave errada, revogada ou vencida:
401. Revogar é na mesma tela e vale na hora. - Nunca ponha a chave no código do navegador (JavaScript de página): ela é do servidor do seu sistema.
Limite de pedidos
60 pedidos por minuto por chave (minuto de relógio). Toda resposta traz:
X-RateLimit-Limit— o teto (60);X-RateLimit-Remaining— quanto sobra neste minuto;X-RateLimit-Reset— quando o minuto vira (segundos Unix).
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)."
}
}| Status | codigo | Quando |
|---|---|---|
| 400 | corpo_invalido · parametro_invalido | corpo que não é um objeto JSON; parâmetro da URL errado (limite, cursor, data) |
| 401 | nao_autenticado | sem chave, chave errada, revogada, vencida ou de quem não é mais Dono/Admin |
| 403 | sem_permissao | chave “Só leitura” num POST ou PATCH |
| 404 | nao_encontrado | o id não existe, é de outro workspace ou está na lixeira |
| 409 | conflito | WhatsApp que já é de outro contato; mover negócio fechado sem reabrir; o mesmo externo_id sendo gravado agora por outro pedido |
| 413 | corpo_grande | corpo acima de 64 KB |
| 415 | tipo_de_conteudo | POST/PATCH sem Content-Type: application/json |
| 422 | validacao | campo inválido ou desconhecido, id de funil/etapa/produto/responsável que não existe |
| 429 | limite_excedido | mais de 60 pedidos no minuto |
| 500 | erro_interno | falha 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"
}email_consentimento_em: quando o consentimento de e-mail foi registrado (LGPD);null= a pessoa não entra nas campanhas de e-mail. Para registrar, mandeemail_consentimento: truecom oemail(veja o POST abaixo).email_suprimido:truequando o endereço está suprimido (descadastro, e-mail que voltou, reclamação de spam ou bloqueio pela equipe). Suprimido não recebe nenhum e-mail marketing, mesmo com consentimento. A supressão é do endereço e não muda oatualizado_emdo contato: o?atualizado_desde=não a traz, então confira lendo o contato.- Os dois são só leitura: mandados no POST ou no PATCH voltam
422. Retirar o consentimento, suprimir e reativar endereço é pela tela.
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: truedeclara 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 oemaildo mesmo pedido (sem ele,422) e nunca troca um consentimento que já existe; ausente oufalsenão muda nada (retirar é pela tela). Também vale nocontatodo 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 recebe409— tente de novo.- Sem
valor_centavos, o valor é a soma dos produtos (e acompanha se a equipe mexer nos produtos). Comvalor_centavose 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ão409). - 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 }
]
}]
}