Documentação da Plataforma

v3.0

Visão Geral

O 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 Evento	Dimensão	Impacto	Crítico	Descrição
`login_success`	uso	+2	—	Usuário fez login com sucesso
`first_value_generated`	adocao	+10	—	Cliente gerou primeiro valor
`feature_used`	adocao	+3	—	Feature utilizada
`critical_feature_used`	adocao	+3	—	Usou funcionalidade crítica
`critical_feature_not_used_14d`	adocao	-8	—	Não usou feature crítica por 14 dias
`payment_overdue`	financeiro	-15	—	Pagamento em atraso
`payment_confirmed`	financeiro	+5	—	Pagamento confirmado
`plan_downgrade`	financeiro	-10	—	Cliente fez downgrade do plano
`cancellation`	financeiro	-30	Sim	Cliente cancelou o serviço
`integration_error`	estabilidade	-10	—	Erro na integração
`critical_incident`	estabilidade	-20	—	Incidente crítico ocorreu
`ticket_opened`	relacionamento	-5	—	Ticket de suporte aberto
`ticket_resolved`	relacionamento	+5	—	Ticket de suporte resolvido

Eventos do Sistema

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

Tipo de Evento	Dimensão	Impacto	Crítico	Descrição
`inactivity_7d`	uso	-5	—	Inatividade por 7 dias — gerado automaticamente
`inactivity_14d`	uso	-10	Sim	Inatividade por 14 dias — gerado automaticamente
`nps_promoter`	relacionamento	+3	—	Resposta NPS Promotor (9-10) — gerado pelo Pixel SDK
`nps_neutral`	relacionamento	+1	—	Resposta NPS Neutro (7-8) — gerado pelo Pixel SDK
`nps_detractor`	relacionamento	-4	—	Resposta NPS Detrator (0-6) — gerado pelo Pixel SDK

Health Score

Pontuação de 0 a 100 calculada automaticamente a partir dos eventos enviados. Cada evento impacta uma das cinco dimensões abaixo.

Uso30%

Frequência de login e atividade

Adoção30%

Uso das funcionalidades principais

Financeiro20%

Status de pagamentos e plano

Estabilidade10%

Erros e incidentes técnicos

Relacionamento10%

Tickets de suporte e NPS

Fórmula ponderada

score = (uso × 0.3) + (adoção × 0.3) + (financeiro × 0.2) + (estabilidade × 0.1) + (relacionamento × 0.1)

Saudável

≥ 80 pontos

Atenção

50–79 pontos

Risco

25–49 pontos

Crítico

< 25 pontos

Limites e Planos

Plano	Eventos/mês	Pesquisas ativas	NPS In-App	NPS Email
FREE	3.000	1	Incluído	—
STARTER	50.000	5	Incluído	1.000 disparos/mês
GROWTHRecomendado	150.000	Ilimitado	Incluído	10.000 disparos/mês
SCALE	Personalizado	Ilimitado	Incluído	Personalizado

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",
    "status": "active"
  },
  "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

Campo	Tipo	Obrigatório	Descrição
`client_public_token`	string	sim	Token público da sua conta Fidly (pk_...).
`account`	object	sim	Dados da conta do seu cliente.
`account.external_id`	string	sim	ID da conta no seu sistema.
`account.name`	string	sim	Nome da conta. Atualizado a cada evento.
`account.document_id`	string	não	CPF ou CNPJ da conta (aceita o novo CNPJ alfanumérico) — só letras e números, sem pontuação.
`account.nmrr`	number	não	Mensalidade 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_at`	string (AAAA-MM-DD)	não	Data real de início do contrato — não a data de cadastro no Fidly. Essencial para calcular tempo de permanência.
`account.status`	"active" \| "cancelled"	não	Use "cancelled" para arquivar um cliente via API. Padrão: "active".
`user`	object	não	Dados do usuário que gerou o evento. Cria ou atualiza o usuário vinculado à conta.
`user.external_id`	string	sim	Obrigatório quando o objeto user é enviado.
`user.email`	string	não	E-mail do usuário.
`user.name`	string	não	Nome do usuário.
`user.phone`	string	não	Telefone/WhatsApp do usuário. Envie com DDD (ex: 11987654321) — pontuação é ignorada. Sem DDI, assume Brasil (+55).
`user.job`	string	não	`owner`Proprietário ou sócio — decisor de renovação e expansão `admin`Administrador técnico — configura e gerencia acessos `manager`Gerente de área — supervisiona e influencia a decisão `analyst`Analista — usuário ativo que extrai valor do produto
`event_type`	string	sim	Tipo do evento. Ver tabela de eventos acima.
`occurred_at`	string (ISO 8601)	sim	Data e hora em que o evento ocorreu.
`properties`	object	não	Dados de negócio sobre o evento (ex: feature_name, módulo). Separado de metadata.
`properties.feature_name`	string	não	Obrigatório para feature_used. Identifica qual feature foi utilizada.
`metadata`	object	não	Contexto 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",
      "status": "active"
    },
    "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.