Documentação da API Fidly — Integração REST e Pixel SDK

Documentação da Plataforma

v3.0

Visão Geral

O Fidly oferece duas 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.

Health Score

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

Recomendação: Use a API REST no backend para eventos de negócio e o Pixel SDK no frontend para identificação de usuários e NPS. Os dois são independentes — você pode usar um, outro ou ambos.

Tokens de Autenticação

Ambas as integrações usam os mesmos tokens. Você os encontra em Configurações → Chaves da API.

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_...

⚠️

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
`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_passive`	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",
    "status": "active"
  },
  "user": {
    "external_id": "user-456",
    "email": "joao@empresa.com",
    "name": "João Silva",
    "job": "manager"
  },
  "event_type": "critical_feature_used",
  "occurred_at": "2026-01-05T16:50:59.730Z",
  "properties": {
    "feature_name": "automation_builder"
  },
  "metadata": {
    "source": "mobile_app"
  }
}

O objeto user é opcional. Quando enviado, cria ou atualiza o usuário vinculado à conta — útil para enriquecer o perfil e segmentar pesquisas NPS. O campo user.external_id é obrigatório se o objeto for incluído.

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 critical_feature_used, envie sempre properties.feature_name — isso permite identificar adoção por feature individualmente.

user.job (cargo)	Perfil
`owner`	Proprietário ou sócio da empresa — 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

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.
`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.job`	string	não	Cargo: owner \| admin \| manager \| analyst.
`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).
`properties.feature_name`	string	não	Recomendado para critical_feature_used. Identifica qual feature foi utilizada.
`metadata`	object	não	Contexto técnico do evento (ex: source, versão do app, ambiente).

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",
      "status": "active"
    },
    "user": {
      "external_id": "user-456",
      "email": "joao@empresa.com",
      "name": "João Silva",
      "job": "manager"
    },
    "event_type": "critical_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 com valor fora da lista.

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.