Introdução
Bem-vindo à referência oficial da API do ZapFácil. Nossa API permite integrar fluxos de comunicação do WhatsApp diretamente em seus sistemas, ERPs e aplicações, automatizando o envio e recebimento de mensagens através de conexões estáveis.
Painel de Controle vs. Integração via API
Se o seu objetivo é apenas conectar a sua conta do WhatsApp de forma visual via QR Code, você pode fazer isso de maneira simples no Painel de Controle (Dashboard) do ZapFácil. A API é indicada para:
- Envio e Recepção (Para qualquer usuário): Automatizar os disparos de mensagens (como textos, áudios e marcação de leitura) e receber eventos de mensagens recebidas ou conexões em tempo real no seu servidor.
- Gestão de Múltiplos Clientes (Endpoints de Instâncias e Empresas): Criar, listar, atualizar ou deletar instâncias programaticamente. Essa parte da API é voltada para desenvolvedores e plataformas SaaS (por exemplo, um SaaS de delivery que precisa criar uma nova instância de forma automática para um novo restaurante parceiro assim que ele se cadastrar no sistema).
Base URL
Todas as requisições à nossa API devem ser feitas usando o seguinte endereço base:
Autenticação
A API do ZapFácil possui dois níveis de segurança dependendo do tipo de recurso acessado:
1. Token de Empresa (Bearer) — Obrigatório em todas as rotas
Identifica e autentica a sua empresa em todas as chamadas à API (tanto na gestão de instâncias quanto nas operações do WhatsApp). Forneça o token como credencial Bearer no header Authorization.
2. Token de Instância — Adicional nas Operações WhatsApp
Exigido em conjunto com o Authorization: Bearer nas rotas de operação de uma instância específica do WhatsApp (como send-text, send-image e mark-read). Forneça o token correspondente à instância no header X-Instance-Token.
Versionamento da API
A API do ZapFácil utiliza um sistema de versionamento baseado em datas (ex: 2026-04-09) para garantir a compatibilidade e estabilidade das suas integrações, permitindo que você atualize sua aplicação no seu próprio ritmo.
Como especificar a versão
Existem duas formas principais de definir qual versão da API sua requisição deve utilizar:
Cabeçalho X-ZapFacil-Version
Você pode enviar explicitamente a versão desejada no cabeçalho X-ZapFacil-Version de cada requisição. Isso garante que a requisição seja processada sob a estrutura daquela data específica, independente de qualquer configuração padrão.
Configuração de Perfil / Painel
Caso o cabeçalho X-ZapFacil-Version não seja enviado, a API utilizará automaticamente a versão que você pinou (definiu) na configuração do seu usuário diretamente no Painel de Controle. Se nenhuma versão estiver pinada em sua conta, o sistema utilizará a versão estável padrão atual (2026-04-09).
Formato de Resposta
Todos os endpoints retornam JSON com a mesma estrutura:
Resposta Padrão
{
"data": { ... } | null,
"success": true,
"error": null
}Em caso de erro:
{
"data": null,
"success": false,
"error": "Mensagem descritiva do erro"
}success antes de acessar data. Nunca assuma que a requisição funcionou apenas pelo status HTTP.
Status HTTP
A API do ZapFácil utiliza códigos de status HTTP convencionais para indicar o sucesso ou falha de uma requisição de API.
| Código | Descrição |
|---|---|
| 200 OK | A requisição foi bem-sucedida e retornou o conteúdo solicitado. |
| 400 Bad Request | Parâmetros inválidos ou ausentes na requisição. |
| 401 Unauthorized | Autenticação ausente ou inválida (Header Authorization: Bearer inválido ou X-Instance-Token ausente). |
| 402 Payment Required | Conta ou instância bloqueada devido a pendências de faturamento/assinatura. |
| 403 Forbidden | Acesso negado por regras de firewall (IP/domínio/protocolo), X-Instance-Token inválido para a instância informada ou limite de instâncias do plano atingido. |
| 404 Not Found | O recurso ou instância solicitada não pôde ser encontrada. |
| 412 Precondition Failed | A instância não está conectada (CONNECTED) no WhatsApp para realizar a operação solicitada. |
| 422 Unprocessable | Falha de validação dos parâmetros enviados no corpo da requisição. |
| 429 Too Many Requests | Limite diário de mensagens do plano atingido ou excesso de requisições no período. |
| 500 Server Error | Erro inesperado no servidor do ZapFácil. |