Integrações via API: guia completo de uso

A API do WiseData NPS permite que outro sistema — seu CRM, e-commerce ou ERP — leia e mantenha seus contatos e listas de forma automática, sem ninguém precisar mexer no painel. É uma API REST: você faz requisições HTTP e recebe respostas em JSON. Tudo fica na página Integrações, disponível no plano Business.

Visão geral

• Base da URL: https://api.wisedatanps.com
• Autenticação: token no cabeçalho Authorization: Bearer SEU_TOKEN
• Formato: JSON nas requisições (com Content-Type: application/json) e nas respostas
• O que dá para fazer hoje: listar, criar, consultar, atualizar e excluir contatos, e listar suas listas de contatos

Passo 1 — Crie um token

Na página Integrações, clique em Novo Token, dê um nome que ajude a identificar a integração (ex.: "Integração CRM") e confirme. O token é exibido uma única vez: copie e guarde em local seguro, pois ele não será mostrado de novo. Depois, a lista mostra apenas uma prévia (os últimos dígitos), a data de criação e o último uso.

Se um token vazar ou deixar de ser usado, revogue-o — qualquer sistema que o utilize perde o acesso na hora. Dica: use um token por integração, para revogar só o que precisar.

Passo 2 — Autentique suas requisições

Envie o token em todas as chamadas, no cabeçalho de autorização:

Authorization: Bearer SEU_TOKEN Content-Type: application/json

Passo 3 — Sua primeira requisição

Comece listando suas listas de contatos para descobrir o id de cada uma:

curl https://api.wisedatanps.com/api/v1/contact-lists/all \   -H "Authorization: Bearer SEU_TOKEN"

Com o id de uma lista em mãos, você já pode consultar ou adicionar contatos a ela.

Endpoints

Listar todas as listas

GET /api/v1/contact-lists/all — retorna todas as suas listas de contatos.

Listar contatos de uma lista

GET /api/v1/contact-lists/{listId}/contacts — retorna os contatos de uma lista, de forma paginada. Parâmetros de consulta aceitos:

• search — busca por nome, e-mail ou telefone.
• sort — campo de ordenação: name, email, phone ou created_at.
• order — asc ou desc.
• page — número da página.
• per_page — itens por página (de 1 a 100).

A resposta vem paginada, com os dados em data e as informações de paginação em meta:

{   "data": [     {       "id": 123,       "name": "João Silva",       "email": "joao@empresa.com",       "phone": "+5511999999999",       "emailStatus": "valid",       "phoneStatus": "valid",       "createdAt": "2026-06-05T13:40:00.000000Z"     }   ],   "meta": { "current_page": 1, "per_page": 15, "total": 42, "last_page": 3 } }

Criar um contato

POST /api/v1/contact-lists/{listId}/contacts — cria um contato e o adiciona à lista indicada. Campos do corpo:

• name — obrigatório, de 2 a 100 caracteres.
• email — opcional, precisa ser um e-mail válido (e-mails descartáveis são recusados).
• phone — opcional, de 8 a 20 caracteres.

curl -X POST https://api.wisedatanps.com/api/v1/contact-lists/1/contacts \   -H "Authorization: Bearer SEU_TOKEN" \   -H "Content-Type: application/json" \   -d '{ "name": "João Silva", "email": "joao@empresa.com", "phone": "+5511999999999" }'

Em caso de sucesso, a resposta é 201 com o contato criado:

{   "message": "Contato criado com sucesso.",   "data": {     "id": 123,     "name": "João Silva",     "email": "joao@empresa.com",     "phone": "+5511999999999",     "emailStatus": "pending",     "phoneStatus": "pending",     "createdAt": "2026-06-05T13:40:00.000000Z"   } }

Observação: e-mail e telefone começam com status pending e passam por uma verificação automática em segundo plano — o status muda para válido (ou outro) em seguida.

Consultar um contato

GET /api/v1/contacts/{contactId} — retorna os detalhes de um contato em data.

Atualizar um contato

PUT /api/v1/contacts/{contactId} — atualiza name, email e/ou phone. A resposta traz uma message e o contato atualizado em data.

Excluir um contato

DELETE /api/v1/contacts/{contactId} — remove o contato permanentemente. A resposta é apenas uma message de confirmação.

Como ler as respostas

Os retornos seguem um padrão simples: um único recurso vem dentro de data; quando há uma ação, vem também uma message; e listas vêm paginadas, com data (os itens) e meta (página atual, total, etc.).

Erros comuns

• 401 — token ausente ou inválido. Confira o cabeçalho Authorization.
• 403 — sem permissão para o recurso (por exemplo, plano sem acesso à API).
• 404 — a lista ou o contato informado não existe (ou não é da sua conta).
• 422 — dados inválidos. O corpo traz message e um objeto errors indicando cada campo com problema.
• 429 — você ultrapassou o limite de requisições (veja abaixo).

Limites de uso

• Leitura (GET): até 60 requisições por minuto (varia conforme o plano).
• Escrita (POST/PUT/DELETE): até 30 requisições por minuto.
• Ao atingir o limite, a API responde 429 com o cabeçalho Retry-After, indicando em quantos segundos você pode tentar de novo.

Boas práticas e segurança

• Nunca exponha o token em código que roda no navegador nem em repositórios públicos — use-o apenas a partir do seu servidor.
• Trate o status 429 aguardando o tempo do Retry-After antes de repetir a requisição.
• Mantenha um token por integração e revogue imediatamente qualquer token que possa ter vazado.

A própria página de Integrações traz exemplos prontos em cURL, JavaScript e PHP para você copiar e adaptar.