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)
Usado para criar, listar, obter detalhes, conectar e deletar instâncias. Forneça o token como credencial Bearer no header Authorization de suas requisições.
2. Token de Instância
Usado exclusivamente em operações de envio de mensagens do WhatsApp e obtenção de QR code específicos da instância. 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 (Token de Empresa/Instância incorreto). |
| 403 Forbidden | Autorização rejeitada devido a regras de firewall de IP/domínio. |
| 404 Not Found | O recurso solicitado não pôde ser encontrado. |
| 422 Unprocessable | Falha de validação dos parâmetros de entrada. |
| 500 Server Error | Erro inesperado no servidor do ZapFácil. |