Português

Application Programming Interface (SMS API)

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"
}
Cada função tem parâmetros de resposta diferentes. Poder ver a especificação detalhada aqui.

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."
}
Sempre podes esperar por um código de erro de três dígitos e uma descrição que ajuda-te a identificar o problema serem retornados quando o parâmetro de sucesso da resposta é false.

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);
Em Java, é quase a mesma coisa.
InputStream body = request.getInputStream();
Por favor, note que independente da linguagem de programação que escolha podes ler a entrada apenas uma vez. Armazene o corpo noutro lugar para processar.

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!');

?>
Bem claro? Se isto é tudo o que precisas, simplesmente descarrega o Kit de Início de Mensagens PHP, observa os comentários no código, executa send-sms.php e estás pronto.

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,
        ));
        
    }

}

?>
Mesmo código acima num arquivo chamado MyCoolSMS.class.php e começa a usar desta forma:
<?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);
}

?>

Estás pronto para seguir!

Vamos olhar a documentação de função e retornos API agora.
Nós esquecemos de algo? Tens alguma pergunta? Tens alguma sugestão ou algo que deveríamos adicionar aqui? Se sim, avise-nos!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Polski
Руccкий
繁体中文