API do WaSap

Tempo de leitura estimado: 12 minutos 130 visualizações

Este documento é destinado a desenvolvedores que desejam integrar seus próprios sites, sistemas, aplicativos ou serviços à API fornecida pelo WaSap. Ele descreve as operações de envio e agendamento de mensagens, contatos e tarefas. Os exemplos usam valores fictícios; adapte a URL, os identificadores e os campos às configurações da sua instalação.

Segurança: nunca grave uma API Key real no Git, em logs, em capturas de tela ou no código-fonte distribuído ao navegador.

1. Pré-requisitos

Antes de iniciar, obtenha com o administrador da sua instalação:

a URL base, por exemplo https://suaapi.wasap.com.br;
uma API Key ativa;
os IDs de conexão do WhatsApp, usuário e fila necessários ao seu fluxo;
os escopos/permissões correspondentes às operações que serão executadas.

Para testar os exemplos de terminal, tenha o curl instalado. Para integrar em uma aplicação, utilize um cliente HTTP capaz de enviar cabeçalhos de autenticação, corpos JSON e, no envio de arquivos, requisições multipart/form-data.

2. Configuração e autenticação

Defina a URL sem barra no final e o token sem o prefixo Bearer:

export WASAP_URL='https://suaapi.wasap.com.br'
export WASAP_TOKEN='SUA_API_KEY'

As requisições autenticadas enviam a chave no cabeçalho HTTP:

Authorization: Bearer SUA_API_KEY

Nos corpos JSON, envie também:

Content-Type: application/json

Teste básico de autenticação:

curl "$WASAP_URL/api/contacts?pageNumber=1" \
  -H "Authorization: Bearer $WASAP_TOKEN"

Um retorno 401 UNAUTHORIZED normalmente indica chave ausente, inválida, expirada ou desativada. Um 403 INSUFFICIENT_SCOPE indica que a chave é reconhecida, mas não possui a permissão pedida. Nesse caso, consulte error.details.requiredScope na resposta.

3. Convenções

3.1 Telefones

Use somente dígitos, incluindo DDI e DDD:

correto: 5511999999999;
incorreto: +55 (11) 99999-9999.

Antes de enviar uma mensagem, o telefone pode ser verificado por GET /api/contacts/check/:number.

3.2 Datas e horários

Use ISO 8601 com fuso explícito. UTC é recomendado:

2026-04-01T10:00:00Z

Também é possível representar um deslocamento explícito, como 2026-04-01T07:00:00-03:00. Evite datas sem fuso, pois elas podem ser interpretadas de maneira diferente entre ambientes.

3.3 IDs, booleanos e arrays

Envie IDs numéricos como números, não como descrições.
Envie booleanos JSON como true ou false, não como strings.
Envie listas como arrays JSON, por exemplo "assignedUserIds": [1, 2].
Garanta que IDs relacionados pertençam ao mesmo ambiente/empresa.

3.4 Campos opcionais e paginação

Omita propriedades e filtros opcionais que não forem usados; não os envie como string vazia.
pageNumber começa em 1.
Nas listagens, use count e hasMore da resposta para decidir se a próxima página deve ser consultada.
Codifique parâmetros de consulta; curl --data-urlencode faz isso automaticamente.

4. Referência rápida

Método	Rota	Finalidade
`POST`	`/api/messages/send`	Enviar mensagem de texto ou mídia
`POST`	`/api/messages/schedule`	Agendar mensagem
`GET`	`/api/messages/schedule`	Listar agendamentos
`DELETE`	`/api/messages/schedule/:id`	Cancelar agendamento pendente
`GET`	`/api/contacts`	Listar/pesquisar contatos
`GET`	`/api/contacts/:number`	Consultar contato pelo telefone
`POST`	`/api/contacts`	Criar ou sincronizar contato
`GET`	`/api/contacts/check/:number`	Validar conta do WhatsApp
`GET`	`/api/tasks`	Listar tarefas
`GET`	`/api/tasks/:taskId`	Consultar tarefa
`POST`	`/api/tasks`	Criar tarefa
`PUT`	`/api/tasks/:taskId`	Atualizar tarefa
`DELETE`	`/api/tasks/:taskId`	Excluir tarefa

5. Mensagens

5.1 Enviar texto

Rota: POST /api/messages/send

Campo	Tipo	Obrigatoriedade	Descrição
`number`	string	obrigatório	Telefone com DDI e DDD, somente dígitos
`body`	string	obrigatório no envio textual	Conteúdo da mensagem
`userId`	number	conforme instalação	Usuário/atendente associado
`whatsappId`	number	conforme instalação	Conexão usada no envio
`queueId`	number	conforme instalação	Fila/setor associado
`disableBot`	boolean	opcional	Controla o bot no atendimento
`openTicket`	boolean	opcional	Controla a abertura do ticket

curl -X POST "$WASAP_URL/api/messages/send" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "5511999999999",
    "body": "Olá! Esta é uma mensagem de teste.",
    "userId": 1,
    "whatsappId": 1,
    "queueId": 1,
    "disableBot": false,
    "openTicket": true
  }'

Considere a mensagem aceita somente depois de receber um status HTTP de sucesso. Guarde o identificador retornado pela sua instalação quando precisar acompanhar o envio.

5.2 Enviar mídia

Use a mesma rota com multipart/form-data. O arquivo é enviado no campo medias:

curl -X POST "$WASAP_URL/api/messages/send" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  -F 'number=5511999999999' \
  -F 'body=Confira o anexo' \
  -F 'whatsappId=1' \
  -F 'medias=@./arquivo.pdf'

O curl cria o cabeçalho multipart e seu boundary; não defina manualmente Content-Type nesse exemplo. Confirme previamente tamanho e tipo de arquivo aceitos pela sua instalação. Não envie URL ou Base64 como se fosse um arquivo, salvo quando sua instalação documentar explicitamente esse formato.

6. Agendamentos

6.1 Agendar uma mensagem

Rota: POST /api/messages/schedule

number, body e scheduledAt formam os dados centrais. Os IDs dependem da configuração operacional.

curl -X POST "$WASAP_URL/api/messages/schedule" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "5511999999999",
    "body": "Lembrete agendado",
    "scheduledAt": "2026-04-01T10:00:00Z",
    "userId": 1,
    "whatsappId": 1,
    "queueId": 1
  }'

Use uma data futura e confira o fuso. Registre o ID retornado para consultar ou cancelar o agendamento.

6.2 Listar agendamentos

Rota: GET /api/messages/schedule

Os filtros contactId e userId são opcionais:

curl --get "$WASAP_URL/api/messages/schedule" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  --data-urlencode 'contactId=42' \
  --data-urlencode 'userId=1'

Para listar sem filtros, não inclua esses parâmetros.

6.3 Cancelar um agendamento

Rota: DELETE /api/messages/schedule/:id

curl -X DELETE "$WASAP_URL/api/messages/schedule/45" \
  -H "Authorization: Bearer $WASAP_TOKEN"

Somente agendamentos pendentes podem ser cancelados. Consulte o recurso antes da exclusão e confirme o ID; SCHEDULE_NOT_CANCELLABLE significa que o estado já não permite cancelamento.

7. Contatos

7.1 Listar e pesquisar

Rota: GET /api/contacts

Parâmetro	Tipo	Descrição
`searchParam`	string	Busca por nome ou número
`pageNumber`	integer	Página, iniciando em 1

curl --get "$WASAP_URL/api/contacts" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  --data-urlencode 'searchParam=João' \
  --data-urlencode 'pageNumber=1'

Resposta representativa:

{
  "contacts": [],
  "count": 120,
  "hasMore": true
}

7.2 Consultar pelo telefone

Rota: GET /api/contacts/:number

curl "$WASAP_URL/api/contacts/5511999999999" \
  -H "Authorization: Bearer $WASAP_TOKEN"

Resposta representativa:

{
  "id": 42,
  "name": "João",
  "number": "5511999999999",
  "tags": [],
  "advanceData": []
}

7.3 Criar ou sincronizar

Rota: POST /api/contacts

name e number são obrigatórios; email é opcional. A operação cria ou atualiza o contato e sincroniza os dados disponíveis.

curl -X POST "$WASAP_URL/api/contacts" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "João",
    "number": "5511999999999",
    "email": "[email protected]"
  }'

Resposta representativa:

{
  "id": 42,
  "name": "João",
  "number": "5511999999999"
}

7.4 Validar WhatsApp

Rota: GET /api/contacts/check/:number

curl "$WASAP_URL/api/contacts/check/5511999999999" \
  -H "Authorization: Bearer $WASAP_TOKEN"

Resposta representativa:

{
  "isValid": true,
  "number": "5511999999999",
  "remoteJid": "[email protected]"
}

Essa validação é útil antes de sincronizar um contato ou iniciar um envio. Trate isValid: false como um resultado de negócio, além de tratar eventuais erros HTTP.

8. Tarefas

8.1 Listar tarefas

Rota: GET /api/tasks

Todos os filtros são opcionais:

Filtro	Tipo	Descrição
`status`	string	Ex.: `pending`, `in_progress`, `done`
`searchParam`	string	Busca no título ou descrição
`pageNumber`	integer	Página, iniciando em 1
`columnId`	integer	Coluna do Kanban
`priority`	string	`low`, `medium` ou `high`
`queueId`	integer	Fila/setor
`assignedUserId`	integer	Usuário atribuído
`assignedToMe`	boolean	Limita às tarefas do dono do token
`contactId`	integer	Contato vinculado
`ticketId`	integer	Ticket vinculado

curl --get "$WASAP_URL/api/tasks" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  --data-urlencode 'status=pending' \
  --data-urlencode 'priority=high' \
  --data-urlencode 'pageNumber=1'

Resposta representativa:

{
  "tasks": [
    {"id": 1, "title": "Retornar contato", "status": "pending"}
  ],
  "count": 1,
  "hasMore": false
}

8.2 Consultar detalhes

Rota: GET /api/tasks/:taskId

curl "$WASAP_URL/api/tasks/1" \
  -H "Authorization: Bearer $WASAP_TOKEN"

A resposta detalhada pode incluir checklist e comentários, além dos campos básicos.

8.3 Criar tarefa

Rota: POST /api/tasks

title é obrigatório. Os demais campos devem ser incluídos apenas quando necessários:

curl -X POST "$WASAP_URL/api/tasks" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Retornar contato",
    "description": "Responder pelo WhatsApp",
    "status": "pending",
    "priority": "high",
    "dueDate": "2026-04-01T10:00:00Z",
    "contactId": 42,
    "ticketId": 10,
    "columnId": 2,
    "assignedUserIds": [1, 2],
    "queueIds": [1]
  }'

Resposta representativa:

{
  "id": 2,
  "title": "Retornar contato",
  "status": "pending"
}

8.4 Atualizar tarefa

Rota: PUT /api/tasks/:taskId

Envie somente os campos que pretende alterar:

curl -X PUT "$WASAP_URL/api/tasks/2" \
  -H "Authorization: Bearer $WASAP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Contato respondido","status":"done"}'

Não repita campos antigos sem necessidade, pois eles podem sobrescrever alterações feitas por outro processo.

8.5 Excluir tarefa

Rota: DELETE /api/tasks/:taskId

curl -X DELETE "$WASAP_URL/api/tasks/2" \
  -H "Authorization: Bearer $WASAP_TOKEN"

A exclusão é permanente. Consulte a tarefa e confirme seu ID antes de executar.

9. Exemplos em JavaScript e Python

As chamadas devem ser realizadas no servidor da sua aplicação, onde a API Key possa permanecer protegida. Não exponha o token em JavaScript executado no navegador, aplicativos distribuídos sem armazenamento seguro ou repositórios públicos.

9.1 JavaScript com `fetch`

Exemplo para runtimes com fetch nativo:

const baseUrl = process.env.WASAP_URL;
const token = process.env.WASAP_TOKEN;

const response = await fetch(`${baseUrl}/api/messages/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    number: '5511999999999',
    body: 'Olá pela API!',
    whatsappId: 1,
  }),
});

const result = await response.json().catch(() => null);
if (!response.ok) {
  throw new Error(`WaSap ${response.status}: ${JSON.stringify(result)}`);
}

console.log(result);

9.2 Python com `requests`

import os
import requests

base_url = os.environ["WASAP_URL"]
token = os.environ["WASAP_TOKEN"]

response = requests.get(
    f"{base_url}/api/contacts",
    headers={"Authorization": f"Bearer {token}"},
    params={"searchParam": "João", "pageNumber": 1},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Sempre defina timeout no cliente HTTP e trate separadamente falhas de rede, respostas não JSON e status HTTP sem sucesso.

10. Erros e tentativas

Formato defensivo representativo (os campos podem variar conforme a instalação):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Um ou mais campos enviados são inválidos.",
    "details": {}
  },
  "requestId": "request-id"
}

HTTP	Código	Causa provável	Ação
400	`VALIDATION_ERROR`	Campo ausente ou inválido	Corrigir o payload; não repetir sem alteração
400	`INVALID_NUMBER`	Formato do telefone inválido	Enviar somente dígitos com DDI e DDD
400	`WHATSAPP_NUMBER_INVALID`	Número sem conta ativa	Verificar o telefone pelo endpoint `check`
400	`MESSAGE_SEND_FAILED`	Falha no envio	Conferir conexão e dados; repetir com cautela
400	`SCHEDULE_NOT_CANCELLABLE`	Agendamento não está pendente	Consultar o estado atual
401	`UNAUTHORIZED`	Chave inválida/expirada/desativada	Corrigir ou renovar a chave
403	`INSUFFICIENT_SCOPE`	Escopo ausente	Conceder `error.details.requiredScope`
403	`FORBIDDEN`	Recurso não autorizado	Conferir escopo e propriedade do recurso
404	`CONTACT_NOT_FOUND`	Contato não localizado	Conferir número/contexto
404	`WHATSAPP_NOT_FOUND`	Conexão não localizada	Conferir `whatsappId` e conexão
404	`SCHEDULE_NOT_FOUND`	Agendamento não localizado	Conferir ID
404	`TASK_NOT_FOUND`	Tarefa não localizada	Conferir ID
500	`INTERNAL_ERROR`	Falha inesperada no servidor	Guardar `requestId` e tentar com backoff

Política de retry recomendada

Não repita automaticamente erros 400, 401, 403 ou 404; eles normalmente exigem correção ou mudança de estado.
Em falhas temporárias de rede e respostas 5xx, faça poucas tentativas com backoff exponencial e jitter, por exemplo 1 s, 2 s e 4 s.
Respeite um eventual cabeçalho Retry-After.
Tenha cuidado ao repetir operações POST: sem garantia de idempotência, uma resposta perdida pode resultar em mensagem ou tarefa duplicada.
Registre requestId, método, rota, status e horário UTC, mas nunca o token ou o corpo completo com dados pessoais.

11. Boas práticas de produção

Menor privilégio: crie chaves apenas com os escopos necessários.
Segredos: use cofre de segredos ou credenciais protegidas e faça rotação periódica.
Validação: normalize telefones e valide payloads antes da chamada.
Timeout: configure limites de conexão e leitura em todos os clientes.
Observabilidade: registre status, latência, rota e requestId, ocultando dados sensíveis.
Paginação: percorra páginas respeitando hasMore, sem criar loops ilimitados.
Concorrência: evite que dois processos atualizem a mesma tarefa sem coordenação.
Exclusões: consulte e confirme recurso/estado antes de qualquer DELETE.
Dados pessoais: retenha apenas o necessário e aplique as políticas de privacidade da organização.
Ambientes: mantenha tokens, URLs e IDs de teste separados dos de produção.

12. Solução de problemas

A URL retorna 404 em todas as rotas

Confirme o domínio da instalação.
Remova a barra final de WASAP_URL para evitar //api/....
Confirme que a rota começa com /api.

A API retorna 401

Confira se o cabeçalho é exatamente Authorization: Bearer TOKEN.
Não duplique o prefixo (Bearer Bearer ...).
Verifique expiração, desativação e ambiente da chave.

A API retorna 403

Leia error.details.requiredScope.
Confirme se a chave pode acessar a conexão, contato, tarefa ou fila informada.

O número é recusado

Remova +, espaços, parênteses e hífens.
Inclua DDI e DDD.
Consulte /api/contacts/check/:number antes do envio.

A data ocorre no horário errado

Envie Z para UTC ou offset explícito.
Converta a data no sistema de origem antes de montar o JSON.

A mídia não chega

Confirme que a requisição é multipart e que o campo se chama medias.
Envie o conteúdo binário real do arquivo.
Confirme que sua biblioteca HTTP está enviando o arquivo como conteúdo binário no campo medias.
Verifique limites e formatos aceitos pela instalação.

Checklist final de diagnóstico

URL e rota estão corretas?
O token pertence ao ambiente correto e tem o escopo exigido?
O telefone contém apenas dígitos com DDI e DDD?
IDs e tipos JSON estão corretos?
Campos opcionais vazios foram removidos?
Datas contêm fuso horário?
O requestId foi preservado para suporte?

Os exemplos de respostas são representativos. Campos adicionais, limites operacionais e regras específicas podem variar conforme a versão e a configuração do sistema WaSap.

API do WaSap

Sumário

1. Pré-requisitos

2. Configuração e autenticação

3. Convenções

3.1 Telefones

3.2 Datas e horários

3.3 IDs, booleanos e arrays

3.4 Campos opcionais e paginação

4. Referência rápida

5. Mensagens

5.1 Enviar texto

5.2 Enviar mídia

6. Agendamentos

6.1 Agendar uma mensagem

6.2 Listar agendamentos

6.3 Cancelar um agendamento

7. Contatos

7.1 Listar e pesquisar

7.2 Consultar pelo telefone

7.3 Criar ou sincronizar

7.4 Validar WhatsApp

8. Tarefas

8.1 Listar tarefas

8.2 Consultar detalhes

8.3 Criar tarefa

8.4 Atualizar tarefa

8.5 Excluir tarefa

9. Exemplos em JavaScript e Python

9.1 JavaScript com fetch

9.2 Python com requests

10. Erros e tentativas

Política de retry recomendada

11. Boas práticas de produção

12. Solução de problemas

A URL retorna 404 em todas as rotas

A API retorna 401

A API retorna 403

O número é recusado

A data ocorre no horário errado

A mídia não chega

Checklist final de diagnóstico

9.1 JavaScript com `fetch`

9.2 Python com `requests`