Pontos finais
A primeira coisa que precisas saber é aonde enviar sue requisição API. My-Cool-SMS aceita requisições GET, POST e JSON via porta 80 ou SSL pela porta 443. Podes conectar com os seguintes URL, respectivamente.HTTP
O ponto final da API para requisições HTTP é:
http://www.my-cool-sms.com/api-socket.php
HTTPS
Se necessitas de conexão segura, podes usar a API via SSL pela porta 443. O ponto final da API para requisições HTTPS é:
https://www.my-cool-sms.com/api-socket.php
Componentes de API
My-Cool-SMS tem dois tipos de componentes API. Funções e Retornos.Funções
Funções são usadas, por exemplo, para requisitar o envio duma mensagem de texto, verificar teu saldo ou requerer relatórios de entrega. Uma função pode ser chamada através duma estrutura de requisição HTTP como destacada abaixo.Retornos
Retornos são requisições enviadas do My-Cool-SMS ao teu servidor. Um retorno é chamado em tempo real quando eventos como receber uma mensagem ou um novo relatório de entrega e esse é informado ao URL do teu servidor para processo.Estrutura de requisição
Podes enviar requisições via HTTP, POST, GET ou JSON. Embora My-Cool-SMS não impeça-te de usar POST ou GET é altamente recomendado o uso de requisições JSON. JSON é um formato de transferência de dados leve que é fácil de ler e escrever e também de analisar e gerar para a linguagem de programação de tua escolha. Acima de tudo, JSON é muito robusto quando a enviar mensagem de texto em Unicode e não requer uma implementação complexa de procedimentos de codificação e descodificação UCS2. Se já tiveste que trabalhar com codificação e descodificação entre servidores Unicode, UCS2 ou GSM7, deves saber que é bom evitar-las. Podes saber mais sobre JSON aqui.Credenciais de acesso e Se selectores de função
Uma requisição à API do My-Cool-SMS deve conter sempre teu nome de usuário, senha e um selector de função que diga à API o que queres fazer.JSON
Vamos olhar um exemplo JSON que usarias para consultar teu saldo:
{
"username":"xxx",
"password":"yyy",
"function":"getBalance"
}
POST/GET
Com POST ou GET a mesma requisição seria como:
username=xxx&password=yyyy&function=getBalance
Parâmetros opcionais e mandatários
O nome de usuário, senha e parâmetros da função sempre são obrigatórios, e além disto, cada função pode especificar parâmetros mandatários ou opcionais que também devem ser fornecidos. Quando a requerer um relatório de entrega, por exemplo, também queres especificar a qual mensagem o relatório se refere. Podes fazer isto ao adicionar um parâmetro, neste caso, "id"
{
"username":"xxx",
"password":"yyy",
"function":"getDeliveryReport",
"id":"ce184cc0a6d1714d1ac763f4fe89f521"
}
Estrutura de resposta
Uma requisição API sempre retorna um objecto JSON. Toda resposta contém um parâmetro de sucesso que indica se a requisição pôde ser processada ou não. A depender deste parâmetro, tratarás a resposta diferentemente.Respondido com sucesso
Uma requisição de sucesso para a função getDeliveryReport retornaria um objecto JSON como o seguinte:
{
"success":true,
"smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
"status":"SMS_STATUS_DELIVERED"
}
Erro de resposta
Digamos que tens um erro de digitação no parâmetro de senha. Neste caso, a API retornará um objecto JSO com a seguinte estrutura:
{
"success":false,
"errorcode":"101",
"description":"Login Failed. Wrong Username or Password."
}
A lidar com respostas
Ler resposta
A resposta da API sempre é enviada em formato JSON. Tudo o que precisas fazer é converter a resposta em um objecto. Isto é simples porque praticamente toda linguagem de programação oferece métodos nativos para esta operação. Para mais informações sobre JSON para a linguagem de programação de tua escolha, vá a esta página e olha um pouco mais abaixo. Em PHP, deves fazer algo entre as linhas a seguir para processar a resposta da API:
// Let's assume you sent a getDeliveryReport request and
// the HTTP response is stored in $response...
// Now simply convert the response into a PHP object
$oResponse = json_decode($response);
//$oResponse is now an object
if($oResponse->success) {
//Great. It worked!
echo($oResponse->smsid);
echo($oResponse->status);
} else {
//Oops. something went wrong.
echo($oResponse->errorcode);
echo($oResponse->description);
}
A lidar com retornos
Ler entrada
Retornos não são muito diferentes de respostas de funções e podes convertê-los em objectos exactamente da mesma forma acima. Contudo, algo que deves saber é como capturar a Entrada de Requisição Bruta HTTP. O retorno não é enviado via GET nem POST, mas em Dado Bruto HTTP o qual podes ler como destacado a seguir. Em PHP, deves fazer algo entre as linhas a seguir para processar a requisição de retorno:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));
//$oCallback is now an object.
print_r($oCallback);
InputStream body = request.getInputStream();
Exemplos de PHP
Função: sendSms
Vamos olhar como o código de fato da mensagem pode parecer. Provavelmente queres implementar a API a usar menos linhas de código quanto possível. Então, o que achas do seguinte?
<?php
$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');
?>
Kit de Início de Mensagens PHP
Descarrega o Kit de Início de Mensagens PHP
O kit de início contém códigos prontos para chamar funções API e lidar com retornos.
Para técnicos
Se entendes um pouco mais de tecnologia, podes querer olhar a classe que lida com a requisição de fato:
<?php
class MyCoolSMS {
function __construct() {
$this->username = 'xxx'; //your username here...
$this->password = 'yyy'; //your password here...
$this->endpoint = 'http://www.my-cool-sms.com/api-socket.php';
}
public function sendSms($number, $message, $senderid='MyNumber') {
return($this->request(json_encode(array(
'username' => $this->username,
'password' => $this->password,
'function' => 'sendSms',
'number' => $number,
'senderid' => $senderid,
'message' => $message
))));
}
public function getDeliveryReport() {}
public function getBalance() {}
//add more functions as you please...
private function request($oRequest) {
$oCurl = curl_init($this->endpoint);
curl_setopt($oCurl, CURLOPT_POST, 1);
curl_setopt($oCurl, CURLOPT_POSTFIELDS, $oRequest);
curl_setopt($oCurl, CURLOPT_RETURNTRANSFER, 1);
if(curl_errno($oCurl) == 0) {
$oResponse = json_decode(curl_exec($oCurl));
if(!is_object($oResponse)) {
$oResponse = $this->getError('001', 'Bad Response');
}
} else {
$oResponse = $this->getError(curl_error($oCurl));
}
curl_close($oCurl);
return $oResponse;
}
private function getError($error = '000', $description = NULL) {
return json_encode(array(
'success' => false,
'error' => $error,
'description' => $description,
));
}
}
?>
<?php
require_once('MyCoolSMS.class.php');
$oMyCoolSMS = new MyCoolSMS();
$oResponse = $oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');
if($oResponse->success) {
//Great, it worked!
print_r($oResponse);
} else {
//Oops, Something went wrong...
print_r($oResponse);
}
?>
