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