Envio de SMS em Kotlin: Biblioteca de API

Envio de SMS em Kotlin: Biblioteca de API para Integração Rápida

No desenvolvimento web moderno, a capacidade de enviar mensagens SMS programaticamente continua sendo uma funcionalidade demandada — desde autenticação de dois fatores até notificações de status de pedidos. Se você usa Kotlin para o backend (Ktor, Spring Boot) ou aplicativo móvel (Android), precisará de uma ferramenta confiável para trabalhar com provedores de SMS. Neste artigo, abordaremos a biblioteca de API para envio de SMS em Kotlin, seus recursos, exemplos de integração e melhores práticas.

O que é uma biblioteca de API para envio de SMS?

Uma biblioteca de API é um conjunto de classes e funções que abstrai o trabalho com requisições HTTP ao servidor do provedor de SMS. Em vez de formar manualmente URLs, cabeçalhos e analisar JSON, você chama métodos simples em Kotlin: sendSms(phone, message). A biblioteca cuida da autenticação, serialização, novas tentativas em caso de erros de rede e tratamento de respostas.

Principais recursos da biblioteca

Envio simples de SMS — especificação do número do destinatário, texto e opcionalmente o nome do remetente (alfa-nome).
Envio em lote — envio de uma única mensagem para uma lista de números.
Verificação de status — obtenção de informações sobre a entrega (entregue, na fila, erro).
Suporte a diferentes provedores — Twilio, Vonage (Nexmo), SMSC.ru, Smsc.ua e outros.
Assincronicidade — todos os métodos retornam funções suspend ou Deferred para corrotinas.
Registro e tratamento de erros — mecanismos integrados para depuração.

Instalação e configuração

A biblioteca é distribuída via Maven Central ou JitPack. Adicione a dependência no build.gradle.kts:

// build.gradle.kts (para Gradle Kotlin DSL)dependencies {    implementation("com.example:sms-api:1.0.0")    // se você usa Ktor Client    implementation("io.ktor:ktor-client-core:2.3.0")    implementation("io.ktor:ktor-client-okhttp:2.3.0")}

Para Android, adicione também a permissão de internet no AndroidManifest.xml.

Exemplo básico de envio de SMS

Vamos considerar um exemplo mínimo de envio de uma única mensagem através do provedor SMSC.ru (similar para outros).

import com.example.smsapi.SmsClientimport com.example.smsapi.model.SmsRequestimport com.example.smsapi.model.SmsResponse

suspend fun sendSingleSms() {    // Cria o cliente com as credenciais    val client = SmsClient.create(        login = "your_login",        password = "your_password",        provider = SmsProvider.SMSC    )

    // Monta a requisição    val request = SmsRequest(        phone = "+71234567890",        message = "Seu código de confirmação: 1234",        sender = "MyApp" // alfa-nome, se suportado    )

    // Envia e recebe a resposta    val response: SmsResponse = client.send(request)

    when (response.status) {        SmsStatus.SUCCESS -> println("SMS enviado, ID: ${response.id}")        SmsStatus.ERROR -> println("Erro: ${response.errorMessage}")        else -> println("Status desconhecido")    }}

Envio em lote

Para enviar uma única mensagem para vários números, use o método sendBatch:

val phones = listOf("+71234567890", "+70987654321", "+71112223344")val batchRequest = BatchSmsRequest(    phones = phones,    message = "Prezados clientes, a promoção foi estendida até sexta-feira!",    sender = "ShopBot")

val batchResponse = client.sendBatch(batchRequest)batchResponse.results.forEach { result ->    println("Telefone: ${result.phone}, status: ${result.status}")}