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

POST 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.

Requisição — JSON
{
  "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.

Resposta — JSON
{
  "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

POST https://www.smsfacil.com.br/api/v2/cancelaenvio
Requisição — JSON
{
  "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

POST https://www.smsfacil.com.br/api/v2/consultaenvio
Requisição — JSON
{
  "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

POST https://www.smsfacil.com.br/api/v2/consultarsaldo
Requisição — JSON
{
  "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
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#
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
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
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
<?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
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átis

cadastro grátis · sem cartão · créditos sem validade

Demonstração de envio.

Tentando reconectar ao SMS Fácil...