Fidly

Documentação da Plataforma

v3.0

Visão Geral

A Fidly oferece três formas de integração, complementares entre si:

API REST

Envie eventos de negócio (pagamentos, cancelamentos, tickets) a partir do seu backend.

Pixel SDK

Script frontend para identificar usuários, exibir pesquisas NPS e enviar eventos de negócio sem backend.

Zapier / Make

Conecte HubSpot, Zendesk, Stripe e 6.000+ apps sem escrever código.

Health Score

Calculado automaticamente a partir dos eventos — sem configuração adicional.

Recomendação: Use a API REST no backend para máximo controle. Sem desenvolvedor disponível? O Zapier entrega o mesmo resultado sem código. O Pixel SDK cuida do frontend e NPS.

Tokens de Autenticação

Cada forma de integração usa seu próprio token. Você os encontra em Configurações → API Keys.

Token Público

Identifica sua conta. Usado no body da API e no init() do SDK. Pode ser exposto no frontend.

client_public_token: "pk_..."

Token Privado

Autentica requisições. Usado no header Authorization da API REST. Nunca exponha no frontend.

Authorization: Bearer sk_...

Webhook Secret

Exclusivo para integrações Zapier / Make. Enviado no header X-Fidly-Secret.

X-Fidly-Secret: wh_...
⚠️

Mantenha o token privado seguro. Nunca o inclua em código frontend ou repositórios públicos.

Tipos de Evento

Referência completa de todos os eventos que afetam o Health Score.

Eventos da API

Enviados via API REST a partir do seu backend.

Tipo de EventoDimensãoImpactoCríticoDescrição
login_successuso+2—Usuário fez login com sucesso
first_value_generatedadocao+10—Cliente gerou primeiro valor
feature_usedadocao+3—Feature utilizada
critical_feature_usedadocao+3—Usou funcionalidade crítica
critical_feature_not_used_14dadocao-8—Não usou feature crítica por 14 dias
payment_overduefinanceiro-15—Pagamento em atraso
payment_confirmedfinanceiro+5—Pagamento confirmado
plan_downgradefinanceiro-10—Cliente fez downgrade do plano
cancellationfinanceiro-30SimCliente cancelou o serviço
integration_errorestabilidade-10—Erro na integração
critical_incidentestabilidade-20—Incidente crítico ocorreu
ticket_openedrelacionamento-5—Ticket de suporte aberto
ticket_resolvedrelacionamento+5—Ticket de suporte resolvido

Eventos do Sistema

Gerados automaticamente pela Fidly — não precisam ser enviados.

Tipo de EventoDimensãoImpactoCríticoDescrição
inactivity_7duso-5—Inatividade por 7 dias — gerado automaticamente
inactivity_14duso-10SimInatividade por 14 dias — gerado automaticamente
nps_promoterrelacionamento+3—Resposta NPS Promotor (9-10) — gerado pelo Pixel SDK
nps_neutralrelacionamento+1—Resposta NPS Neutro (7-8) — gerado pelo Pixel SDK
nps_detractorrelacionamento-4—Resposta NPS Detrator (0-6) — gerado pelo Pixel SDK
csat_satisfiedrelacionamento+3—Resposta CSAT Satisfeito (4-5) — pesquisa por link, gerado pelo Pixel SDK
csat_neutralrelacionamento+1—Resposta CSAT Neutro (3) — pesquisa por link, gerado pelo Pixel SDK
csat_dissatisfiedrelacionamento-4—Resposta CSAT Insatisfeito (1-2) — pesquisa por link, gerado pelo Pixel SDK

Health Score

Pontuação de 0 a 100, recalculada todo dia. Usa três dimensões com pesos fixos; dimensão sem dado sai da conta e o peso dela vai para as outras. Eventos de pagamento e de estabilidade não entram na nota hoje: alimentam os comportamentos (como Risco Financeiro). Como o Health Score funciona.

Uso45%

Dias com atividade nos últimos 30 dias e dias desde a última atividade

Adoção45%

Etapas do cliente atrasadas: quanto mais passou do prazo, mais pesa

Relacionamento10%

NPS e CSAT dos últimos 90 dias e eventos ticket_opened / ticket_resolved

Fórmula ponderada

score = (uso × 0.45) + (adoção × 0.45) + (relacionamento × 0.10)

Saudável

≥ 80 pontos

Atenção

50–79 pontos

Risco

25–49 pontos

Crítico

< 25 pontos

Limites e Planos

PlanoEventos/mêsPesquisas ativasNPS In-AppNPS Email
FREE
3.0001Incluído—
STARTER
50.0005Incluído1.000 disparos/mês
GROWTHRecomendado
150.000IlimitadoIncluído10.000 disparos/mês
SCALE
PersonalizadoIlimitadoIncluídoPersonalizado

NPS In-App: respostas coletadas via Pixel SDK no frontend.  NPS Email: disparos de pesquisa por email configurados no dashboard.

Endpoint

POSThttps://api-clients.fidly.com.br/v2/events

Payload

{
  "client_public_token": "seu_token_publico",
  "account": {
    "external_id": "client-123",
    "name": "Nome do cliente final",
    "document_id": "00000000000",
    "nmrr": 2500,
    "started_at": "2023-03-10",
    "contracted_plan": "Pro anual",
    "status": "active",
    "custom_fields": { "Segmento": "Varejo", "Cidade": "São Paulo" },
    "tags": ["VIP", "Piloto plano novo"]
  },
  "user": {
    "external_id": "user-456",
    "email": "joao@empresa.com",
    "name": "João Silva",
    "job": "manager",
    "phone": "11987654321"
  },
  "event_type": "feature_used",
  "occurred_at": "2026-01-05T16:50:59.730Z",
  "properties": {
    "feature_name": "automation_builder"
  },
  "metadata": {
    "source": "mobile_app"
  }
}

properties vs metadata — quando usar cada um?

  • properties → dados de negócio sobre o que aconteceu: qual feature, módulo, objetivo. Ex: { "feature_name": "automation_builder" }
  • metadata → contexto técnico do evento: origem da requisição, versão do app, ambiente. Ex: { "source": "mobile_app" }

Para o evento feature_used, properties.feature_name é obrigatório — isso permite identificar adoção por feature individualmente.

Header obrigatório: Authorization: Bearer seu_token_privado

CampoTipoObrigatórioDescrição
client_public_tokenstringsimToken público da sua conta Fidly (pk_...).
accountobjectsimDados da conta do seu cliente.
account.external_idstringsimID da conta no seu sistema.
account.namestringsimNome da conta. Atualizado a cada evento.
account.document_idstringnãoCPF ou CNPJ da conta (aceita o novo CNPJ alfanumérico) — só letras e números, sem pontuação.
account.nmrrnumbernãoMensalidade da conta (receita recorrente mensal), em reais. Ex: 2500. Aparece no cabeçalho da conta e alimenta o churn de receita no dashboard.
account.started_atstring (AAAA-MM-DD)nãoData real de início do contrato — não a data de cadastro na Fidly. Essencial para calcular tempo de permanência.
account.contracted_planstringnãoPlano que o cliente contratou de você, com o nome que o seu sistema usa (ex: "Pro anual"). Até 80 caracteres; null limpa. Aparece no cadastro do cliente e filtra a lista de clientes na Fidly. Evento sem o campo não altera o plano gravado.
account.custom_fieldsobject (chave → valor)nãoCampos próprios do seu negócio, como Segmento, Cidade, etc. A chave é o nome do campo, e o campo é criado no primeiro envio, com o tipo definido pelo valor: número, data (DD/MM/AAAA ou AAAA-MM-DD) ou texto. Valores de texto aceitam até 500 caracteres. Campo não enviado não altera nada; null ou vazio limpa a informação do cliente.
account.tagsarray (texto)nãoTags do cliente, como "VIP" ou "Piloto plano novo". O envio apenas adiciona tags ao cliente: nunca remove nem substitui as que ele já tem. A tag que ainda não existe é criada no primeiro envio. Até 10 tags por envio (acima disso o evento é rejeitado com erro 400); o cliente também não passa de 10 tags no total, e as que não couberem são ignoradas. Cada nome tem até 40 caracteres; nome só com símbolos ou acima de 40 caracteres é ignorado. A tag é reconhecida pelo nome, sem diferenciar maiúsculas e minúsculas nem acentos (Carteira Sul e carteira sul são a mesma tag). Deve ser uma lista de textos; texto único ou null é rejeitado. Para remover uma tag de um cliente, use a interface da Fidly.
account.status"active" | "cancelled"nãoUse "cancelled" para arquivar um cliente via API. Padrão: "active".
userobjectnãoDados do usuário que gerou o evento. Cria ou atualiza o usuário vinculado à conta.
user.external_idstringsimObrigatório quando o objeto user é enviado.
user.emailstringnãoE-mail do usuário.
user.namestringnãoNome do usuário.
user.phonestringnãoTelefone/WhatsApp do usuário. Envie com DDD (ex: 11987654321) — pontuação é ignorada. Sem DDI, assume Brasil (+55).
user.jobstringnão
  • ownerProprietário ou sócio — decisor de renovação e expansão
  • adminAdministrador técnico — configura e gerencia acessos
  • managerGerente de área — supervisiona e influencia a decisão
  • analystAnalista — usuário ativo que extrai valor do produto
event_typestringsimTipo do evento. Ver tabela de eventos acima.
occurred_atstring (ISO 8601)simData e hora em que o evento ocorreu.
propertiesobjectnãoDados de negócio sobre o evento (ex: feature_name, módulo). Separado de metadata.
properties.feature_namestringnãoObrigatório para feature_used. Identifica qual feature foi utilizada.
metadataobjectnãoContexto técnico do evento (ex: source, versão do app, ambiente). Dados livres — objeto JSON.

Exemplo cURL

curl -X POST https://api-clients.fidly.com.br/v2/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu_token_privado" \
  -d '{
    "client_public_token": "seu_token_publico",
    "account": {
      "external_id": "client-123",
      "name": "Nome do cliente",
      "document_id": "00000000000",
      "nmrr": 2500,
      "started_at": "2023-03-10",
      "contracted_plan": "Pro anual",
      "status": "active",
      "custom_fields": { "Segmento": "Varejo", "Cidade": "São Paulo" },
      "tags": ["VIP", "Piloto plano novo"]
    },
    "user": {
      "external_id": "user-456",
      "email": "joao@empresa.com",
      "name": "João Silva",
      "job": "manager",
      "phone": "11987654321"
    },
    "event_type": "feature_used",
    "occurred_at": "2026-01-05T16:50:59.730Z",
    "properties": {
      "feature_name": "automation_builder"
    },
    "metadata": {
      "source": "mobile_app"
    }
  }'

Resposta de Sucesso

Status: 202 Accepted
Body: (vazio)

O evento é aceito e processado de forma assíncrona. Nenhum corpo é retornado.

Erros

400 — Payload inválido

Campo obrigatório ausente, tipo incorreto ou campo não permitido.

422 — Valor inválido

Payload bem formado, mas valor não aceito — ex: user.job fora da lista ou user.phone em formato inválido.

401 — Não autenticado

Token privado ausente, inválido ou expirado.

429 — Limite excedido

Cota mensal de eventos atingida para o plano atual.

500 — Erro interno

Erro no servidor — tente novamente em instantes.