SOFTG API WhatsApp

Não é a API oficial da Meta (WhatsApp Business Cloud). A conexão funciona como o WhatsApp Web: o celular do cliente precisa ter internet de tempos em tempos para a sessão continuar ativa.

Integrar um cliente (equipe SoftG)

1. Criar a conexão no painel /administrador → Dispositivos → Criar dispositivo (nome do cliente, CNPJ e limite de envios por minuto).
2. Conectar o número: Conectar WhatsApp no card do dispositivo, por QR Code ou código de pareamento — ou pelo próprio ERP, com a rota instance/connect.
3. Entregar as credenciais: na aba APIs, copie a URL base, a instância e o token. Use Testar credenciais para conferir.
4. Configurar o ERP do cliente com esses três valores (seção Usar no SOFTG ERP).
5. Acompanhar no Painel: status do número, mensagens enviadas, bloqueio e troca de token.

Autenticação

Toda requisição leva o token da conexão no cabeçalho apikey. O token só opera a própria instância.

Teste rápido — GET /v1

200 OK
{ "ok": true, "instancia": "cli_borges_distribuidora_7f3a", "cliente": "Borges Distribuidora", "estado": "open" }

Conectar o WhatsApp

Uma vez por número. Estados possíveis: open (conectado), connecting (aguardando leitura do QR ou reconectando) e close (desconectado).

Estado da conexão — GET /v1/instance/connectionState/{instancia}

200 OK
{ "instancia": "cli_borges_distribuidora_7f3a", "estado": "open", "telefone": "5563984045945" }

QR Code ou código de pareamento — GET /v1/instance/connect/{instancia}

Devolve o QR Code em base64 (PNG pronto para <img src>), que vence em cerca de 30 s. Chame de novo a cada 20 s até estado virar open. Com ?number=5563999999999, devolve um código de 8 letras para digitar no celular, em Aparelhos conectados → Conectar com número de telefone.

200 OK
{ "estado": "connecting", "base64": "data:image/png;base64,iVBORw0KGgo...", "code": "2@...", "expiraEm": "2026-10-31T15:04:30.000Z" }

// com ?number=5563999999999
{ "estado": "connecting", "pairingCode": "ABCD-1234" }

// já conectado
{ "estado": "open" }

Fluxo típico no sistema: mostrar o QR → repetir a chamada a cada 20 s → quando vier {"estado": "open"}, fechar a tela.

Reiniciar — POST /v1/instance/restart/{instancia}

Reabre a conexão sem apagar a sessão (útil se o status ficou parado).

Desconectar — DELETE /v1/instance/logout/{instancia}

Encerra a sessão no WhatsApp. Para voltar é preciso ler um novo QR Code.

Enviar mensagens

Todas as rotas de envio são POST com corpo JSON. O campo number é DDI + DDD + número; máscaras como +55 (63) 98404-5945 são aceitas. O servidor descobre se o número existe com ou sem o 9º dígito e envia para a forma certa. A resposta 201 sai quando o WhatsApp aceita a mensagem; guarde o id para consultar entrega e leitura.

Texto — POST /v1/message/sendText/{instancia}

201 Created
{ "id": "0f8c3a52-6c1e-4b8e-9a51-2a1d3f7c9e10", "whatsappId": "3EB0A1B2C3D4E5F6", "status": "ENVIADA", "destino": "5563999999999", "criadoEm": "2026-10-31T15:04:12.000Z" }

PDF, imagem, vídeo e documentos — POST /v1/message/sendMedia/{instancia}

Aceitos: PDF, XML, TXT, CSV, DOCX, XLSX, ZIP, JPEG, PNG, GIF, WEBP, MP4 e MOV, até 25 MB. O servidor confere a assinatura do arquivo: o mimetype precisa corresponder ao conteúdo.

Áudio (nota de voz) — POST /v1/message/sendWhatsAppAudio/{instancia}

audio: URL https ou base64 de OGG/Opus, MP3, M4A ou WAV. Chega como mensagem de voz.

Localização — POST /v1/message/sendLocation/{instancia}

Verificar números — POST /v1/chat/whatsappNumbers/{instancia}

Confere até 50 números por chamada antes de enviar. jid mostra a forma que existe no WhatsApp (com ou sem o 9º dígito).

200 OK
[ { "numero": "5563984045945", "existe": true, "jid": "556384045945@s.whatsapp.net" },
  { "numero": "5511999999999", "existe": false, "jid": null } ]

Status da mensagem — GET /v1/message/status/{instancia}/{id}

ENVIADA (aceita pelo WhatsApp) → ENTREGUE (chegou no celular) → LIDA. FALHOU quando o WhatsApp recusou. O status só avança; se o celular do destinatário estiver sem internet, fica em ENVIADA até ele conectar.

200 OK
{ "id": "0f8c3a52-...", "status": "LIDA", "criadoEm": "2026-10-31T15:04:12.000Z", "entregueEm": "2026-10-31T15:04:13.000Z", "lidaEm": "2026-10-31T15:06:40.000Z", "erro": null }

Idempotência — envio seguro de repetir

Se a rede cair no meio do envio, o ERP não sabe se a mensagem saiu. Envie o cabeçalho Idempotency-Key com um valor estável por operação (ex.: danfe-000123, de 8 a 150 caracteres A-Z a-z 0-9 . _ : -) e repita a chamada com a mesma chave:

• Envio já concluído: a resposta é a mesma (mesmo id), sem enviar de novo, por 24 h.
• Primeiro envio ainda em andamento, ou mesma chave com outro conteúdo: 409 IDEMPOTENCIA_CONFLITO.
• Envio que falhou: a chave é liberada e pode ser repetida.

Erros e limites

Formato: {"erro": "mensagem em português", "codigo": "CODIGO"}; em validação vem também campos com o problema de cada campo.

Limites

• Por conexão: 20 envios por minuto (padrão, ajustável pela SoftG).
• Por IP: 300 requisições por minuto.
• Arquivos: 25 MB.

Usar no SOFTG ERP (VB.NET)

A classe SoftGWhatsAppClient funciona no .NET Framework 4.8, sem pacotes NuGet (usa System.Net.Http, System.Web.Extensions e System.Drawing).

⬇ Baixar SoftGWhatsAppClient.vb

Configuração

SoftGWhatsApp.UrlBase=https://api.whats.softgempresarialsistemas.com.br/v1
SoftGWhatsApp.Instancia=cli_borges_distribuidora_7f3a
SoftGWhatsApp.Token=sgw_...

Enviar a DANFE ao faturar

Imports SoftG.WhatsApp

Private ReadOnly _whats As New SoftGWhatsAppClient(Config.UrlBase, Config.Instancia, Config.Token)

Private Async Sub btnEnviarDanfe_Click(sender As Object, e As EventArgs) Handles btnEnviarDanfe.Click
    btnEnviarDanfe.Enabled = False
    Try
        ' Chave estável por nota: repetir após falha de rede não envia duas vezes.
        Dim envio = Await _whats.EnviarArquivoAsync(txtCelular.Text, caminhoPdf, "Segue sua nota fiscal " & numeroNota & ".", "danfe-" & numeroNota)
        MessageBox.Show("DANFE enviada. Id: " & envio.Id)
    Catch ex As SoftGWhatsAppException When ex.Codigo = "WHATSAPP_DESCONECTADO"
        MessageBox.Show("O WhatsApp da empresa está desconectado. Conecte em Configurações → WhatsApp.")
    Catch ex As SoftGWhatsAppException When ex.Codigo = "NUMERO_SEM_WHATSAPP"
        MessageBox.Show("Este cliente não tem WhatsApp neste número.")
    Catch ex As SoftGWhatsAppException
        MessageBox.Show("Envio recusado: " & ex.Message)
    Finally
        btnEnviarDanfe.Enabled = True
    End Try
End Sub

Tela de conexão por QR Code

' Timer de 20 s: atualiza o QR até conectar.
Private Async Sub tmrQr_Tick(sender As Object, e As EventArgs) Handles tmrQr.Tick
    Dim conexao = Await _whats.ConectarQrAsync()
    If conexao.Estado = "open" Then
        tmrQr.Stop()
        lblStatus.Text = "WhatsApp conectado!"
    ElseIf conexao.QrCodeImagem IsNot Nothing Then
        picQrCode.Image = conexao.QrCodeImagem
    End If
End Sub

Use Async Sub só em manipuladores de evento; nunca chame .Result ou .Wait() na thread da interface.

Boas práticas

• Sem disparo em massa: envie mensagens esperadas pelo cliente (nota, boleto, aviso de pedido). Volume alto para quem não espera leva a bloqueio do número pelo WhatsApp.
• Número novo: comece com poucos envios por dia e aumente aos poucos.
• Celular com internet: a sessão pode cair se o celular ficar muitos dias sem conexão.
• Token protegido: guarde o token na configuração protegida do ERP, nunca no código-fonte nem em planilhas.
• Idempotency-Key em todo envio que o sistema possa repetir.
• Respeite o 429: aguarde o Retry-After antes de tentar de novo.

Solução de problemas

409 WHATSAPP_DESCONECTADO

O número saiu da conexão (desconectado pelo celular, sem internet por muito tempo ou bloqueado). Gere um novo QR Code e leia pelo WhatsApp do cliente. Nada foi enviado.

A mensagem não chega e o número não tem o 9º dígito

Envie normalmente com o 9: o servidor confere as duas formas e usa a que existe. Para conferir antes, use Verificar números.

401 TOKEN_INVALIDO depois de funcionar

O token foi trocado no painel ou a conexão foi excluída. Peça à SoftG o token atual e atualize a configuração do ERP.

403 CONEXAO_BLOQUEADA

A conexão foi bloqueada pela SoftG. Entre em contato com o suporte.

Status parado em ENVIADA

O celular do destinatário está sem internet ou desligado; o status muda para ENTREGUE quando ele conectar.

422 MIDIA_INVALIDA com PDF

Confira se o mimetype é application/pdf e se o base64 é do arquivo inteiro, sem o prefixo de outro tipo.

SOFTG Empresarial Sistemas · Suporte: tecnologia@softgempresarial.com.br