KambaSMS 1.1.2

🇦🇴 KambaSMS C# SDK

SDK oficial e leve da KambaSMS para integração de envio de mensagens SMS em Angola. Desenvolvido em C# com suporte nativo a async/await e tipagem forte.

✨ Funcionalidades

• 🚀 Zero Dependências: Utiliza HttpClient nativo do .NET.
• 🛡️ Validação no Cliente: Deteta números inválidos, URLs ou emojis antes de fazer a chamada à API.
• 💎 Totalmente Assíncrono: Suporte nativo a async/await e CancellationToken.
• 📦 MVP Completo: Envio único, envio em massa, agendamento e gestão de saldo/histórico.

📦 Instalação

Instala o pacote via NuGet:

dotnet add package KambaSMS

Ou via Package Manager Console:

Install-Package KambaSMS

Nota: Requer .NET 6.0 ou superior.

⚡ Início Rápido

1. Inicialização

using KambaSMS;

using var client = new KambaClient(
    apiKey: "kamba_tua_chave_aqui",
    baseUrl: "https://nexasms-api.onrender.com" // Opcional
);

2. Enviar um SMS Único

try
{
    var response = await client.Sms.SendAsync(new SendSmsRequest
    {
        To = "+244923456789",
        Text = "O seu código de verificação é 1234. Não partilhe com ninguém.",
        SenderId = "KAMBA"
    });

    Console.WriteLine($"✅ SMS Enviado! ID: {response.MessageId}");
    Console.WriteLine($"Saldo Restante: {response.RemainingBalance}");
}
catch (Exception ex)
{
    Console.WriteLine($"Falha no envio: {ex.Message}");
}

3. Envio em Massa (Bulk)

try
{
    var response = await client.Sms.SendBulkAsync(new SendBulkRequest
    {
        Name = "Campanha Natal 2024",
        SenderId = "PROMO",
        Text = "Feliz Natal! Aproveite 20% de desconto.",
        Recipients = new[]
        {
            "+244923456789",
            "+244933123456",
            "+244943987654"
        }
    });

    Console.WriteLine($"✅ Job criado! ID: {response.JobId} | Total: {response.Total}");
}
catch (Exception ex)
{
    Console.WriteLine($"Falha: {ex.Message}");
}

4. Agendar um SMS

try
{
    var dataFutura = DateTime.UtcNow.AddHours(2).ToString("o"); // ISO 8601

    var response = await client.Sms.ScheduleAsync(new ScheduleSmsRequest
    {
        To = "+244923456789",
        Text = "Lembrete: A sua consulta está marcada para amanhã.",
        SenderId = "CLINICA",
        ScheduledAt = dataFutura
    });

    Console.WriteLine("✅ SMS agendado com sucesso!");
}
catch (Exception ex)
{
    Console.WriteLine($"Falha: {ex.Message}");
}

5. Consultar Saldo e Histórico

// Verificar Saldo
var balance = await client.Account.GetBalanceAsync();
Console.WriteLine($"Saldo atual: {balance.Balance} SMS");

// Ver Histórico
var history = await client.Account.GetHistoryAsync(limit: 10);
foreach (var msg in history)
{
    Console.WriteLine($"Para: {msg.To} | Status: {msg.Status}");
}

🔐 OTP Service

Serviço gerido de autenticação por SMS. Rate limiting (3/hora/número), expiração (5min) e validação incluídos.

Enviar OTP

var otp = await client.Otp.SendAsync(new OtpSendRequest
{
    Phone = "+244912345678"
});

Console.WriteLine($"Expira em: {otp["expires_in"]} segundos");
// → Expira em: 300 segundos

Verificar OTP

⚠️ O endpoint verify é público — não requer API Key. Pode ser chamado diretamente do frontend.

var result = await client.Otp.VerifyAsync(new OtpVerifyRequest
{
    Phone = "+244912345678",
    Code = "123456"
});

if ((bool)result["success"])
{
    Console.WriteLine("✅ Código válido!");
}
else
{
    Console.WriteLine("❌ Código inválido ou expirado.");
}

Regras do OTP

🛡️ Regras de Validação (Específicas para Angola)

O SDK faz validações automáticas no lado do cliente. Se estas regras forem violadas, o SDK lança uma KambaValidationException sem sequer chamar a API.

1. Formato do Número: Deve começar obrigatoriamente com +244 seguido de exatamente 9 dígitos.
2. Sem URLs: Mensagens contendo URLs são rejeitadas (filtradas como spam).
3. Sem Emojis: Caracteres emoji não são suportados.
4. Limite de Caracteres: Máximo de 160 caracteres por SMS.

⚠️ Tratamento de Erros

using KambaSMS;
using KambaSMS.Exceptions;

try
{
    await client.Sms.SendAsync(new SendSmsRequest
    {
        To = "923456789",
        Text = "Teste",
        SenderId = "KAMBA"
    });
}
catch (KambaValidationException ex)
{
    Console.WriteLine($"🚫 Dados inválidos: {ex.Message}");
}
catch (KambaApiException ex)
{
    Console.WriteLine($"🔌 Erro da API ({ex.StatusCode}): {ex.Message}");
}
catch (KambaException ex)
{
    Console.WriteLine($"💥 Erro KambaSMS: {ex.Message}");
}

📚 Documentação Completa

Para mais detalhes, consulta a Documentação Oficial da KambaSMS.

🆘 Suporte

• Abre uma Issue neste repositório.
• Contacta: support@kambasms.ao.

📄 Licença

Este projeto está licenciado sob a Licença MIT.