Documentação da API

A API da plataforma, para o seu sistema

Confirmação de pedido, código de acesso, aviso de entrega e cobrança saindo direto do seu ERP, site ou aplicativo. Simples de propósito: quatro chamadas resolvem o dia a dia.

Baixar em PDF Gerar a minha chave no painel

1 · Autenticação

Tudo passa pela chave da conta, gerada no painel em Integração › API › Nova chave. A chave aparece uma única vez: guarde no cofre de segredos do seu sistema, nunca dentro de página, aplicativo de celular ou repositório.

Authorization: Bearer SUA_CHAVE
Content-Type: application/json

Endereço base: https://oficial.inovawebplus.com.br/api/v1

O que a chave não faz, de propósito

A chave é para mensagem transacional: uma pessoa, um evento, uma mensagem. Ela tem teto de 240 chamadas por minuto e devolve 429 quando passa. Campanha em massa é pela plataforma, onde existem ritmo por número, parada de conferência, descadastro e pausa automática de qualidade. Um laço de repetição no seu sistema, sem isso, derruba a nota do número em uma tarde.

2 · Enviar mensagem de modelo

POST/api/v1/mensagens

Manda um modelo aprovado para um telefone. Funciona com a janela fechada, porque modelo aprovado pode sempre.

{
  "para": "5588999998888",
  "modelo": "confirmacao_pedido",
  "idioma": "pt_BR",
  "variaveis": ["Maria", "1042", "18h"],
  "referencia": "pedido-1042"
}

Campo	Obrigatório	O que é
para	sim	Telefone com DDI e DDD, só números: `5588999998888`
modelo	sim	Nome do modelo aprovado, em minúsculas com sublinhado. A lista vem de `GET /modelos`
idioma	não	Padrão `pt_BR`
variaveis	se o modelo tem	Lista na ordem (`["Maria","1042"]`) ou objeto por nome (`{"nome":"Maria","pedido":"1042"}`) quando o modelo veio do catálogo
variaveis_cabecalho	se o cabeçalho tem	Mesmo formato, para a variável do cabeçalho
codigo	modelos de autenticação	O código de acesso, até 15 letras e números. Vai no corpo e no botão de copiar
cards	modelos de carrossel	Um item por cartão: `{"imagem_url":"…","link":"…","resposta":"…"}`. A quantidade tem que bater com a do modelo
referencia	recomendado	Um texto seu (até 80 caracteres). Se repetir em 24 h, nada é enviado de novo e a resposta devolve o envio original. É o que evita cobrança duplicada
agendar_para	não	Data ISO (`2026-09-10T14:00:00-03:00`) para enviar depois, até um ano
numero_id / de	não	Qual dos seus números envia. Sem informar, vai o primeiro ativo

Respostas

201  { "ok": true, "id": 123, "situacao": "enviada", "wamid": "wamid.XXX", "categoria": "utilidade" }
202  { "ok": true, "id": 124, "situacao": "agendada", "agendada_para": "2026-09-10T17:00:00.000Z" }
200  { "ok": true, "repetida": true, "id": 123, "aviso": "Ja existia um envio com esta referencia…" }

3 · Responder com texto livre

POST/api/v1/mensagens/texto

Texto sem modelo, até 4096 caracteres. Só funciona com a janela de 24 horas aberta, ou seja, quando a pessoa escreveu para você nas últimas 24 horas. Fora dela a API devolve 409 e o caminho é o modelo aprovado.

{ "para": "5588999998888", "texto": "Seu pedido saiu para entrega." }

Atenção ao custo a partir de outubro

Em 1º de outubro de 2026 cada mensagem dessas passa a ser cobrada pela Meta no preço de utilidade. Responda completo em uma mensagem em vez de cinco curtas.

3A · Código de acesso (OTP) em uma chamada

POST/api/v1/otp

Acha sozinho o modelo de autenticação aprovado da conta e manda o código no corpo e no botão de copiar. Para escolher o modelo, mande "modelo".

{ "para": "5588999998888", "codigo": "482913", "referencia": "login-9912" }

O código aceita até 15 letras e números. A resposta é a mesma do envio de modelo.

3B · Pedir um modelo novo

POST/api/v1/modelos

O modelo não vai direto para a Meta: entra na revisão da Inova Web Plus. Aprovado aqui, segue para a Meta sozinho. Assim todo modelo que sai pela plataforma tem dono, data e quem aprovou. A resposta é 202 com "situacao": "EM_REVISAO_INOVA" e alertas automáticos do texto.

{ "nome": "pedido_enviado", "categoria": "UTILITY",
  "corpo": "Olá {{1}}, seu pedido {{2}} saiu para entrega hoje.",
  "exemplos": ["Ana", "4521"],
  "rodape": "Loja Exemplo",
  "botoes": [{ "tipo": "URL", "texto": "Acompanhar", "valor": "https://loja.com/rastreio" }] }

Código de acesso tem texto fixo da Meta, só escolhe a validade:

{ "nome": "codigo_login", "categoria": "AUTHENTICATION", "validade_minutos": 10 }

GET/api/v1/modelos/{nome}

Mostra revisao_inova (pendente, aprovado, recusado com motivo_recusa), situacao_meta, qualidade e pode_enviar. Só envia o que estiver aprovado pela Inova e pela Meta.

Permissões da chave

Cada chave pode ser limitada a tipos de mensagem (código de acesso, utilidade, marketing, texto livre) e a um máximo por 24 horas. Fora disso a API devolve 403 dizendo o que a chave pode. Use uma chave por sistema: se a nota do número cair, o painel mostra de qual chave saiu cada envio.

4 · Consultar e cancelar

GET/api/v1/mensagens/{id}

Devolve a situação atual: agendada, enviada, entregue, lida ou falhou, com o erro da Meta quando houver, a referência e o wamid.

GET/api/v1/mensagens?limite=50

Os últimos envios da conta, do mais novo para o mais velho.

DELETE/api/v1/mensagens/{id}

Cancela um envio agendado que ainda não saiu. Depois que saiu, não há o que cancelar e a resposta é 409.

As três de apoio

GET/api/v1/conta

GET/api/v1/numeros

GET/api/v1/modelos

Conta e cotas do mês, números com faixa e qualidade, e os modelos com situação e as variáveis que cada um espera, no campo espera.

5 · Como saber o que aconteceu com a mensagem

Os avisos da Meta (entregue, lida, falhou, cobrança) chegam sozinhos na plataforma: o webhook da Meta é configurado por nós, você não precisa mexer em nada disso. Do seu lado, hoje, o caminho é consultar GET /api/v1/mensagens/{id} quando o seu fluxo precisar do status, por exemplo alguns minutos depois do envio.

Webhook de saída para o seu sistema

O aviso empurrado para o seu endereço, assinado e com retentativa, está em desenvolvimento e vai aparecer na tela API quando estiver no ar. Esta página será atualizada junto.

6 · Códigos de resposta

Código	Quando	O que fazer
401	Chave ausente, errada ou revogada	Gerar outra no painel e trocar no seu sistema
402	A cota do plano para essa categoria acabou	A resposta diz a categoria, a cota e o usado. Mudar de plano ou esperar o mês virar
403	A chave não tem permissão para esse tipo de mensagem, ou chegou ao limite de 24 horas	A resposta diz o que a chave pode. Ajuste em API > Chaves > Permissões
404	Modelo ou número não existe nessa conta	Conferir com GET /modelos e GET /numeros
409	Modelo em revisão ou recusado pela Inova, não aprovado pela Meta, número desativado, janela fechada, envio já saiu, ou a pessoa pediu para sair	A resposta explica qual dos casos é. Optout traz `{"optout":true,"nivel":"…"}`: não insista
422	Campo faltando ou errado: telefone, variáveis, data	A resposta lista o que faltou, campo por campo
429	Mais de 240 chamadas por minuto na chave	Segurar e reenviar com espera crescente
502	A Meta devolveu erro na hora do envio	O corpo traz o erro da Meta. Tentar de novo vale para erro temporário

7 · Exemplo completo

curl -X POST https://oficial.inovawebplus.com.br/api/v1/mensagens \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "para": "5588999998888",
    "modelo": "confirmacao_pedido",
    "variaveis": ["Maria", "1042", "18h"],
    "referencia": "pedido-1042"
  }'

Na tela API do painel o mesmo exemplo aparece pronto em PHP, Node e Python, já com o seu modelo e as suas variáveis, e dá para fazer um disparo de teste sem sair de lá.

Dúvida que a página não resolveu: WhatsApp (88) 99305-8441.