HubOficial API v1 Produção

Documentação da API — HubOficial

Envie templates de WhatsApp Business aprovados oficialmente diretamente via API REST — sem intermediários, com maior estabilidade e limites de envio mais altos. Suporte a variáveis, imagens, documentos, botões de URL e links dinâmicos de cobrança.

Endpoint de Envio

https://softpower.net.br/jov_whatsapp/api_huboficial/mensagem

Autenticação

Bearer Token (clientToken)

Formato

JSON

Esta página é pública e usa dados fictícios — token, UUID de instância e templates abaixo são apenas exemplos ilustrativos. Para pegar seu token real e o UUID da sua instância, acesse o painel logado em Serviços → HubOficial → API.

Diferença para o JovEnvios Qrcode: aqui você não manda texto livre — toda mensagem usa um template pré-aprovado oficialmente (criado e aprovado no painel de templates e sincronizado no painel). Você só informa o nome do template e preenche as variáveis/botões dele.

Autenticação

Toda requisição precisa do seu clientToken, via header ou no corpo.

Via Header (recomendado)

Authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Content-Type: application/json

Via Body JSON

{ "token": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" }

POST /mensagem

Envia um template WhatsApp aprovado para um destinatário.

https://softpower.net.br/jov_whatsapp/api_huboficial/mensagem

Use sempre a URL completa acima, terminando em /mensagem. Chamar apenas a base (sem /mensagem) não corresponde a nenhuma rota e retorna erro.

Campo	Tipo	Obrig.	Descrição
`uuid`	string	sim	UUID da instância (WABA) conectada no painel
`destinatario`	string	sim	Número com DDI, ex: `5511999998888`
`mensagem.template.nome`	string	sim	Nome do template aprovado (sincronizado do canal oficial)
`mensagem.template.idioma`	string	não	Padrão: `pt_BR`
`mensagem.metadados.variaveis`	array	não	Valores para `{{1}}`, `{{2}}`... do corpo do template, na ordem
`mensagem.metadados.url_header`	string	não	URL pública de imagem/documento/vídeo, se o template tiver header de mídia
`mensagem.metadados.botoes`	array	não	Valores para os botões de URL dinâmica do template, na ordem
`mensagem.metadados.dados_cobranca`	object	não	Dados de cobrança para templates de PIX/boleto (ver seção específica)

JSON — Exemplo (template simples com 1 variável)

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "lembrete_vencimento", "idioma": "pt_BR" },
    "metadados": { "variaveis": ["Nome Exemplo", "R$ XXX,XX", "XX/XX/XXXX"] }
  }
}

cURL

curl -s -X POST "https://softpower.net.br/jov_whatsapp/api_huboficial/mensagem" \
     -H "Authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" \
     -H "Content-Type: application/json" \
     -d '{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "lembrete_vencimento", "idioma": "pt_BR" },
    "metadados": { "variaveis": ["Nome Exemplo", "R$ XXX,XX", "XX/XX/XXXX"] }
  }
}'

Resposta — 200 OK

{
  "ok": true,
  "codigo": "200",
  "token_envio": "XXXXXXXXXXXXXXXX",
  "wamid": "wamid.XXXXXXXXXXXXXXXXXXXXX",
  "message": "Enviado"
}

Diferente do JovEnvios Qrcode, o envio aqui é síncrono: a chamada já retorna o resultado real do canal oficial (sucesso ou erro), sem precisar consultar status separadamente na maioria dos casos.

Com variáveis no corpo

Substitua {{1}}, {{2}}... do template pelas variáveis do array (índice 0 = {{1}}).

JSON

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "lembrete_vencimento", "idioma": "pt_BR" },
    "metadados": { "variaveis": ["Nome Exemplo", "R$ XXX,XX", "XX/XX/XXXX"] }
  }
}

Com imagem no header

Templates com HEADER de imagem aceitam uma URL pública para a foto.

JSON

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "promocao_banner", "idioma": "pt_BR" },
    "metadados": {
      "url_header": "https://exemplo.com.br/banner.jpg",
      "variaveis": ["30% OFF"]
    }
  }
}

A imagem precisa ser acessível publicamente (URL https). Formatos: JPG, PNG, WEBP. Máximo 5 MB.

Com documento (PDF)

Templates com HEADER de documento — ideal para boletos, contratos e faturas.

JSON

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "fatura_pdf", "idioma": "pt_BR" },
    "metadados": {
      "url_header": "https://seusite.com.br/exemplo-fatura.pdf",
      "variaveis": ["Nome Exemplo", "R$ XXX,XX"]
    }
  }
}

Botões de URL dinâmica

Templates com botão tipo URL — passe a parte variável da URL (sufixo, ou a URL completa) no array botoes.

JSON

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "segunda_via_link", "idioma": "pt_BR" },
    "metadados": {
      "variaveis": ["Nome Exemplo", "R$ XXX,XX", "XX/XX/XXXX"],
      "botoes": ["https://seusite.com.br/pagamento/XXXXX"]
    }
  }
}

Cada item do array botoes corresponde a um botão URL do template, na mesma ordem em que foram criados no template oficial.

Envio com dados de cobrança

Para templates de cobrança com PIX, boleto e link de pagamento — passe o objeto dados_cobranca.

JSON

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "lembrete_com_pdf", "idioma": "pt_BR" },
    "metadados": {
      "variaveis": ["Nome Exemplo", "R$ XXX,XX", "XX/XX/XXXX"],
      "usa_link_cobranca": true,
      "dados_cobranca": {
        "jov_bank_id_fatura": "XXXXX",
        "jov_bank_pix": "000201XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "jov_bank_boleto": "XXXXX.XXXXX XXXXX.XXXXXX...",
        "jov_bank_cliente": "Nome Exemplo",
        "jov_bank_vencimento": "XX/XX/XXXX",
        "jov_bank_valor": "XXX.XX",
        "jov_bank_boleto_url": "https://boleto.exemplo.com.br/12345"
      }
    }
  }
}

Campo	Descrição
`jov_bank_id_fatura`	ID da fatura no sistema de origem
`jov_bank_pix`	Código PIX copia e cola
`jov_bank_boleto`	Linha digitável do boleto
`jov_bank_cliente`	Nome do cliente
`jov_bank_vencimento`	Data de vencimento (DD/MM/AAAA)
`jov_bank_valor`	Valor em decimal, ex: `"XXX.XX"`
`jov_bank_boleto_url`	URL do boleto/PDF — usada no botão URL do template

GET /status

Consulta o resultado de um envio pelo token_envio retornado na resposta do POST.

https://softpower.net.br/jov_whatsapp/api_huboficial/status?token_envio={TOKEN_ENVIO}

cURL

curl -s "https://softpower.net.br/jov_whatsapp/api_huboficial/status?token_envio=XXXXXXXXXXXXXXXX" \
     -H "Authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Resposta — 200 OK

{
  "ok": true,
  "data": {
    "status_resultado": "ok",
    "template_nome": "lembrete_vencimento",
    "destinatario": "55XXXXXXXXXXX",
    "wamid": "wamid.XXXXXXXXXXXXXXXXXXXXX",
    "created_at": "2026-07-16 14:32:01"
  }
}

GET /get_templates

Lista os templates sincronizados de uma instância. Filtre por status, categoria ou nome.

⚠️ Erros comuns

Use GET (não POST)
URL correta: /api_huboficial/get_templates — não confundir com /mensagem/templates
O uuid vai na query string, não no header
O token de autenticação é o clientToken do painel, não o UUID da instância

https://softpower.net.br/jov_whatsapp/api_huboficial/get_templates?uuid={UUID_DA_INSTANCIA}

Parâmetro	Tipo	Obrig.	Descrição
`uuid`	string	sim	UUID da instância
`status`	string	não	`APPROVED`, `PENDING` ou `REJECTED`
`categoria`	string	não	`MARKETING`, `UTILITY` ou `AUTHENTICATION`
`nome`	string	não	Busca parcial pelo nome do template

cURL — Somente aprovados de MARKETING

curl -s "https://softpower.net.br/jov_whatsapp/api_huboficial/get_templates?uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&status=APPROVED&categoria=MARKETING" \
     -H "Authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Resposta — 200 OK

{
  "ok": true,
  "templates": [
    {
      "nome": "lembrete_vencimento",
      "categoria": "UTILITY",
      "idioma": "pt_BR",
      "status": "APPROVED",
      "componentes": [
        { "type": "BODY", "text": "Olá {{1}}, sua fatura de {{2}} vence em {{3}}." }
      ]
    }
  ]
}

Códigos de retorno

HTTP	Quando ocorre
`200`	Mensagem enviada com sucesso pelo canal oficial
`400`	Campo obrigatório ausente (`uuid`, `destinatario` ou `template.nome`)
`401`	Token ausente ou inválido
`402`	Assinatura/fatura pendente — envios bloqueados até regularização
`403`	UUID não encontrado ou não pertence a este cliente
`405`	Método HTTP incorreto (use POST em /mensagem, GET em /status e /get_templates)
`422`	Template não encontrado — sincronize os templates no painel

Exemplo — Erro (template não encontrado)

{
  "ok": false,
  "codigo": "422",
  "message": "Template \"lembrete_vencimento\" não encontrado. Vá em HubOficial → Templates → Sincronizar."
}

JOV WhatsApp — Documentação pública · dados fictícios para fins de exemplo