📱 API MelhorSMS

Documentação da API REST para Envio de SMS

Versão 1.0

Índice

🔐 Autenticação

Todas as requisições à API devem incluir os seguintes headers de autenticação:

X-API-Key: sua_api_key_aqui
X-API-Secret: seu_api_secret_aqui
⚠️ Importante: Nunca exponha suas credenciais em código client-side ou repositórios públicos.

Para obter suas credenciais, acesse o painel de gerenciamento de API no seu dashboard.

📡 Endpoints

POST /api/v1/enviar.php

Envia mensagens SMS para um ou múltiplos destinatários.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
destinatario string/array Sim Número(s) de telefone(s) com DDD (10 ou 11 dígitos)
mensagem string Sim Texto da mensagem (máx. 1000 caracteres)
remetente string Não Nome do remetente (opcional)
Exemplo de Requisição (JSON)
{
  "destinatario": "11999999999",
  "mensagem": "Olá! Esta é uma mensagem de teste da API MelhorSMS"
}
Exemplo com Múltiplos Destinatários
{
  "destinatario": ["11999999999", "11888888888", "11777777777"],
  "mensagem": "Mensagem em massa via API"
}
Resposta de Sucesso (200)
{
  "success": true,
  "timestamp": "2025-10-06T14:30:00+00:00",
  "data": {
    "message": "Envios processados",
    "total_solicitado": 3,
    "total_enviado": 3,
    "total_falhas": 0,
    "bloqueados": 0,
    "saldo_restante": 97
  }
}

GET /api/v1/saldo.php

Consulta o saldo disponível e estatísticas da conta.

Resposta de Sucesso (200)
{
  "success": true,
  "timestamp": "2025-10-06T14:30:00+00:00",
  "data": {
    "saldo_disponivel": 97,
    "conta": {
      "usuario": "cliente123",
      "id": 1
    },
    "estatisticas": {
      "total_enviados": 1523,
      "total_falhas": 12,
      "enviados_hoje": 3
    }
  }
}

GET /api/v1/historico.php

Retorna o histórico de envios realizados via API.

Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
pagina int Não Número da página (padrão: 1)
limite int Não Itens por página (padrão: 20, máx: 100)
status string Não Filtrar por status: pendente, enviado, falha
data_inicio date Não Data inicial (formato: YYYY-MM-DD)
data_fim date Não Data final (formato: YYYY-MM-DD)
Exemplo de Requisição
GET /api/v1/historico.php?pagina=1&limite=10&status=enviado
Resposta de Sucesso (200)
{
  "success": true,
  "timestamp": "2025-10-06T14:30:00+00:00",
  "data": {
    "envios": [
      {
        "id": 1234,
        "destinatario": "11999999999",
        "mensagem_preview": "Olá! Esta é uma mensagem de teste...",
        "status": "enviado",
        "mensagem_id": "msg_abc123",
        "erro": null,
        "criado_em": "2025-10-06 14:25:30",
        "atualizado_em": "2025-10-06 14:25:31"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "limite": 10,
      "total_registros": 1523,
      "total_paginas": 153
    }
  }
}

⚠️ Códigos de Erro

Código HTTP Código Interno Descrição
400 VALIDATION_ERROR Erro de validação nos parâmetros enviados
401 AUTH_MISSING Credenciais de autenticação não fornecidas
401 AUTH_INVALID Credenciais de autenticação inválidas
401 AUTH_EXPIRED API Key expirada
402 INSUFFICIENT_BALANCE Saldo insuficiente para realizar envio
403 IP_FORBIDDEN IP não autorizado para esta API Key
403 FORBIDDEN_WORDS Mensagem contém palavras proibidas
405 METHOD_NOT_ALLOWED Método HTTP não permitido
429 RATE_LIMIT_EXCEEDED Limite de requisições excedido
500 INTERNAL_ERROR Erro interno do servidor
Exemplo de Resposta de Erro
{
  "success": false,
  "timestamp": "2025-10-06T14:30:00+00:00",
  "error": {
    "message": "Saldo insuficiente",
    "code": "INSUFFICIENT_BALANCE",
    "saldo_disponivel": 5,
    "saldo_necessario": 10
  }
}

⏱️ Rate Limiting

A API possui limite de 60 requisições por minuto por API Key.

Quando o limite é excedido, a API retorna código HTTP 429 com a seguinte resposta:

{
  "success": false,
  "error": {
    "message": "Limite de requisições excedido",
    "code": "RATE_LIMIT_EXCEEDED",
    "limite": 60,
    "tentativas": 61
  }
}

💻 Exemplos de Código

PHP (cURL)

<?php
$apiKey = 'sua_api_key';
$apiSecret = 'seu_api_secret';

$data = [
    'destinatario' => '11999999999',
    'mensagem' => 'Olá! Mensagem via API'
];

$ch = curl_init('https://melhorsms.pro/api/v1/enviar.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey,
    'X-API-Secret: ' . $apiSecret
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

Python (requests)

import requests

api_key = 'sua_api_key'
api_secret = 'seu_api_secret'

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key,
    'X-API-Secret': api_secret
}

data = {
    'destinatario': '11999999999',
    'mensagem': 'Olá! Mensagem via API'
}

response = requests.post(
    'https://melhorsms.pro/api/v1/enviar.php',
    json=data,
    headers=headers
)

print(response.json())

JavaScript (fetch)

const apiKey = 'sua_api_key';
const apiSecret = 'seu_api_secret';

const data = {
    destinatario: '11999999999',
    mensagem: 'Olá! Mensagem via API'
};

fetch('https://melhorsms.pro/api/v1/enviar.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey,
        'X-API-Secret': apiSecret
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Erro:', error));

Node.js (axios)

const axios = require('axios');

const apiKey = 'sua_api_key';
const apiSecret = 'seu_api_secret';

const data = {
    destinatario: '11999999999',
    mensagem: 'Olá! Mensagem via API'
};

axios.post('https://melhorsms.pro/api/v1/enviar.php', data, {
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey,
        'X-API-Secret': apiSecret
    }
})
.then(response => console.log(response.data))
.catch(error => console.error('Erro:', error));