NAV
REST PHP cURL

Introdução

Bem-vindo a Documentação API da Sms Empresa! Você pode usar no API para acessar os serviços Sms, Torpedo de Voz.

A comunicação é feita através de protocolo HTTP. Nós temos exemplos de código em REST, PHP, cURL. Você pode ver exemplos de código na area escura a direita, e pode alterar as linguagens clicando na guia superior direita no nome da linguagem.

Qualquer dúvida na utilização dessa documentação entre em contato através do e-mail suporte@smsempresa.com.br.

Autenticação

A autenticação é feita por Chave Key, uma sequência composta de até 128 caracteres.

Em cada requisição seja ela feita via POST, GET ou JSON o parâmetro key deve ser configurado com sua chave.

Você encontra sua CHAVE KEY no menu Configurações -> Minha Conta ou clique em https://painel.smsempresa.com.br/configuracao/conta/perfil

Sms

Envio (MT)


[
    {
        "key" : "XXXXXXXXXXXXXXXXXXXX",
        "type" : 9,
        "number" : 11988887777,
        "msg" : "Teste de envio 1"
    },
    {
        "key" : "XXXXXXXXXXXXXXXXXXXX",
        "type" : 9,
        "number" : 62988886666,
        "msg" : "Linha 1\nLinha 2"
    }
]

<?php
    $ch = curl_init();

    $data = array('key'         => 'SUA_CHAVE_KEY', 
                  'type'        => '9',     //(9-Sms 
                  'number'      => '11988887777',
                  'msg'         => 'Teste de envio.',
                  'out'         => 'json' //Se desejar retorno em json ou xml
              );    

    curl_setopt($ch, CURLOPT_URL, 'https://api.smsempresa.com.br/v1/send');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $res    = curl_exec ($ch);
    $err    = curl_errno($ch);
    $errmsg = curl_error($ch);
    $header = curl_getinfo($ch);

    curl_close($ch);

    print_r($res); 
?>  
curl \
-X POST "https://api.smsempresa.com.br/v1/send" \
-d '{ "key":"SUA_CHAVE_KEY", "type":"9", "number":"11988887777", "msg":"Teste de envio." }'

O comando acima retorna estrutura XML como esta abaixo, ou JSON se parâmetro OUT informado:

<?xml version="1.0"?>
<smsempresa>
  <retorno situacao="OK" codigo="1" id="637849052">MENSAGEM NA FILA</retorno>
  <retorno situacao="OK" codigo="1" id="637849053">MENSAGEM NA FILA</retorno>
</smsempresa>
[
    {
        "situacao" : "OK",
        "codigo" : "1",
        "id" : "637849052",
        "descricao" : "MENSAGEM NA FILA"
    },
    {
        "situacao" : "OK",
        "codigo" : "1",
        "id" : "637849053",
        "descricao" : "MENSAGEM NA FILA"
    }
]

Envio de SMS podendo ser enviada 1 (uma) ou N mensagem(ns) por requisição.

HTTP Request

GET, POST ou JSON https://api.smsempresa.com.br/v1/send

Parâmetros

Nome Tipo Padrão Obrigatório Descrição
key varchar(16) obrigatório Chave de identificação do usuário
type number obrigatório Tipo de serviço: 9-Sms
number number(13) obrigatório Número destinatário. Não é necessário inserir código do país ‘55’
msg varchar obrigatório Texto da mensagem
out varchar xml opcional Define tipo de retorno XML ou JSON
jobdate varchar data atual opcional Data de agendamento para envio. '01/01/2016’
jobtime varchar hora atual opcional Hora de agendamento para envio. '10:30’
refer varchar(100) opcional Referência do usuário para identificação da mensagem
url_imagem varchar opcional Url da imagem para envio. É necessário existir no texto da mensagem a variável ’[imagem]’

Cada mensagem é composta de até 160 caracteres. Caso a mensagem seja maior é cobrado 1 crédito a cada 160 caracteres.

Recebimento (MO)


{
    "key" : "XXXXXXXXXXXXXXXXXXXX",
    "status" : 0,
    "date_from" : "01/01/2020",
    "date_to" : "30/01/2020",
    "id" : [999999,888888,777777]
}

<?php
    $ch = curl_init();

    $data = array('key'         => 'SUA_CHAVE_KEY', 
                  'status'      => '0', //0-Somente novas ; 1-Todas
                  'out'         => 'json' //Se desejar retorno em json ou xml
                      );    

    curl_setopt($ch, CURLOPT_URL, 'https://api.smsempresa.com.br/v1/inbox');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $res    = curl_exec ($ch);
    $err    = curl_errno($ch);
    $errmsg = curl_error($ch);
    $header = curl_getinfo($ch);

    curl_close($ch);

    print_r($res); 
?>  
curl \
-X POST "https://api.smsempresa.com.br/v1/inbox" \
-d '{ "key":"SUA_CHAVE_KEY", "status":"0"}'

O comando acima retorna estrutura XML como esta abaixo, ou JSON se parâmetro OUT informado:

<?xml version="1.0"?>
<smsempresa>
  <retorno situacao="OK" data_read="01/01/2016 11:35:14" telefone="5511988887777" id="" refer_id="" nome="" msg_sent="" id_sms_read="2515973">Resposta 1</retorno>
  <retorno situacao="OK" data_read="01/01/2016 11:36:11" telefone="5521977776666" id="" refer_id="" nome="" msg_sent="" id_sms_read="2515974">Resposta 2</retorno>
  <retorno situacao="OK" data_read="01/01/2016 11:39:24" telefone="556288887777"  id="" refer_id="" nome="" msg_sent="" id_sms_read="2515975">Resposta 3</retorno>
</smsempresa>   
[
  {"situacao":"OK","data_read":"01\/01\/2016 11:35:14","telefone":"5511988887777","id":"","refer_id":"","nome":"","msg_sent":"","id_sms_read":"2515973","descricao":"Reposta 1"},
  {"situacao":"OK","data_read":"01\/01\/2016 11:36:11","telefone":"5521977776666","id":"","refer_id":"","nome":"","msg_sent":"","id_sms_read":"2515974","descricao":"Reposta 2"},
  {"situacao":"OK","data_read":"01\/01\/2016 11:39:24","telefone":"556288887777","id":"","refer_id":"","nome":"","msg_sent":"","id_sms_read":"2515975","descricao":"Reposta 3"}
]

Esse método é utilizado para consultar as respostas recebidas.

HTTP Request

GET ou POST https://api.smsempresa.com.br/v1/inbox

Parâmetros

Nome Tipo Padrão Obrigatório Descrição
key varchar(16) obrigatório Chave de identificação do usuário.
out varchar xml opcional Define tipo de retorno XML ou JSON
status number 0 opcional Situação da resposta: 0-Somente novas respostas ; 1-Todas as respostas.
date_from date opcional Data início para filtro '01/01/2016’.
date_to date opcional Data fim para filtro '02/01/2016’.
id number opcional ID único da mensagem na Sms Empresa.

Consulta Situação (DLR)


{
    "key" : "XXXXXXXXXXXXXXXXXXXX",
    "id" : [9999999,888888,7777777]
}

<?php
    $ch = curl_init();

    $data = array('key'         => 'SUA_CHAVE_KEY', 
                  'id'          => '175570049',
                  'out'         => 'json' //Se desejar retorno em json ou xml
                      );

    curl_setopt($ch, CURLOPT_URL, 'https://api.smsempresa.com.br/v1/dlr');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $res    = curl_exec ($ch);
    $err    = curl_errno($ch);
    $errmsg = curl_error($ch);
    $header = curl_getinfo($ch);

    curl_close($ch);

    print_r($res); 
?>  
curl \
-X POST "https://api.smsempresa.com.br/v1/dlr" \
-d '{ "key":"SUA_CHAVE_KEY", "id":"123456789"}'

O comando acima retorna estrutura XML como esta abaixo, ou JSON se parâmetro OUT informado:

<?xml version="1.0"?>
<smsempresa>
  <retorno situacao="OK" codigo="1" data_envio="20/01/2016 10:33:39" operadora="VIVO-PORTABILIDADE">RECEBIDA</retorno>
</smsempresa>
{"situacao":"OK","codigo":"1","data_envio":"20\/01\/2016 10:33:39","operadora":"VIVO-PORTABILIDADE","descricao":"RECEBIDA"}

Esse método é utilizado para consultar a situação da mensagem (DLR).

Você deve guardar o ID único da mensagem no momento do envio (MT) para utilizar esse método.

HTTP Request

GET ou POST https://api.smsempresa.com.br/v1/dlr

Parâmetros

Nome Tipo Padrão Obrigatório Descrição
key varchar(16) obrigatório Chave de identificação do usuário
id array number obrigatório ID único da mensagem na Sms Empresa

Retorno

Situação Descrição
RECEBIDA Mensagem entregue no aparelho do cliente
ENVIADA Mensagem enviada a operadora
ERRO Erro de validação da mensagem
FILA Mensagem aguardando processamento
CANCELADA Mensagem cancelada pelo usuário
BLACK LIST Destinatário ativo no grupo 'Black List’

CallBack Retorno (MO)

{       

    "from": "5562988887777", 
    "id": "123456789",       
    "id_sent": "637849052",  
    "message": "Teste de retorno", 
    "refer": "XXXXXXX" 
}

Esse método é utilizado para que o servidor da Sms Empresa realize uma chamada via POST ou GET para uma URL definida pelo usuário a cada nova resposta.

É necessário definir a URL no menu API & Integrações -> Configuração CallBack https://painel.smsempresa.com.br/integracao/callback

Dados enviados pelo CallBack

Nome Tipo Descrição
from number Remetente da resposta.
message varchar Texto da resposta.
id number ID único da resposta.
id_sent number ID único da mensagem enviada origem da resposta.
refer varchar Referência do usuário utilizado na mensagem de origem da resposta.

CallBack Situação (DLR)

{       

    "key" : "XXXXXXXXXXXXXXX", 
    "id" : "123456789",       
    "refer" : "XXXXXXX",  
    "situacao" : "RECEBIDA",  
    "data_envio" : "28022020145322", 
    "operadora" : "VIVO-PORTABILIDADE", 
    "qtd_credito" : "1"
}

Essa opção é utilizada para que o servidor da SMS Dev realize uma chamada para uma URL definida pelo usuário para Situação de Mensagens (DLR).

É necessário definir a URL no menu API & Integrações -> Configuração CallBack https://painel.smsempresa.com.br/integracao/callback

Dados enviados pelo CallBack

Nome Tipo Descrição
key varchar Chave key do usuário.
id number ID da mensagem de envio (MT).
refer varchar Referencia utiliza na mensagem de envio (MT).
situacao varchar Situação da mensagem.
data_envio number Formato (DLR) ddmmrrrrhh24miss.
operadora varchar Operadora identificada (HLR).
qtd_credito number Qtd de crédito consumido.

Torpedo de Voz

Envio

[
    {
        "key" : "XXXXXXXXXXXXXXXXXXXX",
        "type" : 1,
        "number" : 11988887777,,
        "msg" : "Teste de envio 1"
    },
    {
        "key" : "XXXXXXXXXXXXXXXXXXXX",
        "type" : 1,
        "number" : 62988886666,
        "msg" : "Linha 1\nLinha 2"
    }
]
<?php
    $ch = curl_init();

    $data = array('key'         => 'SUA_CHAVE_KEY', 
                  'type'        => '1',
                  'number'      => '11988887777',
                  'msg'         => 'Teste de envio.',           //Para envio de texto conversão automática
                  'out'         => 'json',      //Se desejar retorno em json ou xml                      
                  'url_audio'       => 'www.seusiste.com.br/audio.wav');    //Para envio de arquivo de áudio

    curl_setopt($ch, CURLOPT_URL, 'https://api.smsempresa.com.br/v1/send');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $res    = curl_exec ($ch);
    $err    = curl_errno($ch);
    $errmsg = curl_error($ch);
    $header = curl_getinfo($ch);

    curl_close($ch);

    print_r($res); 
?>  
curl \
-X POST "https://api.smsempresa.com.br/v1/send" \
-d '{ "key":"SUA_CHAVE_KEY", "type":"1", "number":"11988887777", "msg":"Teste de envio","url_audio":"www.seusiste.com.br/audio.wav" }'

O comando acima retorna estrutura XML como esta abaixo, ou JSON se parâmetro OUT informado:

<?xml version="1.0"?>
<smsempresa>
  <retorno situacao="OK" codigo="1" id="175570049">MENSAGEM NA FILA.</retorno>
</smsempresa>
[
    {
        "situacao" : "OK",
        "codigo" : "1",
        "id" : "637849052",
        "descricao" : "MENSAGEM NA FILA"
    },
    {
        "situacao" : "OK",
        "codigo" : "1",
        "id" : "637849053",
        "descricao" : "MENSAGEM NA FILA"
    }
]

Esse método é utilizado para enviar uma única mensagem por requisição.

No retorno já é disponibilizado o ID único da mensagem na Sms Empresa.

Ideal quando as mensagens são diferentes para cada destinatário.

HTTP Request

GET ou POST https://api.smsempresa.com.br/v1/send

Parâmetros

Nome Tipo Padrão Obrigatório Descrição
key varchar(16) obrigatório Chave de identificação do usuário
type number obrigatório Tipo de serviço: 1-Torpedo de Voz
number number(13) obrigatório Número destinatário. Não é necessário inserir código do país '55’
out varchar xml opcional Define tipo de retorno XML ou JSON
msg varchar opcional Mensagem de texto a ser convertida para áudio
url_audio varchar opcional Url do arquivo de áudio formato ’.wav’ ou ’.mp3’
jobdate varchar data atual opcional Data de agendamento para envio. '01/01/2016’
jobtime varchar hora atual opcional Hora de agendamento para envio. '10:30’
refer varchar(100) opcional Referência do usuário para identificação da mensagem

Consulta Situação

<?php
    $ch = curl_init();

    $data = array('key'         => 'SUA_CHAVE_KEY', 
                  'id'          => '175570049',
                  'out'         => 'json' //Se desejar retorno em json ou xml
                      );

    curl_setopt($ch, CURLOPT_URL, 'https://api.smsempresa.com.br/v1/dlr');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $res    = curl_exec ($ch);
    $err    = curl_errno($ch);
    $errmsg = curl_error($ch);
    $header = curl_getinfo($ch);

    curl_close($ch);

    print_r($res); 
?>  
curl \
-X POST "https://api.smsempresa.com.br/v1/dlr" \
-d '{ "key":"SUA_CHAVE_KEY", "id":"175570049" }'

O comando acima retorna estrutura XML como esta abaixo, ou JSON se parâmetro OUT informado:

<?xml version="1.0"?>
<smsempresa>
  <retorno situacao="OK" codigo="1" data_envio="01/01/2016 10:30:00" data_atendeu_voz="01/01/2016 10:31:15" operadora="VIVO-PORTABILIDADE">RECEBIDA</retorno>
</smsempresa>
{"situacao":"OK","codigo":"1","data_envio":"01\/01\/2016 10:30:00","data_atendeu_voz":"01\/01\/2016 10:31:15","operadora":"VIVO-PORTABILIDADE","descricao":"RECEBIDA"}

Esse método é utilizado para consultar a situação da mensagem.

Você deve guardar o ID único da mensagem na Sms Empresa no momento do envio para utilizar esse método.

HTTP Request

GET ou POST https://api.smsempresa.com.br/v1/dlr

Parâmetros

Nome Tipo Padrão Obrigatório Descrição
key varchar(16) obrigatório Chave de identificação do usuário
action varchar obrigatório Definir 'status’ para consulta de situação
id number obrigatório ID único da mensagem na Sms Empresa

Retorno

Situação Descrição
RECEBIDA Mensagem entregue no aparelho do cliente
ENVIADA Mensagem enviada a operadora
ERRO Erro de validação da mensagem
FILA Mensagem aguardando processamento
CANCELADA Mensagem cancelada pelo usuário
BLACK LIST Destinatário ativo no grupo 'Black List’
PROCON Destinatário com bloqueio no 'Procon’

Conta

Saldo


{
    "key" : "XXXXXXXXXXXXXXXXXXXX"
}

<?php
    $ch = curl_init();

    $data = array('key'         => 'SUA_CHAVE_KEY', 
                  'out'         => 'json' //Se desejar retorno em json ou xml
                      );

    curl_setopt($ch, CURLOPT_URL, 'https://api.smsempresa.com.br/v1/balance');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $res    = curl_exec ($ch);
    $err    = curl_errno($ch);
    $errmsg = curl_error($ch);
    $header = curl_getinfo($ch);

    curl_close($ch);

    print_r($res); 
?>  
curl \
-X POST "https://api.smsempresa.com.br/v1/balance" \
-d '{ "key":"SUA_CHAVE_KEY"}'

O comando acima retorna estrutura XML como esta abaixo, ou JSON se parâmetro OUT informado:

<?xml version="1.0"?>
<smsempresa>
 <retorno situacao="OK" saldo_sms="100" saldo_voz="12" saldo_email="0">SALDO ATUAL</retorno>
</smsempresa>
{ 
   "situacao" : "OK",
   "saldo_sms" : "1200",
   "saldo_voz" : "550",
   "descricao" : "SALDO ATUAL"
}

Esse método é utilizado para consultar saldo de todos os serviços.

Ideal para que o usuário não fique sem saldo.

HTTP Request

GET ou POST https://api.smsempresa.com.br/v1/balance

Parâmetros

Nome Tipo Padrão Obrigatório Descrição
key varchar(16) obrigatório Chave de identificação do usuário.

Códigos de Retorno

Abaixo a tabela de códigos de retornos.

Caso o código recebido não esteja listado abaixo entre em contato através dos e-mail suporte@smsempresa.com.br .

Código Descrição
1 Operação realizada com sucesso.
400 Texto ou Url da mensagem não definida.
401 Campo ACTION valor inválido.
402 Campo NUMBER sem valor definido.
403 Chave Key não e válida e/ou usuário não autenticado.
405 Campo ID sem valor definido.
407 Campo NUMBER erro de validação.
408 Saldo insuficiente. – Realize uma nova recarga.
409 Campo TYPE valor inválido.
414 Conta não confirmada ou bloqueada. – Efetue login no site confirmar sua conta.
416 Campo REFER máximo de caracteres permitido.
420 Campo MSG máximo de caracteres permitido.
421 Campo MSG no Torpedo de Voz máximo de caracteres permitido.
435 Campo ACTION sem valor definido.
436 Campo ID não encontrado.