API de SMS MozeSMS v2.0 - Documentação Oficial

API de SMS v2.0

Introdução

MozeSMS API v2.0 é uma plataforma moderna e robusta, permitindo a integração eficiente de qualquer aplicativo com o nosso sistema de envio de mensagens SMS.
A principal vantagem da nova versão é a simplicidade de implementação, maior segurança e novos recursos como Bulk SMS e OTP.
A mensagem pode ter remetente (SenderID) personalizado com nome da empresa ou qualquer número de telefone autorizado.

Novidades da Versão 2.0:

✅ Autenticação Bearer Token: Maior segurança com tokens de acesso
✅ Bulk SMS: Envio de até 1000 mensagens em uma única requisição
✅ Sistema OTP: Geração e verificação automática de códigos
✅ Validação de SenderID: Controle rigoroso de remetentes autorizados
✅ Respostas JSON: Formato padronizado para todas as respostas
✅ Logs Detalhados: Melhor rastreabilidade e debugging

Passos para Começar com o MozeSMS API v2.0:

1. Criar uma Conta ou Fazer Login:
Acesse o site do MozeSMS em https://my.mozesms.com/ e crie uma conta gratuita ou faça login se já tiver uma conta existente.

2. Registrar o SenderID:
Após criar a conta e fazer login, registre um nome ou número de remetente (SenderID).
Isso permitirá que você personalize o remetente das mensagens SMS enviadas para seus destinatários.
⚠️ Importante: SenderIDs alfanuméricos devem ser registrados previamente no painel.

3. Obter Bearer Token:
No painel de cliente, copie seu Bearer Token para autenticação na API v2.0.
Este token deve ser incluído no header de todas as requisições.

API Base URL

A nova API v2.0 utiliza um endpoint unificado para todos os serviços:

Base URL da API v2.0:

https://api.mozesms.com

Autenticação

A API v2.0 utiliza autenticação Bearer Token para maior segurança:

Método	Descrição
Bearer Token	Inclua o header: `Authorization: Bearer SEU_TOKEN_AQUI`
Formato	Todas as requisições e respostas em JSON
Segurança	Tokens únicos por cliente, gerados no painel

Enviar SMS Individual

Endpoint: POST /v2/sms/send

Você precisa de 3 parâmetros obrigatórios para enviar um SMS:

Parametro	Descrição
phone	Número do destinatário com código do país (ex: +258845888195)
message	Conteúdo da mensagem (máximo 1600 caracteres)
sender_id	SenderID/remetente (nome da empresa ou número autorizado)

<?php 
$curl = curl_init();

$data = json_encode([
    'phone' => '+258845888195',
    'message' => 'Olá! Esta é uma mensagem de teste da API v2.0',
    'sender_id' => 'MozeSMS'
]);

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.mozesms.com/v2/sms/send',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer SEU_TOKEN_AQUI'
    ],
    CURLOPT_RETURNTRANSFER => true
]);

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

echo "HTTP: $httpCode\n";
echo "Response: $response\n";
?>

curl -X POST "https://api.mozesms.com/v2/sms/send" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-d '{
  "phone": "+258845888195",
  "message": "Olá! Esta é uma mensagem de teste da API v2.0",
  "sender_id": "MozeSMS"
}'

import requests
import json

url = 'https://api.mozesms.com/v2/sms/send'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer SEU_TOKEN_AQUI'
}
data = {
    'phone': '+258845888195',
    'message': 'Olá! Esta é uma mensagem de teste da API v2.0',
    'sender_id': 'MozeSMS'
}

response = requests.post(url, json=data, headers=headers)
print(f"Status: {response.status_code}")
print(f"Response: {response.json()}")

const axios = require('axios');

const data = {
    phone: '+258845888195',
    message: 'Olá! Esta é uma mensagem de teste da API v2.0',
    sender_id: 'MozeSMS'
};

const config = {
    method: 'POST',
    url: 'https://api.mozesms.com/v2/sms/send',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    },
    data: data
};

axios(config)
    .then(response => {
        console.log('Status:', response.status);
        console.log('Response:', response.data);
    })
    .catch(error => {
        console.error('Error:', error.response?.data || error.message);
    });

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer SEU_TOKEN_AQUI");
        
        var data = new
        {
            phone = "+258845888195",
            message = "Olá! Esta é uma mensagem de teste da API v2.0",
            sender_id = "MozeSMS"
        };
        
        var json = JsonConvert.SerializeObject(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync("https://api.mozesms.com/v2/sms/send", content);
        var result = await response.Content.ReadAsStringAsync();
        
        Console.WriteLine($"Status: {response.StatusCode}");
        Console.WriteLine($"Response: {result}");
    }
}

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class MozeSMSv2 {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String json = "{\"phone\":\"+258845888195\",\"message\":\"Olá! Esta é uma mensagem de teste da API v2.0\",\"sender_id\":\"MozeSMS\"}";
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.mozesms.com/v2/sms/send"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer SEU_TOKEN_AQUI")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println("Status: " + response.statusCode());
        System.out.println("Response: " + response.body());
    }
}

Enviar Bulk SMS (Em Massa)

Endpoint: POST /v2/sms/bulk

Envie até 1000 mensagens SMS em uma única requisição para máxima eficiência:

Parâmetro	Descrição
sender_id	SenderID padrão para todas as mensagens
messages	Array de mensagens (máx: 1000 mensagens)
messages[].phone	Número do destinatário
messages[].message	Conteúdo da mensagem
messages[].sender_id	SenderID específico (opcional)

<?php
$data = json_encode([
    'sender_id' => 'MozeSMS',
    'messages' => [
        [
            'phone' => '+258845888195',
            'message' => 'Mensagem para cliente 1'
        ],
        [
            'phone' => '+258847123456',
            'message' => 'Mensagem para cliente 2'
        ],
        [
            'phone' => '+258848555666',
            'message' => 'Mensagem especial para cliente 3',
            'sender_id' => 'PROMO'
        ]
    ]
]);

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.mozesms.com/v2/sms/bulk',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer SEU_TOKEN_AQUI'
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

curl -X POST "https://api.mozesms.com/v2/sms/bulk" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-d '{
  "sender_id": "MozeSMS",
  "messages": [
    {
      "phone": "+258845888195",
      "message": "Mensagem 1"
    },
    {
      "phone": "+258847123456", 
      "message": "Mensagem 2"
    }
  ]
}'

import requests

data = {
    'sender_id': 'MozeSMS',
    'messages': [
        {
            'phone': '+258845888195',
            'message': 'Mensagem para cliente 1'
        },
        {
            'phone': '+258847123456',
            'message': 'Mensagem para cliente 2'
        }
    ]
}

response = requests.post(
    'https://api.mozesms.com/v2/sms/bulk',
    json=data,
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    }
)

print(response.json())

const axios = require('axios');

const data = {
    sender_id: 'MozeSMS',
    messages: [
        {
            phone: '+258845888195',
            message: 'Mensagem para cliente 1'
        },
        {
            phone: '+258847123456',
            message: 'Mensagem para cliente 2'
        }
    ]
};

axios.post('https://api.mozesms.com/v2/sms/bulk', data, {
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error.response.data);
});

// C# example for Bulk SMS
var data = new {
    sender_id = "MozeSMS",
    messages = new[] {
        new { phone = "+258845888195", message = "Mensagem 1" },
        new { phone = "+258847123456", message = "Mensagem 2" }
    }
};
// ... rest of HttpClient code similar to single SMS

// Java example for Bulk SMS
String json = "{\"sender_id\":\"MozeSMS\",\"messages\":[{\"phone\":\"+258845888195\",\"message\":\"Mensagem 1\"},{\"phone\":\"+258847123456\",\"message\":\"Mensagem 2\"}]}";
// ... rest of HttpClient code similar to single SMS

Enviar Código OTP

Endpoint: POST /v2/otp/send

Gere e envie códigos OTP (One-Time Password) para autenticação de dois fatores:

Parâmetro	Descrição
phone	Número do destinatário
sender_id	SenderID (opcional, padrão: MozeSMS)
code_length	Tamanho do código (4-8 dígitos, padrão: 6)
expires_in	Tempo de expiração em segundos (60-3600, padrão: 300)
template	Template da mensagem (use {code} para inserir o código)
app_name	Nome da aplicação (opcional)

<?php 
$data = json_encode([
    'phone' => '+258845888195',
    'sender_id' => 'MOZOTP',
    'code_length' => 6,
    'expires_in' => 300,
    'template' => 'Seu código de verificação é: {code}',
    'app_name' => 'MeuApp'
]);

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.mozesms.com/v2/otp/send',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer SEU_TOKEN_AQUI'
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

curl -X POST "https://api.mozesms.com/v2/otp/send" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-d '{
  "phone": "+258845888195",
  "sender_id": "MOZOTP",
  "code_length": 6,
  "expires_in": 300,
  "template": "Seu código é: {code}"
}'

import requests

data = {
    'phone': '+258845888195',
    'sender_id': 'MOZOTP',
    'code_length': 6,
    'expires_in': 300,
    'template': 'Seu código de verificação é: {code}'
}

response = requests.post(
    'https://api.mozesms.com/v2/otp/send',
    json=data,
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    }
)

print(response.json())

fetch('https://api.mozesms.com/v2/otp/send', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    },
    body: JSON.stringify({
        phone: '+258845888195',
        sender_id: 'MOZOTP',
        code_length: 6,
        expires_in: 300
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

// C# example for OTP Send
var data = new {
    phone = "+258845888195",
    sender_id = "MOZOTP",
    code_length = 6,
    expires_in = 300,
    template = "Seu código é: {code}"
};
// ... rest of HttpClient code

// Java example for OTP Send
String json = "{\"phone\":\"+258845888195\",\"sender_id\":\"MOZOTP\",\"code_length\":6,\"expires_in\":300}";
// ... rest of HttpClient code

Verificar Código OTP

Endpoint: POST /v2/otp/verify

Valide códigos OTP enviados anteriormente:

Parâmetro	Descrição
phone	Número que recebeu o OTP
code	Código OTP a ser verificado
otp_id	ID do OTP retornado no endpoint /otp/send

<?php 
$data = json_encode([
    'phone' => '+258845888195',
    'code' => '123456',
    'otp_id' => 'OTPID_1755034567_12345'
]);

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.mozesms.com/v2/otp/verify',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer SEU_TOKEN_AQUI'
    ],
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

curl -X POST "https://api.mozesms.com/v2/otp/verify" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN_AQUI" \
-d '{
  "phone": "+258845888195",
  "code": "123456",
  "otp_id": "OTPID_1234567890_12345"
}'

import requests

data = {
    'phone': '+258845888195',
    'code': '123456',
    'otp_id': 'OTPID_1234567890_12345'
}

response = requests.post(
    'https://api.mozesms.com/v2/otp/verify',
    json=data,
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    }
)

print(response.json())

fetch('https://api.mozesms.com/v2/otp/verify', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    },
    body: JSON.stringify({
        phone: '+258845888195',
        code: '123456',
        otp_id: 'OTPID_1234567890_12345'
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Validação de SenderID

Endpoint: GET /v2/senderids

A API v2.0 inclui validação rigorosa de SenderIDs para garantir que apenas remetentes autorizados sejam utilizados:

Tipo de SenderID	Validação
Alfanumérico	Deve estar registrado na tabela sms_senderid com status ativo
Numérico	Permitido automaticamente (máximo 15 dígitos)
Comprimento	Máximo 11 caracteres para alfanumérico
Status	0=Inativo, 1=Ativo, 2=Desativado, 3=Aguardando aprovação

⚠️ Importante: SenderIDs alfanuméricos não registrados retornarão erro HTTP 403 com código SENDER_ID_NOT_ALLOWED.

<?php 
// Listar SenderIDs válidos
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.mozesms.com/v2/senderids',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer SEU_TOKEN_AQUI'
    ]
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

curl -X GET "https://api.mozesms.com/v2/senderids" \
-H "Authorization: Bearer SEU_TOKEN_AQUI"

import requests

response = requests.get(
    'https://api.mozesms.com/v2/senderids',
    headers={
        'Authorization': 'Bearer SEU_TOKEN_AQUI'
    }
)

print(response.json())

Códigos de Resposta

A API v2.0 utiliza códigos de status HTTP padrão e retorna respostas em formato JSON:

Status HTTP	Código	Descrição
200	SUCCESS	Requisição processada com sucesso
400	VALIDATION_ERROR	Parâmetros obrigatórios em falta ou inválidos
401	UNAUTHORIZED	Token de autenticação inválido ou em falta
402	INSUFFICIENT_CREDITS	Saldo insuficiente para enviar SMS
403	SENDER_ID_NOT_ALLOWED	SenderID não autorizado ou inativo
404	NOT_FOUND	Endpoint não encontrado
405	METHOD_NOT_ALLOWED	Método HTTP não permitido
429	RATE_LIMIT_EXCEEDED	Limite de rate (OTP) excedido
500	INTERNAL_ERROR	Erro interno do servidor
502	SEND_FAILED	Falha no envio via gateway SMS

Exemplo de Resposta de Sucesso - SMS:

{
  "success": true,
  "data": {
    "sms_id": "SMS_1755034567_1234",
    "phone": "+258845888195",
    "message": "Olá! Esta é uma mensagem de teste.",
    "sender_id": "MozeSMS",
    "segments": 1,
    "status": "sent",
    "credits_used": 1,
    "credits_remaining": 7890,
    "timestamp": "2025-08-12T23:45:00+02:00"
  }
}

Exemplo de Resposta de Sucesso - Bulk SMS:

{
  "success": true,
  "data": {
    "bulk_id": "BULK_1755034567_89012",
    "total_messages": 2,
    "successful_sends": 2,
    "failed_sends": 0,
    "total_segments": 2,
    "credits_used": 2,
    "credits_remaining": 7888,
    "results": [...]
  }
}

Exemplo de Resposta de Sucesso - OTP:

{
  "success": true,
  "data": {
    "otp_id": "OTPID_1755034567_12345",
    "sms_id": "OTP_1755034567_6789",
    "phone": "+258845888195",
    "code_length": 6,
    "expires_in": 300,
    "expires_at": "2025-08-12T23:50:00+02:00",
    "status": "sent",
    "credits_used": 1,
    "credits_remaining": 7887
  }
}

Exemplo de Resposta de Erro:

{
  "success": false,
  "error": "SENDER_ID_NOT_ALLOWED",
  "message": "SenderID alfanumérico não autorizado. Registe primeiro o SenderID no painel de cliente.",
  "timestamp": "2025-08-12T23:45:00+02:00"
}

Limites e Restrições

Serviço	Limite
SMS Individual	Sem limite específico
Bulk SMS	Máximo 1000 mensagens por requisição
OTP Rate Limit	1 OTP por minuto por número
Tamanho da Mensagem	Máximo 1600 caracteres
Segmentação	Automática (160 chars por segmento)
Custo	1 crédito por segmento enviado

Endpoints Disponíveis

Método	Endpoint	Descrição
POST	/v2/sms/send	Enviar SMS individual
POST	/v2/sms/bulk	Enviar SMS em massa
POST	/v2/otp/send	Enviar código OTP
POST	/v2/otp/verify	Verificar código OTP
GET	/v2/senderids	Listar SenderIDs válidos

Suporte

Para suporte técnico ou dúvidas sobre a integração:

📧 Email: support@mozesms.com
🌐 Website: https://mozesms.com
👤 Painel: https://my.mozesms.com