Como enviar SMS com PHP usando a SDK da APIBrasil

Enviar SMS continua sendo uma das formas mais confiáveis de falar com um cliente: chega em qualquer celular, não depende de internet nem de aplicativo instalado e tem taxa de leitura altíssima. É por isso que códigos de verificação (2FA), confirmações de pedido, lembretes de consulta e alertas de cobrança ainda usam esse canal.

Neste tutorial você vai aprender a enviar SMS com PHP usando a SDK oficial da APIBrasil: da instalação pelo Composer ao primeiro envio, passando pela configuração segura das credenciais, pelo tratamento de erros e pela integração com Laravel. Também mostramos como fazer a mesma chamada sem SDK, apenas com cURL, para você entender o que acontece por baixo.

Como funciona o envio de SMS por API

Em vez de contratar uma operadora e lidar com protocolos de telecomunicação, você faz uma requisição HTTP para um gateway de SMS. O gateway recebe o número e a mensagem, entrega à operadora e devolve o resultado. Para o seu código PHP, enviar um SMS vira uma chamada de função.

Na APIBrasil, a API de SMS é um serviço do tipo device-based, o que significa que toda requisição precisa de duas credenciais:

Credencial	O que identifica	Onde fica
Bearer token	A sua conta na APIBrasil	Painel → credenciais (ou retorno do login)
DeviceToken	A instância do serviço de SMS que você criou	Painel → API de SMS → device criado

Essa separação permite, por exemplo, ter devices diferentes para o time comercial e para o suporte, cada um com seu próprio controle. A documentação completa dos endpoints fica em doc.apibrasil.io.

Pré-requisitos

• PHP 8.0 ou superior com a extensão curl habilitada.
• Composer instalado (getcomposer.org).
• Uma conta na APIBrasil com o serviço de SMS ativo.
• O Bearer token e o DeviceToken do serviço de SMS, obtidos no painel.

Se você ainda não tem PHP e Composer configurados, siga a primeira parte do tutorial Laravel da instalação ao Hello World, que cobre a instalação nos três sistemas operacionais.

Passo 1: instalando a SDK PHP com Composer

Crie uma pasta para o projeto e instale a SDK:

mkdir sms-php
cd sms-php
composer require jhowbhz/apigratis-sdk-php

O Composer cria o composer.json, baixa a SDK para a pasta vendor/ e gera o autoload, o arquivo que carrega as classes automaticamente. A SDK usa o Guzzle quando ele está disponível e cai para o cURL nativo do PHP caso contrário, então funciona até em hospedagens mais restritas.

O código-fonte da SDK é aberto e está no GitHub da APIBrasil, com exemplos para todos os serviços.

Passo 2: guardando as credenciais com segurança

Nunca escreva tokens diretamente no código. Se o arquivo for parar no GitHub, qualquer pessoa poderá enviar SMS cobrados na sua conta. Crie um arquivo .env:

E adicione o .env ao .gitignore:

vendor/
.env

A SDK lê automaticamente as variáveis APIBRASIL_BEARER_TOKEN, APIBRASIL_DEVICE_TOKEN, APIBRASIL_SECRET_KEY e APIBRASIL_BASE_URL do ambiente. Por isso, um simples new ApiBrasil() já sai autenticado. Entenda a fundo esse padrão no tutorial Variáveis de ambiente e arquivo .env.

Passo 3: o código para enviar SMS com PHP

Crie o arquivo enviar-sms.php:

Vamos por partes:

1. require vendor/autoload.php carrega a SDK e todas as dependências.
2. new ApiBrasil() cria o cliente lendo os tokens das variáveis de ambiente. Se preferir, passe explicitamente: new ApiBrasil(['bearerToken' => '...', 'deviceToken' => '...']).
3. $api->sms->send([...]) faz o POST /sms/send no gateway com os campos number e message.
4. O número vai no formato internacional, só com dígitos: 55 (Brasil) + DDD + número. Sem espaços, parênteses ou traços.
5. A resposta chega como array associativo já decodificado, pronto para ser salvo no seu banco.

O método send aceita ainda campos opcionais como operator, user_reply e webhook_url (para receber atualizações do envio no seu sistema). Consulte a documentação para os valores aceitos em cada um.

Passo 4: executando o envio

Carregue as variáveis do .env no terminal e rode o script:

set -a && source .env && set +a
php enviar-sms.php

No segundo comando do print, forçamos um DeviceToken de outro serviço para mostrar o tratamento de erro em ação: em vez de uma exceção genérica, a SDK lança um PermissionError, e o script mostra uma mensagem clara.

No Windows: o comando source não existe no PowerShell. Defina as variáveis com $env:APIBRASIL_BEARER_TOKEN="..." antes de rodar o script, ou carregue o .env com a biblioteca vlucas/phpdotenv.

Entendendo os erros da SDK

A SDK traduz cada status HTTP em uma classe de exceção própria, todas herdando de ApiBrasilError. Isso permite reagir a cada situação de forma diferente:

Exceção	Status HTTP	O que significa	O que fazer
ValidationError	400 / 422	Payload inválido (número mal formatado, mensagem vazia)	Corrigir os dados antes de reenviar
AuthenticationError	401	Bearer token ausente ou expirado	Gerar um novo token
InsufficientBalanceError	402	Sem saldo ou plano	Recarregar a conta
PermissionError	403	DeviceToken de outra API, IP fora da whitelist	Conferir o device e a whitelist
RateLimitError	429	Muitas requisições por minuto	Aguardar getRetryAfterMs()
ServerError	5xx	Falha no gateway ou na operadora	Tentar novamente mais tarde

Todo erro expõe getStatus(), getErrorCode() e getResponse(), com o corpo completo devolvido pela API — ótimo para registrar em log.

Um detalhe importante: por padrão, a SDK refaz automaticamente a chamada em caso de 429 e de falhas de conexão, com espera exponencial. Timeouts e erros de negócio nunca são refeitos, justamente para evitar enviar o mesmo SMS duas vezes e ser cobrado em dobro.

Enviando SMS com PHP sem SDK (cURL puro)

A SDK é a forma recomendada, mas vale entender a requisição por trás. Este é o equivalente com a extensão cURL nativa do PHP:

<?php

$ch = curl_init('https://gateway.apibrasil.io/api/v2/sms/send');

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('APIBRASIL_BEARER_TOKEN'),
        'DeviceToken: ' . getenv('APIBRASIL_DEVICE_TOKEN'),
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'number'  => '5511999999999',
        'message' => 'Olá! Mensagem enviada com PHP puro.',
    ]),
]);

$corpo  = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status: {$status}" . PHP_EOL;
print_r(json_decode($corpo, true));

Funciona, mas repare em tudo o que você teria de implementar por conta própria: montagem de cabeçalhos, conversão de JSON, tratamento de cada status, retentativas e timeouts. É exatamente isso que a SDK resolve.

Integrando o envio de SMS no Laravel

Em um projeto Laravel, instale a SDK normalmente com composer require jhowbhz/apigratis-sdk-php e crie um serviço dedicado:

Registre as credenciais em config/services.php:

'apibrasil' => [
    'bearer'     => env('APIBRASIL_BEARER_TOKEN'),
    'sms_device' => env('APIBRASIL_DEVICE_TOKEN'),
],

E use em qualquer lugar via injeção de dependência:

public function enviarCodigo(Request $request, SmsService $sms)
{
    $codigo = random_int(100000, 999999);
    cache()->put("codigo:{$request->user()->id}", $codigo, now()->addMinutes(10));

    $sms->enviar($request->user()->telefone, "Seu código é {$codigo}. Válido por 10 minutos.");

    return back()->with('status', 'Enviamos um código por SMS.');
}

Para envios em volume, coloque a chamada dentro de um Job do Laravel e processe pela fila. Assim a requisição do usuário não fica esperando a resposta do gateway.

Boas práticas para envio de SMS

• Respeite os 160 caracteres. Esse é o limite de um SMS simples no padrão GSM-7. Acima disso, a mensagem é dividida em partes e cada parte pode ser cobrada. Acentos e emojis podem mudar a codificação e reduzir o limite, então teste suas mensagens.
• Valide e normalize o número antes de enviar: remova tudo o que não for dígito e garanta o prefixo 55.
• Envie em sequência, não em paralelo, quando for um lote. Disparar centenas de requisições simultâneas bate no limite por minuto e, se algo falhar no meio, você não sabe quem recebeu. Para volume, use a fila do gateway (sufixo /queue) ou um worker.
• Registre cada envio (número, horário, status e resposta). Essa informação costuma ser cobrada depois, por clientes ou auditoria.
• Tenha consentimento. Envie apenas para quem autorizou e ofereça forma de descadastro em mensagens promocionais, em linha com a LGPD.
• Não coloque dados sensíveis na mensagem. SMS não é criptografado de ponta a ponta.

Perguntas frequentes sobre envio de SMS com PHP

Qual o formato correto do número de telefone?

Use o padrão internacional apenas com dígitos: código do país (55), DDD e número. Exemplo: 5511999999999. Não use +, espaços, parênteses ou hífens.

Posso enviar SMS sem criar um device?

Sim. A SDK tem o método $api->sms->sendWithCredits([...]), que usa o POST /sms/send/credits e debita o valor do saldo da conta, sem precisar de DeviceToken. Essa rota também aceita 'homolog' => true para testes em ambiente de homologação, sem cobrança.

A SDK funciona em hospedagem compartilhada?

Na maioria dos casos, sim. Ela exige PHP 8.0+ e usa cURL como fallback quando o Guzzle não está disponível. Se a hospedagem não permitir Composer, gere a pasta vendor/ localmente e envie junto com o projeto.

Como enviar para vários números?

Percorra a lista com um foreach, chamando send para cada número, com uma pequena pausa entre os envios e registrando o resultado individual. Interrompa o lote se o erro for de saldo ou autenticação, porque ele vai se repetir em todos os números seguintes.

Existe SDK para outras linguagens?

Sim. A APIBrasil mantém SDKs oficiais para Node.js, Python, Go, Java, Ruby, Rust, C++ e Flutter, além de exemplos REST para linguagens sem SDK. Veja os exemplos no repositório apigratis-exemplos. No tutorial Enviar WhatsApp com Node.js usamos a SDK Node.

Conclusão

Você aprendeu a enviar SMS com PHP usando a SDK oficial da APIBrasil: instalou com Composer, configurou as credenciais em variáveis de ambiente, fez o primeiro envio, tratou cada tipo de erro com exceções específicas e integrou o envio a um projeto Laravel. Também viu como a mesma chamada funciona com cURL puro e as boas práticas que evitam cobranças inesperadas.

Quer ir além do SMS? A mesma SDK envia mensagens de WhatsApp, consulta CEP, CNPJ, placas de veículos e muito mais, sempre com a mesma lógica de $api->servico->acao(). Crie sua conta na APIBrasil e explore o catálogo completo.