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://sejajov.com.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" }

Testador Interativo

Cole seu clientToken e o UUID da sua instância pra buscar seus templates reais, preencher os campos e gerar o cURL — ou executar o envio direto por aqui.

Seu clientToken

UUID da instância

Essa página é pública — seu token nunca é enviado pra nós nem salvo em lugar nenhum, ele só fica no seu navegador e vai direto pra API na hora de buscar templates/executar. Mesmo assim, evite testar com destinatários reais fora de um teste controlado.

POST /mensagem

Envia um template WhatsApp aprovado para um destinatário.

https://sejajov.com.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 — pra Pix, use o gerador de recibo em vez de QR cru: ver seção abaixo
`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)
`mensagem.metadados.pix_code`	string	condicional	Obrigatório se o template tiver botão de pagamento Pix (copia-e-cola / BR Code)
`mensagem.metadados.boleto_linha_digitavel`	string	condicional	Obrigatório se o template tiver botão de pagamento Boleto
`mensagem.metadados.payment_link`	string	condicional	Obrigatório se o template tiver botão "Open payment link"
`mensagem.metadados.valor_pagamento`	string	não	Só enriquece o log interno — não é usado no envio (o Chatwoot resolve o valor do próprio lado dele). Ex: `"12.96"`
`mensagem.metadados.item_nome`	string	não	Nome do item exibido no botão de pagamento (padrão: "Fatura")

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://sejajov.com.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.

Templates com botão de pagamento (PIX / Boleto / Link)

Pra templates com botão de pagamento (tipo PAYMENT_REQUEST na Meta), passe os campos direto em metadados — um por tipo de botão que o template tiver.

JSON

{
  "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "destinatario": "55XXXXXXXXXXX",
  "mensagem": {
    "template": { "nome": "jov_fatura_proximo_vencimento", "idioma": "pt_BR" },
    "metadados": {
      "variaveis": ["Nome Exemplo", "R$ XXX,XX", "XX/XX/XXXX"],
      "url_header": "https://sejajov.com.br/jov_whatsapp/recibo_pix/imagem?codigopix=000201...&valor=R$ XXX,XX&vencimento=XX/XX/XXXX",
      "pix_code": "000201XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "boleto_linha_digitavel": "XXXXX.XXXXX XXXXX.XXXXXX...",
      "payment_link": "https://exemplo.com.br/cobranca/12345"
    }
  }
}

Campo	Obrigatório quando...
`pix_code`	O template tem um botão de pagamento Pix (copia-e-cola / BR Code)
`boleto_linha_digitavel`	O template tem um botão de pagamento Boleto
`payment_link`	O template tem um botão "Open payment link"
`url_header`	O template tem header de imagem — use o gerador de recibo abaixo em vez de um QR cru

Use GET /get_templates pra ver exatamente quais botões de pagamento cada template tem — o campo campo_metadados_esperado de cada botão já diz qual desses campos preencher.

Recibo Pix com o layout JOV

Em vez de gerar um QR code cru pra usar como url_header, use o gerador de recibo próprio (cabeçalho, QR com a marca no centro, valor, vencimento, selo de segurança):

GET

https://sejajov.com.br/jov_whatsapp/recibo_pix/imagem?codigopix={pix_copia_cola}&valor={valor}&vencimento={vencimento}

Link de cobrança em botão URL (mecanismo separado)

Pra templates com um botão URL comum (não pagamento) que precisa de um link dinâmico de cobrança, use usa_link_cobranca + dados_cobranca.jov_bank_boleto_url:

JSON

{
  "metadados": {
    "usa_link_cobranca": true,
    "dados_cobranca": {
      "jov_bank_boleto_url": "https://boleto.exemplo.com.br/12345"
    }
  }
}

GET /status

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

https://sejajov.com.br/jov_whatsapp/api_huboficial/status?token_envio={TOKEN_ENVIO}

cURL

curl -s "https://sejajov.com.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://sejajov.com.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://sejajov.com.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