ProFeedback
Quickstart

Primeira nota em cinco passos

Use uma chave pf_test_ para testar: tudo vai para o sandbox, separado da produção, e não consome cota.

1. Autenticação

No painel, abra Chaves de API e gere uma chave. Ela aparece uma única vez; guarde-a no cofre do seu sistema. Envie em toda chamada:

Authorization: Bearer pf_test_xxxxxxxxxxxxxxxx

Chave pf_live_ grava em produção. Chave de escopo leitura só faz GET; para criar clientes, notas e links use escopo completo.

2. Criar um cliente

O external_id é o identificador do cliente no seu sistema e é único por conta (repetido devolve 409 com o id existente).

curl -X POST https://api.profeedback.com.br/v1/customers \
  -H "Authorization: Bearer $PROFEEDBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "crm-001", "name": "Maria Souza",
       "phone": "11987654321", "email": "maria@exemplo.com.br",
       "attributes": {"plano": "Mensal", "unidade": "Centro"}}'

3. Registrar uma nota

Nota de 0 a 10, comentário opcional. Cliente por customer_id ou external_id; um external_id novo cria o cliente com os dados de customer.

curl -X POST https://api.profeedback.com.br/v1/responses \
  -H "Authorization: Bearer $PROFEEDBACK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: atendimento-98765" \
  -d '{"external_id": "crm-001", "score": 9, "comment": "Atendimento rápido",
       "source": "whatsapp", "attributes": {"atendente": "Ana"}}'

Antes de perguntar, consulte se o cliente já respondeu na janela da conta (padrão de 90 dias):

curl https://api.profeedback.com.br/v1/customers/<id>/eligibility \
  -H "Authorization: Bearer $PROFEEDBACK_KEY"
# {"customer_id": "...", "days": 90, "eligible": true, "last_response_at": null}

4. Gerar um link de pesquisa

Prefere que o próprio cliente escolha a nota numa página? Gere um link de uso único e envie por WhatsApp, e-mail ou SMS. A nota respondida passa pelas mesmas regras de POST /v1/responses e dispara os mesmos webhooks.

curl -X POST https://api.profeedback.com.br/v1/survey-links \
  -H "Authorization: Bearer $PROFEEDBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "crm-001", "expires_in_days": 7, "source": "whatsapp",
       "attributes": {"protocolo": "98765"}}'
# {"id": "...", "url": "https://r.profeedback.com.br/AbC...", "expires_at": "..."}

A URL leva o token e só aparece nesta resposta. Validade padrão de 7 dias (de 1 a 90). Sem source, a nota fica com origem link.

5. Ler o NPS

curl "https://api.profeedback.com.br/v1/metrics/nps?from=2026-10-01&to=2026-10-31&group_by=atendente" \
  -H "Authorization: Bearer $PROFEEDBACK_KEY"

Devolve total, promotores, neutros, detratores, percentuais, nps (de -100 a +100, null sem respostas) e, com group_by, o NPS por valor do atributo (ou source).

Para listar as notas: GET /v1/responses?from=&to=&category=detractor&external_id=. Consumo do mês: GET /v1/usage.

Próximos passos