Eventos de uso: avise a plataforma quando o cliente usa o seu sistema

Evento de uso é um aviso simples: o seu sistema conta para a plataforma que determinado cliente usou alguma coisa, em determinado dia, determinada quantidade de vezes. Com esse aviso, a plataforma consegue enxergar o cliente que está se afastando. O começo deste artigo serve para qualquer pessoa entender para que isso existe; a parte da integração é para quem vai programar o envio.

Por que isso existe

Os outros sinais de saúde — conversa, chamado, avaliação, NPS — só aparecem quando o cliente procura a empresa. O problema é que quem está indo embora quase nunca reclama: some calado. O evento de uso é o sinal que enxerga esse silêncio, porque não depende de o cliente falar com ninguém.

A plataforma não sabe o que o evento significa

Ela recebe três coisas: um nome, um dia e uma quantidade. O sentido é seu. Pode ser um atendimento realizado, uma aula assistida, um acesso ao sistema, uma entrada registrada — para a plataforma é sempre a mesma estrutura. Quem decide o que contar, e o que aquilo quer dizer, é quem manda.

Como mandar

É um POST autenticado com uma chave de API:

POST /api/v1/clients/usage-events
{
  "source": "sistema", "external_id": "48211",
  "events": [
    { "name": "acesso", "label": "Acessos", "date": "2026-09-20", "count": 14 }
  ]
}

Como o cliente é identificado

De dois jeitos: pelo id do cliente na plataforma, ou pelo par origem + id no seu sistema (source e external_id) — a mesma chave usada para criar-ou-atualizar cliente. Nunca por nome nem por documento.

Cliente que não existe é recusado, não criado. E mandar evento não coloca ninguém no funil.

Com data e sem data

  • Com date: o número é o total daquele dia. Mandar de novo corrige em vez de somar, então o seu processo diário pode rodar quantas vezes precisar sem duplicar nada.
  • Sem date: significa "aconteceu agora" e soma ao total de hoje.

Mandar vários clientes de uma vez

Quem envia de madrugada, para a base inteira, não precisa fazer uma chamada por
cliente. O mesmo endereço aceita uma lista em clients, cada item com a
identificação do cliente e os eventos dele:

POST /api/v1/clients/usage-events
{
  "clients": [
    { "source": "sistema", "external_id": "48211",
      "events": [ { "name": "acesso", "date": "2026-09-20", "count": 1 } ] },
    { "source": "sistema", "external_id": "48212",
      "events": [ { "name": "atendimento", "date": "2026-09-20", "count": 9 } ] }
  ]
}

São até 200 clientes por chamada e 50 eventos por cliente. A resposta diz
quantos clientes entraram, quantos eventos foram registrados e quais ficaram de
fora, em skipped — normalmente uma empresa que ainda não foi cadastrada aqui.
Um cliente desconhecido não derruba o lote: os outros entram do mesmo jeito.
Vale guardar essa lista, porque ela é exatamente o que falta cadastrar.

Regras e limites

  • name aceita letras minúsculas, números, hífen e sublinhado.
  • label é opcional e só serve para a tela.
  • Até 200 eventos por chamada.
  • Um cliente por chamada.
  • 300 chamadas por minuto.

O que a plataforma faz com isso

Ela guarda o total por dia e usa esse histórico no fator Uso da saúde do cliente. A nota do fator vem do tempo desde o último uso:

  • usou nos últimos 7 dias: 100
  • até 14 dias: 80
  • até 30 dias: 50
  • até 60 dias: 25
  • acima disso: 0

Há ainda a regra da queda: se o último mês somar menos da metade do mês anterior, a nota do fator cai pela metade e a ficha informa o tamanho da queda. É assim que o cliente que usava muito e passou a usar pouco aparece, mesmo tendo usado ontem.

O bloco Uso na ficha

Na ficha do cliente aparece o bloco Uso, com o total do período, a variação contra o período anterior, quando foi a última vez e o que o cliente mais usa.

Quem não manda evento não muda em nada

Conta que não envia nenhum evento continua exatamente como estava: o fator Uso simplesmente não existe e a saúde do cliente segue sendo calculada pelos outros sinais. Você pode começar por um único evento e ir acrescentando outros depois.

Dúvidas frequentes

Se eu reenviar o mesmo dia, o número dobra?
Não, desde que você mande date. Com data, o valor enviado é o total daquele dia e substitui o anterior. Sem data, o envio soma ao total de hoje.

O que acontece se o cliente ainda não estiver cadastrado?
A chamada é recusada. A plataforma não cria cliente a partir de evento de uso.

Que nome devo dar ao evento?
O que fizer sentido para o seu negócio, em letras minúsculas, números, hífen e sublinhado. Se quiser um texto mais bonito na tela, use o label.

Preciso mandar tudo o que o cliente faz?
Não. Escolha os usos que mostram que o cliente está tirando valor do seu sistema. Evento demais não melhora a leitura da saúde.