Documentação
API de SMS: documentação para desenvolvedores
Tudo o que você precisa para integrar o envio de SMS ao seu sistema: exemplos de código, agendamento, consulta de saldo e acompanhamento de entregas.
Visão geral
Todas as chamadas usam POST com Content-Type: application/json e
HTTPS. As credenciais vão no corpo da requisição, nunca na URL: assim elas não ficam no
histórico do navegador, nos logs de servidores e proxies intermediários nem no cabeçalho
Referer.
| Endpoint | Campos do JSON | Resposta |
|---|---|---|
POST /api/v2/EnviaSMS |
usuario, senha, mensagens |
JSON |
POST /api/v2/cancelaenvio |
usuario, senha, nr_pedido |
texto simples |
POST /api/v2/consultaenvio |
usuario, senha, nr_pedido |
texto simples |
POST /api/v2/consultarsaldo |
usuario, senha |
texto simples |
Já integrado com o formato antigo?
As chamadas que enviam os parâmetros na URL continuam funcionando normalmente e não exigem nenhuma alteração. Esta documentação cobre o formato atual, recomendado para quem está começando agora.
Enviar SMS
https://www.smsfacil.com.br/api/v2/EnviaSMS
A lista mensagens aceita de 1 a 1.000 itens. Para um envio individual, inclua
somente um item. Cada mensagem tem o próprio destino e texto, e pode ser agendada com
data e hora — quando esses campos são omitidos, o envio é imediato.
Use DDD + número, com 10 ou 11 dígitos.
{
"usuario": "SEU_USUARIO",
"senha": "SUA_SENHA",
"mensagens": [
{ "para": "11999999999", "texto": "Primeira mensagem" },
{ "para": "21999999999", "texto": "Mensagem agendada", "data": "25/09/2026", "hora": "14:30" }
]
}
A resposta é JSON com HTTP 200 depois do processamento, mesmo quando há falhas individuais.
O campo indice começa em zero e identifica a posição original da mensagem na
lista. Cada item traz o recibo de envio ou o código de erro correspondente.
{
"total": 2,
"aceitos": 1,
"falhas": 1,
"resultados": [
{ "indice": 0, "para": "11999999999", "sucesso": true, "resultado": "OK 123456789012345678901234567890" },
{ "indice": 1, "para": "21999999999", "sucesso": false, "resultado": "-7" }
]
}
Sucesso significa inclusão na fila, não confirmação de entrega. As mensagens são processadas
em ordem e uma falha não desfaz os envios anteriores. Itens repetidos são enviados
separadamente. Se os créditos acabarem no meio do lote, os itens afetados retornam
-7 e os anteriores permanecem aceitos.
Valores do campo resultado
| Valor | Descrição |
|---|---|
OK 1234567890923 |
Mensagem aceita. O número de solicitação retornado pode ser consultado depois. |
-2 |
Formato de número móvel do destinatário inválido. |
-3 |
O texto da mensagem está vazio ou inválido. |
-4 |
Número móvel inválido ou não suportado pelo sistema. |
-5 |
Sistema indisponível, tente novamente mais tarde (muito raro). |
-6 |
Conta bloqueada. |
-7 |
Crédito insuficiente para realizar o envio. |
-8 |
Usuário ou senha inválidos. |
-9 |
Data ou hora de agendamento inválidos. Se informados, precisam ter valores válidos. |
* O campo data usa o formato dd/mm/aaaa e o campo hora usa hh:mm. * O relógio do servidor de envio está ajustado para o horário de Brasília. * Atente-se ao fuso horário da sua localidade e ao horário de verão. * Agendamentos com data ou hora já passadas são enviados imediatamente.
Cancelar um envio agendado
https://www.smsfacil.com.br/api/v2/cancelaenvio{
"usuario": "SEU_USUARIO",
"senha": "SUA_SENHA",
"nr_pedido": "123456789012345678901234567890"
}
O valor de nr_pedido deve ser exatamente o número de solicitação retornado no
envio da mensagem. A resposta é texto simples.
| Resposta | Descrição |
|---|---|
OK |
O envio programado foi cancelado com sucesso. |
-1 |
Formato de número de pedido inválido. Verifique se contém apenas dígitos. |
-2 |
Envio não encontrado. Ele já está em andamento, foi concluído ou não existe. Não é possível cancelar um envio em andamento. |
-8 |
Usuário ou senha inválidos. |
Consultar o status de entrega
https://www.smsfacil.com.br/api/v2/consultaenvio{
"usuario": "SEU_USUARIO",
"senha": "SUA_SENHA",
"nr_pedido": "123456789012345678901234567890"
}A resposta é texto simples com a situação atual da mensagem.
| Resposta | Descrição |
|---|---|
| Entregue | A mensagem foi entregue ao destinatário. |
| Não entregue | A mensagem não pôde ser entregue. |
| Enviada | A mensagem foi enviada, mas não foi possível saber se chegou ao destinatário. A confirmação pode levar até 3 dias a contar da data do envio. |
| Não enviada | A mensagem não pôde ser enviada. |
| Número inválido | Destinatário inválido, inexistente ou sem cobertura. Neste caso não há cobrança de créditos. |
| Texto inválido | A mensagem está em formato incorreto. |
| Pendente | A mensagem está na fila aguardando o envio. |
| Aguardando envio | A mensagem está pronta para ser enviada. |
| dd/mm/aaaa hh:mm | Para mensagens agendadas ainda não disparadas, o retorno é a data e a hora do disparo. |
-8 |
Usuário ou senha inválidos. |
-9 |
Formato de número de pedido inválido. Verifique se contém apenas dígitos. |
-10 |
Mensagem inexistente ou com data de histórico expirada. |
Consultar o saldo
https://www.smsfacil.com.br/api/v2/consultarsaldo{
"usuario": "SEU_USUARIO",
"senha": "SUA_SENHA"
}A resposta é texto simples.
| Resposta | Descrição |
|---|---|
N |
Número de créditos disponíveis na sua conta. |
-8 |
Usuário ou senha inválidos. |
Erros e limites
| Status HTTP | Quando acontece |
|---|---|
200 |
Requisição processada. No envio em lote, pode haver falhas individuais — verifique cada item. |
400 |
Corpo ausente, JSON inválido, tipos incompatíveis ou lista inválida. A lista não pode estar vazia, conter itens nulos ou exceder 1.000 mensagens. |
415 |
Formato de conteúdo incompatível. Envie Content-Type: application/json. |
Campos de negócio inválidos são avaliados por mensagem e retornam no campo
resultado do item correspondente, não como erro HTTP. Parâmetros enviados na
URL não substituem nem completam o JSON.
Cuidado ao repetir requisições
Lotes grandes podem demorar, e uma desconexão ou timeout pode acontecer depois de parte das mensagens já ter sido aceita. A API não oferece deduplicação nem protocolo de lote: repetir a requisição pode duplicar mensagens e cobranças. Não configure repetição automática do lote após timeout — consulte o status antes de reenviar.
Exemplos de integração
Envio de uma mensagem pela API do SMS Fácil nas principais linguagens. Para
enviar um lote, basta acrescentar itens à lista mensagens.
Enviar SMS com cURL
curl -X POST https://www.smsfacil.com.br/api/v2/EnviaSMS \
-H "Content-Type: application/json" \
-d '{
"usuario": "SEU_USUARIO",
"senha": "SUA_SENHA",
"mensagens": [
{ "para": "11999999999", "texto": "Olá, SMS Fácil" }
]
}'Enviar SMS com C#
using System.Net.Http.Json;
using var client = new HttpClient();
using var response = await client.PostAsJsonAsync(
"https://www.smsfacil.com.br/api/v2/EnviaSMS",
new
{
usuario = "SEU_USUARIO",
senha = "SUA_SENHA",
mensagens = new[]
{
new { para = "11999999999", texto = "Olá, SMS Fácil" }
}
});
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
// Verifique "sucesso" e "resultado" de cada item, mesmo com HTTP 200.Enviar SMS com Java
import java.net.URI;
import java.net.http.*;
public class EnviarSms {
public static void main(String[] args) throws Exception {
String json = "{"
+ "\"usuario\": \"SEU_USUARIO\","
+ "\"senha\": \"SUA_SENHA\","
+ "\"mensagens\": ["
+ " { \"para\": \"11999999999\", \"texto\": \"Olá, SMS Fácil\" }"
+ "]}";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
.uri(URI.create("https://www.smsfacil.com.br/api/v2/EnviaSMS"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
var response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Enviar SMS com Node.js
const resposta = await fetch(
"https://www.smsfacil.com.br/api/v2/EnviaSMS",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
usuario: "SEU_USUARIO",
senha: "SUA_SENHA",
mensagens: [
{ para: "11999999999", texto: "Olá, SMS Fácil" }
]
})
});
const resultado = await resposta.json();
console.log(resultado);
// resultado.resultados[0].sucesso indica se a mensagem foi aceita.Enviar SMS com PHP
<?php
$payload = json_encode([
"usuario" => "SEU_USUARIO",
"senha" => "SUA_SENHA",
"mensagens" => [
["para" => "11999999999", "texto" => "Olá, SMS Fácil"],
],
]);
$ch = curl_init("https://www.smsfacil.com.br/api/v2/EnviaSMS");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_RETURNTRANSFER => true,
]);
$resposta = curl_exec($ch);
curl_close($ch);
echo $resposta;Enviar SMS com Delphi
uses
System.Classes, System.SysUtils, System.Net.HttpClient,
System.Net.URLClient;
procedure EnviarSms;
var
Http: THTTPClient;
Corpo: TStringStream;
Response: IHTTPResponse;
begin
Http := THTTPClient.Create;
try
Corpo := TStringStream.Create(
'{"usuario": "SEU_USUARIO",' +
' "senha": "SUA_SENHA",' +
' "mensagens": [' +
' {"para": "11999999999", "texto": "Ola, SMS Facil"}' +
' ]}', TEncoding.UTF8);
try
Response := Http.Post(
'https://www.smsfacil.com.br/api/v2/EnviaSMS',
Corpo, nil,
[TNetHeader.Create('Content-Type', 'application/json')]);
WriteLn(Response.ContentAsString(TEncoding.UTF8));
finally
Corpo.Free;
end;
finally
Http.Free;
end;
end;* Substitua SEU_USUARIO e SUA_SENHA pelas credenciais da sua conta. * O número de destino usa DDD + número, com 10 ou 11 dígitos. * Verifique sucesso e resultado de cada item, mesmo quando a resposta for HTTP 200. * Nunca coloque as credenciais na URL: mantenha-as sempre no corpo da requisição.
Pronto para integrar?
Crie uma conta gratuita para obter suas credenciais e começar a enviar.
Criar conta grátiscadastro grátis · sem cartão · créditos sem validade
Demonstração de envio.