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. (Cuidado Vibers)

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