Cards e pipelines

“Card” é o nome público do funil do Whatix — venda, suporte, cobrança, qualquer processo em etapas (o nome interno é “opportunity”, mas a API usa “card” por ser mais genérico). Um pipeline tem etapas (stages) ordenadas; cada card está numa etapa de um pipeline, tem um contato, um valor opcional e um status (open, won, lost).

Mapa mental

pipeline "Vendas"
 ├─ etapa "Novo lead"     (order: 0)
 ├─ etapa "Qualificado"   (order: 1)
 ├─ etapa "Proposta"      (order: 2)
 └─ etapa "Fechado"       (order: 3, isFinal: true, isWon: true)

card #501 → pipeline "Vendas", etapa "Qualificado", contato Maria, value: 4200, sourceId: 3 (Instagram Ads)

Todos os endpoints de card/pipeline exigem cards:read (leitura) ou cards:write (criar/mover) e enxergam a conta inteira — como um admin vendo o kanban completo, não só os cards do usuário do token.

Caso guiado: dashboard de marketing

Você quer montar um painel externo com: cards do mês por etapa, por origem (sourceId — de onde veio o lead, ex. Instagram Ads, indicação) e motivos de perda. Nenhum endpoint devolve isso pronto — você monta agregando as respostas.

Monte o funil com os pipelines

GET /v1/pipelines devolve os pipelines da sua conta com as etapas já ordenadas (stages[].order). Use isso para saber quais stageId existem e montar as colunas do funil antes de buscar os cards.

curl https://sua-instancia.whatix.cloud/wapi/v1/pipelines \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN"

Busque os cards do período, paginando

GET /v1/cards filtra por pipelineId, createdAtAfter/createdAtBefore (offset de fuso obrigatório — veja Paginação e filtros). Pagine até hasMore: false:

async function fetchCardsDoMes(pipelineId) {
  const all = [];
  let pageNumber = 1;
  let hasMore = true;

  while (hasMore) {
    const url = new URL("https://sua-instancia.whatix.cloud/wapi/v1/cards");
    url.searchParams.set("pipelineId", pipelineId);
    url.searchParams.set("createdAtAfter", "2026-09-01T00:00:00-03:00");
    url.searchParams.set("createdAtBefore", "2026-09-30T23:59:59-03:00");
    url.searchParams.set("pageNumber", pageNumber);
    url.searchParams.set("pageSize", 100);

    const r = await fetch(url, {
      headers: { Authorization: "Bearer wtx_live_SEU_TOKEN" }
    });
    const { cards, hasMore: more } = await r.json();
    all.push(...cards);
    hasMore = more;
    pageNumber++;
  }

  return all;
}

A resposta também traz totalValue — soma de value de todos os cards que casam o filtro, não só da página atual. Útil pra um card de “valor total do funil” sem somar manualmente.

Agrupe por etapa e por origem

Cada card na resposta já vem com stage: { id, name } e source: { id, name } embutidos — não precisa de outra chamada pra resolver os nomes:

function agrupar(cards) {
  const porEtapa = {};
  const porOrigem = {};
  for (const card of cards) {
    const etapa = card.stage?.name ?? "sem etapa";
    const origem = card.source?.name ?? "sem origem";
    porEtapa[etapa] = (porEtapa[etapa] ?? 0) + 1;
    porOrigem[origem] = (porOrigem[origem] ?? 0) + 1;
  }
  return { porEtapa, porOrigem };
}

Resolva os motivos de perda

Pra um card com status: "lost", o objeto já traz lostReason: { id, name }. Se quiser a lista completa de motivos configurados (pra montar um filtro no seu painel, por exemplo), use GET /v1/lost-reasons:

curl https://sua-instancia.whatix.cloud/wapi/v1/lost-reasons \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN"

Agende a atualização respeitando o rate limit

Rode a coleta a cada 15 minutos (ou o intervalo que fizer sentido pro seu painel). Com paginação de 100 cards por página, um pipeline com 500 cards no mês gasta 5 requisições — bem abaixo do limite de 120/min por token. Se você tem vários pipelines ou várias companies, distribua as chamadas em vez de disparar tudo no mesmo segundo:

import { setTimeout as sleep } from "node:timers/promises";

async function coletarTodosPipelines(pipelineIds) {
  const resultado = {};
  for (const id of pipelineIds) {
    resultado[id] = agrupar(await fetchCardsDoMes(id));
    await sleep(500); // espaça as chamadas entre pipelines
  }
  return resultado;
}

Criar card por webhook de formulário

Quando um lead preenche um formulário externo, crie o card direto pelo número — sem precisar buscar o contactId antes. POST /v1/cards aceita phone como alternativa a contactId; o contato é criado/reaproveitado automaticamente:

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/cards \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5534999990000",
    "name": "João Pereira",
    "pipelineId": 1,
    "sourceId": 3,
    "title": "Interesse via landing page",
    "value": 1500
  }'

Envie exatamente um entre contactId e phone — os dois juntos (ou nenhum) resultam em 400 ERR_CONTACT_IDENTIFIER_REQUIRED.

Envie sempre stageId ao criar um card. Se omitir, o card é criado sem etapa (stage: null) e não aparece nas colunas do kanban.

Se o pipeline tiver uma etapa que exige origem (sourceRequired) e você não enviar sourceId, a API responde 400 ERR_SOURCE_REQUIRED_FOR_STAGE — só quando stageId também é enviado no POST. Confira as etapas em GET /v1/pipelines antes de montar a integração.

Preenchendo campos personalizados

customFields aceita os campos personalizados do pipeline informado (ou globais da sua conta) — a chave é o name técnico do campo, o valor já no formato do tipo (select/multiselect precisam bater com as options cadastradas):

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/cards \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5534999990000",
    "name": "João Pereira",
    "pipelineId": 1,
    "sourceId": 3,
    "title": "Interesse via landing page",
    "value": 1500,
    "customFields": {
      "referred_by": "Indicação",
      "payment_method": "Cartão"
    }
  }'

Campo inexistente, de outro pipeline/conta ou com valor inválido é ignorado — nunca falha a criação do card — e reportado em ignoredCustomFields ([{ name, reason }]) na resposta, presente só quando algum campo foi ignorado.

Mover card de etapa

PATCH /v1/cards/{cardId}/stage move exatamente como um arrastar-e-soltar no kanban: dispara as mesmas automações da etapa e atualiza em tempo real pra quem estiver com o kanban aberto.

curl -X PATCH https://sua-instancia.whatix.cloud/wapi/v1/cards/501/stage \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stageId": 8 }'

stageId precisa ser do mesmo pipeline do card. Mover para etapa de outro pipeline devolve 422 ERR_STAGE_NOT_IN_PIPELINE — mover entre pipelines não é permitido pela API.

Erros comuns

Código	HTTP	Causa
`ERR_INVALID_DATE_FILTER`	400	Filtro de data sem offset de fuso ou intervalo invertido.
`ERR_NO_CARD_FOUND`	404	Card inexistente ou de outra conta.
`ERR_CONTACT_IDENTIFIER_REQUIRED`	400	Nenhum ou ambos `contactId`/`phone` informados ao criar card.
`ERR_PIPELINE_NOT_FOUND`	404	`pipelineId` inexistente ou de outra conta.
`ERR_STAGE_NOT_IN_PIPELINE`	422	`stageId` existe, mas é de outro pipeline.
`ERR_SOURCE_NOT_FOUND`	404	`sourceId` inexistente ou de outra conta.

Veja o catálogo completo de erros.

Início

Guias

Referência

Cards e pipelines

Mapa mental

Caso guiado: dashboard de marketing

Criar card por webhook de formulário

Preenchendo campos personalizados

Mover card de etapa

Erros comuns

​Mapa mental

​Caso guiado: dashboard de marketing

​Criar card por webhook de formulário

​Preenchendo campos personalizados

​Mover card de etapa

​Erros comuns

Mapa mental

Caso guiado: dashboard de marketing

Criar card por webhook de formulário

Preenchendo campos personalizados

Mover card de etapa

Erros comuns