API do Inova SMS

Envie SMS pelos chips conectados à sua conta, gere códigos de verificação e receba respostas. Todas as chamadas usam JSON e o endereço base é .

Base: /api/v1

Autenticação

Crie uma chave no painel em Integração > API e OTP. Ela aparece uma única vez. Envie em todo pedido, de uma destas formas:

Authorization: Bearer isk_XXXXXXXXXXXXXXXX
X-API-Key: isk_XXXXXXXXXXXXXXXX

Limite padrão: 120 requisições por minuto por chave (resposta 429 com Retry-After).

Fila e ritmo de envio

A API não envia na hora: ela coloca na fila, e cada aparelho busca as mensagens no ritmo seguro do chip (limite por dia, por hora, intervalo e janela de horário configurados no painel). Códigos OTP passam na frente e podem sair fora da janela. Por isso o status começa como fila e muda para enviada, entregue ou falhou. Use os webhooks para saber na hora.

Enviar SMS

curl -X POST /api/v1/sms \
  -H "Authorization: Bearer SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"para":"(88) 99999-0000","mensagem":"Ola Ana, consulta amanha 14h. Responda 1 para confirmar.","referencia":"agenda-1234"}'

HTTP 201
{"mensagens":[{"id":5821,"para":"+5588999990000","status":"fila","segmentos":1,"codificacao":"gsm","referencia":"agenda-1234", ...}],
 "aceitas":1,"recusadas":[]}

Com lista em para, números inválidos ou descadastrados vão em recusadas e os outros seguem.

Consultar uma mensagem

{"mensagem":{"id":5821,"status":"entregue","enviado_em":"2026-11-10 14:02:11","entregue_em":"2026-11-10 14:02:19","erro":null, ...}}

Listar mensagens

Mais recentes primeiro, até 200 por chamada. Use desde_id para buscar só as novas.

Cancelar

Só funciona enquanto a mensagem está na fila. Depois disso devolve 409.

Respostas recebidas

{"recebidas":[{"id":77,"de":"+5588999990000","mensagem":"1","recebido_em":"2026-11-10 14:05:40","em_resposta_a":5821}]}

Respostas que são só SAIR, PARAR, CANCELAR, STOP (e outras configuradas) descadastram o número automaticamente.

Código de verificação: enviar

{"otp_id":42,"para":"+5588999990000","expira_em":"2026-11-10 14:12:00","mensagem_id":5822}

Máximo de 3 códigos por número a cada 10 minutos. Um código novo invalida o anterior. O código nunca volta na resposta: só a pessoa vê.

Código de verificação: conferir

{"otp_id":42,"codigo":"482913"}     ou     {"para":"88999990000","codigo":"482913"}

{"valido":true,"para":"+5588999990000"}
{"valido":false,"motivo":"codigo_incorreto","tentativas_restantes":3}

Motivos: codigo_incorreto, expirado, ja_usado, tentativas_esgotadas (5 tentativas), nao_encontrado.

Aparelhos

{"dispositivos":[{"id":3,"nome":"Moto G recepção","online":true,"bateria":100,"carregando":1,"pausado":false}]}

Conta

{"conta":{"id":12,"nome":"Clínica Vida","situacao":"ativa","vencimento":"2026-12-05","hoje":{"enviadas":130,"na_fila":12}}}

Webhooks

Cadastre a URL do seu sistema no painel em Integração > Webhooks e escolha os eventos. Cada evento chega como POST JSON:

{"evento":"sms.recebida","enviado_em":"2026-11-10T14:05:41-03:00",
 "dados":{"id":77,"de":"+5588999990000","mensagem":"1","em_resposta_a":5821,"referencia_original":"agenda-1234","descadastrou":false}}

Conferir a assinatura

Cabeçalhos: X-Inova-Evento, X-Inova-Timestamp e X-Inova-Assinatura = sha256= + HMAC-SHA256 de timestamp + "." + corpo com o segredo do webhook.

<?php
$corpo = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_INOVA_TIMESTAMP'];
$certo = 'sha256=' . hash_hmac('sha256', $ts . '.' . $corpo, 'SEU_SEGREDO');
if (!hash_equals($certo, $_SERVER['HTTP_X_INOVA_ASSINATURA']) || abs(time() - (int)$ts) > 300) {
    http_response_code(401); exit;
}
echo 'ok'; // qualquer 2xx confirma

Sem resposta 2xx, tentamos de novo em 1, 5, 15 e 60 minutos, 3 horas e 12 horas.

Erros

{"erro":"Número de telefone inválido: 1234","campo":"para"}